Modding/draft

What this guide covers

This is a beginner-focused guide to making a Necesse mod, based on what the game’s mod loader requires for a mod to be considered valid. It focuses on getting a mod to load successfully

Beginner Guide: Making a Necesse Mod

What the game considers a “valid” mod

To be loaded by the game, your mod must meet these requirements:

1. It must be a .jar file.
2. The jar must contain a mod.info file at the root of the jar.
3. The mod.info must include required fields (see below).
4. The jar must contain exactly one mod entry class annotated with @ModEntry.
5. The mod entry class must have a public no-argument constructor.
If any of these are missing, the loader will reject the mod or log an error.

Step 1: Pick a unique Java package

Before writing any code, choose a unique Java package name for your mod. Avoid using:
• examplemod (the loader warns about this)
• necesse (reserved for the base game)
• the default package (no package)
Use something unique, for example:
• com.yourname.yourmod

If your mod contains classes in the examplemod package, the loader will log a warning. In dev mod loading it specifically warns that you must move packages to upload, and in normal loading it warns that this will likely not be allowed in future versions.

Step 2: Create the mod.info file

Create a plain text file named mod.info. This file must be included in the jar at the root (top level).

Required fields

The loader requires these fields to exist and not be empty:

• id
• name
• version
• gameVersion
• author
• description

Optional fields

These are supported by the loader and are commonly included:

• clientside (boolean)
• dependencies
• optionalDependencies

Example mod.info

id = "mytestmod"
name = "My Test Mod"
version = "1.0"
gameVersion = "1.1.1"
author = "YourName"
description = "A beginner test mod."
clientside = false
dependencies = []
optionalDependencies = []

The loader validates the format of id, name, and version. If you use strange characters or invalid version formatting, the mod can be rejected. Keep them simple (letters/numbers, dots, dashes).

Step 3: Create your Mod Entry class

A mod must have exactly one “entry point” class marked with the @ModEntry annotation. Rules: If the loader finds no @ModEntry class, the mod will not load. If the loader finds more than one @ModEntry class, it errors. The class must have a public no-argument constructor because the loader creates it at runtime

Minimal example

import necesse.engine.modLoader.annotations.ModEntry;

@ModEntry
public class MyTestMod {
    public MyTestMod() {
        // Public no-arg constructor required by the loader
    }
}

Step 4: Build the jar with the correct contents

When you build your mod, the final .jar must contain:

/mod.info

Your compiled class files, including the entry class

A simple “jar contents” checklist:

/mod.info /com/yourname/mytestmod/MyTestMod.class

Optional: Mod lifecycle methods

The loader can call lifecycle methods on your mod entry class if they exist. If they do not exist, the loader simply skips them.

Common lifecycle method names include:

preInit()

init()

initResources()

postInit()

initSettings() (special case: if present, it must return a ModSettings type)

dispose()

Troubleshooting

“Did not contain a mod.info file”

Your jar is missing mod.info, or it is not at the root of the jar.

Mod is ignored / not loaded

The file is not a .jar.

The jar does not contain a valid mod.info.

No @ModEntry class was found.

Error about @ModEntry being used multiple times

More than one class in your jar has @ModEntry. You must have exactly one.

Entry class fails to construct

Your entry class does not have a public no-argument constructor.

Warning about examplemod package

Some of your classes are in examplemod.*. Move them to a unique package.

Next steps

Once your mod loads successfully, you can start adding actual content and logic. A good first milestone is:

Confirm the game loads your jar with no errors.

Add one small change at a time (so you know what broke if something stops loading).