World Dimension Loader (WDL) 1.0.0
日本語 README / 設定ガイド
Minecraft 1.20.1 / Forge 47.4.22 / Java 17

============================================================
0. はじめに
============================================================

World Dimension Loader（WDL）は、外部のMinecraftワールドを
「必要なときだけ読み込むDimension」として登録し、
Gateから移動できるようにするForge MODです。

大量の配布ワールドを登録しても、すべてを常時ServerLevelとして
読み込むのではなく、必要なワールドだけをLazy Mountする構造です。

このREADMEは、最初に「1つの外部ワールドを登録してGateから入る」
最短チュートリアルを説明し、その後で各Config項目を詳しく解説します。


------------------------------------------------------------
対応環境
------------------------------------------------------------

Minecraft : 1.20.1
Forge     : 47.4.22
Java      : 17
MOD ID    : worlddimensionloader

安定Storage方式:
IMPORT

AUTOを指定した場合も、WDL 1.0.0では検証済みのIMPORT方式を使用します。

DIRECTは将来・実験用の項目です。
WDL 1.0.0では安定運用に使用しないでください。


------------------------------------------------------------
重要
------------------------------------------------------------

・外部ワールドを追加・変更する前にバックアップを推奨します。
・WDLの設定ファイルはTOML形式です。
・設定変更後は「/wdl scan」でConfigと外部ワールドCatalogを再読み込みできます。
・Gateの設定に曖昧な定義がある場合、WDLは安全のため該当Gateを無効化します。
・同じWDL Dimensionから、そのDimension自身へDIMENSION Gateで移動することはできません。



------------------------------------------------------------
初めて使う方へ - まずここだけ読めばOK
------------------------------------------------------------

最初からこのREADMEを全部読む必要はありません。

初回は:

1. WDLを導入して一度起動する
2. 外部ワールドを WDL_custom_dimensions に入れる
3. dimensions.toml に1ワールドだけ登録する
4. gates.toml に1Gateだけ登録する
5. /wdl scan → /wdl list で READY を確認する
6. Gateを作ってBasic Dimension Igniterで開く

ここまでで十分です。

最初の動作確認では common.toml を変更しなくても構いません。
まず「1. 簡単設定チュートリアル」だけ進めてください。

正常に1ワールドへ移動できてから、

・複数Dimension
・LIST / ALL
・rarity / weight
・同一フレーム複数Gate
・Gate Cost
・Auto-Unload

へ拡張するのがおすすめです。


------------------------------------------------------------
どこにMOD・Config・外部ワールドを置く？
------------------------------------------------------------

【シングルプレイ】

WDL-1.0.0.jar:
.minecraft/mods/

Config:
.minecraft/config/worlddimensionloader/

外部ワールド:
.minecraft/WDL_custom_dimensions/


【専用サーバー】

WDL-1.0.0.jar:
サーバーの mods/ フォルダ

Config:
サーバールート/config/worlddimensionloader/

外部ワールド:
サーバールート/WDL_custom_dimensions/


マルチプレイ / 専用サーバーでは、
WDLはクライアントとサーバーの両方へ導入してください。

クライアントとサーバーでは同じWDLバージョンを使用することを推奨します。

外部ワールド本体を各クライアントPCへコピーする必要はありません。
外部ワールドとWDLのRuntime管理はサーバー側で行います。


------------------------------------------------------------
最初に覚える4つの名前
------------------------------------------------------------

WDLでは似た名前がいくつか登場します。

id
  WDL内部で使うDimension名。
  Gateの dimensions = [...] にはこの名前を書きます。

folder
  WDL_custom_dimensions 内にある実際のフォルダ名。

display_name
  人が読むための表示名。

Gate id
  Gate定義そのものの一意ID。


例:

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

この場合:

Gateに書く名前:
"my_world"

実フォルダ:
WDL_custom_dimensions/my_world/


============================================================
============================================================
1. 簡単設定チュートリアル
============================================================

ここでは例として、外部ワールド

    my_world

をWDLへ登録し、黒曜石のGateから移動できるようにします。


------------------------------------------------------------
STEP 0 : 事前チェック
------------------------------------------------------------

開始前に次を確認してください。

・Minecraft 1.20.1
・Forge 47.4.22
・Java 17
・WDL 1.0.0
・使用する外部ワールドのバックアップ

配布ワールドがZIP形式なら、先に展開してください。

展開後は:

my_world/level.dat

となっている必要があります。

「my_world の中に、さらに my_world がある」二重フォルダは
非常によくある失敗です。




------------------------------------------------------------
STEP 1 : WDLを一度起動する
------------------------------------------------------------

WDLをmodsフォルダへ入れてMinecraft / Serverを起動すると、
WDLのConfigが生成されます。

主な構成:

.minecraft/
├─ WDL_custom_dimensions/
└─ config/
   └─ worlddimensionloader/
      ├─ common.toml
      ├─ dimensions.toml
      └─ gates.toml


WDL_custom_dimensions が存在しない場合はWDLが作成します。

専用サーバーでは `.minecraft/` ではなく、サーバーの起動ディレクトリが基準です。
Config編集と外部ワールド配置はサーバー側で行ってください。


------------------------------------------------------------
STEP 2 : 外部ワールドを配置する
------------------------------------------------------------

読み込みたいMinecraftワールドを、

.minecraft/WDL_custom_dimensions/

の中へ配置します。

例:

.minecraft/
└─ WDL_custom_dimensions/
   └─ my_world/
      ├─ level.dat
      ├─ region/
      ├─ data/
      └─ ...


