============================================================
Hxwi1Structures — User Guide
============================================================

This mod generates structures from JSON rules and NBT templates.


============================================================
1. Quick Start
============================================================
1. Put the mod in your mods folder, launch the game
2. Default config auto-generates at config/hxwi1structures/
3. Sample NBT files appear in structures/
4. Load a world — the mod picks rules and generates on chunk load
5. Type /hxwi1 config to open the visual config editor


============================================================
2. File Layout
============================================================
config/hxwi1structures/
├── mod_settings.json          # Global settings
├── structure_rules.json       # Generation rules
├── structures/                # NBT templates (sub-folders supported)
│   ├── example.nbt
│   ├── dock_example.nbt
│   ├── forest_cabin.nbt
│   └── village/               # Sub-folder example
│       └── house.nbt
└── backups/                   # Auto-backups (created on save)
    └── structure_rules_20260602_153000.json


============================================================
3. Creating NBT Templates
============================================================
Method 1 — In-game Structure Block
  1. /give @p structure_block
  2. Place it at a corner of your build
  3. Set name, relative position, size, then click SAVE
  4. Copy the .nbt from saves/<world>/generated/structures/
  5. Paste into config/hxwi1structures/structures/

Method 2 — Third-party tools
  Amulet Editor, WorldEdit schematics, etc. can export NBT.

Method 3 — /hxwi1 spawn testing
  1. Drop the .nbt into the structures/ folder
  2. Type /hxwi1 spawn <filename> to place at your position
  3. Press Tab to auto-complete (sub-folder aware)


============================================================
4. Rule Fields Reference
============================================================
Each rule is a JSON object; all rules go in the "rules" array.

【Required】
  Biomes       [array]   e.g. ["minecraft:plains", "#minecraft:is_forest"]
  NBT file     [string]  e.g. "structures/village/house.nbt"
  Chance       [0-1]     0.0 ~ 1.0
  Min Y        [int]
  Max Y        [int]

【Terrain Match】
  Snap to Surface     [toggle] default OFF
  Snap to Water       [toggle] default OFF
  Underwater Mode     [toggle] default OFF
  Clear Trees         [toggle] default OFF
  Dock Mode           [toggle] default OFF (auto-detect water edge)
  Flatten Ground      [toggle] default OFF (requires Ground Block)

【Spatial Control】
  Y Offset            [int]    positive = up, default 0
  Conflict Ratio      [0-1]    0.0 ~ 1.0, default 0.2
  Min Chunk Distance  [int]    default 5 (0 = no limit)

【Rotation】
  Rotations           [array]  default [0,90,180,270]
  Rotation Offset     [int]    corrects NBT orientation

【Other】
  Dimensions          [array]  whitelist, empty = all
  Loot Table          [string] e.g. "minecraft:chests/village_temple"
  Enabled             [toggle] default ON (modpack debugging)


============================================================
5. mod_settings.json — Global Settings
============================================================
{
  "grid_interval":        2,       // sample rate: 1=dense 2=25% 4=6%
  "debug_logging":        false,   // debug log toggle
  "commands_enabled":     true,    // /hxwi1 command toggle
  "max_backups":          2        // max backup count (0=off)
}


============================================================
6. Commands
============================================================
/hxwi1 config           Open visual config editor (single-player)
/hxwi1 reload           Hot-reload rules from file
/hxwi1 spawn <nbt>      Manually place structure at your position
                         e.g. /hxwi1 spawn village/house
                         Press Tab for NBT file suggestions
/hxwi1 biomeinfo         Show current biome & matching structures


============================================================
7. Config Editor
============================================================
Left panel — auto-scans structures/ recursively for .nbt files
             displays relative path, e.g. "village/house"
             click to select and edit

Right panel — scrollable edit area
  Inputs: Biomes, NBT file, Chance, Min Y, Max Y,
          Rotations, Rotation Offset, Conflict Ratio, Y Offset,
          Dimensions, Loot Table, Min Chunk Distance
  Toggles: Snap to Surface, On Water, Dock Mode,
           Underwater Mode, Clear Trees, Enabled
  Save button: Save → auto-backup → auto-reload

Backups — auto-saved to backups/ folder, timestamped,
          oldest pruned when count exceeds max_backups


============================================================
8. Workflows
============================================================
Debugging:
  1. Set grid_interval to 1 in mod_settings.json
  2. Set the rule's chance to 1.0
  3. /hxwi1 spawn <file> to test position and rotation
  4. Tune rotation_offset to fix orientation
  5. Restore original grid_interval and chance when done

Dock creation:
  1. Build dock NBT facing east
  2. Set Dock Mode to true
  3. The mod auto-detects the water edge and rotates the dock
  4. Conflicting options auto-toggle

Modpack authoring:
  1. Disable Enabled for rules still being tuned
  2. Set Min Chunk Distance on every structure
  3. Organise NBTs with sub-folders (dungeons/, villages/)
  4. Raise max_backups for extra history
  5. Set commands_enabled: false on servers to hide commands
