============================================================
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 項），改語言而重啓則再生成。

============================================================
structure_rules.json 格式
============================================================

{
  "rules": [
    {
      "biomes": ["minecraft:plains"],
      "dimensions": ["minecraft:overworld"],
      "nbt_file": "structures/my_structure.nbt",
      "chance": 0.2,
      "min_y": 60,
      "max_y": 70,
      "snap_to_surface": true,
      "allowed_rotations": [0, 90, 180, 270],
      "max_conflict_ratio": 0.2,
      "place_on_water": false,
      "dock_mode": false,
      "y_offset": 0,
      "underwater_mode": false,
      "clear_trees": false,
      "loot_table": ""
    }
  ]
}

============================================================
字段說
============================================================

biomes（必填）
  群系 ID 之陣列，原版及模組群系皆可。
  示例: "minecraft:plains", "terralith:highlands"
  當世不存之群系 ID 終不匹配。

dimensions（可選，默：諸維度）
  維度 ID 之陣列，僅於此諸維度生成。
  原版 ID: "minecraft:overworld", "minecraft:the_nether",
           "minecraft:the_end"
  闕或空則於諸維度生成。

nbt_file（必填）
  相對於 config/hxwi1structures/ 之 .nbt 檔案徑。
  須用原版結構方塊之格式。
  製法見下「NBT 結構檔案」節。

chance（必填）
  浮點數 0.0 - 1.0，每區塊生成之機率。
  0.0  = 永不生成
  0.05 = 百之五
  1.0  = 必生（群系合則生）

min_y / max_y（必填）
  生成高度之範圍（Y 座標）。
  僅 snap_to_surface 為否時用。
  原版高度限:
    主世: -64 至 319
    地獄:   0 至 255
    末地:   0 至 255
  min_y 須不大於 max_y。
  超越維度實際高度者自正。

snap_to_surface（可選，默：否）
  啟則略 min_y/max_y，直以結構底貼地。
  依 MOTION_BLOCKING_NO_LEAVES 高度圖。
  所在位地高逾世限則跳過。

allowed_rotations（可選，默：[0, 90, 180, 270]）
  允旋之度數。唯 0、90、180、270 四值有效。
  非法者（如 45、100、-90）於行時默作 0°。
  闕或空則於四角中隨機擇一。
  常用子集: [0], [0, 180], [90, 270]

max_conflict_ratio（可選，默：0.2）
  浮點數 0.0 - 1.0。主放置衝突之忍度。
  置前察結構圍盒中諸方塊之可覆數。
  不可替者（石、土、木等實體方塊），計為受阻。
  受阻之率逾此值則跳過。
  0.0 = 不容衝突（全平曠）
  0.2 = 忍百之二十（默，宜地表）
  0.5 = 忍半（糙地形）
  1.0 = 全略衝突之檢（強置，宜地下）

place_on_water（可選，默：否）
  僅 snap_to_surface 為是時效。
  啟則許結構生於水上。
  否則遇水面之位即跳過。
  宜水上平臺、碼頭、海構。

dock_mode（可選，默：否）
  啟則覆 allowed_rotations，自檢陸水之界而
  定方向。須 snap_to_surface 為是。
  法於四向掃之：前五格尋水，後三格尋陸。
  選陸水界最明之向為結構之向。
  四向皆無合界則跳過。
  宜碼頭、棧橋、濱構。

y_offset（可選，默：0）
  整數。Y 座標已定後加之垂移（在水下查前）。
  正數上移，負數下移。
  示例:
    -1  = 沉一格（船體半入水）
    -2  = 更深
     1  = 浮一格

underwater_mode（可選，默：否）
  啟則結構僅生於位上有水者（水下）。
  自 placementY 上察八格，尋水方塊。
  無水則跳過。
  宜水下遺跡、沉船、珊瑚、海帶。

clear_trees（可選，默：否）
  置前清結構圍盒中諸原木與樹葉。
  以原版 LOGS 與 LEAVES 標籤配之:
    - 原版諸木皆清
    - 用準標籤之模組木亦清
    - 他方塊不染
  清在衝突檢測之前，故衝突率甚低。

