18. API リファレンス

18.1 グローバル公開 API 一覧

本編とミニゲーム/アドオンから利用できる公開 API を一覧にまとめています。UI から利用する場合は window グローバルにエクスポートされている関数・オブジェクトを参照してください。

API	概要	主なプロパティ / 引数	実装位置
`window.SandboxBridge`	サンドボックス実行用ユーティリティ。最小/最大マップサイズや検証ヘルパーを提供します。	`minSize`, `maxSize`, `maxLevel`, `computePlayerStats()`, `sanitize()`, `validate()`, `start()`, `isActive()`	`main.js` 400–419 行
`window.registerMiniGame(def)`	MiniExp MOD が自身を登録するための関数。`id` と `create` 実装を含む定義を渡します。	`def.id`（必須）、`def.create(root, awardXp, options)` などのメタデータ	`main.js` 6669–6693 行
`window.showTransientPopupAt(x, y, text, opts)`	MiniExp コンテナ上に一時的なフローティングポップアップを描画します。	`opts.variant`（`'info'` / `'warning'` / `'combo'` など）、`opts.duration`	`main.js` 6761–6783 行
`window.showMiniExpBadge(text, opts)`	MiniExp HUD に EXP バッジを表示します。`opts.tone` や `opts.variant` で演出を切り替えられます。	`opts.variant`（`'combo'` など）、`opts.level`、`opts.tone`（`'loss'`対応）	`main.js` 6735–6760 行
`window.getMiniExpBalance()`	セッション中の累計 EXP（MiniExp タブ基準）を取得します。	戻り値: 現在の EXP 残高（数値）	`main.js` 6824–6827 行
`window.registerDungeonAddon(def)`	ダンジョン生成アドオンを登録し、生成器・構造・BlockDim テーブルを拡張します。	`def.id`（必須）、`def.generators`、`def.blocks`、`def.structures`	`main.js` 7480–7512 行

18.2 MiniExp モジュールのライフサイクル

MiniExp MOD は registerMiniGame で登録されると、プレイヤーが開始したタイミングで create() が呼び出されます。create() は以下のシグネチャを満たし、制御用のランタイムオブジェクトを返します。

function create(rootElement, awardXp, options) {
    // 必須: rootElement へ DOM を構築
    // 必須: awardXp(delta) で EXP を授与
    // options.difficulty, options.shortcuts を利用可能
    return {
        start(),   // ゲーム開始
        stop(),    // 一時停止／終了時に呼ばれる
        destroy(), // クリーンアップ
        getScore() // 数値を返すとベストスコアに記録
    };
}

ゲーム終了時にはランタイムの stop() → getScore() → destroy() が順番に呼び出され、記録情報が更新されます。これらの呼び出しは startSelectedMiniGame() および quitMiniGame() から管理されます。

コンテキスト	内容	参照
`options.difficulty`	UI の難易度セレクター値（`EASY`/`NORMAL`/`HARD` 等）。	`main.js` 11620–11634 行
`options.shortcuts`	ショートカットの有効/無効を制御するコントローラー。`enableKey()`・`disableKey()` などを提供します。	`main.js` 161–188 行
`options.player`	プレイヤー操作 API（v0.3+）。HP/ SP / インベントリの更新や `getState()` によるスナップショット取得を提供します。	`main.js` 11610–11634 行
`awardXp(amount, meta)`	EXP を付与するコールバック。MiniExp HUD にバッジが表示され、内部残高が更新されます。	`main.js` 11544–11580 行

18.3 プレイヤー操作 API

options.player は MiniExp MOD からプレイヤーの状態を安全に操作するためのヘルパーです。ホストが v0.3 以前の場合は未定義のため、存在を確認してから使用してください。主なメソッドは次のとおりです。

getState(): レベル/HP/SP/インベントリを含むスナップショットを返します。
awardItems() / adjustItems(): アイテム ID と増減個数のマップを適用し、実際の変化量を返します。
adjustHp()・healHp()・damageHp(): HP の増減（上限は自動で考慮）。
adjustSp()・fillSp(): SP の増減および最大値までの回復。

すべての操作はホスト側で UI 更新とセーブを自動的に行います。必要に応じて opts.silent や opts.allowNegative などのオプションを利用できます。

18.4 ショートカットコントローラー API

options.shortcuts の実体は createMiniShortcutController() で生成され、ミニゲームごとにキーボードショートカットの有効/無効化を制御できます。主要メソッドは次のとおりです。

setGlobal(enabled) / setAll(enabled): すべてのショートカットを一括で切り替え。
enableKey(key) / disableKey(key): 指定キーのみ個別に制御。
isKeyEnabled(key): 現在の有効状態を確認。
reset(): すべての設定を初期状態に戻す。

実装は main.js 132–188 行にあり、MiniExp タブのショートカット（P=一時停止、R=リスタート）とも連動します。

18.5 ダンジョン生成アドオン API

registerDungeonAddon() で登録されたアドオンは、生成器ごとに makeGenContext() から供給されるコンテキストオブジェクトを受け取ります。生成アルゴリズムは以下のヘルパーを利用できます。

メソッド	説明	参照
`ctx.set(x, y, solid)`	タイルを壁/床に切り替えます。周辺メタデータも自動で調整されます。	`main.js` 7514–7549 行
`ctx.ensureConnectivity()`	孤立領域がないよう通路を自動整備します。	`main.js` 7534–7537 行
`ctx.structures.place(id, x, y, options)`	登録済み構造物をマップに配置します。パターン ID またはインライン定義に対応。	`main.js` 7376–7416 行
`ctx.fixedMaps.apply(floor)`	固定レイアウトを適用。アドオン側で提供した固定マップを読み込みます。	`main.js` 3203–3240 行
`ctx.setFloorColor(x, y, cssColor)`	床の描画色を上書きします。同様に `setWallColor()` や `setFloorType()` も利用可能です。	`main.js` 8911–8922 行
`ctx.setFloorType(x, y, type[, options])`	床の挙動を設定します。`type` には `'ice' \| 'poison' \| 'bomb' \| 'conveyor' \| 'one-way' \| 'vertical' \| 'horizontal'` を指定できます。コンベヤー床・一方通行床の進行方向は `options.direction` か `ctx.setFloorDirection()` で `'up'\|'down'\|'left'\|'right'` を与えてください。	`main.js` 8924–8951 行
`ctx.setFloorDirection(x, y, dir)`	コンベヤー床 / 一方通行床の進行方向を個別に設定します（`dir` は `'up'\|'down'\|'left'\|'right'`）。	`main.js` 8952–8964 行

コンベヤー床と一方通行床は進行方向が未指定の場合、通常床として扱われます。縦通行／横通行のみ床はそれぞれ上下／左右方向にしか移動できないため、プレイヤーや敵の経路制御に利用できます。推奨レベルがプレイヤーより 5 以上低いダンジョンでは、床ギミックは自動的に無効化されます。

ctx.random にはアドオン固有の乱数生成器が渡されるため、実装側で Math.random() を直接呼ぶのではなく ctx.random() を使用すると再現性の高い生成が行えます。