重要:

my_world フォルダの直下に level.dat が存在する必要があります。

次のような二重フォルダになっている場合は認識できません。

誤:
WDL_custom_dimensions/my_world/my_world/level.dat

正:
WDL_custom_dimensions/my_world/level.dat


------------------------------------------------------------
STEP 3 : dimensions.toml にワールドを登録する
------------------------------------------------------------

.minecraft/config/worlddimensionloader/dimensions.toml

を開き、次を追加します。


[[dimensions]]
id = "my_world"
display_name = "My World"
enabled = true
folder = "my_world"
rarity = "COMMON"
weight = 100

[dimensions.destination]
prefer_anchor = true
prefer_world_spawn = true
fallback_x = 0
fallback_y = 80
fallback_z = 0
fallback_yaw = 0.0
fallback_pitch = 0.0

[dimensions.respawn]
mode = "INHERIT"

[dimensions.return_scroll]
enabled = true
xp_level_cost = 5


id:
WDL内部で使用するDimension IDです。
他の登録と重複しない名前にしてください。

folder:
WDL_custom_dimensions 内にある実際のフォルダ名です。


------------------------------------------------------------
STEP 4 : WDLに再スキャンさせる
------------------------------------------------------------

ゲーム内で権限レベル2以上の状態で、

/wdl scan

を実行します。

続けて、

/wdl list

を実行してください。

正常な場合:

[READY] my_world -> ...

のように表示されます。


主な状態:

READY
  使用可能です。

DISABLED
  dimensions.tomlで enabled = false になっています。

MISSING_FOLDER
  指定されたワールドフォルダがありません。

MISSING_LEVEL_DAT
  ワールドフォルダ直下に level.dat がありません。

INVALID_PATH
  dimension rootの外へ出るような不正なfolder指定です。


------------------------------------------------------------
STEP 5 : gates.toml にGateを登録する
------------------------------------------------------------

.minecraft/config/worlddimensionloader/gates.toml

へ次を追加します。


[[gates]]
id = "my_world_gate"
display_name = "My World Gate"
enabled = true
gate_type = "DIMENSION"

frame_block = "minecraft:obsidian"
corner_block = "minecraft:crying_obsidian"

min_inner_width = 2
min_inner_height = 3
max_inner_width = 8
max_inner_height = 8

allowed_igniters = [
  "worlddimensionloader:basic_dimension_igniter"
]

selection_mode = "LIST"
dimensions = ["my_world"]

open_time_seconds = 10


この例ではGate起動コストを設定していません。

コストを追加したい場合は、Gate定義の後ろへ例えば次を追加します。


[[gates.costs]]
type = "XP_LEVEL"
amount = 5


設定後:

/wdl scan

を再度実行してください。


------------------------------------------------------------
STEP 6 : Gateを建てる
------------------------------------------------------------

上記設定の場合:

角:
minecraft:crying_obsidian

それ以外のフレーム:
minecraft:obsidian


最小サイズは内側 2 x 3 です。

例:

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

◆ = crying_obsidian
■ = obsidian
空白 = Gate内部


Gateは縦向きの長方形として作成します。

設定したmin/max範囲内なら、より大きなGateも使用できます。


------------------------------------------------------------
STEP 7 : IgniterでGateを開く
------------------------------------------------------------

この例では:

worlddimensionloader:basic_dimension_igniter

が起動アイテムです。

テスト目的で取得する場合:

/give @s worlddimensionloader:basic_dimension_igniter


Igniterを手に持ち、設定したGateフレームへ使用します。

正常ならGate内部にWDL Portalが生成されます。

Gateへ入ると my_world へ移動します。

my_world がまだロードされていない場合も、
WDLが必要に応じてLazy Mountを行います。


------------------------------------------------------------
STEP 8 : 転移先
------------------------------------------------------------

WDL Dimensionへの到着地点は、基本的に次の順番で決まります。

1. Dimensional Anchor
2. 外部ワールド本来のSpawn
3. dimensions.toml のfallback座標


最初はAnchorが存在しないため、
通常は外部ワールドのSpawnが使われます。



------------------------------------------------------------
ここまで成功したら
------------------------------------------------------------

次の4点が確認できれば、WDLの基本セットアップは完了です。

・/wdl list で対象が READY
・IgniterでGateが開く
・Portalへ入ると登録ワールドへ移動できる
・元ワールドのSpawn、または設定した到着地点へ着く

ここまで正常なら、3章以降は必要な機能だけ読めばOKです。


============================================================
2. Configファイルの構成
============================================================

WDLの主な設定ファイルは3つです。


config/worlddimensionloader/
├─ common.toml
├─ dimensions.toml
└─ gates.toml


common.toml
  WDL全体の共通設定。
  Runtime、Auto-Unload、Return Scroll、rarity weightなど。

dimensions.toml
  外部ワールドごとの登録情報。
  folder、rarity、転移先、Respawn、Return Scrollなど。

gates.toml
  Gateの形、起動アイテム、接続先、抽選方法、コストなど。


============================================================
3. common.toml 詳細
============================================================

------------------------------------------------------------
[general]
------------------------------------------------------------

strict_validation = true

安全性の高い検証を行う設定です。

true:
  WDLが外部ワールドのWorldGen情報などを安全に利用できない場合、
  無理にHost側Generatorへ置き換えず、危険なMountを拒否します。

false:
  一部の互換Fallbackを許可します。
  外部ワールド本来と異なる新規Chunkが生成される可能性があります。

