Getting started

← Back to index

This walks through adding a help page to a mod from nothing. It assumes you already have a working Big Ambitions mod built with the official modding SDK.

---

1. Get the library

Either:

• Subscribe to the Steam Workshop item, or
• Download BAHelpApi.dll from Releases and place it at:

%LocalAppData%Low\Hovgaard Games\Big Ambitions\ModsLocal\BAHelpApi\BAHelpApi.dll

The library is a mod in its own right. It has exactly one DLL at the top level of its folder, which is what the game’s mod discovery requires.

To build it into your Unity SDK project instead, copy src/BAHelpApi/ into Assets/Mods/BAHelpApi/ and build it as a normal mod.

---

2. Declare the dependency

Add BAHelpApi to your mod assembly’s references:

{
  "name": "MyMod",
  "rootNamespace": "MyMod",
  "references": ["BAHelpApi"],
  "overrideReferences": true,
  "precompiledReferences": [
    "BigAmbitions.dll",
    "BigAmbitions.Items.dll",
    "BigAmbitions.ModAPI.dll"
    // ... the rest of the game DLLs your mod uses
  ],
  "autoReferenced": false,
  "defineConstraints": ["BA_GAME_DLLS_IMPORTED"]
}

That reference is the entire dependency declaration. Big Ambitions maps each loaded assembly back to the mod that owns it, so when it sees your mod referencing BAHelpApi it will:

• defer loading your mod until BAHelpApi has loaded,
• refuse to load your mod if BAHelpApi failed, with Dependency mod 'BAHelpApi' failed to load,
• reject the pair if their major versions disagree.

There is no manifest field to fill in.

One thing to avoid

Do not copy BAHelpApi.dll into your mod’s own Dependencies/ folder. The game loads DLLs from there too, so you would end up with two BAHelpApi assemblies loaded from different paths. Each has its own static registration list, only one drives the help window, and the other mod’s pages silently never appear. Depend on the Workshop item instead.

---

3. Register a page

using System.Threading.Tasks;
using BAModAPI;
using BigAmbitions.Modding.Help;

[assembly: RegisterModClass(typeof(MyMod.MyMod))]

namespace MyMod
{
    [ModEntryOnInitializationLoad]
    public class MyMod : IModBigAmbitions
    {
        private const string OwnerId = "MyMod";

        public string[] RelativeAssetBundlePaths => System.Array.Empty<string>();

        public Task OnLoadAsync(ModContext context)
        {
            HelpApi.RegisterPage(OwnerId, HelpCategories.Furniture,
                slug: "furniture-mymodwidget",
                pageKeyPrefix: "mymod:itemname_widget");

            return Task.CompletedTask;
        }

        public Task OnUnloadAsync()
        {
            HelpApi.UnregisterOwner(OwnerId);
            return Task.CompletedTask;
        }
    }
}

Registering early is fine. The help window does not exist yet at mod-load time — the library waits for it, forces the game to parse its help structure, and merges your pages in before the player can open the window.

The four arguments

Argument	Meaning
ownerId	Your mod’s id. Scopes the registration so UnregisterOwner removes exactly yours.
categoryKey	Which category to file under. Use a HelpCategories constant.
slug	Stable, unique page id. Other pages link to this, so treat it as public API.
pageKeyPrefix	Localisation key prefix for the title and body.

---

4. Write the text

Page text lives in your mod’s locale files, not in this library. Add to Locales/en.json:

{
  "mymod:itemname_widget": "Widget",
  "help_mymod:itemname_widget_content": "**Widget** does something useful.\n\n**Footprint:** 1.0m x 0.5m\n\nSold at [Ika Bohag](address:50 4s)."
}

Two keys per page:

• <pageKeyPrefix> — the title in the sidebar
• help_<pageKeyPrefix>_content — the body, as Markdown

Reusing an existing key as the prefix, as above, means the page title is the item’s own localised name and you do not maintain it twice.

See Localisation for Markdown support and linking.

---

5. Check it worked

Launch the game and look in Player.log:

[Mod:BAHelpApi] Help API ready (help system reachable: True).
[HelpApi] Applied 1 mod help page(s).

Then open Help and search for your page.

If something is off, the log usually says exactly what — see Troubleshooting.

---

Registering several pages

HelpApi.RegisterPages(OwnerId, HelpCategories.Furniture, new[]
{
    new HelpPage("furniture-mymodwidget", "mymod:itemname_widget"),
    new HelpPage("furniture-mymodgadget", "mymod:itemname_gadget"),
});

---

← Back to index · API reference →