イベントスクリプトについて

イベントスクリプトは、events/ 配下のJSONで、シーンの並びとしてイベントを記述します。

ページ概要

• 対象ファイル: events/*.json（events.json の script_file で指定したファイル）
• 役割: イベントを「シーンの配列」として記述し、会話・選択肢・分岐・背景/音声・状態変更（フラグ/変数/ステータス/関係性）を実行します。
• どこで使われるか: イベント実行時、バリデーション（検証）時
• 最小構成: このページの「最小構成（コピペ用）」
• よくあるミス: このページの「よくあるミス」

最小構成（コピペ用）

{
  "event_id": "first_meeting",
  "scenes": [
    {
      "scene_id": "s01",
      "type": "dialogue",
      "character": "player",
      "text_ja": "（今日はどこに行こうかな）",
      "text_en": "(Where should I go today?)"
    },
    { "scene_id": "s99", "type": "end" }
  ]
}

基本構造

{
  "event_id": "first_meeting",
  "scenes": [
    { "scene_id": "s01", "type": "dialogue", "character": "player", "text_ja": "...", "text_en": "..." },
    { "scene_id": "s02", "type": "dialogue", "character": "my_char", "portrait": "casual.normal", "text_ja": "...", "text_en": "..." },
    { "scene_id": "s99", "type": "end" }
  ]
}

type（シーンタイプ）

シーンタイプはスネークケースで書きます（例: character_show）。

• image: 背景/CG/BGM/SE/Voice などを設定
• dialogue: 会話（character: "player" で主人公。character 省略でナレーション扱い）
• choice: 選択肢
• conditional: 条件分岐
• random: ランダム分岐
• character_show: 立ち絵表示（複数人向け）
• character_hide: 立ち絵非表示
• time_advance: 時間進行
• location_change: 場所移動
• unlock_character: キャラクターアンロック
• end: 終了

シーン別の必須フィールド（早見表）

テキストフィールド（text_ja / text_en / text）

• 推奨: text_ja と text_en を両方書く
• フォールバック: 片方がない場合は、もう片方が使われます
• 後方互換: text も読めますが、将来のため text_ja/text_en 推奨です

シーン別の書き方（代表例）

image（背景/CG）

{
  "scene_id": "img_01",
  "type": "image",
  "background": "cafe",
}

• background: 場所ID（例: cafe）または背景ID（警告対象になり得ます）
• custom_background_path: MOD内の画像パスを直接指定（例: backgrounds/festival.png）
• cg: CG ID（文字列）で表示、false で解除

dialogue（会話/ナレーション）

{
  "scene_id": "d01",
  "type": "dialogue",
  "character": "my_char",
  "portrait": "casual.happy",
  "text_ja": "こんにちは！",
  "text_en": "Hello!"
}

• character: キャラクターID。"player" は主人公。省略（または null）でナレーション扱い
• portrait: "casual.happy" のようなドット記法、または季節マップ（例: {\"winter\":\"uniform.happy\",\"default\":\"casual.normal\"}）
• custom_portrait_path: 立ち絵の直接パス指定（イベント専用差し替え向け）
• background: 会話中でも背景切り替え可能
• next_scene: 次に進むシーンIDを明示（会話→任意ジャンプ）

テキスト内の変数展開（プレースホルダー）

会話テキスト（text_ja/text_en）や話者名（name_display）では、プレイヤー名やゲーム状態変数を埋め込めます。

{
  "scene_id": "d02",
  "type": "dialogue",
  "character": "my_char",
  "text_ja": "おはよう、{{player.given_name}}！",
  "text_en": "Good morning, {{player.given_name}}!"
}

使えるプレースホルダー：

• {{player.*}}: プレイヤー名（given_name, family_name, full_name, nickname など）
• {{var.*}}: ゲーム状態変数（イベントで設定した変数を参照）

使用例：

{
  "scene_id": "d03",
  "type": "dialogue",
  "character": "my_char",
  "name_display": "{{var.current_relationship}}",
  "text_ja": "あのカフェには{{var.visited_cafe_count}}回行ったね！",
  "text_en": "We've been to that cafe {{var.visited_cafe_count}} times!"
}

詳細は 変数とconditional を参照してください。

choice（選択肢）

{
  "scene_id": "c01",
  "type": "choice",
  "text_ja": "どうする？",
  "text_en": "What will you do?",
  "choices": [
    {
      "choice_id": "yes",
      "text_ja": "行く",
      "text_en": "Go",
      "flags_set": ["promised"],
      "next_scene": "d02"
    },
    {
      "choice_id": "no",
      "text_ja": "やめておく",
      "text_en": "Not now",
      "next_scene": "d03"
    }
  ]
}

choices の各要素でも flags_set/variables/stat_changes/relationship/unlock_characters が使えます。

conditional（条件分岐）

{
  "scene_id": "cond_01",
  "type": "conditional",
  "branches": [
    {
      "conditions": { "required_flags": ["flag_a"] },
      "next_scene": "d10"
    },
    {
      "conditions": { "stats": { "affection": { "operator": ">=", "value": 50 } } },
      "next_scene": "d20"
    }
  ],
  "default_next_scene": "d99"
}

conditions は events.json の required_conditions と同じ形です。詳細は イベント発生条件（required_conditions） を参照してください。

random（ランダム分岐）

{
  "scene_id": "rnd_01",
  "type": "random",
  "next_scenes": ["d31", "d32", "d33"]
}

character_show（立ち絵固定表示）

{
  "scene_id": "show_01",
  "type": "character_show",
  "character": "my_char",
  "portrait": "casual.normal",
  "position": "left"
}

position は left/center/right。省略時は center です。

effects（立ち絵の表示調整）

"effects": {
  "scale": 1.15,
  "opacity": 1.0,
  "brightness": 1.0,
  "offset_x": 40,
  "offset_y": -20
}

character_hide（立ち絵非表示）

{ "scene_id": "hide_all", "type": "character_hide" }

{ "scene_id": "hide_one", "type": "character_hide", "character": "my_char" }

character を省略（または null/\"all\"）すると全員を消します。

time_advance（時間進行）

{
  "scene_id": "t01",
  "type": "time_advance",
  "advance_to_time": "evening"
}

advance_to_time の有効値: earlyMorning, morning, afternoon, evening, night

location_change（場所移動）

{
  "scene_id": "loc_01",
  "type": "location_change",
  "location": "cafe"
}

location には、assets/configs/locations.json に定義された「場所ID」を指定します。

移動できる場所ID一覧（locations.json）

unlock_character（キャラクターアンロック）

{
  "scene_id": "u01",
  "type": "unlock_character",
  "characters": ["my_char_friend"]
}

end（イベント終了）

イベントを終了します。最後のシーンとして配置します。

{
  "scene_id": "scene_999",
  "type": "end"
}

オプション: batting_cancel（バッティングイベントのキャンセル）

batting_cancel: true を指定すると、このイベント完了後にバッティングイベント（鉢合わせ）の発生がキャンセルされます。

{
  "scene_id": "scene_037",
  "type": "end",
  "batting_cancel": true,
  "flags_set": ["important_event_done"],
  "stat_changes": {
    "affection": 5
  }
}

使用例:

• 重要なストーリーイベントの余韻を残したい場合
• キャラクターが別の場所に移動したことが暗示される場合
• イベント内容的にバッティングが不自然な場合

音声フィールド（BGM / SE / ボイス）

• BGM: bgm, bgm_fade_in, bgm_fade_out, bgm_volume, bgm_action
• SE: se, se_fade_in, se_fade_out, se_volume, se_action
• ボイス: voice_ja, voice_en, voice_fade_in, voice_fade_out, voice_volume, voice_action

シーンで状態を変える（共通フィールド）

多くのシーンで、次の状態変更フィールドが使えます（ゲーム状態に即時反映）。

• flags_set, flags_unset
• variables（キー→値。既存は上書き）
• stat_changes（対象キャラのステータス加算）
• stat_changes_for（複数キャラのステータス加算）
• relationship（関係性の直接変更。有効値: dislike, acquaintance, friend, bestFriend, dating）
• unlock_characters（このシーン時点でアンロックするキャラクターID配列。会話/選択肢でも使用可）

例: フラグと変数を立てる

{
  "scene_id": "s10",
  "type": "dialogue",
  "character": "my_char",
  "text_ja": "明日、カフェで会おう。",
  "text_en": "Let's meet at the cafe tomorrow.",
  "flags_set": ["my_char_date_promised_cafe"],
  "variables": { "my_char_promise_cafe_day": 2 }
}

分岐（まとめ）

• conditional: branches を上から順に評価し、最初に一致した分岐の next_scene にジャンプします。一致がなければ default_next_scene に進みます。
• random: next_scenes からランダムに1つを選んでジャンプします。

具体例はこのページの conditional / random を参照してください。

よくあるミス

• イベントID不一致: events.json の id とスクリプトの event_id
• 参照ミス: next_scene / default_next_scene が存在しないIDを指す
• typeのスペル: characterShow のような別表記にしてしまう → 正: character_show

関連

• MOD作成ガイド
• events.json（イベント一覧）
• イベント発生条件（required_conditions）
• エンディングの作り方
• 変数とconditional
• 立ち絵について
• 一枚絵（CG）・背景
• 音声（BGM/SE/Voice）
• バリデーションガイド
• 検証コード一覧