通常は true を強く推奨します。


debug_logging = false

WDLの詳細ログを増やします。

通常:
false

問題調査時:
true


default_gate_open_time_seconds = 10

Gate側で open_time_seconds を省略した場合のデフォルト開通時間です。

単位:
秒


default_min_inner_width = 2
default_min_inner_height = 3
default_max_inner_width = 32
default_max_inner_height = 32

Gate定義側でサイズを省略した場合に使用するデフォルト値です。

WDL 1.0.0のGate内部サイズ制限:

幅:
2 ～ 32

高さ:
3 ～ 32


------------------------------------------------------------
[paths]
------------------------------------------------------------

dimension_root_folder = "WDL_custom_dimensions"

外部ワールドを配置するフォルダです。

デフォルト:

.minecraft/WDL_custom_dimensions/


別名へ変更することもできますが、
特別な理由がなければデフォルトを推奨します。


------------------------------------------------------------
[runtime]
------------------------------------------------------------

storage_mode = "AUTO"

指定可能:

AUTO
IMPORT
DIRECT


AUTO:
WDL 1.0.0では安定しているIMPORT方式を選択します。

IMPORT:
外部ワールドをWDLのRuntime用領域へ準備し、
必要時にDimensionとしてMountします。

DIRECT:
将来・実験用。
WDL 1.0.0の安定運用対象ではありません。


max_loaded_dimensions = 4

同時にLive状態で保持できるWDL Dimension数の上限です。

最小:
1

デフォルト:
4

重要:
これは「登録できるDimension数」の制限ではありません。

例:

登録:
300ワールド

max_loaded_dimensions:
4

の場合でも、Catalogには300ワールドを登録できます。
同時にServerLevelとして動作させるWDL Dimensionを最大4に制限します。


auto_unload = false

プレイヤーがおらず、Forced ChunkもないWDL Dimensionを
自動Unloadするかどうかです。

true:
自動Unloadする

false:
自動Unloadしない


unload_delay_seconds = 300

Auto-Unloadまで待つ時間です。

単位:
秒

最低:
10秒

例:

auto_unload = true
unload_delay_seconds = 300

なら、Unload可能な状態になってから約5分後に対象になります。


vs_remount_cooldown_ticks = 100

Valkyrien Skies 2.4.11のsame-ID Remount安全処理用Cooldownです。

単位:
tick

20 tick ≒ 1秒

デフォルト:
100 tick ≒ 5秒

最低:
20

Valkyrien Skiesを使用している環境では、
理由なく極端に短くしないことを推奨します。


------------------------------------------------------------
[respawn]
------------------------------------------------------------

mode = "OVERWORLD"

指定可能:

OVERWORLD
VANILLA


OVERWORLD:
WDL imported Dimension内で死亡した場合、
OverworldへのRespawnをWDLが処理します。

VANILLA:
WDLはRespawn先を上書きしません。


prefer_overworld_player_spawn = true

OVERWORLD mode時に、
プレイヤー個人の有効なSpawn地点を優先します。


fallback_to_overworld_world_spawn = true

個人Spawnが利用できない場合、
OverworldのWorld SpawnへFallbackします。


------------------------------------------------------------
[return_scroll]
------------------------------------------------------------

default_xp_level_cost = 5

Return Scrollのデフォルト必要経験値レベルです。

これは「経験値ポイント」ではなく「レベル」です。

0:
無料

5:
5レベル消費


Dimensionごとにdimensions.tomlで上書きできます。


------------------------------------------------------------
[rarity_weights]
------------------------------------------------------------

デフォルト:

COMMON = 100
UNCOMMON = 60
RARE = 25
EPIC = 10
LEGENDARY = 3


DIMENSION GateのLIST / ALL抽選に使用する重みです。

数字が大きいほど選ばれやすくなります。

0:
Gateのランダム抽選候補から除外


例:

COMMON = 100
LEGENDARY = 3

なら、LEGENDARYはCOMMONよりかなり出にくくなります。

これは確率を直接指定しているのではなく「重み」です。

実際の確率は、そのGateで抽選対象になっている
すべてのDimensionの有効weight合計から計算されます。


============================================================
4. dimensions.toml 詳細
============================================================

1つの外部ワールドにつき、
1つの [[dimensions]] ブロックを作ります。


基本形:


[[dimensions]]
id = "ancient_city"
display_name = "Ancient City"
enabled = true
folder = "ancient_city"
rarity = "RARE"
weight = 25

[dimensions.destination]
prefer_anchor = true
prefer_world_spawn = true
fallback_x = 0
fallback_y = 80
fallback_z = 0
fallback_yaw = 0.0
fallback_pitch = 0.0

[dimensions.respawn]
mode = "INHERIT"

[dimensions.return_scroll]
enabled = true
xp_level_cost = 10


------------------------------------------------------------
id
------------------------------------------------------------

例:

id = "ancient_city"

WDL内部で使用する一意のIDです。

同じidを複数登録しないでください。

Gateの dimensions = [...] でもこのidを使用します。


------------------------------------------------------------
display_name
------------------------------------------------------------

例:

display_name = "Ancient City"

ユーザー向け表示名です。


------------------------------------------------------------
enabled
------------------------------------------------------------

enabled = true

true:
有効

false:
CatalogにはDISABLEDとして存在しますが、
通常のWDL利用対象にはなりません。


------------------------------------------------------------
folder
------------------------------------------------------------

folder = "ancient_city"

common.tomlのdimension_root_folderから見た
外部ワールドフォルダ名です。

