DigOrDie.DODModAPI 1.0.2

DODModAPI

Core API plugin used by the other plugins.

DODModAPI does not add gameplay content by itself. Instead, it provides a standardized modding layer built on top of Dig or Die code, allowing other plugins to add custom content in Dig or Die without manually patching every game system. It solves hard problems in Dig or Die modding, making modifying the game much easier.

If you have a plugin that uses DODModAPI while not having DODModAPI plugin itself installed, you will see a similar error message in the console or in the log file (DigOrDie_Data/output_log.txt):

[Error  :   BepInEx] Could not load [<NAME> <VERSION>] because it has missing dependencies: dodmodapi

Features

DODModAPI provides registration systems and helpers for:

• Custom items (ItemManager)
• Custom recipes and recipe groups (ItemManager)
• Custom units (UnitManager)
• Custom events (EventManager)
• Custom game modes (ModeManager)
• Custom save data stored inside game save files (SaveManager)
• Custom network messages for multiplayer synchronization (NetworkManager)
• Custom UI screens (ScreenManager)
• Custom chat commands (CommandManager)
• Chat message preprocessors (CommandManager)
• Custom textures, sprites, tiles, surfaces, and background surfaces (TextureManager, SurfaceManager)
• Improved Harmony IL patching through CodeCursor
• Useful utility functions (Misc)

Provided managers

Helper utilities

Basic usage

Other plugins should reference DODModAPI and declare it as a dependency:

using BepInEx;

[BepInPlugin("my-mod", "My Mod", "1.0.0")]
// BepInDependency is required
[BepInDependency(DODModAPI.DODModAPIPlugin.GUID)]
public class MyMod : BaseUnityPlugin {
    private void Awake() {
        // register embedded textures generated by AssetPacker or loaded manually.
        DODModAPI.TextureManager.RegisterTexture(MyAssets.TileSpritesheetResource);

        // register custom content.
        DODModAPI.ItemManager.RegisterAllItems(typeof(MyItems));
        DODModAPI.UnitManager.RegisterAllUnits(typeof(MyUnits));

        // register a custom command.
        DODModAPI.CommandManager.Register("/my-command", new() {
            Local = true,
            DisableAchievements = true,
            TabCompleter = argIdx => argIdx == 0 ? ["hello"] : null,
        }, args => {
            string subCommand = args.ArgString("subcommand");
            args.ArgNone();

            if (subCommand == "hello") {
                DODModAPI.Misc.SendChatMessageLocal("Hello from my mod!");
            } else {
                throw new DODModAPI.CommandException("Unknown subcommand", args.Index);
            }
        });
    }
}

Registration rules

Most DODModAPI managers lock registration after the relevant game initialization phase has completed. For example, ItemManager locks item registration after SItems.OnInit has been called.

If registration happens too late, a LateRegistrationException is thrown.

For example:

private void Awake() {
    // Correct: register during plugin initialization.
    DODModAPI.ItemManager.RegisterItem(MyItems.exampleWall);
}

AssetPacker

DODModAPI also includes the optional DigOrDie.DODModAPI.AssetPacker MSBuild task that is available on NuGet.

It can generate C# bindings and optimized sprite atlases from a simple asset configuration file. Instead of manually packing sprites and writing boilerplate code, you describe your assets in a configuration file and AssetPacker generates the required class at build time.

Add package reference to AssetPacker with:

<ItemGroup>
  <PackageReference Include="DigOrDie.DODModAPI.AssetPacker" Version="..." />
</ItemGroup>

or with command:

dotnet add package DigOrDie.DODModAPI.AssetPacker --version ...

Create a configuration file (like assets.cfg, sprites.cfg, etc.):

TILE exampleWall example_wall.png
TILE exampleDevice tile=example_device.png icon=example_device_icon.png

SPRITE exampleBullet example_bullet.png

SURFACE exampleSurface material=example_surface_mat.png top=example_surface_top.png

UNIT exampleUnit stand=example_unit_stand1.png run=example_unit_run1.png+example_unit_run2.png

Then register it in your .csproj:

<ItemGroup>
    <ModAtlas Include="assets.cfg" AtlasName="ExampleAssets" />
</ItemGroup>

Now, all assets you defined in the configuration file will be available in ExampleAssets class, directly in the C# code. Don't forget to register the corresponding texture resource names in the Awake() with DODModAPI.TextureManager.RegisterTexture()!

See AssetPacker/README.md for the full documentation.

Example Mod

The repository contains an example plugin in dodmodapi/example-mod.

It demonstrates how to use TextureManager, ItemManager, UnitManager, EventManager, ModeManager, SaveManager, NetworkManager, ScreenManager, CommandManager, CodeCursor and AssetPacker-generated textures

Configuration

This plugin does not have any configuration options.