World Dimension Loader (WDL) 1.2.2 日本語ガイド
Minecraft 1.20.1 / Forge 47.4.22 / Java 17
Mod ID: worlddimensionloader

============================================================
0. はじめに
============================================================
World Dimension Loaderは、既存Minecraftワールドの「コピー」をWDL管理ディメンションとして読み込み、設定可能なGateから行き来できるForge MODです。

WDL 1.2.2では1.2.xの機能基盤を維持しつつ、Configを「初期値は省略し、変更したい項目だけ書く」方式へ整理しました。

最重要:
- 元ワールドは必ずバックアップしてください。
- WDL_custom_dimensionsには元ワールドそのものではなくコピーを置いてください。
- WDLはワールド変換ツールではありません。導入前後のバックアップを推奨します。

============================================================
1. 必要環境と導入場所
============================================================
対応環境:
- Minecraft 1.20.1
- Forge 47.4.22
- Java 17

シングルプレイ:
- WDL JAR: .minecraft/mods/
- Config: .minecraft/config/worlddimensionloader/
- 外部ワールド: .minecraft/WDL_custom_dimensions/

専用サーバー:
- WDL JAR: server-root/mods/
- Config: server-root/config/worlddimensionloader/
- 外部ワールド: server-root/WDL_custom_dimensions/

マルチプレイではWDLをサーバーと参加クライアントの両方へ導入してください。
外部ワールド本体はサーバー側だけに配置します。クライアント側へWDL_custom_dimensionsをコピーする必要はありません。

============================================================
2. Config生成と1.2.2の構成
============================================================
以下の3ファイルは、存在しない場合Minecraft/Forge起動時に自動生成されます。ワールドを一度開く必要はありません。

config/worlddimensionloader/common.toml
config/worlddimensionloader/dimensions.toml
config/worlddimensionloader/gates.toml

1.2.2の基本ルール:
初期値のまま使う設定は書かず、変更したい項目だけ記述します。

自動生成Configは次の2層構成です。
- ALL OPTIONS TEMPLATE: 全設定を確認できる、すべてコメントアウト済みの有効TOML
- MINIMAL WORKING EXAMPLE / EXAMPLE OVERRIDES: 初期値と同じ項目を省いた実用例

common.tomlは有効な設定行が0件でも正常です。全Common設定にコード側既定値があります。
dimensions.tomlは初期状態で有効Dimensionを作りません。
gates.tomlだけは標準機能としてOverworld Gateを1件生成しますが、初期値と同じ項目は省略されています。

既存1.2.1 Configはそのまま利用でき、自動上書きされません。
1.2.2の簡潔な形式を使いたい場合だけ、config/worlddimensionloader/をバックアップして旧ファイルを退避し、再生成後に「変更したい設定だけ」を移してください。

============================================================
3. 最短セットアップ
============================================================
STEP 1: 外部ワールドをコピー
例:
.minecraft/WDL_custom_dimensions/my_world/level.dat

注意:
.minecraft/WDL_custom_dimensions/my_world/my_world/level.dat
のような二重フォルダにしないでください。

STEP 2: dimensions.tomlへ最小構成で登録

[[dimensions]]
id = "my_world"
display_name = "My World"

folderはid、enabledはtrue、rarityはCOMMONが初期値です。
destination / respawn / runtime / bed / anchor / Policyも省略時に既定動作が適用されるため、この基本例では書く必要がありません。

STEP 3: 読込確認
/wdl scan
/wdl list

READYならGateから利用できます。

STEP 4: gates.tomlへGateを登録

[[gates]]
id = "my_world_gate"
display_name = "My World Gate"
corner_block = "minecraft:crying_obsidian"
max_inner_width = 8
max_inner_height = 8
selection_mode = "LIST"
dimensions = ["my_world"]

省略した項目は初期値になります。
- frame_block = minecraft:obsidian
- enabled = true
- minimum = 2x3
- open_time_seconds = 10
- Costなし = 無料
- allowed_igniters省略 = 通常WDL Dimension Igniterを制限しない

現在の新規Gateではgate_typeを書きません。

STEP 5: Gateフレームを作る
上の例では四隅がcrying_obsidian、その他の外周は省略時既定のobsidianです。

◆■■◆
■  ■
■  ■
■  ■
◆■■◆

◆ = corner_block
■ = frame_block
空白 = Gate内部

STEP 6: Igniterで開通
/give @s worlddimensionloader:basic_dimension_igniter

