NeoModLoader

https://worldboxopenmods.gitbook.io/mod-tutorial-en
Admin
NeoModLoader is a mod loader and modding framework for WorldBox that enables players to load and...
Tokens:7,869
Snippets:131
Trust Score:9.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### JSON locale file format

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/multilingual.md

Example structure for a JSON localization file.

```jsonc
// cz.json
{
    "Humans": "人类",
    "Orcs": "兽人"
}
```

--------------------------------

### Perform a documentation query via HTTP GET

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/llms.txt

Use this request to ask a specific question about the documentation, optionally providing a goal to refine the context of the answer.

```http
GET https://worldboxopenmods.gitbook.io/mod-tutorial-en/make-mod/start.md?ask=<question>&goal=<end_goal>
```

--------------------------------

### GET /make-mod/start.md

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/llms.txt

Performs a query against the documentation index to retrieve an answer based on a specific question and optional goal.

```APIDOC
## GET /make-mod/start.md

### Description
Perform an HTTP GET request on the documentation index with the `ask` parameter, and the optional `goal` parameter to retrieve a direct answer and relevant excerpts.

### Method
GET

### Endpoint
https://worldboxopenmods.gitbook.io/mod-tutorial-en/make-mod/start.md

### Parameters
#### Query Parameters
- **ask** (string) - Required - The immediate question to ask, written in natural language.
- **goal** (string) - Optional - Describes the broader end goal to help tailor the answer.
```

--------------------------------

### Define Mod Configuration

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/make-mod/createmod.md

Create a mod.json file to define metadata such as the mod name, author, and unique GUID.

```json
// mod.json
{
    "name": "Change me to Mod name",
    "author": "Change me to Author name",
    "version": "Change me to Mod version",
    "description": "Change me to Mod description",
    "GUID": "Change me to Global Unique ID of your mod"
}
```

--------------------------------

### Define a ModConfigItem in JSON

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/modconfiguration.md

Example of a configuration item definition within the default_config.json file using the SLIDER type.

```json
{
    "Id": "Example",
    "Type": "SLIDER",
    "FloatVal": 0.5,
    "Callback": "ExampleType:ExampleCallbackMethod"
}
```

--------------------------------

### CSV locale file format

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/multilingual.md

Example structure for a CSV localization file.

```csv
key,cz,en,ch
Humans,人类,Humans,人類
Orcs,兽人,Orcs,獸人
```

--------------------------------

### Get a list of sprites

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/resources/overview.md

Retrieve a list of sprites from a path, utilizing cached Resources.LoadAll functionality.

```csharp
SpriteTextureLoader.getSpriteList("effects/projectiles/arrow")
```

--------------------------------

### Get a single sprite

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/resources/overview.md

Retrieve a single sprite using the SpriteTextureLoader utility.

```csharp
SpriteTextureLoader.getSprite("ui/icons/iconOption")
```

--------------------------------

### Implement Main Mod Class

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/make-mod/createmod.md

Create a Main.cs file implementing the IMod interface to handle mod initialization and lifecycle events.

```csharp
// Main.cs
using UnityEngine;
using NeoModLoader.api;
using NeoModLoader.services;
namespace CHANGEME_TO_YOUR_NAMESPACE;

public class ModClass : MonoBehaviour, IMod
{
    private ModDeclare _declare;
    private GameObject _gameObject;
    
    public ModDeclare GetDeclaration()
    {
        return _declare;
    }
    public GameObject GetGameObject()
    {
        return _gameObject;
    }
    public string GetUrl()
    {
        return "URL of your mod's website or item page on workshop";
    }
    public void OnLoad(ModDeclare pModDecl, GameObject pGameObject)
    {
        _declare = pModDecl;
        _gameObject = pGameObject;
        // Initialize your mod.
        // Methods are called in the order: OnLoad -> Awake -> OnEnable -> Start -> Update
        LogService.LogInfo($"[{pModDecl.Name}]: Hello World!");
    }
}
```

--------------------------------

### Implement IConfigurable Interface

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/modinterface.md

Enables a configuration window entry for the mod.

```csharp
/// <summary>
/// The methods will be called later than OnLoad, you need to return an instance ModConfig, you can create one temporarily or read from file. When configuration window is closed, all changes will be applied to the instance you created.
/// </summary>
public ModConfig GetConfig();
```

--------------------------------

### Implement a Configuration Callback Method

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/modconfiguration.md

Required static method implementation for handling configuration changes, matching the callback defined in the JSON configuration.

