The structure of your mod is important in keeping your mod organized, for both your benefit and the benefit of anyone who wishses to make a feature for your mod. A disorganized mod structure may cause headaches when someone is trying to update it to a higher version, especially if they cannot modify the package structure, due to i.e. licensing.
+
The structure of your mod is important in keeping your mod organized, for both your benefit and the benefit of anyone who wishes to make a feature or an
+
add-on for your mod. A disorganized mod structure may cause headaches when someone is trying to update it to a higher version, especially if they cannot modify the package structure, due to i.e. licensing.
−
{{Colored box|title=Tip|background-title-color=#633193|content=Note that this page is only a recommendation for your mod structure; you may structure your mod in any way you see fit.}}
+
{{Tip|Note that this page is only a recommendation for your mod structure; you may structure your mod in any way you see fit.}}
== Packaging ==
== Packaging ==
Line 9:
Line 10:
The next level package is usually your mod's ID: if your mod ID is <code>examplemod</code>, your mod's package will be <code>com.example.examplemod</code>.
The next level package is usually your mod's ID: if your mod ID is <code>examplemod</code>, your mod's package will be <code>com.example.examplemod</code>.
−
{{Colored box|title=Important|content=Do not use a domain for your top level package if you do not own that domain. It is perfectly acceptable to have your top level package be named with anything, such as your name/nickname, or the name of the mod (<code>me.exampledude.examplemod</code>).}}
+
{{Tip/Important|Do not use a domain for your top level package if you do not own that domain. It is perfectly acceptable to have your top level package be named with anything, such as your name/nickname, or the name of the mod (<code>me.exampledude.examplemod</code>).}}
=== Using Subpackages ===
=== Using Subpackages ===
−
Rather than clutter up a single class and package with everything, it is recommended you break your mod into subpackages.
+
Rather than clutter up a single class and package with everything, it is recommended you break your mod into subpackages. Below are a few possible methods for laying out your folder structure though you may as well come up with your own layout too.
−
A common strategy is to make a subpackage for grouping classes that have a common purpose. For example, your blocks classes can be under <code>blocks</code>, your entities classes can be under <code>entities</code>, your helper utilities can be under <code>helpers</code>, etc.
+
* '''Group by Logic''': One possible strategy is to make subpackages for logical units of your mod. For example, if you have a block called Super Furnace you would put its block, its block entity and its item all under <code>feature/superfurnace</code>.
+
* '''Group by Function''': Another common strategy is to make subpackages for grouping classes that have a common purpose. For example, your blocks classes can be under <code>blocks</code>, your entities classes can be under <code>entities</code>, your helper utilities can be under <code>helpers</code>, etc.
−
It is recommended to add a <code>client</code> subpackage under your main package, to isolate your [[Sides|client-only code]] from the rest, such as your GUIs and renderers.
+
No matter how your final structure looks like it is highly recommended to add a <code>client</code> subpackage under your main package. This helps to isolate your [[Sides|client-only code]] from the rest, such as your Screens and renderers.
By keeping your code in clean subpackages, you can grow your mod much more organically.
By keeping your code in clean subpackages, you can grow your mod much more organically.
+
+
{{Tip|If you are unsure on how exactly you want to structure your mod it can be a good idea to look at the source of others to see how they did it.}}
== Class Naming Schemes ==
== Class Naming Schemes ==
Line 27:
Line 31:
The usual style is to use suffixes for your classes, for example:
The usual style is to use suffixes for your classes, for example:
−
* An <code>Item</code> called <code>PowerRing</code> would be in the <code>items</code> package, with a class name of <code>PowerRingItem</code>.
+
* An <code>Item</code> called <code>PowerRing</code> would have a class name of <code>PowerRingItem</code>.
−
* A <code>Block</code> called <code>NotDirt</code> would be in a <code>blocks</code> package, with a class name of <code>NotDirtBlock</code>.
+
* A <code>Block</code> called <code>NotDirt</code> would have a class name of <code>NotDirtBlock</code>.
−
* A <code>TileEntity</code> for a block called <code>SuperChewer</code> would be in a <code>tile</code> or <code>tileentity</code> package, with a class name of <code>SuperChewerTile</code>.
+
* A <code>BlockEntity</code> for a block called <code>SuperChewer</code> would have a class name of <code>SuperChewerBlockEntity</code>.
== The Mod File ==
== The Mod File ==
Line 37:
Line 41:
The <code>@Mod</code> annotation indicates to the mod loader that this class is the entry point of your mod. Each <code>@Mod</code> annotation and their value should be paired with a mod id entry in your <code>mods.toml</code> file.
The <code>@Mod</code> annotation indicates to the mod loader that this class is the entry point of your mod. Each <code>@Mod</code> annotation and their value should be paired with a mod id entry in your <code>mods.toml</code> file.
−
== The <code>mods.toml</code> file ==
+
== mods.toml file ==
The <code>mods.toml</code> file is read by the mod loader to determine what mods are packaged into your JAR file, and what information to display to the user in the Mods listing screen (accessible by pressing the "Mods" button on the main menu of the game).
The <code>mods.toml</code> file is read by the mod loader to determine what mods are packaged into your JAR file, and what information to display to the user in the Mods listing screen (accessible by pressing the "Mods" button on the main menu of the game).
−
The <code>mods.toml</code> file is formatted in [https://toml.io/en/ Tom's Obvious Minimal Language], or TOML for short. The example <code>mods.toml</code> file in the MDK provides comments explaining the contents of the file. It should be stored under the <code>META-INF</code> folder in your resources directory (<code>src/main/resources/META-INF/mods.toml</code>).
+
More information about the structure of this file and the possible configuration options available to you can be found on the [[Mods.toml file|dedicated page]].
Lets you craft dirt into diamonds. This is a traditional mod that has existed for eons. It is ancient. The holy Notch created it. Jeb rainbowfied it. Dinnerbone made it upside down. Etc.
−
'''
−
−
[[dependencies.examplemod]]
−
modId="forge"
−
mandatory=true
−
versionRange="[34,)"
−
ordering="NONE"
−
side="BOTH"
−
−
[[dependencies.examplemod]]
−
modId="minecraft"
−
mandatory=true
−
versionRange="[1.16.3]"
−
ordering="NONE"
−
side="BOTH"
−
</syntaxhighlight>
−
</div>
−
</div>
−
−
The default Gradle configuration replaces <code>${file.jarVersion}</code> with the project version, but only within <code>mods.toml</code>, so you should use those instead of directly writing them out. Here is a table of attributes that may be given to a mod, where <code>mandatory</code> means there is no default and the absence of the property causes an error.
−
−
The <code>mods.toml</code> is split into three parts: the non-mod-specific properties, which are linked to the mod file; the mod properties, with a section for each mod; and dependency configurations, with a section for each mod's dependencies.
| The language loader for the mod. Used to specify an alternative language for the mod, such as Kotlin, if one exists. The Forge-provided Java loader is <code>javafml</code>.
| The acceptable version range of the language loader, expressed as a [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven version spec]. For the Forge-provided Java loader, the version is the major version of the Forge version.
| The license for the mod(s) in this JAR. This string may be any valid string, but it is suggested to set the value to be the name of your license, and/or a link to that license.
| Whether to display this mod's resources as a separate option in the resource pack menu. If disabled, the mod's resources will be rolled into the "Mod resources" pack.
| A URL for an issues tracker. <inline alert> This should never be a blank string, as that will cause an error. </inline>
−
| <code>"http://my.issue.tracker/"</code>
−
|}
−
−
=== Mod Properties ===
−
−
A mod entry is defined by a new section starting with a <code><nowiki>[[mods]]</nowiki></code> header (In TOML, the <code><nowiki>[[mods]]</nowiki></code> defines an [https://toml.io/en/v1.0.0-rc.2#array-of-tables array of tables]). All properties from that line until the next header will become the properties for that mod.
−
−
{| class="wikitable"
−
! Property !! Type !! Defaults
−
! Description
−
! Example
−
|-
−
| <code>modId</code> || string || '''mandatory'''
−
| The mod's identifier (modid). This must match the following regex: <code>^[a-z][a-z0-9_-]{1,63}$</code> (starts with a lowercase letter; other characters must be a lowercase letter, number, underscore or hyphen; must be 2-64 characters long).
−
| <code>"examplemod"</code>
−
|-
−
| <code>namespace</code> || string || value of <code>modId</code>
−
| An override namespace. <inline info> Currently, there is no use for this property </inline>
| The version of the mod jar, used when the mod is a dependency of another mod, expressed as numbers seperated by dots (<code>.</code>), ideally conforming to [[Semantic_Versioning|Semantic Versioning]]. The default value in the MDK for this is <code>${file.jarVersion}</code>, which is replaced at runtime with the <code>Implementation-Version</code> found in the jar's manifest file.
−
| <code>"0.2.4-beta1"</code>
−
|-
−
| <code>displayName</code> || string || value of <code>modId</code>
−
| The display name of the mod, for use in the Mods listing screen
| The description of the mod, for use in the Mods listing screen. It's recommended to use a multiline string (surrounded by <code>'''<code>)
−
| <code>"Adds things and stuff. "</code>
−
|-
−
| <code>logoFile</code> || string || ''nothing''
−
| The path of the logo file image, for use in the Mods listing screen. The image must be in the root of the jar file, not in any subfolder thereof (e.g. the file is directly in <code>src/main/resources</code>)
| The update JSON URL, used by the [Update_Checker update checker]. <inline alert> This should never be a blank string, as that will cause an error. </inline>
| A URL, displayed on the Mods listing screen. Can be any string.
−
| <code>http://example.com/</code>
−
|}
−
−
=== Dependency Configurations ===
−
−
Mods can define dependencies for their mods, which are checked by Forge before loading mods. This is used for e.g. ensuring your mod loads after another, or hard-crashing if a mod with a specified version does not exist.
−
−
These dependency configurations, like the mod properties, are defined by a new section starting with <code>[[dependencies.<modid>]]</code>, with <code><modid></code> being the mod id that has this dependency. All properties from that line until the next header will become the properties of that dependency configuration.
| The acceptable version range of the dependency, expressed as a [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven version spec]. An empty string is an unbounded version range, which matches any version.
| Defines if the mod must load before or after this dependency. The valid values are <code>BEFORE</code> (must load before), <code>AFTER</code> (must load after), and <code>NONE</code> (does not care about order).
| Defines if this dependency needs only to be met on a specfic [[Sides|physical side]]. The valid values are <code>CLIENT</code> (present on the client), <code>SERVER</code> (present on the dedicated server), and <code>BOTH</code> (present on both sides).
−
| <code>"CLIENT"</code>
−
|}
−
−
{{Colored box|title=Important|content=When specifying dependency ordering between two or more mods, beware of cyclic order!: ex. if mod A must load before mod B, and mod B must load before mod A, the game will crash because of the circular cycle.}}
[[Category:Getting Started]]
[[Category:Getting Started]]
+
[[Category:Beginner Topics]]
Latest revision as of 21:46, 2 September 2021
The structure of your mod is important in keeping your mod organized, for both your benefit and the benefit of anyone who wishes to make a feature or an
add-on for your mod. A disorganized mod structure may cause headaches when someone is trying to update it to a higher version, especially if they cannot modify the package structure, due to i.e. licensing.
Note that this page is only a recommendation for your mod structure; you may structure your mod in any way you see fit.
Pick a unique package name for your mod. If you own a URL associated with your project, you can use it as your top level package. For example if you own "example.com", you may use com.example as your top level package.
The next level package is usually your mod's ID: if your mod ID is examplemod, your mod's package will be com.example.examplemod.
Important
Do not use a domain for your top level package if you do not own that domain. It is perfectly acceptable to have your top level package be named with anything, such as your name/nickname, or the name of the mod (me.exampledude.examplemod).
Using Subpackages
Rather than clutter up a single class and package with everything, it is recommended you break your mod into subpackages. Below are a few possible methods for laying out your folder structure though you may as well come up with your own layout too.
Group by Logic: One possible strategy is to make subpackages for logical units of your mod. For example, if you have a block called Super Furnace you would put its block, its block entity and its item all under feature/superfurnace.
Group by Function: Another common strategy is to make subpackages for grouping classes that have a common purpose. For example, your blocks classes can be under blocks, your entities classes can be under entities, your helper utilities can be under helpers, etc.
No matter how your final structure looks like it is highly recommended to add a client subpackage under your main package. This helps to isolate your client-only code from the rest, such as your Screens and renderers.
By keeping your code in clean subpackages, you can grow your mod much more organically.
If you are unsure on how exactly you want to structure your mod it can be a good idea to look at the source of others to see how they did it.
Class Naming Schemes
A common class naming scheme allows easier deciphering of the purpose of the class, and makes it easier for someone developing for your mod to find specific classes.
The usual style is to use suffixes for your classes, for example:
An Item called PowerRing would have a class name of PowerRingItem.
A Block called NotDirt would have a class name of NotDirtBlock.
A BlockEntity for a block called SuperChewer would have a class name of SuperChewerBlockEntity.
The Mod File
The main mod class - the class that is annotated with @Mod - is usually put into the main package of your mod, and not placed into a subpackage. This allows an easier time to access this, as your main mod class is the entrypoint of your mod.
The @Mod annotation indicates to the mod loader that this class is the entry point of your mod. Each @Mod annotation and their value should be paired with a mod id entry in your mods.toml file.
mods.toml file
The mods.toml file is read by the mod loader to determine what mods are packaged into your JAR file, and what information to display to the user in the Mods listing screen (accessible by pressing the "Mods" button on the main menu of the game).
More information about the structure of this file and the possible configuration options available to you can be found on the dedicated page.