Structuring Your Mod
Let us look at how to organize your mod into different files and what those files should do.
Packaging
Pick a unique package name. 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.
Important
If you do not own a domain, do not use it for your top level package. You can use your email, a subdomain of where you host a website, or your name/username as long as it can be unique.
After the top level package (if you have one), you append a unique name for your mod, such as examplemod
. In our case it will end up as com.example.examplemod
.
The mods.toml
file
Important
The 1.16 release brought with it a substantial change: the license field in the mods.toml is now required. If it is not provided, this is an error state. See your choices at https://choosealicense.com/
This file defines the metadata of your mod. Its information may be viewed by users from the main screen of the game through the ‘Mods’ button. A single info file can describe several mods.
The mods.toml
file is formatted as TOML, the example mods.toml
file in the MDK provides comments explaining the contents of the file. It should be stored as src/main/resources/META-INF/mods.toml
. A basic mods.toml
, describing one mod, may look like this:
# The name of the mod loader type to load - for regular FML @Mod mods it should be javafml
modLoader="javafml"
# A version range to match for said mod loader - for regular FML @Mod it will be the forge version
# Forge for 1.16.5 is version 36
loaderVersion="[36,)"
# The license for your mod. This is mandatory and allows for easier comprehension of your redistributive properties.
# Review your options at https://choosealicense.com/. All rights reserved is the default copyright stance, and is thus the default here.
license="All Rights Reserved"
# A URL to refer people to when problems occur with this mod
issueTrackerURL="github.com/MinecraftForge/MinecraftForge/issues"
# If the mods defined in this file should show as separate resource packs
showAsResourcePack=false
[[mods]]
modId="examplemod"
version="1.0.0.0"
displayName="Example Mod"
updateJSONURL="minecraftforge.net/versions.json"
displayURL="minecraftforge.net"
logoFile="logo.png"
credits="I'd like to thank my mother and father."
authors="Author"
description='''
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="[36,)"
ordering="NONE"
side="BOTH"
[[dependencies.examplemod]]
modId="minecraft"
mandatory=true
versionRange="[1.16.5,1.17)"
ordering="NONE"
side="BOTH"
If any string is specified as ${file.jarVersion}
, Forge will replace the string with the Implementation Version specified in your jar manifest at runtime. Since the user development environment has no jar manifest to pull from, it will be NONE
instead. As such, it is usually recommended to leave the version
field alone. Here is a table of attributes that may be given to a mod, where mandatory
means there is no default and the absence of the property causes an error.
Property | Type | Default | Description |
---|---|---|---|
modid | string | mandatory | The modid this file is linked to. |
version | string | mandatory | The version of the mod. It should be just numbers separated by dots, ideally conforming to Forge’s Semantic Versioning structure. |
displayName | string | mandatory | The user-friendly name of this mod. |
updateJSONURL | string | "" |
The URL to a version JSON. |
displayURL | string | "" |
A link to the mod’s homepage. |
logoFile | string | "" |
The filename of the mod’s logo. It must be placed in the root resource folder, not in a subfolder. |
credits | string | "" |
A string that contains any acknowledgements you want to mention. |
authors | string | "" |
The authors of this mod. |
description | string | mandatory | A description of this mod. |
dependencies | [list] | [] |
A list of dependencies of this mod. |
* All version ranges use the Maven Version Range Specification.
The Mod File
Generally, we will start with a file named after your mod and put into your package. This is the entry point to your mod and will contain some special indicators marking it as such.
What is @Mod
?
This is an annotation indicating to the Forge Mod Loader that the class is a Mod entry point. The @Mod
annotation’s value should match a mod id in the src/main/resources/META-INF/mods.toml
file.
Keeping Your Code Clean Using Sub-packages
Rather than clutter up a single class and package with everything, it is recommended that you break your mod into subpackages.
A common subpackage strategy has packages for common
and client
code, which is code that can be run on both server/client and only client, respectively. Inside the common
package would go things like Items, Blocks, and Tile Entities (which can each, in turn, be another subpackage). Things like Screens and Renderers would go inside the client
package.
Note
This package style is only a suggestion, though it is a commonly used style. Feel free to use your own packaging system.
By keeping your code in clean subpackages, you can grow your mod much more organically.
Class Naming Schemes
A common class naming scheme allows easier deciphering of what a class is, and it also makes it easier for someone developing with your mod to find things.
For Example:
- An
Item
calledPowerRing
would be in anitem
package, with a class name ofPowerRingItem
. - A
Block
calledNotDirt
would be in ablock
package, with a class name ofNotDirtBlock
. - Finally, a
TileEntity
for a block calledSuperChewer
would be atile
ortileentity
package, with a class name ofSuperChewerTile
.
Appending your class names with what kind of object they are makes it easier to figure out what a class is or guess the class for an object.