API Overview
API generation 6 · Requires History Stages 6.0.0+ on NeoForge 1.21, Forge 1.20.1 or Fabric 1.21.1.
These pages are for people writing a mod. If you are building a pack, you want the Wiki instead — nothing here is needed to make stages, and an addon is never required to gate content that History Stages already knows about.
Which half do you need?
Almost every mod that touches History Stages needs only the first one.
| "My mod needs to know what a player has unlocked." | Read stage state, change it, and react when it changes. A plain API surface, no registration, no events to subscribe to at load time. → Stage State & Events |
| "My mod adds something History Stages should be able to gate." | Register your own lock category, requirement, auto-trigger, stage settings or config section — each with a native tab in the in-game editor. → Addon Development |
The second one builds on the first: an addon still reads stage state the same way anybody else does.
The extension points
| Page | Answers |
|---|---|
| Lock Categories | What can be gated? The eighteen built-in kinds are registered through this same path. |
| Requirements | What must a player do before the stage opens? |
| Auto-Triggers | What unlocks a stage by itself, with no pedestal and no command? |
| Stage Settings | Your own settings on every stage, stored in the stage file. |
| Config Sections | Your own rows in the config screen, stored in your own config. |
| Diagnostics | 6.1. Your own checks and sections in the debug report, and runtime log lines. |
The editor toolkit
An addon's tab looks like a built-in tab because it is made of the same widgets. How much of it you write is a choice, and the cheapest tier is "none at all".
| Page | Covers |
|---|---|
| Editor Toolkit | The three tiers, and how a tab is registered in the first place. |
| Editor Widgets | The row widget, pickers, right-click menus — the reference catalogue. |
| Editor Screens | The lifecycle a tab may override, and the one hook that is easy to forget. |
Versioning
HistoryStagesAPI.API_VERSION is the generation. It goes up only when something under api is
removed, renamed or changes signature. API_MINOR counts additions within a generation: 6.0.x is
6.0, 6.1.0 is 6.1.
The generation usually matches the mod's major version, but it does not have to: a later 6.x
release could rebuild part of the API and raise it to 7 on its own. The loader only knows the mod
version, so pin the mod versions you built against in your metadata, and end the range where the
changelog says the generation went up. An addon using something added in 6.1 needs
versionRange="[6.1,7.0)". → Adding the dependency
Unlike the wiki, these pages are not versioned — they describe the current generation only.