API reference

Namespace: BigAmbitions.Modding.Help · Assembly: BAHelpApi

HelpApi

Static entry point. Everything is safe to call at any time; calls made before the help window exists are applied as soon as it does.

RegisterPage

void RegisterPage(
    string ownerId,
    string categoryKey,
    string slug,
    string pageKeyPrefix,
    HelpPageOrder order = HelpPageOrder.Alphabetical)

Adds one page to the help window.

Parameter	Notes
`ownerId`	Your mod’s id. Scopes the registration for `UnregisterOwner`.
`categoryKey`	Localisation key of the category. Use a `HelpCategories` constant to file alongside base-game pages; any other value opens a new category, which you must localise.
`slug`	Unique, stable page id. Links target this. Prefix with your mod id to avoid collisions.
`pageKeyPrefix`	Localisation key prefix — see Localisation.
`order`	Position within the category. Default is alphabetical by localised title.

Throws ArgumentException if any argument is null or blank. A duplicate slug logs a warning and is ignored rather than throwing, so two mods racing for the same slug cannot break each other.

RegisterPages

void RegisterPages(
    string ownerId,
    string categoryKey,
    IEnumerable<HelpPage> pages,
    HelpPageOrder order = HelpPageOrder.Alphabetical)

Adds several pages to one category. Equivalent to calling RegisterPage for each.

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

UnregisterPage

void UnregisterPage(string ownerId, string slug)

Removes one page. Does nothing if the mod does not own that slug.

UnregisterOwner

void UnregisterOwner(string ownerId)

Removes every page registered by one mod. Call this from OnUnloadAsync so your pages disappear when your mod is disabled.

PageExists

bool PageExists(string slug)

Whether a slug resolves to a page the help window can open — base-game or registered through this library. Worth checking before emitting a link to a page you do not own, since a link to a missing slug renders as dead text.

Timing matters. Pages registered through this library are known immediately, but base-game pages are only readable once IsReady is true. Mods load at the main menu, before the help window exists, so calling this from OnLoadAsync reports false for every base-game slug. Do the check from PagesApplied instead.

HelpApi.PagesApplied += () =>
{
    if (HelpApi.PageExists("businesstypes-giftshop"))
        body += HelpLinks.Page("Gift Shop", "businesstypes-giftshop");
};

OpenPage

bool OpenPage(string slug)

Opens the help window at a page. Returns false if the window is unreachable or the slug does not resolve, in which case nothing happens. Useful for a “what’s this?” button.

PagesApplied

event Action PagesApplied

Raised after registered pages have been merged in and the sidebar rebuilt. Fires again each time the game reloads its help structure and pages are re-applied — for example after a language change.

A subscriber that throws is caught and logged; it will not stop other subscribers or the library.

Properties

Member	Type	Notes
`IsReady`	`bool`	Whether the help window exists and its pages are readable. False at mod-load time — see `PageExists`.
`IsSupported`	`bool`	False once the reflection this depends on has failed. Registering while false is a no-op, not an error, so checking is optional.
`Version`	`Version`	Library version.
`RegisteredPageCount`	`int`	Pages registered across all mods.
`RegisteredSlugs`	`IEnumerable<string>`	All slugs registered through the library.
`SlugsFor(ownerId)`	`IEnumerable<string>`	Slugs registered by one mod.

HelpPage

readonly struct HelpPage
{
    public HelpPage(string slug, string pageKeyPrefix);

    public readonly string Slug;
    public readonly string PageKeyPrefix;
}

A page to register. Used by RegisterPages.

HelpPageOrder

enum HelpPageOrder { Alphabetical = 0, Append = 1 }

Alphabetical (default) — insert by localised page title, matching how the base game orders its lists. Only your page is positioned; existing order is left untouched.
Append — add to the end of the category, preserving registration order. Use when your pages form a deliberate sequence, such as a tutorial.

HelpCategories

Constants for the fourteen categories the base game ships with. See Conventions for which to pick and how many pages each already holds.

HelpCategories.General              // "General"
HelpCategories.Finance              // "Finance"
HelpCategories.BuildingManagement   // "Building Management"
HelpCategories.BusinessTypes        // "Business Types"
HelpCategories.EmployeeTypes        // "Employee Types"
HelpCategories.EmployeeManagement   // "Employee Management"
HelpCategories.GoodsAndServices     // "Goods and Services"
HelpCategories.WholesaleAndImport   // "Wholesale / Import"
HelpCategories.Furniture            // "Furniture"
HelpCategories.Rivals               // "Rivals"
HelpCategories.FactoryRecipes       // "Factory Recipes"
HelpCategories.FactoryMachines      // "Factory Machines"
HelpCategories.FactoryIngredients   // "Factory Ingredients"
HelpCategories.Vehicles             // "Vehicles"

HelpSlugPrefixes

The slug prefixes the base game uses, so your pages follow the same convention.

HelpSlugPrefixes.BusinessType   // "businesstypes-"
HelpSlugPrefixes.Furniture      // "furniture-"
HelpSlugPrefixes.Product        // "products-"
HelpSlugPrefixes.Vehicle        // "vehicles-"

HelpLinks

Builders for the link forms the help window understands, so you are not hand-writing Markdown and guessing at syntax.

Method	Produces
`Page(text, slug)`	`[text](slug)` — link to another help page
`Address(text, number, street)`	`[text](address:16 11s)` — focus a building on the city map
`Address(text, address)`	Same, with a pre-formatted `"16 11s"`
`ContentKey(pageKeyPrefix)`	`help_<prefix>_content` — the body’s localisation key

var body =
    "**Commercial Washing Machine** sells a wash cycle in a " +
    HelpLinks.Page("Laundromat", "businesstypes-laundromat") + ".\n\n" +
    "Sold at " + HelpLinks.Address("Essentials Appliances", 16, "11s") + ".";

ContentKey is handy for generating locale files, or asserting in a build step that every page you register has content.

← Getting started · Conventions →