例:

dimension_root_folder = "WDL_custom_dimensions"
folder = "ancient_city"

実際の場所:

.minecraft/WDL_custom_dimensions/ancient_city/


------------------------------------------------------------
rarity
------------------------------------------------------------

指定可能:

COMMON
UNCOMMON
RARE
EPIC
LEGENDARY
CUSTOM


weightを個別指定していない場合、
common.tomlのrarity_weightsを使用します。

CUSTOMにはcommon.tomlの標準rarity weight項目がないため、
CUSTOMをランダムGateで使用する場合は
個別weightを明示することを推奨します。


------------------------------------------------------------
weight
------------------------------------------------------------

例:

weight = 25

Gate抽選用の個別weightです。

これを指定した場合、
rarity_weightsよりこちらが優先されます。

0:
ランダム抽選候補から除外


weightを省略した場合:

rarity
  ↓
common.toml [rarity_weights]
  ↓
有効weight

という流れになります。


------------------------------------------------------------
[dimensions.destination]
------------------------------------------------------------

WDL Dimensionへ到着する座標のルールです。


prefer_anchor = true

trueの場合、Dimensional Anchorが登録されていれば最優先します。


prefer_world_spawn = true

Anchorが利用できない場合、
外部ワールド本来のSpawn地点を使用します。


fallback_x = 0
fallback_y = 80
fallback_z = 0

Anchor / World Spawnを利用しない、または利用できない場合の
Fallback座標です。


fallback_yaw = 0.0
fallback_pitch = 0.0

Fallback使用時のプレイヤー向きです。


転移先の基本優先順位:

1. Dimensional Anchor
2. imported world spawn
3. fallback_x/y/z


------------------------------------------------------------
[dimensions.respawn]
------------------------------------------------------------

mode = "INHERIT"

指定可能:

INHERIT
OVERWORLD
VANILLA


INHERIT:
common.tomlの[respawn]設定を使用します。

OVERWORLD:
このDimensionではOverworld Respawnを使用します。

VANILLA:
このDimensionではWDLのRespawn上書きを使用しません。


------------------------------------------------------------
[dimensions.return_scroll]
------------------------------------------------------------

enabled = true

true:
このDimensionでReturn Scrollを使用可能

false:
このDimensionではReturn Scrollを封印


xp_level_cost = 5

このDimension専用のReturn Scrollコストです。

0:
無料

省略:
common.tomlのdefault_xp_level_costを使用


============================================================
5. gates.toml 詳細
============================================================

Gate 1つにつき [[gates]] ブロックを作ります。


基本例:


[[gates]]
id = "city_gate"
display_name = "City Gate"
enabled = true
gate_type = "DIMENSION"

frame_block = "minecraft:obsidian"
corner_block = "minecraft:crying_obsidian"

min_inner_width = 2
min_inner_height = 3
max_inner_width = 8
max_inner_height = 8

allowed_igniters = [
  "worlddimensionloader:basic_dimension_igniter"
]

selection_mode = "LIST"
dimensions = ["ancient_city", "giant_city"]

open_time_seconds = 10


------------------------------------------------------------
id
------------------------------------------------------------

Gate定義の一意IDです。

重複したGate IDは使用しないでください。


------------------------------------------------------------
display_name
------------------------------------------------------------

Gateの表示用名称です。


------------------------------------------------------------
enabled
------------------------------------------------------------

true:
有効

false:
Gate Resolverの対象外になります。


------------------------------------------------------------
gate_type
------------------------------------------------------------

指定可能:

DIMENSION
RETURN


DIMENSION:
登録したWDL Dimensionへ移動するGate。

RETURN:
Overworldへ帰還するGate。


------------------------------------------------------------
frame_block
------------------------------------------------------------

例:

frame_block = "minecraft:obsidian"

Gateの辺に使用するBlock IDです。


------------------------------------------------------------
corner_block
------------------------------------------------------------

例:

corner_block = "minecraft:crying_obsidian"

Gateの4隅に使用するBlock IDです。

frame_blockと同じBlockを指定することもできます。


------------------------------------------------------------
min_inner_width / max_inner_width
------------------------------------------------------------

Gate内部の横幅範囲です。

制限:
2 ～ 32


------------------------------------------------------------
min_inner_height / max_inner_height
------------------------------------------------------------

Gate内部の高さ範囲です。

制限:
3 ～ 32


------------------------------------------------------------
allowed_igniters
------------------------------------------------------------

そのGateを起動できるアイテムID一覧です。

例:


allowed_igniters = [
  "worlddimensionloader:basic_dimension_igniter",
  "worlddimensionloader:advanced_dimension_igniter"
]


WDL標準Igniter:

worlddimensionloader:basic_dimension_igniter
worlddimensionloader:advanced_dimension_igniter
worlddimensionloader:creative_dimension_igniter


allowed_ignitersを空にした場合、
WDL標準の3種類すべてが許可されます。


------------------------------------------------------------
selection_mode
------------------------------------------------------------

DIMENSION Gateで使用します。

指定可能:

LIST
ALL


LIST:
dimensions = [...] に書いたDimensionだけを候補にします。

ALL:
Catalog内の使用可能なDimension全体から候補を作ります。


------------------------------------------------------------
dimensions
------------------------------------------------------------

LISTモードで使用します。

例:

dimensions = [
  "world_a",
  "world_b",
  "world_c"
]


ここに書く名前はdimensions.tomlのidです。


------------------------------------------------------------
open_time_seconds
------------------------------------------------------------

例:

open_time_seconds = 10

10秒間Gateを開きます。


open_time_seconds = -1

永久開通Gateになります。


有効値:

-1
または
1以上


0や-2以下は無効です。


============================================================
6. Gateのランダム抽選 / Rarity / Weight
============================================================

WDLは1つのDIMENSION Gateに複数Dimensionを登録し、
重み付きランダム抽選を行えます。


例:


[[gates]]
id = "random_gate"
display_name = "Random Gate"
enabled = true
gate_type = "DIMENSION"

frame_block = "minecraft:obsidian"
corner_block = "minecraft:crying_obsidian"

min_inner_width = 2
min_inner_height = 3
max_inner_width = 8
max_inner_height = 8

allowed_igniters = [
  "worlddimensionloader:basic_dimension_igniter"
]

selection_mode = "LIST"
dimensions = [
  "normal_world",
  "rare_world",
  "legendary_world"
]

open_time_seconds = 10


dimensions.toml:


[[dimensions]]
id = "normal_world"
...
rarity = "COMMON"

[[dimensions]]
id = "rare_world"
...
rarity = "RARE"

[[dimensions]]
id = "legendary_world"
...
rarity = "LEGENDARY"


common.tomlがデフォルトなら:

COMMON    = 100
RARE      = 25
LEGENDARY = 3

として抽選されます。


------------------------------------------------------------
個別weightで上書き
------------------------------------------------------------

例えばLEGENDARYでも:

weight = 50

と書けば、そのDimensionは50のweightで抽選されます。

個別weightはrarityより優先されます。


------------------------------------------------------------
現在いるDimensionは自動除外
------------------------------------------------------------

例えば:

現在地:
world_a

Gate:
dimensions = ["world_a", "world_b", "world_c"]

なら、実際の抽選候補は:

world_b
world_c

だけになります。


world_a自身へGate接続してSpawn地点へワープすることはできません。


もしLISTにworld_aしか存在しない場合:

dimensions = ["world_a"]

Gateは開きません。

この失敗では、Gate起動コストやIgniterは消費されません。


============================================================
7. 同じGateフレームに複数のGateを登録する
============================================================

WDL 1.0.0では、
同じframe_block / corner_blockを複数のGate定義で共有できます。

例えば同じ物理フレームでも:

Basic Igniter
  → Gate A
  → world_a / world_bから抽選

Advanced Igniter
  → Gate B
  → world_c / world_dから抽選

という構成が可能です。


例:


[[gates]]
id = "basic_pool"
enabled = true
gate_type = "DIMENSION"

frame_block = "minecraft:obsidian"
corner_block = "minecraft:crying_obsidian"

min_inner_width = 2
min_inner_height = 3
max_inner_width = 8
max_inner_height = 8

allowed_igniters = [
  "worlddimensionloader:basic_dimension_igniter"
]

selection_mode = "LIST"
dimensions = ["world_a", "world_b"]

open_time_seconds = 10


[[gates]]
id = "advanced_pool"
enabled = true
gate_type = "DIMENSION"

frame_block = "minecraft:obsidian"
corner_block = "minecraft:crying_obsidian"

min_inner_width = 2
min_inner_height = 3
max_inner_width = 8
max_inner_height = 8

allowed_igniters = [
  "worlddimensionloader:advanced_dimension_igniter"
]

selection_mode = "LIST"
dimensions = ["world_c", "world_d"]

open_time_seconds = 10


この場合、Igniterが違うため一意に判定できます。


------------------------------------------------------------
Gate定義の競合ルール
------------------------------------------------------------

次の条件がすべて重なる2つの有効Gateは曖昧です。

・frame_block が同じ
・corner_block が同じ
・width範囲が重なる
・height範囲が重なる
・allowed_igniters に共通アイテムがある


この場合、Configの上に書いた方を優先することはありません。

WDLは安全のため、
競合するGate定義を両方ともRuntime対象から除外します。

ログには:

WDL GATE_CONFIG_AMBIGUOUS

が出力されます。


例:

Gate A:
幅 2～8
Basic Igniter

Gate B:
幅 2～8
Basic Igniter

同じframe / corner

→ 競合


一方:

Gate A:
Basic Igniter

Gate B:
Advanced Igniter

→ Igniterが異なるので共存可能


または:

Gate A:
幅 2～4

Gate B:
幅 6～8

同じIgniter

→ サイズ範囲が重ならないので共存可能


注意:

gate_typeがDIMENSIONとRETURNで異なっていても、
物理条件とIgniterが同時に一致する場合は曖昧と判定されます。


============================================================
8. Gate Cost 詳細
============================================================

Gateには複数のコストを設定できます。

すべてのコストは最初に検証され、
Gateが実際に開ける状態になってからまとめて消費されます。

途中で条件を満たせなかった場合に、
一部のコストだけ失うことを避ける設計です。


対応Cost:

ITEM
XP_LEVEL
XP_POINTS
HEALTH
HUNGER


------------------------------------------------------------
ITEM
------------------------------------------------------------

固定数:


[[gates.costs]]
type = "ITEM"
item = "minecraft:ender_pearl"
amount_mode = "FIXED"
amount = 2


範囲ランダム:


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


RANGEではGate起動ごとにmin～maxの範囲で必要数が決定されます。


------------------------------------------------------------
XP_LEVEL
------------------------------------------------------------

[[gates.costs]]
type = "XP_LEVEL"
amount = 5


経験値レベルを5消費します。


------------------------------------------------------------
XP_POINTS
------------------------------------------------------------

