Scenario JSON Manual

`scenario.json` を、
ちゃんと書くための
詳細ガイド。

ここでは `metadata`、`config`、`scenes`、`commands` の役割と、パス指定やよくあるミスまでをまとめています。まずは最小構成を通してから、少しずつ機能を足していくのがおすすめです。

Read Order

最小構成を見る
`metadata` と `config` を埋める
`scenes` を増やす
`commands` と素材参照を足す

サンプルZIPをダウンロード

1. Minimum Example

まずはこの形から始める

最低限必要なのは、`version`、`engine`、`metadata`、`config`、`scenes` です。 `start_scene` で開始地点を指定し、`scenes` にそのIDを定義します。

{
  "version": "1.5",
  "engine": {
    "name": "retro-adv",
    "version": "1"
  },
  "metadata": {
    "title": "作品タイトル",
    "rating": "全年齢",
    "ai_generated": false,
    "thumbnail": "assets/thumbs/main.png",
    "summary": "作品のあらすじです。"
  },
  "config": {
    "start_scene": "entrance",
    "unknown_message": "何も起こらない。",
    "help_message": [
      "この作品では「north」「south」で移動します。"
    ]
  },
  "flags": {},
  "inventory": [
    "knife"
  ],
  "scenes": {
    "entrance": {
      "text": [
        "入口に立っている。"
      ],
      "image": "assets/scenes/entrance.png",
      "exits": {
        "north": "hall"
      }
    },
    "hall": {
      "text": [
        "広いホールだ。"
      ],
      "image": "assets/scenes/hall.png",
      "exits": {
        "south": "entrance"
      }
    }
  }
}

2. Top Level

作品全体のキー

`version`

シナリオデータのバージョン番号です。作者が更新管理のために自由に付けられます。プラットフォーム上ではこの数値に関わらず、最後にアップロードされた内容が最新として扱われます。

`engine.name`

現状は `retro-adv` を指定します。

`engine.version`

再生エンジンのバージョンです。現在のエンジンは `1` なので、現状はこの値で固定です。

`flags` / `inventory`

初期状態の進行フラグと所持品です。たとえば `inventory` に `knife` を入れておけば、開始時点からそのアイテムを持った状態で始められます。

3. metadata

公開ページに出る情報

`title`

作品タイトル。必須です。

`rating`

`全年齢` / `R15` / `R18` のいずれか。必須です。

`ai_generated`

AI生成素材を含むなら `true`、含まないなら `false`。

`thumbnail` / `summary`

サムネイル画像とあらすじ。公開一覧や作品ページにも使われます。

4. config

開始位置と基本挙動

`start_scene`

ゲーム開始時のシーンIDです。必須です。

`unknown_message`

反応しない入力が来たときの標準メッセージです。

`help_message`

`help` で表示する案内文です。配列で複数行にできます。

5. scenes

物語の本体はここに書く

`scenes` は、シーンIDをキーにしたオブジェクトです。各シーンには本文、背景画像、重ね表示、移動先、イベントコマンドを定義できます。

"hall": {
  "text": [
    "広いホールだ。",
    "入口へ戻るなら south。"
  ],
  "image": "assets/scenes/hall.png",
  "bgm": "assets/audio/opening.mp3",
  "overlays": [
    {
      "id": "cover",
      "image": "assets/overlays/cover.png"
    }
  ],
  "commands": [
    {
      "inputs": ["look", "look hall"],
      "type": "message",
      "text": [
        "静かなホールだ。"
      ]
    }
  ],
  "exits": {
    "south": "entrance"
  }
}

`text`

シーン本文です。配列で複数行にできます。

`image` / `bgm`

背景画像とシーンBGMです。

`exits` / `commands`

移動入力と条件付きイベントを定義します。

6. commands

イベント入力の書き方

`commands[].inputs` には、そのイベントで受け付けたい入力を配列で書きます。英語と日本語の両方を登録しても問題ありません。

{
  "inputs": ["open door", "扉を開ける"],
  "type": "message",
  "text": [
    "扉が開いた。"
  ],
  "change_background": "assets/scenes/hall-open.png",
  "show_overlay": "assets/overlays/cover.png",
  "sound": "assets/audio/door.wav"
}

`set_flag` や `unset_flag` には `next` を併用できるので、フラグ更新のあとにそのまま `move` を続ける書き方もできます。

7. Path Rules

素材パスの注意点

素材パスは ZIP 内の相対パスで書きます
`scenario.json` と ZIP 内実ファイル名は完全一致させます
`../` や先頭 `/` のような危険なパスは使えません
大文字小文字の違いでもエラーになります
`assets/` 配下にまとめると管理しやすくなります

8. Common Errors

よくあるミス

`scenario.json は ZIP 直下に 1 つだけ配置してください`

サブフォルダに入れているか、複数入っています。

`scenario.json の JSON 構文が不正です`

カンマ抜け、括弧の閉じ忘れ、ダブルクォート漏れを確認してください。

`metadata または config がありません`

最小構成のキーが抜けています。

`参照しているファイルが見つかりません`

画像や音声のファイル名、拡張子、パスを見直してください。

9. Sample Zip

動く完成例を見ながら読む

`scenario.json` の構造だけでなく、画像や音声を含めた最小構成の実例として `sample.zip` を配布しています。まず動く例を開いてから、自分の作品へ置き換えていくのがおすすめです。