```csharp
namespace ANYNAMESPACE;

class ExampleType
{
    void ExampleCallbackMethod(float pUpdatedValue)
    {
        // Your callback method's code
    }
}
```

--------------------------------

### LM.Get

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/multilingual.md

Retrieves the localized text for a given key based on the current game language.

```APIDOC
## LM.Get(key)

### Description
Retrieves the localized string associated with the provided key for the currently active language.

### Parameters
- **key** (string) - Required - The localization key to look up.
```

--------------------------------

### Implement ILocalizable Interface

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/modinterface.md

Allows NML to load locale files automatically before the mod loads.

```csharp
/// <returns>The folder of locale files to load. It is "Locales" in BasicMod</returns>
public string GetLocaleFilesDirectory(ModDeclare pModDeclare);
```

--------------------------------

### Verify Mod Load Output

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/make-mod/createmod.md

Expected log output in the console when the mod loads successfully.

```log
[NML]: [Mod Name]: Hello World!
```

--------------------------------

### Implement IMod Interface

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/modinterface.md

Required for the mod's main class, which must also inherit from MonoBehaviour.

```csharp
/// <summary>
/// Get declaration of your mod
/// </summary>
public ModDeclare GetDeclaration();
/// <summary>
/// Get gameObject of your mod
/// </summary>
public GameObject GetGameObject();
/// <summary>
/// Get repository url of your mod
/// </summary>
public string GetUrl();
/// <summary>
/// This will be called when mod is loaded, even earlier than Awake, Start, OnEnable.
/// You can initialize your mod here.
/// </summary>
/// <param name="pModDecl">Declaration of the mod(It is initialized by NML already, record it by yourself)</param>
/// <param name="pGameObject">Instance of the mod(It is nearly a useless parameter for most mods)</param>
public void OnLoad(ModDeclare pModDecl, GameObject pGameObject);
```

--------------------------------

### IConfigurable Interface

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/modinterface.md

Interface that enables a configuration window entry for the mod.

```APIDOC
## IConfigurable

### Description
Implementing this interface allows users to access a configuration window for the mod.

### Methods
- **GetConfig()** (ModConfig) - Returns an instance of ModConfig. Changes made in the configuration window are applied to this instance.
```

--------------------------------

### IReloadable Interface

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/modinterface.md

Interface for enabling manual mod reloading during development.

```APIDOC
## IReloadable

### Description
Provides a reload button in the interface when `Config.isEditor` is set to true.

### Methods
- **Reload()** (void) - Called after the mod is recompiled and methods are hotfixed to perform manual state reloading.
```

--------------------------------

### Implement Soft Dependency with Preprocessor Macros

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/moddependency.md

Use #if macros to conditionally include namespaces and logic based on the presence of a soft dependency's mod ID.

```csharp
using System.IO;
// Uses macro to wrap all soft dependencies' code. "一米_中文名" is the ID of the soft dependency. Chinese_Name is a namespace provided by the mod. As shown below.
#if 一米_中文名
using Chinese_Name;
#endif

namespace ExampleMod.Content;

internal static class ExampleNameGenerators
{
    public static void init()
    {
        // If Chinese Name mod is compiled successfully, initialize Chinese name generators. Otherwise, initialize vanilla name generators
#if 一米_中文名
        init_chinese_name_generators();
#else
        init_vanilla_name_generators();
#endif
    }
    private static void init_chinese_name_generators()
    {
        string mod_folder = ExampleModMain.Instance.GetDeclaration().FolderPath;
        // Because the classes and methods are provided by ChineseName, you should wrap them with macro
#if 一米_中文名
        WordLibraryManager.SubmitDirectoryToLoad(Path.Combine(mod_folder,
            "additional_resources/word_libraries"));
        CN_NameGeneratorLibrary.SubmitDirectoryToLoad(Path.Combine(mod_folder,
            "additional_resources/name_generators"));
#endif
    }
    private static void init_vanilla_name_generators()
    {
        // No content yet
    }
}
```

--------------------------------

### Implement IReloadable Interface

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/modinterface.md

Provides a reload button in the UI when Config.isEditor is set to true.

```csharp
/// <summary>
/// Mod reload order: Click Reload Button, recompile mod, hotfix methods, call Reload method
/// Because of limit of unity 2020, you need to control what to reload manually.
/// </summary>
public void Reload();
```

--------------------------------

### Add localization at runtime

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/multilingual.md

Updates or adds localization keys dynamically while the game is running.

```csharp
LM.AddToCurrentLocale("Humans", "New Humans Name Locale");
```

