# Task: Procedural Lodge Generator

Write a procedural generator for furnished Minecraft Java 1.21.1 lodges. Given a seed, it must generate a
complete, attractive, logically sound lodge drawn from the architectural distribution represented by
ref-1 through ref-8. Maximize the variety of buildings the program can generate while keeping every sample
within that distribution and meeting the quality requirements below.

The deliverable is a reusable generator with a large design space, together with generated examples and
validation. Running it without arguments must produce `output.litematic`.

## Eight references

Exactly one generator from each reference run is supplied:

| Reference | Source code | Original reference image |
| --- | --- | --- |
| ref-1 | `references/ref-1/generate.py` | `reference_ref-1.png` |
| ref-2 | `references/ref-2/generate.py` | `reference_ref-2.png` |
| ref-3 | `references/ref-3/generate.py` | `reference_ref-3.png` |
| ref-4 | `references/ref-4/generate.py` | `reference_ref-4.png` |
| ref-5 | `references/ref-5/generate.py` | `reference_ref-5.png` |
| ref-6 | `references/ref-6/generate.py` | `reference_ref-6.png` |
| ref-7 | `references/ref-7/generate.py` | `reference_ref-7.png` |
| ref-8 | `references/ref-8/generate.py` | `reference_ref-8.png` |

`references/README.md` records their provenance. Inspect all eight generators and images before choosing
your procedural design. They define a family, including compact woodland cottages, taller stacked lodges,
cross-gabled wings, tower compositions, cliff or terrace settings, inns, and a conservatory extension.
Learn their shared architectural language and their differences: massing, proportions, roof silhouettes,
timber and plaster framing, stone foundations, room organization, approaches, planting and warm lighting.
Keep the scale and detail comparable to the references. Hidden sides and interiors must be complete.

Use the supplied code as implementation reference. You may reuse and adapt useful geometry routines, but
build a coherent parameterized system that can compose new designs. Selecting one of eight fixed scripts,
or repainting a fixed floor plan, does not meet the objective. Each reference should inform reachable parts
of your design space, without requiring every lodge to contain every reference feature.

These are historical snapshots, not certified correctness examples. Fix any defects you reuse. In
particular, MCIO may reorder blockstate properties on reload. Compare parsed block names and property
mappings using the standard toolset's `blockstates_equivalent` helper when available. Raw string comparison
can report `changed on reload` even after a single write. Overwriting a coordinate is valid when its final
state is correct.

## Objective: maximize valid architectural variety

The quantity to maximize is the number of meaningfully different, valid building types expressible by the
program's parameter combinations. Think of the product of the choices across design parameters, subject
to their compatibility constraints. This space may be astronomically large. Do not calculate, estimate,
enumerate, or report its total size. Spend effort expanding the actual generative system instead.

Prioritize diversity in building structure and layout:

- Footprint topology, connected wings, their relative placement and proportions, setbacks and asymmetry.
- Floor counts, relative wing heights, towers, attics, and the hierarchy of major and minor volumes.
- Roof topology, ridge directions, pitch and profiles, cross-gables, dormers and their placement.
- Entrance position, circulation routes, stairs, room subdivision, adjacency and functional allocation.
- Porches, balconies, conservatories, terraces and other compatible extensions.
- Terrain relationships, foundations, retaining work, height transitions and the exterior approach.

Material families, color choices, weathering, planting and decorative variations also contribute, but have
lower priority than structure and layout. Preserve harmonious palettes and appropriate detail density.
Different seeds, names, unused parameters, duplicate presets, global rotations or translations alone do
not establish additional architectural types. Texture noise on the same building is only minor variety.
Simply making dimensions unbounded is not useful diversity: retain the references' human scale and quality.

Introduce parameters that change real geometry and can combine across multiple architectural decisions.
Make their domains and dependencies explicit. Independent choices multiply variety only when their
combinations remain valid. Use conditional domains and geometric constraints for dependent choices rather
than pretending every combination is compatible. Broaden the feasible design space instead of claiming
combinations the implementation cannot produce.

Seeded sampling must exercise these structural choices, not leave them fixed while randomizing texture.
Avoid overwhelmingly sampling a single topology or requiring lucky seeds to see major branches. Examples
should include new coherent combinations beyond replicas of the eight references.

## Program design

Do not optimize for code length or worry about how many files or lines the implementation needs. Write as
much code as the result requires. Judge success by the generated buildings' quality, correctness and
diversity across seeds. The code must still follow procedural design principles and remain extensible:
use reusable rules, parameterized geometry, explicit constraints and clear module responsibilities so new
building types and features can combine with existing ones. More code is acceptable when it improves the
results, but a growing collection of hardcoded buildings or seed-specific exceptions is not a procedural
solution. Do not sacrifice output quality to keep the implementation short.

Useful architectural patterns to consider, combine or adapt:

- A compiler-style pipeline: seeded design choices -> an explicit building plan -> structural geometry ->
  Minecraft blocks -> validation and export. Keep architectural decisions separate from block placement.
- A constrained building grammar: compose main volumes, wings, towers, roof systems and extensions through
  parameterized rules with compatibility conditions, drawing design patterns from all eight references.
- A room and circulation graph: plan room adjacency and vertical connections alongside the exterior massing,
  then realize and verify those connections in actual geometry.
- Parameterized components with connection interfaces: roofs, stairs, porches and towers declare their
  attachment points, occupied space, support requirements and clearance needs.
- A shared spatial reservation system: protect passages, doorways, windows and stair headroom so later
  roof, furnishing and decoration passes cannot obstruct them.
