MODバリデーションガイド
はじめに
このガイドでは、MOD作成時のバリデーション(検証)について、MOD作成者向けに分かりやすく解説します。バリデーションエラーを避けるためのチェックリストと、エラーが発生した場合の対処法を提供します。
対象読者: MOD作成者(初心者〜中級者)
バリデーションとは?
バリデーション(検証) は、MODが正しく作成されているかを自動的にチェックする機能です。
バリデーションの目的
- エラー防止: ゲーム実行時のクラッシュを防ぐ
- 品質保証: MODが意図した通りに動作することを保証
- ユーザー体験: 不完全な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.jsonのmod_idフィールドを設定 - 例:
"mod_id": "sakura_tanaka"
INVALID_MOD_NAME
- 原因: MOD名が空
- 対処法:
mod.jsonのmod_nameフィールドを設定 - 例:
"mod_name": "田中さくら"
INVALID_AUTHOR
- 原因: 作者名が空
- 対処法:
mod.jsonのauthorフィールドを設定 - 例:
"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.jsonのidフィールドを設定 - 例:
"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
- 原因: 定義した立ち絵ファイルが存在しない
- 対処法:
- ファイルが正しい場所にあるか確認
- ファイル名が
character.jsonの定義と一致しているか確認 - 大文字小文字も区別されます
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を超過
- 対処法:
- 画像を最適化(TinyPNG、OptiPNG)
- 不要なファイルを削除
- 音声ファイルの圧縮率を調整
- 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構文エラー
- 対処法:
- JSON Validatorツールで構文チェック(https://jsonlint.com/)
- 括弧の対応を確認
- カンマの位置を確認
- 引用符の対応を確認
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が存在しないシーンを参照 - 対処法:
- 参照先のシーンIDが存在するか確認
- タイポがないか確認
- シーンIDリストを作成して管理
INVALID_LOCATION_ID
- 原因:
locations.jsonに定義されていない場所IDを使用 - 対処法:
- システム定義の場所IDを使用(
school,cafe,parkなど) - カスタム場所の場合は
custom_プレフィックスを使用
- システム定義の場所IDを使用(
スクリプト警告
EMPTY_EVENT_SCRIPT
- 原因:
scenes配列が空 - 対処法: 最低1つのシーンを追加
INVALID_PORTRAIT_PATH
- 原因: 立ち絵パスがドット記法でない
- 対処法:
clothing.emotion形式で指定 - 例:
"portrait": "casual.happy"(推奨)
INVALID_BACKGROUND_ID
- 原因: 背景IDがシステムに定義されていない
- 対処法:
- システム定義の場所IDを使用
- カスタム背景の場合は
custom_プレフィックス - 主人公の部屋の場合は
my_room
MISSING_CG_DEFINITION
- 原因: CGが
cg_galleryに定義されていない - 対処法:
character.jsonのcg_galleryにCGを追加
バリデーション成功のための10のルール
MOD作成時に常に意識すべき10のルールです。
- 必須立ち絵を最初に作成:
spring.casual.normal.png - バージョンを明確に指定:
min_game_versionとmax_game_version - IDを一貫させる:
events.jsonとスクリプト内のevent_id - シーンIDを一意にする: 重複しないシーンID
- 参照を確認する:
next_sceneの参照先が存在するか - エンディングを定義する: 最低1つのエンディング
- ドット記法を使用: 立ち絵パスは
clothing.emotion - ファイルサイズを管理: MOD全体で200MB以下
- JSON構文を確認: 括弧、カンマ、引用符の対応
- テストを実行: 実際にゲーム内で動作確認
デバッグ手順
ステップ1: MOD管理画面を確認
- ゲームを起動
- 「設定」→「MOD管理」を開く
- 自分のMODを探す
表示の意味:
| 表示 | 意味 | 対処 |
|---|---|---|
| 🔴 赤色 | エラーあり(選択不可) | エラーを修正 |
| 🟡 黄色 | 警告あり(選択可能) | 可能であれば修正 |
| ✅ 緑色 | バリデーション成功 | 問題なし |
ステップ2: エラーメッセージを確認
- MODをクリック
- 「詳細を表示」をクリック
- エラーメッセージを確認
エラーメッセージの見方:
[MISSING_NORMAL_PORTRAIT] 必須立ち絵(spring.casual.normal)が定義されていません
フィールド: character.portraits
- エラーコード:
MISSING_NORMAL_PORTRAIT - メッセージ: 必須立ち絵が未定義
- フィールド:
character.portraits(問題がある場所)
ステップ3: エラーコードから原因を特定
- 上記の「エラーコード一覧と対処法」でエラーコードを検索
- 原因を確認
- 対処法に従って修正
ステップ4: ファイルを修正
- エラーメッセージの指示に従ってファイルを修正
- ファイルを保存
- MOD管理画面で「バリデーション実行」ボタンをクリック
- エラーが解消されたか確認
ステップ5: ゲーム内でテスト
- MODを有効化
- ニューゲームを開始
- キャラクター選択画面で自分のキャラクターが表示されるか確認
- イベントが正常に動作するか確認
よくある質問(FAQ)
Q1: MODが選択できません
A: MOD管理画面でエラーを確認してください。赤色で表示されている場合、バリデーションエラーがあります。エラーメッセージを確認し、このガイドの「エラーコード一覧」を参照して修正してください。
Q2: 「MISSING_NORMAL_PORTRAIT」エラーが表示されます
A: 必須立ち絵(spring.casual.normal)が未定義です。以下を確認してください:
portraits/spring/casual/normal.pngファイルが存在するかcharacter.jsonで正しく定義されているか{ "portraits": { "spring": { "casual": { "normal": "portraits/spring/casual/normal.png" } } } }
Q3: 「EVENT_ID_MISMATCH」エラーが表示されます
A: events.jsonとスクリプト内のevent_idが一致していません。以下を確認してください:
events.jsonのidフィールド- スクリプトファイル(例:
events/first_meeting.json)のevent_idフィールド - 両方が完全に一致しているか(大文字小文字も区別されます)
Q4: 「MOD_SIZE_EXCEEDED」エラーが表示されます
A: MOD全体のサイズが200MBを超えています。以下で対処してください:
- 画像を最適化(TinyPNG: https://tinypng.com/)
- 不要なファイルを削除
- 音声ファイルの圧縮率を調整
- CGや背景の解像度を下げる
Q5: 「MISSING_SCENE_REFERENCE」エラーが表示されます
A: next_sceneが存在しないシーンを参照しています。以下を確認してください:
- 参照先のシーンIDが実際に定義されているか
- タイポがないか
- シーンIDリストを作成して管理することを推奨
Q6: 警告は無視してもいいですか?
A: 警告があってもMODは使用できますが、可能であれば修正することを推奨します:
MISSING_AFFECTION_STAT: 好感度ステータスがないと、恋愛関係の進展が表現できませんNO_ENDINGS_DEFINED: エンディングがないと、31日目に表示されませんINVALID_PORTRAIT_PATH: ドット記法を使用すると、服装も明示的に指定できます
トラブルシューティング
問題: MODがMOD管理画面に表示されない
確認事項:
- MODが正しいフォルダに配置されているか
- ユーザーMOD:
Documents/LoveSystem/mods/
- ユーザーMOD:
mod.jsonファイルが存在するかmod.jsonがJSON構文エラーがないか
問題: キャラクターが選択画面に表示されない
確認事項:
- MODが有効化されているか(MOD管理画面)
- バリデーションエラーがないか
target_player_genderが現在のプレイヤー性別に対応しているか- Phase 1では男性主人公のみなので、女性キャラクターのみ表示されます
問題: イベントが発生しない
確認事項:
- イベントの発生条件を満たしているか
once_onlyイベントを既に実行済みでないかrequired_conditionsの設定を確認- 場所・時間帯・日数などの条件
問題: 立ち絵が表示されない
確認事項:
- 立ち絵ファイルが存在するか
- ファイルパスが正しいか
spring.casual.normalが定義されているか(フォールバック用)- PNGファイルが破損していないか
問題: エンディングが表示されない
確認事項:
endings配列にエンディングが定義されているか- エンディングの発生条件を満たしているか
- エンディングスクリプトファイルが存在するか
バリデーション実行方法
ゲーム内でバリデーション
- ゲームを起動
- 「設定」→「MOD管理」を開く
- 自分のMODを選択
- 「バリデーション実行」ボタンをクリック
- 結果を確認
手動でチェック
チェックリストを印刷して使用:
□ 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を作成してください。
重要なポイント:
- 必須立ち絵(
spring.casual.normal)を最優先で作成 - バージョンを必ず指定
- IDを一貫させる
- ファイルサイズを管理
- テストを実行
質問やサポートが必要な場合は、GitHub Issues、公式フォーラム、Discordをご利用ください。