全設定を確認したい場合は、自動生成ConfigのALL OPTIONS TEMPLATEまたはWDL_CONFIG_GUIDE_JA_1.2.2.txtを参照してください。

============================================================
4. 外部ワールドのWorldGen情報
============================================================
WDLは外部ワールドのlevel.datから、そのワールドのOverworld LevelStem / ChunkGeneratorを読み取り、元ワールドの生成設定を可能な限り維持します。

これによりsuperflatなど、元ワールド固有の生成方式をホストOverworld生成器へ勝手に置き換えないようにしています。

[general]
strict_validation = true

を推奨します。元ワールドのWorldGen情報を安全に解読できない場合、strict_validation=trueでは誤った新規チャンクを生成する危険なMountを拒否します。

============================================================
5. Gateの目的地と抽選
============================================================
selection_mode = "LIST"
- dimensions = [...] に明示した候補から選択

selection_mode = "ALL"
- enabledかつREADYなWDL取込Dimensionから選択
- minecraft:overworldは自動追加されません

Overworld行きGate:
selection_mode = "LIST"
dimensions = ["minecraft:overworld"]

同一Dimensionへの通常Gate転移は候補から除外されます。除外後に候補が無い場合、Gateは開通しません。

============================================================
6. rarity / weight / Random Gate
============================================================
Dimension側にweightを明示しない場合、common.tomlのrarity_weightsを使用します。

初期値:
COMMON = 100
UNCOMMON = 60
RARE = 25
EPIC = 10
LEGENDARY = 3

weightは「%」ではなく相対重みです。

例:
World A = COMMON = 100
World B = RARE = 25
World C = LEGENDARY = 3
合計128なので、それぞれ128に対する重みとして抽選されます。

Dimension側で:
rarity = "LEGENDARY"
weight = 50

と書けば50を使用し、個別weightがrarity標準値より優先されます。
weight = 0 はランダム抽選候補から除外します。

============================================================
7. allowed_igniters と同一フレーム複数Gate
============================================================
allowed_igniters は任意項目です。項目を省略するか allowed_igniters = [] とすると、通常WDL Dimension Igniterを制限しません。
Basic / Advancedを含む通常Igniterは、Gate側へ列挙しなくても使用できます。将来追加される通常WDL Igniterもunrestricted Gateでは自動的に対象になります。

特定Igniterだけに制限する場合だけ非空リストを記述します:
allowed_igniters = ["worlddimensionloader:advanced_dimension_igniter"]

Creative Dimension Igniterは管理・テスト用Master Igniterで、通常Igniterのwildcardとは別経路です。allowed_ignitersへ書かなくても有効なGateを起動でき、Gate Costを無視し、開いたGate SessionではPolicyもbypassします。

ただし次は無視しません:
- Gateフレームの物理形状
- Gateサイズ
- Destinationの有効性
- same-frame複数Gateの曖昧性

同じ物理フレームへ複数Gate定義を登録できます。WDLはframe/corner、実サイズ、使用Igniterから解決します。
省略/空のunrestricted Gateは、同じ物理条件を共有する全ての通常Igniter制限Gateと重なります。重なりがある定義はfail-closedで無効化し、Config上で先に書いた方が勝つ挙動にはしません。
Basic-onlyとAdvanced-onlyのように通常Igniterが分離できる組み合わせは共存できます。unrestricted + Creative-onlyは通常Igniter競合ではなく、Creative明示指定を識別ヒントとして利用できます。

Creativeだけで曖昧な場合、選ばせたいGateのallowed_ignitersへCreativeを明示することで識別ヒントにできます。

============================================================
8. Gate Cost
============================================================
利用可能なCost type:
- ITEM
- XP_LEVEL
- XP_POINTS
- HEALTH
- HUNGER

ITEM:
- amount_mode = "FIXED"
- amount_mode = "RANGE"

RANGE例:
[[gates.costs]]
type = "ITEM"
item = "minecraft:ender_pearl"
amount_mode = "RANGE"
min = 1
max = 3

現在はmax=3なら3個以上を所持していないと開通チャレンジ自体を開始できません。
実際の消費はmin..maxから1回だけ抽選します。少数だけ持ってクリック連打して低い抽選を狙う抜け道を防いでいます。

CostはDestinationが準備でき、Gateを実際に開ける段階でcommitします。失敗時に途中だけ支払う動作を避けます。

============================================================
9. Gate Lifecycle
============================================================
open_time_seconds:
- -1 = 常時開通
- 1以上 = 指定秒数