- Local constraint solving or bounded candidate refinement: resolve difficult layout and roof interactions
  at the planning level before committing to detailed block placement.

These are suggestions, not a required framework or a checklist of abstractions. Choose a structure that
supports a broad, coherent design space and makes quality across samples easier to achieve and extend.

## Generator contract

- `python generate.py` writes one region to `output.litematic` using a documented default seed.
- `python generate.py --seed INTEGER --output PATH` generates a reproducible sample at the requested path.
- Expose architectural parameters through a documented Python API or configuration interface. Record each
  sample's seed and resolved parameters so its design choices can be inspected and reproduced.
- Use seeded randomness for every random decision. The same seed and configuration must reproduce the
  same geometry and schematic bytes in the same environment. Follow the toolset's deterministic export rules.
- Derive bounds from the chosen design, including roofs, terrain, trees and other exterior features. Keep
  parameter domains and resource limits explicit and configurable. Never silently clip a building.
- Generation must work for arbitrary seeds in the documented seed domain, without seed-specific patches,
  manual repairs or a list of handpicked successful seeds. Reject invalid explicit parameter combinations
  with a clear explanation. The built-in sampler must produce valid configurations.
- Resolve compatibility during planning and construction. If retries are needed, bound them and provide
  a valid deterministic recovery strategy. Do not hang, emit broken buildings, or silently fall back to the
  same fixed lodge for most seeds.
- Reused implementation should live in the delivered generator modules. Running the finished program must
  not depend on dispatching to the eight reference scripts or downloading additional assets.

## Quality required for every sample

Treat architectural quality and correctness as constraints on the design space, not costs to trade away
for more parameter values. Every admitted combination and every sampled lodge must satisfy them.

Architecture and aesthetics

- Preserve the references' recognizable lodge language, balanced proportions and composed silhouettes.
  Frame, infill, foundation and roof materials must have coherent roles.
- Join wings, roofs and extensions intentionally. Roof intersections must be weather-tight, with sensible
  eaves and no accidental holes or protrusions through occupied rooms.
- Align openings and framing with usable rooms. Keep a clear entrance, believable supports and continuous
  foundations. Balance exterior detail, planting and negative space.
- Give all enclosed usable levels and rooms purposes and complete furnishings: sleeping, living, cooking,
  storage, work or other functions appropriate to that lodge. Layout must respond to the sampled building.

Geometry and usability

- Use valid vanilla Java 1.21.1 blocks and blockstates, entirely within the schematic bounds.
- Every room and occupied level is reachable from the exterior entrance through a continuous walkable
  route. Maintain at least two blocks of headroom, including over stair treads and at transitions.
- Stairs or ladders must be usable and supported. Exterior paths and stairs must connect actual ground to
  the entrance. Terrain, terraces, supports and foundations must meet without floating joins.
- Doors have matching upper and lower halves. Beds have adjacent matching heads and feet. Respect facing,
  attachment and support requirements for all multi-block furnishings and decorations.
- Keep circulation, doors and windows clear of furniture, roofs, chimneys and later decoration passes.
- Enclosed interiors must be weather-tight, with deliberate glazed windows and complete doors. Intentional
  open porches, balconies and exterior spaces remain distinct from enclosed rooms.
- Light every room near its usable floor, and provide coherent exterior lighting along the approach and
  around important features.

## Validate the system across its design space

Do not validate only the default lodge. Choose a finite, diverse seed corpus and targeted parameter cases
that cover every major architectural branch, domain boundaries, and difficult feature interactions.
Expand or repair the generator when these reveal failures. This is sampled and targeted validation, not
an exhaustive enumeration of the parameter space or proof that all combinations were tested.

- Write `test/test_*.py` tests for determinism, bounds, valid states, support and multi-block consistency,
  room and level reachability, headroom, envelope integrity and clear openings.
- Check actual placed or reloaded geometry. Declared room connections or planned stairs alone do not prove
  the final blocks are traversable after roofs and furnishing have been placed.
- Compare round trips semantically, ignoring property order while detecting changed names or properties.
- Check structural diversity in the sampled corpus using actual massing, roof or room-layout signatures.
  Distinct seeds or file hashes alone do not prove architectural variety. Report only observed sample
  diversity, never a speculative total number of possible buildings.
- Render a representative spread of structurally different seeds from multiple exterior views, with
  cutaways for interior circulation and furnishing. Inspect the images and fix visible problems. Do not
  present only cherry-picked successful builds while leaving reproducible failures unresolved.
- Keep tests bounded and repeatable. Temporary test artifacts belong under `test/` and must be cleaned up.

## Deliverables

All inside `/work/generator/workspace`:

- `generate.py` and any supporting modules: the procedural generator, rerunnable from a clean directory.
  The standard toolset seeds a writable `generate.py` with placement, export and reload helpers.
- `output.litematic`: the default-seed lodge. This exact path remains the harness output contract.
- `GENERATOR.md`: concise usage, parameter domains, dependencies, sampling rules and design rationale.
  Explain how all eight references inform the design space, how structural variation combines, and how
  constraints preserve quality. Include validation commands and known limitations. Do not compute the
  total combination count.
- `samples/`: a finite, representative collection of generated lodges, with seeds and resolved parameters
  recorded in a manifest. Provide a rerunnable command or script for the sample batch.
- `test/test_*.py`: passing tests covering the generator and multiple architectural configurations.
- `previews/`: labeled exterior renders and cutaways for representative samples.

Spend the budget on the procedural system, valid architectural diversity, renders and tests. Do not spend
it enumerating parameter products. State plainly what is complete and what remains unfinished.

Environment, available libraries and rendering tools are described in the workspace `AGENTS.md`.