MODバリデーションガイド

はじめに

このガイドでは、MOD作成時のバリデーション(検証)について、MOD作成者向けに分かりやすく解説します。バリデーションエラーを避けるためのチェックリストと、エラーが発生した場合の対処法を提供します。

対象読者: MOD作成者(初心者〜中級者)

バリデーションとは?

バリデーション(検証) は、MODが正しく作成されているかを自動的にチェックする機能です。

バリデーションの目的

  1. エラー防止: ゲーム実行時のクラッシュを防ぐ
  2. 品質保証: MODが意図した通りに動作することを保証
  3. ユーザー体験: 不完全なMODによる不快な体験を防止

バリデーションのタイミング

タイミング 説明
MOD読み込み時 ゲーム起動時に自動実行
MOD管理画面 「バリデーション実行」ボタンを押した時
MOD有効化時 エラーがあるMODは有効化できない

エラーと警告の違い

項目 エラー(Error) 警告(Warning)
アイコン 🔴 赤色 🟡 黄色
重大度 高(致命的) 低(推奨事項)
MOD選択 選択不可 選択可能
影響 ゲームクラッシュの可能性 機能不足、非推奨機能の使用
対処 修正必須 修正推奨

必須項目チェックリスト

MODを作成する際、以下の項目を必ずチェックしてください。

✅ 1. 必須立ち絵を作成

最も重要: spring.casual.normal立ち絵は必須です。

portraits/
└── spring/
    └── casual/
        └── normal.png  ← これが必須!

理由:

  • この立ち絵がないとMODが選択不可になります(MISSING_NORMAL_PORTRAITエラー)
  • フォールバック機能により、他の立ち絵が未定義でもこれが使用されます

推奨サイズ: 1024×1536px、PNG形式、透過あり

✅ 2. バージョンを必ず指定

mod.jsonに必須:

{
  "min_game_version": "0.1.0",
  "max_game_version": "0.1.999"
}

エラーを避けるポイント:

  • 両方のフィールドが必須です
  • セマンティックバージョニング形式(X.Y.Z)で指定
  • 空文字列は不可