[[gates.costs]]
type = "XP_POINTS"
amount = 100


経験値ポイントを消費します。

XP_LEVELとは別物です。


------------------------------------------------------------
HEALTH
------------------------------------------------------------

[[gates.costs]]
type = "HEALTH"
amount = 4


プレイヤーHealthから指定値を減らします。

安全上、支払い後にHealthが0以下になる条件ではGateを開けません。

Minecraft内部値では通常:

2 Health = ハート1個

です。

amount = 4
なら通常ハート2個分です。


------------------------------------------------------------
HUNGER
------------------------------------------------------------

[[gates.costs]]
type = "HUNGER"
amount = 4


Food Levelから指定値を減らします。

MinecraftのFood Level最大値は通常20です。


------------------------------------------------------------
複数Cost
------------------------------------------------------------

例:


[[gates.costs]]
type = "XP_LEVEL"
amount = 5

[[gates.costs]]
type = "ITEM"
item = "minecraft:ender_pearl"
amount_mode = "FIXED"
amount = 2


この場合:

経験値5レベル
+
エンダーパール2個

の両方が必要です。


============================================================
9. RETURN Gate
============================================================

RETURN GateはOverworldへ帰還するGateです。


例:


[[gates]]
id = "return_gate_default"
display_name = "Return Gate"
enabled = true
gate_type = "RETURN"

frame_block = "minecraft:stone_bricks"
corner_block = "minecraft:emerald_block"

min_inner_width = 2
min_inner_height = 3
max_inner_width = 32
max_inner_height = 32

allowed_igniters = [
  "worlddimensionloader:basic_dimension_igniter",
  "worlddimensionloader:advanced_dimension_igniter",
  "worlddimensionloader:creative_dimension_igniter"
]

open_time_seconds = -1

[[gates.costs]]
type = "ITEM"
item = "minecraft:emerald"
amount_mode = "FIXED"
amount = 1


open_time_seconds = -1 のため永久開通です。

ただし、永久GateでもフレームやPortal構造が壊れた場合は
WDLがGate Sessionを終了します。


============================================================
10. Gate Lifecycle / 壊れたGateの扱い
============================================================

OPEN中のGateは、
フレーム・角・Portal内部の整合性を監視します。

次のような場合:

・必要なframe_blockを破壊
・corner_blockを破壊
・WDL Portal Blockを破壊 / 置換

Gateは無効と判定されます。

その場合:

Portal削除
→ Active Gate Session解除
→ Gate完全Close

となります。


Portalだけを破壊して内部OPEN状態が永久に残る、
という動作を防ぐため、
Igniter使用時にもstale OPEN状態を再検証します。

正常なフレームへ戻せば、同じGateを再び開通できます。


============================================================
11. Dimensional Anchor
============================================================

アイテムID:

worlddimensionloader:dimensional_anchor


WDL imported Dimension内で使用すると、
その位置・向きをDimensionのAnchorとして保存します。

以後、そのDimensionへの転移時はAnchorが最優先されます。


通常使用:
現在位置をAnchorとして登録

Shiftしながら使用:
そのDimensionのAnchorを解除


Overworldや通常の他MOD Dimensionでは登録できません。


登録済みAnchor確認:

/wdl anchors


============================================================
12. Return Scroll
============================================================

アイテムID:

worlddimensionloader:return_scroll


WDL imported DimensionなどからOverworldへ戻るためのアイテムです。

Overworldでは使用できません。


コストの決定:

dimensions.toml に xp_level_cost がある
  ↓
その値

ない
  ↓
common.toml
default_xp_level_cost


Creative Mode:
XP Levelコスト免除


dimensions.toml:

[dimensions.return_scroll]
enabled = false

にすると、そのDimensionではReturn Scrollを封印できます。


============================================================
13. Respawn設定
============================================================

common.toml:

[respawn]
mode = "OVERWORLD"
prefer_overworld_player_spawn = true
fallback_to_overworld_world_spawn = true


OVERWORLDモードでは、
WDL imported Dimension内で死亡した場合:

1. 有効なOverworld個人Spawn
2. Overworld World Spawn

の順でRespawn先を決めます。


Dimensionごとに:

[dimensions.respawn]
mode = "INHERIT"

OVERWORLD

VANILLA

を指定できます。


============================================================
14. 大量の外部ワールドを登録する場合
============================================================

WDLは、

「登録されているDimension数」

と

「現在LiveなServerLevel数」

を分離しています。


例えば:

WDL_custom_dimensions/
├─ world_001/
├─ world_002/
├─ world_003/
├─ ...
└─ world_300/

のように大量のワールドを登録しても、
Catalog登録時点ですべてをServerLevelとして常駐させる設計ではありません。


基本構造:

DimensionCatalog
  ↓
軽量なConfig / Path / Status情報

必要時のみ
  ↓
Lazy Mount
  ↓
ServerLevel


同時ロード数は:

[runtime]
max_loaded_dimensions = 4

で制限できます。


使用しなくなったDimensionを自動でUnloadしたい場合:


[runtime]
auto_unload = true
unload_delay_seconds = 300


を使用してください。


============================================================
15. WDLコマンド
============================================================

WDLコマンドは基本的に権限レベル2以上が必要です。


/wdl scan

Configを再読み込みし、
外部ワールドCatalogを再スキャンします。

設定変更後に最もよく使うコマンドです。


/wdl list

Catalogの各Dimensionと状態を表示します。


/wdl status

Catalog数、READY数、Loaded数、
Runtime設定などの概要を表示します。


