World Dimension Loader 1.4.0 - トラブルシューティング

============================================================
1. インポートワールドがREADYにならない
============================================================
確認:
/wdl scan
/wdl list
/wdl status

確認項目:
- WDL_custom_dimensions/<id>/level.dat がある
- 二重フォルダになっていない
- dimensions.tomlのidが test_world_01 のようなnamespace無しWDL ID
- worlddimensionloader:test_world_01 をdefinition idに使っていない
- 元データがコピーで、正常に読み取れる

不正/namespace付きdefinition IDは早期に拒否されます。

============================================================
2. Gateが起動しない
============================================================
確認:
- 行先がREADY
- frame/corner/sizeが一致
- Igniter条件が一致
- selection_mode/dimensionsが有効
- Policy、Timed Session、Cooldown、Resetが入場を封鎖していない

最小Gate:
[[gates]]
id = "test_world_01_gate"
dimensions = ["test_world_01"]

これはLISTとして扱われます。

============================================================
3. 複数Gateが動かなくなった
============================================================
WDLは物理的に曖昧なGate定義を安全側で無効化します。

次が重複すると曖昧になる場合があります:
- frame block
- corner block
- size range
- 利用可能Igniter

行先IDが違うだけでは物理Gateを区別できません。

frame/corner、重ならないsize、Igniter制限などで区別してください。

============================================================
4. Gateがlisted Dimensionだけを選ぶ
============================================================
WDL 1.3.0以降は、selection_mode省略 + dimensionsありをLISTとして扱います。

旧Configで省略ALLを意図していた場合:
selection_mode = "ALL"
を追加してください。

modeもdimensionsも省略した旧形は互換ALLを維持します。

============================================================
5. ALLでOverworldへ行かない
============================================================
正常です。ALLはREADYなWDLインポートDimensionだけを対象にします。

Overworld:
selection_mode = "LIST"
dimensions = ["minecraft:overworld"]

OverworldとWDL IDを同じLISTへ混ぜないでください。

============================================================
6. Resetで容量が大量に増える
============================================================
安全側初期値:
defer_dimension_cleanup_until_restart = true

旧物理世代は次回ゲーム/サーバー起動まで残ります。
再起動前にResetを繰り返すとRuntimeデータが複数世代になり、一時容量が大きく増えます。

再起動するとStartup GCが安全確認済みretired世代を削除します。

ゲーム/サーバー稼働中にRuntimeフォルダを手動削除しないでください。

============================================================
7. Reset後に建築や変更が消えた
============================================================
reset_on_empty対象では仕様です。

Resetはインポート元コピーから次のRuntime世代を作り直すため、Runtime Dimension内で行った変更は失われる場合があります。

WDL_custom_dimensions内のインポート元コピーは変更しません。

永続的なプレイヤー建築が必要なDimensionでは、別の保存手段がない限りreset_on_emptyを有効にしないでください。

============================================================
8. ゲーム中削除を有効にした
============================================================
defer_dimension_cleanup_until_restart = false でlive unload/deleteを試せます。

ただし非推奨です。他MODがDimension参照を保持している場合、Reset失敗、クラッシュ、データ不整合が起きる可能性があります。

Valkyrien Skies検知時は設定を無視し、安全側deferred cleanupを強制します。

============================================================
9. backup=falseなのにWDL_backupsが残る
============================================================
正常です。

resident_gc_backup = false は新しいResident GC backupを作成/更新しない設定です。
既存archiveは自動削除しません。

保存先:
WDL_backups/resident_gc/<save-id>/latest.zip

不要と判断できる場合のみ、ゲーム/サーバー停止中に手動整理してください。

============================================================
10. /wdl scanで設定が反映されない
============================================================
STARTUP ONLY設定があります。

cleanup/retired-generation方式やAdvanced Dimension Igniter耐久値などは完全な再起動が必要です。

============================================================
11. ResetがFAILED_BLOCKEDになった
============================================================
Runtimeフォルダを強制削除しないでください。