推奨設定:

  • min_game_version: 現在のゲームバージョン(0.1.0
  • max_game_version: マイナーバージョンの最大値(0.1.999

✅ 3. MOD ID・MOD名・作者名を設定

mod.jsonに必須:

{
  "mod_id": "sakura_tanaka",      // 英数字とアンダースコアのみ、先頭は英字
  "mod_name": "田中さくら",         // 表示用名前
  "author": "Your Name"            // 作者名
}

エラーを避けるポイント:

  • mod_idは英数字とアンダースコアのみ、先頭は英字
  • 空文字列は不可

✅ 4. イベントIDを一致させる

events.jsonとスクリプトのIDを一致させる:

// events.json
{
  "id": "first_meeting",
  "script_file": "events/first_meeting.json"
}

// events/first_meeting.json
{
  "event_id": "first_meeting",  // ← 一致させる
  "scenes": [...]
}

エラーを避けるポイント:

  • IDが一致しないとEVENT_ID_MISMATCHエラー
  • コピー&ペーストする際は、必ずIDも変更

✅ 5. シーンIDを一意にする

同じスクリプト内で同じシーンIDを使わない:

{
  "scenes": [
    {"scene_id": "scene_001", "type": "dialogue", ...},
    {"scene_id": "scene_002", "type": "choice", ...},
    {"scene_id": "scene_003", "type": "end"}
    // scene_001 を再利用しない!
  ]
}

エラーを避けるポイント:

  • シーンIDが重複するとDUPLICATE_SCENE_IDエラー
  • 連番を使うと管理しやすい(scene_001, scene_002, ...)

✅ 6. シーン参照を確認

next_sceneの参照先が存在するか確認:

{
  "scenes": [
    {
      "scene_id": "scene_001",
      "next_scene": "scene_002"  // ← scene_002が存在するか確認
    },
    {
      "scene_id": "scene_002",  // ← 参照先
      "type": "end"
    }
  ]
}

エラーを避けるポイント:

  • 存在しないシーンを参照するとMISSING_SCENE_REFERENCEエラー
  • 選択肢のnext_scene、条件分岐のnext_sceneなども同様

✅ 7. MODサイズを200MB以下に抑える

制限:

  • MOD全体(全ファイル合計): 200MB以下

エラーを避けるポイント:

  • MODサイズが200MBを超えるとMOD_SIZE_EXCEEDEDエラー
  • 画像最適化ツールを使用:
    • TinyPNG: https://tinypng.com/ (オンライン、無料)
    • OptiPNG: コマンドラインツール
  • 音声ファイルの圧縮率を調整

✅ 8. JSONの構文を確認

JSON構文エラーを避ける:

{
  "mod_id": "sakura_tanaka",  // ← カンマを忘れずに
  "mod_name": "田中さくら"      // ← 最後のフィールドにはカンマ不要
}

よくあるミス:

  • 括弧の対応({, }, [, ]
  • カンマの位置(最後のフィールドには不要)
  • 引用符の対応("
  • コメントは使用不可(JSONはコメント非対応)

確認方法:

  • JSON Validatorツールを使用: https://jsonlint.com/
  • VSCodeなどのエディタで構文チェック

以下の項目は必須ではありませんが、推奨されます。

✅ 1. 好感度ステータスを定義

{
  "initial_stats": {
    "male": { "affection": 0, "intimacy": 0, "relationship": "acquaintance" },
    "female": { "affection": 0, "intimacy": 0, "relationship": "acquaintance" }
  }
}

警告を避けるポイント:

  • affectionがないとMISSING_AFFECTION_STAT警告

✅ 2. エンディングを定義

{
  "endings": [
    {
      "id": "normal_ending",
      "title_ja": "普通のエンディング",
      "title_en": "Normal Ending",
      "description_ja": "(任意)",
      "description_en": "(optional)",
      "type": "normal",
      "required_conditions": {},
      "script_file": "endings/normal_ending.json",
      "priority": 0
    }
  ]
}

警告を避けるポイント:

  • エンディングがないとNO_ENDINGS_DEFINED警告
  • エンディングがないキャラクターは31日目に表示されません

どこに書く?

  • エンディング一覧(endings)は events.jsoncharacter.json
  • script_file で指定したエンディングスクリプトは、通常のイベントスクリプト(event_id + scenes)と同じ形式です。

✅ 3. 立ち絵パスはドット記法で指定

推奨形式: clothing.emotion

{
  "portrait": "casual.happy"  // ← 推奨形式
}

警告を避けるポイント:

  • portrait にドット(.)を含める場合は 必ず2要素clothing.emotion)にする(例: casual.happy
  • casual.happy.extra のようにドットが増えると INVALID_PORTRAIT_PATH 警告になりやすい

✅ 4. 場所IDを確認

システム定義の場所IDを使用:

  • school, cafe, park, library, shopping_mall, station, homeなど

カスタム場所の場合:

  • custom_プレフィックスを使用(例: custom_secret_garden

警告を避けるポイント:

  • システムに定義されていない場所IDはINVALID_BACKGROUND_ID警告

エラーコード一覧と対処法

このページでは代表例を解説します。全コードの一覧検証コード一覧(バリデーション) を参照してください。

メタデータエラー

INVALID_MOD_ID

  • 原因: MOD IDが空
  • 対処法: mod.jsonmod_idフィールドを設定
  • : "mod_id": "sakura_tanaka"

INVALID_MOD_NAME

  • 原因: MOD名が空
  • 対処法: mod.jsonmod_nameフィールドを設定
  • : "mod_name": "田中さくら"

INVALID_AUTHOR

  • 原因: 作者名が空
  • 対処法: mod.jsonauthorフィールドを設定
  • : "author": "Your Name"

INVALID_MIN_VERSION

  • 原因: 最低ゲームバージョンの形式が不正
  • 対処法: セマンティックバージョニング形式(X.Y.Z)で指定
  • : "min_game_version": "0.1.0"

MISSING_MAX_VERSION

  • 原因: 最高ゲームバージョンが空
  • 対処法: max_game_versionフィールドを追加
  • : "max_game_version": "0.1.999"

INVALID_MAX_VERSION

  • 原因: 最高ゲームバージョンの形式が不正
  • 対処法: セマンティックバージョニング形式(X.Y.Z)で指定
  • : "max_game_version": "0.1.999"

VERSION_TOO_LOW

  • 原因: 現在のゲームバージョンがmin_game_versionより低い
  • 対処法: min_game_versionを現在のゲームバージョン以下に設定
  • : ゲームバージョン0.1.5の場合、"min_game_version": "0.1.0"

INVALID_CHARACTER_ID

  • 原因: キャラクターIDが空
  • 対処法: character.jsonidフィールドを設定
  • : "id": "sakura_tanaka"

MISSING_NORMAL_PORTRAIT

  • 原因: 必須立ち絵(spring.casual.normal)が未定義
  • 対処法: portraits/spring/casual/normal.pngを作成し、character.jsonで定義
  • :
    {
      "portraits": {
        "spring": {
          "casual": {
            "normal": "portraits/spring/casual/normal.png"
          }
        }
      }
    }
    

メタデータ警告

VERSION_UNTESTED

  • 原因: 現在のゲームバージョンがmax_game_versionより高い
  • 対処法: MODが動作するか確認し、max_game_versionを更新
  • 影響: MODは使用できるが、動作未確認

MISSING_AFFECTION_STAT

  • 原因: affectionステータスが未定義
  • 対処法: initial_stats(性別ごと)にaffectionを追加
  • :
    {
      "initial_stats": {
        "male": { "affection": 0, "intimacy": 0, "relationship": "acquaintance" },
        "female": { "affection": 0, "intimacy": 0, "relationship": "acquaintance" }
      }
    }
    

NO_ENDINGS_DEFINED

  • 原因: エンディングが1つも定義されていない
  • 対処法: endings配列に最低1つのエンディングを追加
  • 影響: 31日目のエンディング画面に表示されません

ファイルエラー

MISSING_PORTRAIT

  • 原因: 定義した立ち絵ファイルが存在しない
  • 対処法:
    1. ファイルが正しい場所にあるか確認
    2. ファイル名がcharacter.jsonの定義と一致しているか確認
    3. 大文字小文字も区別されます

MISSING_EVENT_SCRIPT

  • 原因: イベントスクリプトファイルが存在しない
  • 対処法: events.jsonで指定したscript_fileを作成
  • : script_file: "events/first_meeting.json"events/first_meeting.jsonを作成

MISSING_ENDING_SCRIPT

  • 原因: エンディングスクリプトファイルが存在しない
  • 対処法: endingsで指定したscript_fileを作成

MOD_SIZE_EXCEEDED

  • 原因: MOD全体のサイズが200MBを超過
  • 対処法:
    1. 画像を最適化(TinyPNG、OptiPNG)
    2. 不要なファイルを削除
    3. 音声ファイルの圧縮率を調整
    4. CGや背景の解像度を下げる

MISSING_CG_FILE

  • 原因: 一枚絵(CG)ファイルが存在しない
  • 対処法: cg_galleryで定義したCGファイルを作成

スクリプトエラー

スクリプトの「形」が崩れると、以下のエラーが出ます。

EVENT_ID_NOT_DEFINED

  • 原因: スクリプトに event_id がない
  • 対処法: 先頭に "event_id": "..." を追加

SCENES_NOT_DEFINED

  • 原因: スクリプトに scenes がない
  • 対処法: "scenes": [ ... ] を追加

SCENES_NOT_ARRAY

  • 原因: scenes が配列ではない
  • 対処法: scenes を必ず配列([ ... ])にする

EMPTY_EVENT_SCRIPT

  • 原因: scenes が空
  • 対処法: 最低でも1つ以上のシーン+最後に end を入れる

最小の基本構造(コピペ用):

{
  "event_id": "first_meeting",
  "scenes": [
    {
      "scene_id": "d1",
      "type": "dialogue",
      "character": "player",
      "text_ja": "(例)",
      "text_en": "(example)"
    },
    { "scene_id": "end", "type": "end" }
  ]
}

INVALID_JSON

  • 原因: JSON構文エラー
  • 対処法:
    1. JSON Validatorツールで構文チェック(https://jsonlint.com/)
    2. 括弧の対応を確認
    3. カンマの位置を確認
    4. 引用符の対応を確認

INVALID_SCENE_TYPE

  • 原因: scenes[].type が不正
  • 対処法: type はスネークケース(例: character_show)。イベントスクリプト の一覧を参照

INVALID_RELATIONSHIP

  • 原因: relationship / required_relationship の値が不正
  • 対処法: dislike, acquaintance, friend, bestFriend, dating のいずれかにする(stranger は無効)

INVALID_TIME_OF_DAY

  • 原因: time / advance_to_time の値が不正
  • 対処法: 有効な時間帯IDにする(イベントスクリプトtime_advance 参照)

INVALID_ENDING_TYPE

  • 原因: ending_type の値が不正
  • 対処法: 有効な種別にする(エンディング 参照)

INVALID_BGM_ACTION / INVALID_SE_ACTION / INVALID_VOICE_ACTION

  • 原因: *_action に不正な値が入っている
  • 対処法: play/stop/pause/resume のいずれか。音声 参照

有効なシーンtype(scenes[].type):

  • image, dialogue, choice, conditional, random, character_show, character_hide, time_advance, location_change, unlock_character, end

有効な関係性(relationship):

  • dislike, acquaintance, friend, bestFriend, dating

よくある間違い:

  • "type": "dialog" → 正: "type": "dialogue"
  • "type": "characterShow" → 正: "type": "character_show"

EVENT_ID_MISMATCH

  • 原因: events.jsonのIDとスクリプト内のevent_idが異なる
  • 対処法: IDを一致させる

DUPLICATE_SCENE_ID

  • 原因: 同じシーンIDが複数存在
  • 対処法: シーンIDを一意にする(scene_001, scene_002, ...と連番推奨)

MISSING_SCENE_REFERENCE

  • 原因: next_sceneが存在しないシーンを参照
  • 対処法:
    1. 参照先のシーンIDが存在するか確認
    2. タイポがないか確認
    3. シーンIDリストを作成して管理

INVALID_LOCATION_ID

  • 原因: locations.jsonに定義されていない場所IDを使用
  • 対処法:
    1. システム定義の場所IDを使用(school, cafe, parkなど)
    2. カスタム場所の場合はcustom_プレフィックスを使用

スクリプト警告

EMPTY_EVENT_SCRIPT

  • 原因: scenes配列が空
  • 対処法: 最低1つのシーンを追加

INVALID_PORTRAIT_PATH

  • 原因: 立ち絵パスがドット記法でない
  • 対処法: clothing.emotion形式で指定
  • : "portrait": "casual.happy" (推奨)

INVALID_BACKGROUND_ID

  • 原因: 背景IDがシステムに定義されていない
  • 対処法:
    1. システム定義の場所IDを使用
    2. カスタム背景の場合はcustom_プレフィックス
    3. 主人公の部屋の場合はmy_room

MISSING_CG_DEFINITION

  • 原因: CGがcg_galleryに定義されていない
  • 対処法: character.jsoncg_galleryにCGを追加

バリデーション成功のための10のルール

MOD作成時に常に意識すべき10のルールです。

  1. 必須立ち絵を最初に作成: spring.casual.normal.png
  2. バージョンを明確に指定: min_game_versionmax_game_version
  3. IDを一貫させる: events.jsonとスクリプト内のevent_id
  4. シーンIDを一意にする: 重複しないシーンID
  5. 参照を確認する: next_sceneの参照先が存在するか
  6. エンディングを定義する: 最低1つのエンディング
  7. ドット記法を使用: 立ち絵パスはclothing.emotion
  8. ファイルサイズを管理: MOD全体で200MB以下
  9. JSON構文を確認: 括弧、カンマ、引用符の対応
  10. テストを実行: 実際にゲーム内で動作確認

デバッグ手順

ステップ1: MOD管理画面を確認

  1. ゲームを起動
  2. 「設定」→「MOD管理」を開く
  3. 自分のMODを探す

表示の意味:

表示 意味 対処
🔴 赤色 エラーあり(選択不可) エラーを修正
🟡 黄色 警告あり(選択可能) 可能であれば修正
✅ 緑色 バリデーション成功 問題なし

ステップ2: エラーメッセージを確認

  1. MODをクリック
  2. 「詳細を表示」をクリック
  3. エラーメッセージを確認

エラーメッセージの見方:

[MISSING_NORMAL_PORTRAIT] 必須立ち絵(spring.casual.normal)が定義されていません
フィールド: character.portraits
  • エラーコード: MISSING_NORMAL_PORTRAIT
  • メッセージ: 必須立ち絵が未定義
  • フィールド: character.portraits(問題がある場所)

ステップ3: エラーコードから原因を特定

  1. 上記の「エラーコード一覧と対処法」でエラーコードを検索
  2. 原因を確認
  3. 対処法に従って修正

ステップ4: ファイルを修正

  1. エラーメッセージの指示に従ってファイルを修正
  2. ファイルを保存
  3. MOD管理画面で「バリデーション実行」ボタンをクリック
  4. エラーが解消されたか確認

ステップ5: ゲーム内でテスト

  1. MODを有効化
  2. ニューゲームを開始
  3. キャラクター選択画面で自分のキャラクターが表示されるか確認
  4. イベントが正常に動作するか確認

よくある質問(FAQ)

Q1: MODが選択できません

A: MOD管理画面でエラーを確認してください。赤色で表示されている場合、バリデーションエラーがあります。エラーメッセージを確認し、このガイドの「エラーコード一覧」を参照して修正してください。

Q2: 「MISSING_NORMAL_PORTRAIT」エラーが表示されます

A: 必須立ち絵(spring.casual.normal)が未定義です。以下を確認してください:

  1. portraits/spring/casual/normal.pngファイルが存在するか
  2. character.jsonで正しく定義されているか
    {
      "portraits": {
        "spring": {
          "casual": {
            "normal": "portraits/spring/casual/normal.png"
          }
        }
      }
    }
    

Q3: 「EVENT_ID_MISMATCH」エラーが表示されます

A: events.jsonとスクリプト内のevent_idが一致していません。以下を確認してください:

  1. events.jsonidフィールド
  2. スクリプトファイル(例: events/first_meeting.json)のevent_idフィールド
  3. 両方が完全に一致しているか(大文字小文字も区別されます)

Q4: 「MOD_SIZE_EXCEEDED」エラーが表示されます

A: MOD全体のサイズが200MBを超えています。以下で対処してください:

  1. 画像を最適化(TinyPNG: https://tinypng.com/)
  2. 不要なファイルを削除
  3. 音声ファイルの圧縮率を調整
  4. CGや背景の解像度を下げる

Q5: 「MISSING_SCENE_REFERENCE」エラーが表示されます

A: next_sceneが存在しないシーンを参照しています。以下を確認してください:

  1. 参照先のシーンIDが実際に定義されているか
  2. タイポがないか
  3. シーンIDリストを作成して管理することを推奨

Q6: 警告は無視してもいいですか?

A: 警告があってもMODは使用できますが、可能であれば修正することを推奨します:

  • MISSING_AFFECTION_STAT: 好感度ステータスがないと、恋愛関係の進展が表現できません
  • NO_ENDINGS_DEFINED: エンディングがないと、31日目に表示されません
  • INVALID_PORTRAIT_PATH: ドット記法を使用すると、服装も明示的に指定できます

トラブルシューティング

問題: MODがMOD管理画面に表示されない

確認事項:

  1. MODが正しいフォルダに配置されているか
    • ユーザーMOD: Documents/LoveSystem/mods/
  2. mod.jsonファイルが存在するか
  3. mod.jsonがJSON構文エラーがないか

問題: キャラクターが選択画面に表示されない

確認事項:

  1. MODが有効化されているか(MOD管理画面)
  2. バリデーションエラーがないか
  3. target_player_genderが現在のプレイヤー性別に対応しているか
  4. Phase 1では男性主人公のみなので、女性キャラクターのみ表示されます

問題: イベントが発生しない

確認事項:

  1. イベントの発生条件を満たしているか
  2. once_onlyイベントを既に実行済みでないか
  3. required_conditionsの設定を確認
  4. 場所・時間帯・日数などの条件

問題: 立ち絵が表示されない

確認事項:

  1. 立ち絵ファイルが存在するか
  2. ファイルパスが正しいか
  3. spring.casual.normalが定義されているか(フォールバック用)
  4. PNGファイルが破損していないか

問題: エンディングが表示されない

確認事項:

  1. endings配列にエンディングが定義されているか
  2. エンディングの発生条件を満たしているか
  3. エンディングスクリプトファイルが存在するか

バリデーション実行方法

ゲーム内でバリデーション

  1. ゲームを起動
  2. 「設定」→「MOD管理」を開く
  3. 自分のMODを選択
  4. 「バリデーション実行」ボタンをクリック
  5. 結果を確認

手動でチェック

チェックリストを印刷して使用:

□ mod.jsonが存在する
□ mod_id, mod_name, authorが設定されている
□ min_game_version, max_game_versionが設定されている
□ character.jsonが存在する(characterFileで指定している場合)
□ character.idが設定されている
□ spring.casual.normal立ち絵が存在する
□ 全ての立ち絵ファイルが存在する
□ events.jsonが存在する(eventsMetadataFileで指定している場合)
□ 全てのイベントスクリプトファイルが存在する
□ 全てのエンディングスクリプトファイルが存在する
□ events.jsonのIDとスクリプト内のevent_idが一致している
□ シーンIDが重複していない
□ next_scene参照が正しい
□ エンディングが最低1つ定義されている
□ MOD全体のサイズが200MB以下

まとめ

バリデーションは、MODの品質を保証するための重要な機能です。このガイドのチェックリストとエラーコード一覧を活用して、エラーのない高品質なMODを作成してください。

重要なポイント:

  1. 必須立ち絵(spring.casual.normal)を最優先で作成
  2. バージョンを必ず指定
  3. IDを一貫させる
  4. ファイルサイズを管理
  5. テストを実行

質問やサポートが必要な場合は、GitHub Issues、公式フォーラム、Discordをご利用ください。

参考資料