/wdl anchors

登録済みDimensional Anchorを表示します。


/wdl loaded

STAGING / STAGED / LOADED /
MOUNT-QUEUED / UNLOAD-QUEUED /
VS-CLEANUP

などRuntime状態を確認します。


/wdl load <id>

指定した外部ワールドをRuntime用に準備します。


/wdl mount <id>

準備済みのDimensionをServerLevelとしてMountします。


/wdl unload <id>

指定したWDL DimensionをUnloadします。


/wdl tp <id>

すでにMount済みのWDL Dimensionへ直接Teleportします。

主に管理・テスト用です。


/wdl probe <id>

内部Runtime情報を確認する診断用コマンドです。


通常のプレイではGateがLazy Mountを行うため、
毎回 /wdl load や /wdl mount を手動実行する必要はありません。



============================================================
16. WDL標準アイテム / サバイバル入手方法
============================================================

WDL 1.0.0には、Gate起動・帰還・到着地点設定用の標準アイテムがあります。


------------------------------------------------------------
Basic Dimension Igniter
------------------------------------------------------------

ID:
worlddimensionloader:basic_dimension_igniter

用途:
Gateを起動する基本Igniter。

スタック:
最大16個

消費:
Gateの開通に成功すると1個消費されます。


クラフト:

    A
   EFE
    A

実際の3x3配置:

[ ][A][ ]
[E][F][E]
[ ][A][ ]

A = Amethyst Shard / アメジストの欠片
E = Ender Pearl / エンダーパール
F = Flint and Steel / 火打石と打ち金


テスト用コマンド:

/give @s worlddimensionloader:basic_dimension_igniter


------------------------------------------------------------
Advanced Dimension Igniter
------------------------------------------------------------

ID:
worlddimensionloader:advanced_dimension_igniter

用途:
複数回使用できる上位Igniter。

最大耐久:
100

消費:
Gate開通成功時に耐久を1消費します。


クラフト:

[ ][D][ ]
[N][S][N]
[ ][D][ ]

D = Diamond / ダイヤモンド
N = Nether Star / ネザースター
S = Basic Dimension Igniter


------------------------------------------------------------
Creative Dimension Igniter
------------------------------------------------------------

ID:
worlddimensionloader:creative_dimension_igniter

用途:
Creative / 管理 / テスト用。

クラフト:
不可

使用回数:
無制限

取得例:

/give @s worlddimensionloader:creative_dimension_igniter


注意:
gates.toml の allowed_igniters には、
WDL以外のアイテムIDも明示的に登録できます。

ただしWDL 1.0.0が自動で消費 / 耐久減少させるのは
Basic / Advanced Igniterだけです。

Creative Igniterは無限使用です。
それ以外の第三者アイテムはWDL側では消費・損傷させません。


------------------------------------------------------------
Dimensional Anchor
------------------------------------------------------------

ID:
worlddimensionloader:dimensional_anchor

用途:
WDL imported Dimensionの到着地点を固定します。

消費:
なし


クラフト:

[ ][A][ ]
[E][C][E]
[ ][A][ ]

A = Amethyst Shard / アメジストの欠片
E = Eye of Ender / エンダーアイ
C = Compass / コンパス


通常使用:
現在位置 + yaw / pitch をAnchorへ登録

Shift + 使用:
そのDimensionのAnchorを解除


------------------------------------------------------------
Return Scroll
------------------------------------------------------------

ID:
worlddimensionloader:return_scroll

用途:
Overworldへ帰還します。

クラフト:
不定形レシピ

Book x1
Emerald x1

消費:
Return Scroll本体は消費されません。

XPコスト:
common.toml または dimensions.toml で設定します。


重要:
WDL 1.0.0の実装では、Return ScrollはOverworldでは使用不可です。
Overworld以外では帰還処理を試行します。

WDL imported Dimensionでは、
dimensions.toml のReturn Scroll個別設定
（enabled / xp_level_cost）が適用されます。


============================================================
17. よくある設定例
============================================================

------------------------------------------------------------
例1 : 1つのワールドへ固定接続
------------------------------------------------------------

selection_mode = "LIST"
dimensions = ["world_a"]


------------------------------------------------------------
例2 : 3ワールドからランダム
------------------------------------------------------------

selection_mode = "LIST"
dimensions = ["world_a", "world_b", "world_c"]


各Dimensionのrarity / weightによって抽選されます。


------------------------------------------------------------
例3 : 登録済みの使用可能Dimension全体からランダム
------------------------------------------------------------

selection_mode = "ALL"


READYで有効weightが正のDimensionから抽選します。

Gateが存在する現在のWDL Dimension自身は除外されます。


------------------------------------------------------------
例4 : レアDimension
------------------------------------------------------------

dimensions.toml:

[[dimensions]]
id = "secret_world"
rarity = "LEGENDARY"


common.toml:

LEGENDARY = 3


------------------------------------------------------------
例5 : rarityを無視して個別weight
------------------------------------------------------------

[[dimensions]]
id = "special_world"
rarity = "LEGENDARY"
weight = 50


この場合は50が使用されます。


------------------------------------------------------------
例6 : 同じフレームをIgniterで切り替える
------------------------------------------------------------

同一フレーム:

Basic Igniter
  → 普通のDimension Pool

Advanced Igniter
  → Rare Dimension Pool

のように設定できます。

この場合、allowed_ignitersが重ならないように設定してください。


============================================================
18. トラブルシューティング
============================================================

------------------------------------------------------------
Gateが開かない
------------------------------------------------------------

