18. API Reference

18.1 Global Public APIs

The following APIs are exposed to the main game, MiniExp modules, and add-ons. When calling them from the UI, reference the functions and objects exported to the window global.

API	Description	Key Properties / Args	Defined In
`window.SandboxBridge`	Utility for sandboxed execution. Provides min/max map sizes and validation helpers.	`minSize`, `maxSize`, `maxLevel`, `computePlayerStats()`, `sanitize()`, `validate()`, `start()`, `isActive()`	`main.js` lines 400–419
`window.registerMiniGame(def)`	Registers a MiniExp mod. Pass a definition with `id` and a `create` implementation.	`def.id` (required), `def.create(root, awardXp, options)`, optional metadata	`main.js` lines 6669–6693
`window.showTransientPopupAt(x, y, text, opts)`	Draws a floating popup over the MiniExp container.	`opts.variant` (`'info'` / `'warning'` / `'combo'`, etc.), `opts.duration`	`main.js` lines 6761–6783
`window.showMiniExpBadge(text, opts)`	Displays an EXP badge on the MiniExp HUD. Use `opts.tone` and `opts.variant` to adjust the styling.	`opts.variant` (e.g., `'combo'`), `opts.level`, `opts.tone` (supports `'loss'`)	`main.js` lines 6735–6760
`window.getMiniExpBalance()`	Returns the cumulative EXP gained during the current session (MiniExp tab).	Return value: number	`main.js` lines 6824–6827
`window.registerDungeonAddon(def)`	Registers dungeon-generation add-ons, extending generators, structures, and BlockDim tables.	`def.id` (required), `def.generators`, `def.blocks`, `def.structures`	`main.js` lines 7480–7512

18.2 MiniExp Module Lifecycle

After a module calls registerMiniGame, the player’s launch action invokes its create() function. Implement the following signature and return a runtime controller:

function create(rootElement, awardXp, options) {
    // Required: build DOM under rootElement
    // Required: call awardXp(delta) to grant EXP
    // options.difficulty and options.shortcuts are provided
    return {
        start(),   // Begin the game
        stop(),    // Pause or handle shutdown
        destroy(), // Clean up resources
        getScore() // Return a number for best-score tracking
    };
}

When the game ends, the runtime is called in order: stop() → getScore() → destroy(). Records update through startSelectedMiniGame() and quitMiniGame().

Context	Details	Reference
`options.difficulty`	Value from the UI difficulty selector (`EASY` / `NORMAL` / `HARD`, etc.).	`main.js` lines 11620–11634
`options.shortcuts`	Shortcut controller that toggles key bindings. Provides `enableKey()`, `disableKey()`, and more.	`main.js` lines 161–188
`options.player`	Player-control API (v0.3+). Offers HP/SP/inventory updates and `getState()` snapshots.	`main.js` lines 11610–11634
`awardXp(amount, meta)`	Callback for granting EXP. Updates the MiniExp HUD and internal balance.	`main.js` lines 11544–11580

18.3 Player Control API

options.player lets MiniExp modules interact with the player state safely. It is undefined on host versions prior to v0.3, so check for availability before use. Major methods include:

getState(): Returns a snapshot containing level, HP, SP, and inventory.
awardItems() / adjustItems(): Apply an item-id map and return the actual delta.
adjustHp() / healHp() / damageHp(): Modify HP with caps handled automatically.
adjustSp() / fillSp(): Change SP or refill to the maximum.

All operations trigger UI updates and saving on the host side. Use options such as opts.silent or opts.allowNegative when provided.

18.4 Shortcut Controller API

options.shortcuts is created by createMiniShortcutController(). It enables each mini-game to manage keyboard shortcuts independently.

setGlobal(enabled) / setAll(enabled): Toggle all shortcuts at once.
enableKey(key) / disableKey(key): Control individual keys.
isKeyEnabled(key): Check the current state.
reset(): Restore the defaults.

Implementation lives in main.js lines 132–188 and integrates with MiniExp shortcuts (P = pause, R = restart).

18.5 Dungeon Add-on API

Add-ons registered via registerDungeonAddon() receive a context object from makeGenContext(). Generation helpers include:

Method	Description	Reference
`ctx.set(x, y, solid)`	Toggle tiles between wall and floor. Neighbour metadata adjusts automatically.	`main.js` lines 7514–7549
`ctx.ensureConnectivity()`	Creates corridors to eliminate isolated regions.	`main.js` lines 7534–7537
`ctx.structures.place(id, x, y, options)`	Places registered structures by pattern ID or inline definition.	`main.js` lines 7376–7416
`ctx.fixedMaps.apply(floor)`	Applies fixed layouts supplied by the add-on.	`main.js` lines 3203–3240
`ctx.setFloorColor(x, y, cssColor)`	Overrides floor colour. `setWallColor()` and `setFloorType()` are also available.	`main.js` lines 8911–8922
`ctx.setFloorType(x, y, type[, options])`	Configures floor behaviour. Valid `type` values: `'ice' \| 'poison' \| 'bomb' \| 'conveyor' \| 'one-way' \| 'vertical' \| 'horizontal'`. For conveyor and one-way floors, supply `options.direction` or call `ctx.setFloorDirection()` with `'up'\|'down'\|'left'\|'right'`.	`main.js` lines 8924–8951
`ctx.setFloorDirection(x, y, dir)`	Sets the direction for conveyor or one-way floors (`dir` = `'up'\|'down'\|'left'\|'right'`).	`main.js` lines 8952–8964

Conveyor and one-way floors act as normal tiles if no direction is assigned. Vertical-only and horizontal-only floors restrict movement to the specified axis, making them useful for directing players and enemies. When a dungeon’s recommended level is five or more below the player, floor hazards are disabled automatically.

Each context provides ctx.random, a deterministic RNG. Use it instead of Math.random() to keep generation reproducible.