Skip to content

Monster API 0.1 — De Facto Specification

Status: Descriptive — the contract as it ships on branch version/0.43.0 + System 8 module version/system8-0.5.0. Versioned by MODULE_API_VERSION 1.5.0. Master spec: 4-system-platform-separation/requirements.md (R2).

1. What it is

A monster is just a Character (systemId-tagged) produced by a generator and projected to a token via CS-2/CS-6. So the Monster API is a thin generation surface on the same SystemModule — not a second character system, and not a parallel GeneratedMonster contract. Two optional members, both in systems/types.ts:

listTemplates?(): Template[]                              // M-1: roles/classes as build templates
generateCharacter?(seed: MonsterSeed): Partial<Character> | Promise<…>   // M-2: pure, seeded

2. Version

Ships as part of Module API 1.5.0. Additive/optional (see the Character Sheet API §2).

3. Surfaces (M-1 … M-5)

# Surface How Notes
M-1 listTemplates(): Template[] a Template is a class or a monster role, carrying its build recipe (abilityPriority, allowedClasses, acSeed, speed) passed opaquely by the platform (CS-4.3)
M-2 generateCharacter(seed): Partial<Character> pure & seeded; MonsterSeed = { level, template, flavor?, castingStat?, rngSeed }. Internally composes CS-4's auto-fill — M-2 IS CS-4.2 in the monster direction may be async for content lookups; deterministic given (seed, module data)
M-3 project the generated Character flows through the same CS-2/CS-6 projectToken — no second path ⚠︎ retires the parallel GeneratedMonster → tokenFromMonster.ts path (5e side in Phase 5)
M-4 bestiary not the Monster API — a bestiary is a queryable content type on the Content API (contentProvider.listMonsters) the Monster API stays purely about generation
M-5 editors monster editors ride the CS-7 CharacterSheetSectionExtension (resolved dynamically) ⚠︎ re-homing the S8 System8*Editor components is UI work, deferred

4. Proven against System 8

In modules/system8/src/ (in this repository since v0.118.0):

  • roles.ts — the six combat roles (Brute/Ravager/Controller/Lurker/Skirmisher/Artillery) + ability priority resolver (M-1 catalog).
  • generate.ts — listTemplates (M-1), generateCharacter (M-2, seeded: assigns the base array down the role priority, allocates proficiency greedily, derives HP/AC/speed), and autoFill.fillCharacter delegating to the same generateCharacter (CS-4.2).
  • M-3 verified by a test: generateCharacter → construct → projectToken yields a token whose derived HP matches the generator (one projection path).

5. Known gaps / deferred

  • ⚠︎ S8 power/feat auto-fill deferred. generateCharacter currently produces ability scores + derived stats + class; weighted power/feat auto-fill needs fetched module content and composes via the Content API. The Monster API explicitly tolerates a partial generator.
  • ⚠︎ App-side rewiring deferred. Flipping apps/web MonsterGenerator.tsx off its file-path imports + isSystem8Campaign gate onto the module seams is UI work (needs interactive verification).
  • ⚠︎ 5e (Phase 5). 5e implements only a CR-table stat synthesizer; C1–C5 are absent/random. The 5e module will ship whatever exists unchanged behind M-1…M-3; richer roles/weights are a later release.