確認:

1. /wdl scan
2. /wdl list
3. 対象DimensionがREADYか
4. Gateのframe_block / corner_blockが正しいか
5. Gate内部サイズがmin/max範囲内か
6. 使用Igniterがallowed_ignitersに含まれるか
7. コストを所持しているか
8. LISTの場合、dimensionsに正しいIDがあるか
9. 現在Dimension自身しか候補に残っていない状態ではないか
10. latest.logに GATE_CONFIG_AMBIGUOUS がないか


------------------------------------------------------------
MISSING_FOLDER
------------------------------------------------------------

dimensions.tomlのfolderと、
実際のWDL_custom_dimensions内のフォルダ名を確認してください。


------------------------------------------------------------
MISSING_LEVEL_DAT
------------------------------------------------------------

外部ワールドフォルダ直下にlevel.datがあるか確認してください。


------------------------------------------------------------
Gate設定が競合している
------------------------------------------------------------

latest.log:

WDL GATE_CONFIG_AMBIGUOUS

を探してください。


競合している2つのGateについて:

・Igniterを分ける
または
・サイズ範囲を重ならないようにする
または
・frame / corner Blockを変更する

ことで解消できます。


------------------------------------------------------------
外部ワールドの新規Chunkが心配
------------------------------------------------------------

通常は:

strict_validation = true

を使用してください。

WDLはsource WorldGenSettings / LevelStemを利用し、
元ワールドのGeneratorを維持する設計です。

安全にDecodeできない場合にHost側Generatorを勝手に使用することを
避けたい場合は、strict_validation=trueを維持してください。


------------------------------------------------------------
大量登録時のメモリ使用量を抑えたい
------------------------------------------------------------

例:


[runtime]
max_loaded_dimensions = 4
auto_unload = true
unload_delay_seconds = 300


登録数とLive Dimension数は別なので、
必要以上にmax_loaded_dimensionsを大きくする必要はありません。



------------------------------------------------------------
専用サーバーでConfigを変えたのに反映されない
------------------------------------------------------------

確認:

1. 編集しているのがクライアント側ではなくサーバー側Configか
2. サーバールート/config/worlddimensionloader/ を編集しているか
3. 外部ワールドがサーバールート/WDL_custom_dimensions/ にあるか
4. /wdl scan をサーバー上で実行したか
5. /wdl list で状態が変化したか


------------------------------------------------------------
マルチプレイで参加できない / WDLアイテムが見えない
------------------------------------------------------------

WDLはクライアント・サーバー両方へ導入してください。

バージョン違いを避け、
同じWDL 1.0.0.jarを使用することを推奨します。


============================================================
19. 推奨初期設定
============================================================

初めて使用する場合は、
まず次のような保守的な設定を推奨します。


[general]
strict_validation = true
debug_logging = false

[paths]
dimension_root_folder = "WDL_custom_dimensions"

[runtime]
storage_mode = "AUTO"
max_loaded_dimensions = 4
auto_unload = false
unload_delay_seconds = 300
vs_remount_cooldown_ticks = 100

[respawn]
mode = "OVERWORLD"
prefer_overworld_player_spawn = true
fallback_to_overworld_world_spawn = true

[return_scroll]
default_xp_level_cost = 5

[rarity_weights]
COMMON = 100
UNCOMMON = 60
RARE = 25
EPIC = 10
LEGENDARY = 3


動作確認後、大量ワールドを使用する場合は:

auto_unload = true

へ変更する方法があります。


============================================================
20. WDL 1.0.0での重要仕様まとめ
============================================================

・外部ワールドは WDL_custom_dimensions に配置
・1ワールドにつき dimensions.toml の [[dimensions]] を1件登録
・Gateは gates.toml で完全に設定可能
・LIST / ALL の両方に対応
・rarity / weightによる重み付きランダム抽選
・個別weightはrarityより優先
・weight 0はランダム候補外
・Gate元のWDL Dimension自身はDIMENSION Gate候補から除外
・同じフレームに複数Gate定義を設定可能
・物理フレームサイズ + Igniterで一意にGateを解決
・曖昧なGate定義は安全のため両方無効化
・Gateコストは条件確認後にまとめて消費
・Gate破壊 / Portal破壊でActive Sessionも終了
・stale OPEN状態は自己修復
・Dimensional Anchorを転移先の最優先にできる
・Return ScrollのDimension別コスト / 封印に対応
・RespawnをOverworldへ戻す設定に対応
・大量登録とLive ServerLevel数を分離
・IMPORTがWDL 1.0.0の安定方式
・AUTOは1.0.0ではIMPORTを使用
・DIRECTは将来 / 実験用


============================================================
21. 最後に
============================================================

WDLは、外部ワールドを大量に登録しておき、
必要なDimensionだけをその都度利用することを目的にしています。

初めての方は、このREADMEの全項目を理解してから始める必要はありません。
まず1章のチュートリアルだけで1ワールドを動かし、必要になった設定だけ後から参照してください。

最初は1ワールド + 1Gateだけで動作を確認し、
その後に:

・複数Dimension
・LISTランダム抽選
・ALL抽選
・rarity / weight
・同一フレーム複数Gate
・Gate Cost
・Auto-Unload

の順に拡張すると設定しやすくなります。


問題調査時は、まず:

/wdl scan
/wdl list
/wdl status
/wdl loaded

を確認し、必要に応じてlatest.log / debug.logを確認してください。


World Dimension Loader (WDL) 1.0.0
End of Japanese README