Active Gateはフレーム、角、Portal内部を検証します。
必要なフレーム/角/Portalが壊れたり置換された場合、Gate Sessionは閉鎖され、残っているPortalもcleanupされます。

古いOPEN SavedDataがあっても物理Gateが壊れている場合は再検証し、stale状態を安全側へ戻します。

============================================================
10. Gate Travel History
============================================================
Gate Travel Historyは目的Dimensionを決める機能ではありません。

Destination = Config / ActiveGateが決定
Landing Point = Historyが補助

通常Gate転移成功時にプレイヤー別でsourceDimension、destinationDimension、sourceGate、Frame/位置などを記録します。

例:
OverworldのA Gate -> World A
  履歴PUSH: Overworld A -> World A

World A -> Overworld
  最新履歴が完全な逆経路ならOverworld A Gate付近を着地点候補にして成功後POP

完全逆経路条件:
- history.source == 今回のdestination
- history.destination == 現在Dimension

古い履歴を自由検索しません。
Gateが壊れている/安全な立ち位置がない場合は通常Destinationへfallbackします。転移自体が成功した逆経路なら履歴はPOPされます。

初期保持数:
[gate_history]
max_entries = 3

範囲1..10。
Policy拒否、Inventory拒否、Mount待ち、転移失敗では履歴を先に変更しません。
Return Scroll成功、死亡、/wdl tp成功、WDL Gate以外のDimension移動では古い履歴をクリアします。
ログアウト/再起動、Session Resumeでは維持します。

============================================================
11. Dimension Policy
============================================================
Inventory Policy:
- import = そのWDL Dimensionへの持込
- export = そのWDL Dimensionからの持出
- BLOCK_ALL / WHITELIST / BLACKLIST

Inventory PolicyはGate開通そのものを止めません。Igniterを持っているだけでGateを開けなくなる問題を避け、実際のプレイヤー通過時に判定します。

Travel Policy:
- import = どのDimensionから転入可能か
- export = どのDimensionへ転出可能か
- ALLOW_ALL / WHITELIST / BLACKLIST

Travel Policyは経路そのものを制限するため、Gate開通と通過で適用します。
Policyで禁止された経路は「封鎖」メッセージで拒否されます。

Overworld自身には[[dimensions]]設定がありません。
- Overworld -> WDL: 到着WDL側のTravel Importを確認
- WDL -> Overworld: 出発WDL側のTravel Exportを確認

Gate HistoryはPolicyをbypassしません。

============================================================
12. Return Scroll
============================================================
Return ScrollはGate Historyとは別の緊急帰還手段です。常にOverworldへの直接帰還を試みます。

確認される条件:
- [dimensions.return_scroll] enabled
- Inventory Export
- Travel Export -> minecraft:overworld
- XP Level Cost

XPは転移がcommitした後だけ消費します。
Creative ModeではXPだけ免除され、Policyは免除されません。
成功時はGate Travel Historyをクリアします。

============================================================
13. Dimensional Anchor
============================================================
WDL取込Dimension内でDimensional Anchorを使用すると、そのDimensionの優先到着地点を登録できます。

到着候補の基本順序:
1. Anchor（prefer_anchor=true）
2. 外部ワールド本来のSpawn（prefer_world_spawn=true）
3. fallback座標

[dimensions.anchor]
enabled = false
なら新規登録を禁止し、保存済みAnchorも到着候補として使いません。

Anchorは死亡Respawn地点ではありません。

============================================================
14. Bed Respawn / Death Respawn
============================================================
[dimensions.bed]
allow_bed_respawn = false

省略/falseでは、ベッドで睡眠はできますがWDL Dimensionを死亡Respawn地点として許可しません。
trueの場合だけそのWDL DimensionのベッドRespawnを許可します。

common.tomlの[respawn] mode=OVERWORLDでは、WDL Dimension内の死亡時にOverworldへ戻す方針です。
Anchorは死亡fallbackには使用しません。

============================================================
15. Lazy Mount / keep_loaded / Auto-Unload
============================================================
登録数と同時Live数は別です。多数のDimensionをCatalogへ登録しつつ、max_loaded_dimensionsで同時Live数を制限できます。

[dimensions.runtime]
keep_loaded = true

なら対象Dimensionを常駐させます。keep_loaded Dimensionもmax_loaded_dimensions枠を消費し、Auto-Unload対象外です。

[runtime]
auto_unload = true
unload_delay_seconds = 300

なら、プレイヤー不在・強制ロードチャンクなし等の安全条件でWDL Dimensionを遅延Unloadします。