```csharp
LM.Add("en", "Humans", "New Humans Name Locale");
```

--------------------------------

### LM.ApplyLocale

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/multilingual.md

Applies localization changes and optionally updates UI text.

```APIDOC
## LM.ApplyLocale(language?, updateText?)

### Description
Applies all pending localization changes. If a language is specified, it switches to that language.

### Parameters
- **language** (string) - Optional - The language code to apply.
- **updateText** (boolean) - Optional - Whether to update all existing LocalizedText elements (defaults to True).
```

--------------------------------

### LM.Add

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/multilingual.md

Adds a localization entry for a specific language at runtime.

```APIDOC
## LM.Add(language, key, value)

### Description
Adds a localization key-value pair for a specific language code.

### Parameters
- **language** (string) - Required - The language code (e.g., 'en').
- **key** (string) - Required - The localization key.
- **value** (string) - Required - The localized text string.
```

--------------------------------

### Retrieve localized text

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/multilingual.md

Fetches the localized string for a specific key based on the current game language.

```csharp
LM.Get("Humans"); // It returns "人类" if your game language is Chinese
```

--------------------------------

### Clone Mod Template

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/make-mod/createmod.md

Use this command to clone the official mod template repository into your Mods directory.

```shell
git clone git@github.com:WorldBoxOpenMods/ModTemplate.git <ModName>
```

--------------------------------

### Load locale files

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/multilingual.md

Methods for loading localization data from CSV or JSON files.

```csharp
LM.LoadLocales("path-to-csv-file");
```

```csharp
LM.LoadLocale("path-to-mod-folder/Locales/en.json"); // Load English locale file
LM.LoadLocale("path-to-mod-folder/Locales/cz.json"); // Load Simplified Chinese locale file
```

--------------------------------

### LM.LoadLocale

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/multilingual.md

Loads localization data from a JSON file.

```APIDOC
## LM.LoadLocale(path)

### Description
Loads locale definitions from a .json file. The filename must correspond to the target language short name (e.g., en.json).

### Parameters
- **path** (string) - Required - The file system path to the .json locale file.
```

--------------------------------

### ILocalizable Interface

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/modinterface.md

Interface for automatic localization support.

```APIDOC
## ILocalizable

### Description
Allows NML to load locale files for the mod before the OnLoad method is called.

### Methods
- **GetLocaleFilesDirectory(ModDeclare pModDeclare)** (string) - Returns the directory path containing the locale files.
```

--------------------------------

### IMod Interface

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/modinterface.md

The primary interface required for a mod's main class. It must be implemented by a class inheriting from MonoBehaviour.

```APIDOC
## IMod

### Description
Required interface for the mod main class. The class must also inherit from `MonoBehaviour`.

### Methods
- **GetDeclaration()** (ModDeclare) - Returns the declaration of the mod.
- **GetGameObject()** (GameObject) - Returns the GameObject of the mod.
- **GetUrl()** (string) - Returns the repository URL of the mod.
- **OnLoad(ModDeclare pModDecl, GameObject pGameObject)** (void) - Called when the mod is loaded, before Awake, Start, or OnEnable.
```

--------------------------------

### LM.LoadLocales

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/multilingual.md

Loads localization data from a CSV file.

```APIDOC
## LM.LoadLocales(path)

### Description
Loads locale definitions from a .csv file.

### Parameters
- **path** (string) - Required - The file system path to the .csv locale file.
```

--------------------------------

### Apply Hotfixable to Lambda

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/other-techs/modreload.md

Demonstrates applying the Hotfixable attribute to a lambda expression for runtime modification.

```csharp
trait.action_special_effect = [Hotfixable] (pTarget, pTile) =>
{
    LogService.LogInfo("Before hotfixed trait action");
}
```

--------------------------------

### BepInEx Mod Directory Structure

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/make-mod/bepinex.md

The required file hierarchy for a BepInEx mod, including the main DLL and optional assets.

```text
BepInEx
    |---plugins
    |       |---Mod folder
    |       |       |---The only main DLL file
    |       |       |---icon.png(as mod icon)
    |       |       |---other not-DLL files
    |       |       |---other folders
```

--------------------------------

### Apply locale changes

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/multilingual.md

Refreshes the UI or internal state with the latest localization changes.

```csharp
LM.ApplyLocale(); // Apply changes of current language and update all LocalizedText
LM.ApplyLocale(False); // Apply changes of current language but not update all LocalizedText
LM.ApplyLocale("cz"); // Apply changes of Simplified Chinese and update all LocalizedText
LM.ApplyLocale("cz", False); // Apply changes of Simplified Chinese but not update all LocalizedText
```