確認:
/wdl status
/wdl loaded
/wdl probe <id>

latest.log/debug.logを保存してください。FAILED_BLOCKEDは安全側の停止状態で、block原因となるauthority/referenceを診断する必要があります。

============================================================
12. Valkyrien Skies / Distant Horizons
============================================================
Valkyrien Skies (VS) と Distant Horizons (DH) はどちらも必須ではありません。
VS/DHを導入していない環境でもWDLを使用できます。

現在の安全挙動はValkyrien Skies 2.4.11、DH 3.2.0-bを中心に検証しています。
将来の未知バージョンを保証するものではありません。
VS検知時はdeferred cleanupを強制します。

============================================================
13. 既存Configのコメントが古い
============================================================
WDLは既存Configを上書きしません。

最新コメント取得:
1) config/worlddimensionloader/をバックアップ
2) 旧ファイルを退避
3) 一度起動して再生成
4) 意図した上書き値だけ移す============================================================
14. Reset OFFなのにtimestamp保存先のまま
============================================================
既存1.3.0などですでにtimestamp世代がcurrentの場合は正常です。

1.4.0の固定ID規則は、新規/Pristine Runtimeを reset_on_empty=false で初期化するときに適用されます。

既存timestamp currentをReset OFFへ変更しても:
- 自動reverse migrationしません
- フォルダをリネームしません
- current authorityをそのまま維持します

既存Runtimeを fixed/timestamp/旧canonical の別レイアウトへ手動で移動/リネームしないでください。

============================================================
15. 起動時にRuntime authorityが曖昧としてBLOCKされる
============================================================
同じlogical IDについて、exact lifecycle authorityが無いのに複数Physical候補が存在する場合、1.4.0は安全側で停止します。

例:
dimensions/wdl/test_world_01/                 # fixed payload
dimensions/wdl/test_world_01/<timestamp>/     # timestamp generation

旧canonicalの `dimensions/worlddimensionloader/test_world_01/` が同時に残る場合もBLOCK対象です。

この状態でWDLは:
- どちらがcurrentか推測しない
- 新しいGenerationを勝手に作らない
- フォルダを移動しない
- 候補を削除しない
- current/retiredを証明できない候補をStartup GCで削除しない

対処:
1) ゲーム/サーバーを停止
2) セーブ全体をバックアップ
3) latest.log/debug.logを保存
4) /wdl status や /wdl probe の結果がある場合は保存
5) Runtimeフォルダを手動削除せず原因を確認

============================================================
16. reset_on_empty=falseへ変えたのにReset処理が続く
============================================================
Resetがまだ破壊処理へ進む前なら、Config変更でキャンセルできる場合があります。

ただし同一Reset operationの破壊/Recovery authorityがすでに成立した後は、単純キャンセルしません。
Recovery/transaction safetyがConfig変更より優先されます。

破損/競合したJournalやRecovery authorityも「何もない」と扱わずFAIL-CLOSEDします。

Runtimeフォルダの強制削除で解除しないでください。

============================================================
17. RESET DEFERRED / RESET BLOCKED の意味
============================================================
`WDL RESET DEFERRED` (INFO) は通常、非終端の待機/再試行を示します。例としてTimed Sessionがまだ存在する場合や、Resident Resetが再起動安全条件を待っている場合があります。同じreasonは同じ logical Dimension + operation + phase 内で1回へ抑制されるため、通常の待機reasonが交互に発生してもログストームにはなりません。

同じscope内でも別reasonは初回1回表示されます。Resetが次phaseへ進んだ場合や、新しいReset operationが始まった場合は、同じreasonを再び1回表示できます。

`WDL RESET BLOCKED` (ERROR) は別物で、terminal FAIL-CLOSED安全処理を示します。latest.log/debug.logとバックアップを保管してreasonを確認してください。強制復旧のためにRuntimeフォルダ、Journal、Rotation Receipt、quarantineデータを削除しないでください。

