================================================================================
  Hxwi1Structures 模组 - 使用教程
================================================================================

一、快速开始
──────────────────────────────────────────────────────────────────────────────
1. 将模组放入 mods 文件夹，启动游戏
2. 自动生成默认配置：config/hxwi1structures/structure_rules.json
3. 示例 NBT 结构文件生成在：config/hxwi1structures/structures/
4. 进入世界，模组自动按规则在区块加载时生成结构
5. 输入 /hxwi1 config 打开可视化配置编辑器


二、文件结构
──────────────────────────────────────────────────────────────────────────────
config/hxwi1structures/
├── mod_settings.json          # 全局设置
├── structure_rules.json       # 结构生成规则
├── structures/                # NBT 模板文件夹（支持子文件夹）
│   ├── example.nbt
│   ├── dock_example.nbt
│   ├── forest_cabin.nbt
│   └── village/               # 子文件夹示例
│       └── house.nbt
└── backups/                   # 自动备份（保存配置时生成）
    └── structure_rules_20260602_153000.json


三、创建 NBT 结构模板
──────────────────────────────────────────────────────────────
方式一：游戏内结构方块
  1. 用 /give @p structure_block 获取结构方块
  2. 在要保存的建筑角落放置结构方块
  3. 设置名称、相对位置、大小，点击 SAVE
  4. NBT 文件保存在 world/generated/structures/
  5. 复制到 config/hxwi1structures/structures/

方式二：第三方工具
  可使用 Amulet Editor、WorldEdit schematics 等工具导出 NBT

方式三：/hxwi1 spawn 测试
  1. 将 NBT 放入 structures/ 文件夹
  2. 输入 /hxwi1 spawn <文件名> 手动生成到当前位置
  3. 按 Tab 自动补全文件名（支持子文件夹）


四、配置规则字段详解
──────────────────────────────────────────────────────────────
每条规则一个 JSON 对象，所有规则放在 "rules" 数组中。

【必填字段】
  生物群系      [数组]   例: ["minecraft:plains", "..."]
                        支持 #tag 格式: "#minecraft:is_forest"
  NBT文件      [字符串] 例: "structures/village/house.nbt"
  生成概率      [小数]   0.0 ~ 1.0
  最小Y        [整数]
  最大Y        [整数]

【可选字段 - 地形匹配】
  贴合地表   [开关] 默认 关
  贴合水面   [开关] 默认 关
  水下模式   [开关] 默认 关
  清除树木   [开关] 默认 关
  码头模式   [开关] 默认 关（自动检测水面边缘朝向）
  平整地表   [开关] 默认 关（必须填写填充方块内容）

【可选字段 - 空间控制】
  Y偏移         [整数]   正=向上，默认 0
  冲突比例       [小数]   0.0~1.0，默认 0.2
  最小区块间距    [整数]   默认 5（0=不限制）

【可选字段 - 旋转】
  旋转角度      [数组]   默认 [0,90,180,270]
  角度偏移      [整数]   修正 NBT 方向错误

【可选字段 - 其他】
  维度         [数组]   白名单，空=所有维度
  战利品表      [字符串] 例: "minecraft:chests/village_temple"
  启用生成      [开关]   默认 开（整合包调试用）


五、mod_settings.json 全局设置
──────────────────────────────────────────────────────────────
{
  "grid_interval":        2,       // 采样间隔：1=密集 2=25% 4=6%
  "debug_logging":        false,   // 调试日志开关（可避免调试日志刷屏）
  "commands_enabled":     true,    // /hxwi1 指令开关（隐藏配置入口）
  "max_backups":          2        // 最大备份数量（0=不备份）
}


六、指令参考
──────────────────────────────────────────────────────────────
/hxwi1 config           打开可视化配置编辑器（仅单人）
/hxwi1 reload           从文件重新加载规则（热重载）
/hxwi1 spawn <nbt文件>   手动生成结构到当前位置（测试用，仅单人）
                         例: /hxwi1 spawn village/house
                         按 Tab 显示可用的 NBT 文件列表
/hxwi1 biomeinfo         显示当前群系名称，并列出当前群系可以生成的结构


七、配置编辑器使用
──────────────────────────────────────────────────────────────
左栏：自动扫描 structures/ 文件夹，递归显示所有 .nbt 文件
      只显示相对路径名，如 "village/house"
      点击选中一个 NBT 进行编辑

右栏：可滚动编辑面板
      输入框：生物群系、NBT文件、概率、最小Y、最大Y、
              旋转角度、角度偏移、冲突比例、Y偏移、
              维度、战利品表、最小区块距离
      开关按钮：贴合地表、水面上、码头模式、水下模式、清除树木、启用生成
      保存按钮：保存 → 自动备份 → 自动重载

备份：保存时自动备份旧配置到 backups文件夹
      文件名含时间戳，数量超限自动删除最旧的


八、常见工作流
──────────────────────────────────────────────────────────────
调试模式：
  1. 将 mod_settings.json 中 grid_interval 设为 1
  2. 将目标规则的 chance 设为 1.0
  3. 用 /hxwi1 spawn <文件> 测试结构位置和方向
  4. 调整 rotation_offset 修正方向
  5. 满意后恢复原来的 grid_interval 和 chance

码头制作：
  1. 制作朝向东方的码头 NBT
  2. 设置 码头模式: true
  3. 模组自动检测水面边缘，将码头旋转到正确方向
  4. 模组会自动匹配前置与冲突选项自动开关

整合包制作：
  1. 关闭 启用生成 屏蔽正在调试的规则
  2. 每个结构建议设 最小区块距离 避免密集生成
  3. 用子文件夹组织 NBT（如 dungeons/、villages/）
  4. 修改 max_backups 数量保留更多历史配置
  5. 服务器部署时 commands_enabled: false 隐藏调试指令