============================================================
16. Session Resume
============================================================
WDL Dimension内でログアウトしてサーバー/ゲームを再起動しても、WDLはプレイヤー別のSession Resumeを使って元のWDL Dimensionを必要に応じてLazy Mountし、元位置へ戻す処理を行います。

準備中は安全なOverworld待機位置を使用します。
対象Dimensionが削除・無効・恒久的に復元不能ならOverworldへ安全fallbackします。

============================================================
17. 標準アイテム
============================================================
Basic Dimension Igniter
ID: worlddimensionloader:basic_dimension_igniter
Stack: 16
Gate成功時に1個消費。

Advanced Dimension Igniter
ID: worlddimensionloader:advanced_dimension_igniter
耐久100。Gate成功時に耐久1消費。

Creative Dimension Igniter
ID: worlddimensionloader:creative_dimension_igniter
Craftなし。管理/テスト用Master Igniter。

Dimensional Anchor
ID: worlddimensionloader:dimensional_anchor
消費なし。

Return Scroll
ID: worlddimensionloader:return_scroll
本体消費なし。

正確なレシピ図は docs/WDL_ITEMS_AND_RECIPES_JA_1.2.2.txt を参照してください。

============================================================
18. コマンド
============================================================
OP権限2以上:
/wdl scan
/wdl list
/wdl status
/wdl anchors
/wdl loaded
/wdl load <id>
/wdl mount <id>
/wdl unload <id>
/wdl probe <id>
/wdl tp <id>

通常セットアップでは /wdl scan -> /wdl list -> /wdl status の順で確認すると分かりやすいです。

============================================================
19. 1.1.x互換
============================================================
旧Configは自動破壊書換えしません。

旧 gate_type="DIMENSION"
-> 通常Gateとして読込

旧 gate_type="RETURN"
-> Legacy aliasとしてOverworld行き通常Gateへ内部変換

旧[dimensions.return_gate].enabled
-> 旧RETURN aliasに対する互換ガードとしてのみ扱います。新しいDIMENSION -> Overworld Gateには適用しません。

旧[return_history].max_entries
-> 新[gate_history].max_entriesが無い場合のみ互換fallback

旧Return History SavedDataはdestination情報が不足するため、新Gate Travel Historyへ危険な自動変換をしません。

============================================================
20. よくあるトラブル
============================================================
/wdl scanが0件:
- dimensions.tomlの空欄を確認
- WDL_custom_dimensionsの二重フォルダを確認
- level.datが外部ワールドフォルダ直下にあるか確認

Gateが開かない:
1. /wdl scan
2. /wdl listでREADYか
3. frame/cornerが一致するか
4. サイズ範囲内か
5. Igniter条件
6. Cost条件
7. LIST ID
8. 現在Dimension除外後に候補が残るか
9. latest.logのGATE_CONFIG_AMBIGUOUS
10. Travel Policyで経路が封鎖されていないか

元Gate付近へ戻らない:
- Gate Travel Historyは最新の完全逆経路だけを使用
- Return Scrollや/wdl tpを使うと履歴はクリア
- source Gateフレームを壊すと通常Landingへfallback

Configを変えたのに反映されない:
- /wdl scan または再起動
- 専用サーバーではサーバー側Configを編集

詳細は docs/WDL_TROUBLESHOOTING_JA_1.2.2.txt を参照してください。

============================================================
21. 詳細ドキュメント
============================================================
WDL_TUTORIAL_JA_1.2.2.txt             初回導入
WDL_CONFIG_GUIDE_JA_1.2.2.txt         Config詳細
WDL_ITEMS_AND_RECIPES_JA_1.2.2.txt    アイテム/レシピ
WDL_TROUBLESHOOTING_JA_1.2.2.txt      トラブル対応
WDL_UPGRADE_GUIDE_JA_1.2.2.txt        1.1.xから更新
WDL_COMMAND_GUIDE_JA_1.2.2.txt        コマンド
WDL_RELEASE_NOTES_JA_1.2.2.txt        1.2.2変更点

============================================================
22. 安全運用
============================================================
- 元ワールドはバックアップしてコピーを使用
- strict_validation=true推奨
- 大型更新前にConfigをバックアップ
- Configを大きく変更したら/wdl scanとログを確認
- 新しいMOD構成で動的Dimensionを使う場合は、重要ワールドのコピーで先に検証


Gate Destination制限:
Gate DestinationはWDL取込Dimensionと minecraft:overworld をサポートします。Nether/End/他MOD DimensionはGate目的地として未対応で、OverworldとWDL IDを同じLISTへ混在させることもできません。
