============================================================
Hxwi1Structures - 使用教學
============================================================

本模組透過 JSON 設定與 NBT 範本檔案來生成結構，
不內建任何結構。

============================================================
檔案位置
============================================================

  設定:   .minecraft/config/hxwi1structures/structure_rules.json
  選項:   .minecraft/config/hxwi1structures/mod_settings.json
  NBT:     .minecraft/config/hxwi1structures/structures/
  教學:   .minecraft/config/hxwi1structures/readme.txt

首次啟動時，模組會自動建立:
  - mod_settings.json  網格取樣與日誌設定
  - structure_rules.json  含三條範例規則
  - structures/example.nbt  石磚小屋
  - structures/dock_example.nbt  木製碼頭
  - structures/forest_cabin.nbt  原木小屋
  - readme.txt  本檔案

readme 語言隨遊戲語言自動切換（偵測 options.txt
中的 lang 項），更改語言後重啟即生效。

============================================================
欄位說明
============================================================

biomes（必填）
  生態域 ID 陣列，支援原版與模組生態域。
  範例: "minecraft:plains", "terralith:highlands"

dimensions（可選，預設：全部維度）
  維度 ID 陣列，僅在指定維度生成。
  原版 ID: "minecraft:overworld", "minecraft:the_nether",
           "minecraft:the_end"
  留空則在所有維度生成。

nbt_file（必填）
  相對於 config/hxwi1structures/ 的 .nbt 檔案路徑。
  NBT 檔案須使用原版結構方塊格式。

chance（必填）
  浮點數 0.0 ~ 1.0，每個區塊的生成機率。

min_y / max_y（必填）
  生成高度範圍（世界 Y 座標）。
  僅在 snap_to_surface 為 false 時使用。
  主世界高度: -64 至 319
  地獄高度:   0 至 255
  min_y 必須 <= max_y。

snap_to_surface（可選，預設: false）
  啟用時忽略 min_y/max_y，直接將結構底部貼合地表。
  使用 MOTION_BLOCKING_NO_LEAVES 高度圖。

allowed_rotations（可選，預設: [0, 90, 180, 270]）
  允許的旋轉角度陣列。僅接受 0、90、180、270。
  非法角度（如 45、100、-90）執行時靜默當作 0°。

max_conflict_ratio（可選，預設: 0.2）
  浮點數 0.0 ~ 1.0。控制放置衝突容忍度。
  放置前掃描結構包圍盒，統計不可替換方塊比例。
  超過此值則跳過放置。
  0.0 = 不允許任何衝突
  1.0 = 完全略過衝突檢測（強制放置，適合地下結構）

place_on_water（可選，預設: false）
  僅 snap_to_surface 為 true 時生效。
  啟用則允許結構生成於水面上。

dock_mode（可選，預設: false）
  覆蓋 allowed_rotations，自動偵測陸地-水面交界
  並確定方向。需要 snap_to_surface 為 true。
  適合碼頭、棧橋。

y_offset（可選，預設: 0）
  整數。Y 座標確定後的垂直偏移。
  正數上移，負數下移。

underwater_mode（可選，預設: false）
  啟用則結構僅生成於水下位置。
  從放置 Y 向上掃描最多 8 格尋找水方塊。

clear_trees（可選，預設: false）
  放置前清除結構包圍盒內的所有原木與樹葉。
  使用原版 LOGS 與 LEAVES 標籤。
  清除在衝突檢測之前執行。

loot_table（可選，預設: 空）
  放置後掃描包圍盒內所有容器（儲物箱、木桶等），
  注入戰利品表。留空則跳過。
  戰利品種子 = worldSeed ^ blockPos。

============================================================
使用技巧
============================================================

- 森林結構（自動清除樹木）:
    "snap_to_surface": true,
    "clear_trees": true,
    "max_conflict_ratio": 0.2
- 碼頭 / 棧橋（自動面向水面）:
    "snap_to_surface": true,
    "dock_mode": true,
    "max_conflict_ratio": 0.6
- 船體（部分浸入水中）:
    "snap_to_surface": true,
    "place_on_water": true,
    "y_offset": -1
- 水下遺跡:
    "snap_to_surface": true,
    "underwater_mode": true,
    "max_conflict_ratio": 0.8
- 地下結構（強制放置）:
    "snap_to_surface": false,
    "min_y": -40, "max_y": -10,
    "max_conflict_ratio": 1.0
- 帶獎勵箱的結構:
    "loot_table": "minecraft:chests/simple_dungeon"

============================================================
常見問題
============================================================

Q: 為什麼結構生成很少？
A: 預設 grid_interval 為 2，只覆蓋約 25% 的區塊。
   在 mod_settings.json 中設為 1 即可全覆蓋。

Q: 能使用其他模組的生態域嗎？
A: 可以，生態域 ID 在生成時透過原版註冊表動態解析。

Q: 如何除錯？
A: 在 mod_settings.json 中設 "debug_logging": true，
   查看遊戲日誌中的 [hxwi1structures] 輸出。

============================================================
NBT 結構檔案
============================================================

在創造模式下使用結構方塊儲存結構：
  1. 放置結構方塊並設定名稱與邊界大小
  2. 在邊界內建造結構
  3. 點擊「SAVE」
  4. 前往 .minecraft/saves/<世界>/generated/<命名空間>/structures/
  5. 複製 .nbt 檔案到 config/hxwi1structures/structures/

可建立子目錄分類管理，如：
  structures/overworld/houses/cottage.nbt

============================================================
生成流程
============================================================

1. 區塊載入時檢查 grid_interval，僅 X 與 Z 皆為倍數的區塊處理
2. 符合條件的區塊立即排入佇列並返回（不阻塞世界生成）
3. 佇列中的區塊在後續 tick 逐批處理，每 tick 最多 2 個
4. 每個區塊僅處理一次（SavedData 持久化，伺服器重啟不重複）
5. 規則依序檢查，首個成功的規則停止後續檢查
6. 每條規則依序執行：維度過濾 → XZ 選位 → 生態域檢查 →
   機率擲骰 → Y 座標 → 旋轉 → 樹木清除 → 衝突檢測 →
   跨區塊載入 → 方塊放置 → 戰利品表注入

============================================================
mod_settings.json
============================================================

{
  "grid_interval": 2,
  "debug_logging": false
}

grid_interval（預設: 2）
  區塊取樣密度。1=100%，2=~25%，3=~11%，4=~6%

debug_logging（預設: false）
  DEBUG 日誌總開關，排障時開啟