loot_table（可選，默：空）
  置後察圍盒中諸容器（箱、桶、潛影盒等），
  注戰利品表。留空則跳過。
  戰利品於玩家首開容器時生，
  種子為 worldSeed ^ blockPos（同位同世同物）。
  示例:
    "minecraft:chests/simple_dungeon"
    "hxwi1structures:chests/forest_cabin"
  自定戰利品表置於:
    data/hxwi1structures/loot_tables/

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

創模式下以結構方塊存:
  1. 置結構方塊
  2. 於其圍內營建
  3. 設方塊（名、大小諸項）
  4. 點「SAVE」
  5. 至:
     .minecraft/saves/<world>/generated/<namespace>/structures/
  6. 複 .nbt 檔案
  7. 貼至:
     .minecraft/config/hxwi1structures/structures/

亦可於 structures/ 下立子目錄分類:
  structures/overworld/houses/cottage.nbt
  structures/nether/fortress.nbt

NBT 檔案須為原版結構格式。
結構方塊所存者全兼容。

============================================================
生成之序
============================================================

1. 區塊載時，依 mod_settings.json 中 grid_interval
   驗之。唯 X 與 Z 皆為 grid_interval 之倍數者行。
2. 合者立入待處之列而返，不塞世之生成。
3. 列中之區塊於後續伺服 tick 逐批處之，
   每 tick 至多二區塊，以免滯。
4. 每區塊唯處一次（以 SavedData 存於磁，
   伺服重啓不復生）。
5. 規則依序查之，首合者停。
6. 每規則之序:
   a. 維度濾（若有）
   b. 區塊內隨機 XZ 位（0-15）
   c. 驗群系
   d. 機率
   e. Y 座標（貼地或 min-max 隨機）
   f. 旋角（自 allowed_rotations 擇）
   g. 中心點速敗檢測
   h. 全衝突掃（除非 max_conflict_ratio = 1.0）
   i. 越區塊界載
   j. 注戰利品表（若有）
   k. placeInWorld 置方塊

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

模組自設之件（非屬單結構）。

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

grid_interval（默：2）
  主區塊取樣之密。X % N == 0 且 Z % N == 0
  之區塊乃行。
   1 = 100%（區區察）
   2 = ~25%（默，棋格布）
   3 = ~11%
   4 = ~6%
  值愈大則結構愈稀，效愈高。

debug_logging（默：否）
  DEBUG 級日誌之總關。否則僅見
  INFO、WARN、ERROR；是則全詳。

============================================================
用技
============================================================

- 多規則為異群系創異構
- 稀構設低機率（0.01-0.05）
- 地下構（穴/牢）:
    "snap_to_surface": false,
    "min_y": -40, "max_y": -10,
    "max_conflict_ratio": 1.0
- 地表構（屋/塔）:
    "snap_to_surface": true,
    "max_conflict_ratio": 0.2
- 水上構（浮水面）:
    "snap_to_surface": true,
    "place_on_water": true,
    "max_conflict_ratio": 0.4
- 碼頭/棧橋（自面水）:
    "snap_to_surface": true,
    "dock_mode": true,
    "max_conflict_ratio": 0.6
    (NBT 構使向南延)
- 船體（半入水）:
    "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": true,
    "clear_trees": true,
    "max_conflict_ratio": 0.2
- 規則序定優先：重者在前
- 旋角唯 0、90、180、270 四值
- 配中無效規則跳過而記 WARN
- 全配壞則禁所有生成並記 ERROR
- 察問題時啓 DEBUG 日誌

============================================================
日誌
============================================================

INFO  - 配載、規則數、自生檔案
WARN  - 配字段闕誤、NBT 載敗、生時群系不存
DEBUG - 生嘗試、衝突跳、位選、群系不匹、隊列態
ERROR - 配檔讀敗、JSON 式誤

欲啓 DEBUG 日誌，設 mod_settings.json 中
"debug_logging": true。或需再設日誌框:
  <logger name="com.hxwi1.hxwi1structures" level="DEBUG"/>