--------------------------------

### Define SpritesSettings structure

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/resources/overview.md

The class structure used for deserializing sprites.json configuration files.

```csharp
class SpritesSettings
{
    public Setting Default;
    public List<Setting> Specific;
}
class Setting
{ 
    public float BorderB = 0.0f; // border bottom
    public float BorderL = 0.0f; // border left
    public float BorderR = 0.0f; // border right
    public float BorderT = 0.0f; // border top
    public string Path = "\\";   // corresponded file path
    public float PivotX = 0.5f;  // pivot x, default to be center
    public float PivotY = 0.0f;  // pivot y, default to be center
    public float PixelsPerUnit = 1f; // if you dont know what it is, keep it 1
    public float RectX = 0.0f;   // keep it 0 now
    public float RectY = 0.0f;   // keep it 0 now
}
```

--------------------------------

### Define Mod Declaration Structure

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/make-mod/commonfeatures.md

The ModDeclare class defines the metadata structure for a mod, including identity, dependencies, and file paths.

```csharp
// Some fields are not shown here, see 'Basic Concept/Mod Declaration' for details
public class ModDeclare
{
    // Mod's name
    public string Name { get; private set; }
    // Mod's ID(It should be unique)
    public string UID { get; private set; }
    // Mod's author
    public string Author { get; private set; }
    // Mod's version
    public string Version { get; private set; }
    // Mod's simple description
    public string Description { get; private set; }
    // URL to repository of the mod
    public string RepoUrl { get; private set; }
    // Necessary(hard) dependencies
    public string[] Dependencies { get; private set; }
    // Optional(soft) dependencies
    public string[] OptionalDependencies { get; private set; }
    // Path to the folder of mod.json
    public string FolderPath { get; private set; };
    // Path to mod's icon file(Related to the folder of mod.json)
    public string IconPath { get; private set; }
}
```

--------------------------------

### LM.AddToCurrentLocale

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/multilingual.md

Adds or updates a localization entry for the current language at runtime.

```APIDOC
## LM.AddToCurrentLocale(key, value)

### Description
Adds a localization key-value pair to the currently active language immediately.

### Parameters
- **key** (string) - Required - The localization key.
- **value** (string) - Required - The localized text string.
```

--------------------------------

### ModDeclare Class Definition

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/moddeclaration.md

The initial class structure used for deserializing the mod.json file.

```csharp
public class ModDeclare
{
    public string name;                      // Name
    public string author;                    // Author
    public string version;                   // Version
    public string description;               // Simple description
    public string iconPath;                  // Icon path(related to folder of mod.json)
    public string GUID;                      // GUID of mod
    public string RepoUrl;                   // Url to repository
    public string[] Dependencies;            // Hard dependencies
    public string[] OptionalDependencies;    // Soft dependencies
    public string[] IncompatibleWith;        // Incompatible mods(Not implement yet)
}
```

--------------------------------

### ModDeclare Usage Class

Source: https://worldboxopenmods.gitbook.io/mod-tutorial-en/basic-concepts/moddeclaration.md

The processed ModDeclare class available during the OnLoad event, utilizing JsonProperty attributes.

```csharp
public class ModDeclare
{
    // Mod name
    [JsonProperty("name")] 
    public string Name { get; private set; }
    // Mod ID
    public string UID { get; private set; }
    // Author
    [JsonProperty("author")] 
    public string Author { get; private set; }
    // Version
    [JsonProperty("version")] 
    public string Version { get; private set; }
    // Simple description
    [JsonProperty("description")] 
    public string Description { get; private set; }
    // Url to repository
    [JsonProperty("RepoUrl")] 
    public string RepoUrl { get; private set; }
    // Array of hard dependencies' ID
    [JsonProperty("Dependencies")] 
    public string[] Dependencies { get; private set; }
    // Array of soft dependencies' ID
    [JsonProperty("OptionalDependencies")] 
    public string[] OptionalDependencies { get; private set; }
    // Array of incompatible mods' ID
    [JsonProperty("IncompatibleWith")] 
    public string[] IncompatibleWith { get; private set; }
    // Path of the folder of mod.json
    public string FolderPath { get; private set; } = null!;
    // Path to mod's icon file(related to FolderPath)
    [JsonProperty("iconPath")] 
    public string IconPath { get; private set; }
}
```
Tokens:
Raw