Proc-8：从八份建筑参考
到共享生成与验证库

# Task: Shared Procedural Architecture and Validation Library Build a reusable Python library for generating and validating furnished Minecraft Java 1.21.1 buildings and their immediate sites. Users must be able to write short, high-level client programs that compose the library's abstractions to generate a wide variety of complete, attractive, logically sound buildings. The eight `exp8` references below establish the intended architectural range and quality bar. The main deliverable is the shared generation and validation library, together with lightweight example clients, generated samples and tests. The library may be large and sophisticated. User code must remain small, readable and architectural: it describes what to build, while the library handles how to realize and verify it. Users explicitly control the seed. Do not introduce a building-family selector, a reference-name dispatch API, or an eight-preset generator. The references are examples from which to derive reusable abstractions, not an enumeration of supported building types. A new building should be expressible by a new composition of the public API, without adding a named building type or editing the library's core dispatch logic. Maximize the variety of buildings expressible through these compositions and their seeded parameter choices, while keeping generated samples within the reference distribution and satisfying the quality requirements below. One example invocation produces one dwelling or coherent property, such as a farmhouse with its farmyard. A thin `generate.py` client must preserve the harness contract: running it without arguments produces `output.litematic`. ## Eight references Exactly one final generator from each named `runs/exp8` run is supplied: | Reference | Source code | Original reference image | | --- | --- | --- | | mediterranean-villa | `references/mediterranean-villa/generate.py` | `reference_mediterranean_villa.jpg` | | merchant-manor | `references/merchant-manor/generate.py` | `reference_merchant_manor.jpg` | | red-roof-farmstead | `references/red-roof-farmstead/generate.py` | `reference_red_roof_farmstead.jpg` | | root-house | `references/root-house/generate.py` | `reference_root_house.jpg` | | sandstone-cottage | `references/sandstone-cottage/generate.py` | `reference_sandstone_cottage.jpg` | | stilt-water-cabin | `references/stilt-water-cabin/generate.py` | `reference_stilt_water_cabin.jpg` | | stilted-manor | `references/stilted-manor/generate.py` | `reference_stilted_manor.jpg` | | stone-cottage | `references/stone-cottage/generate.py` | `reference_stone_cottage.jpg` | `references/README.md` records provenance and SHA-256 hashes. These are the exp8 building references, not the ref-1 through ref-8 lodge set. Inspect all eight generators and images before choosing your procedural design. Images establish intended appearance; source code supplies implementation examples. Hidden sides and interiors must be complete. Text overlays, logos and presentation borders in the images are not architectural features to reproduce. This distribution contains several distinct architectural families, not one uniform lodge style: - **Mediterranean villa:** white plaster, blue or turquoise accents, tiled roofs at different heights, offset volumes, upper and lower terraces, open pergolas and a garden pool. The image includes furnished floor plans. Learn their circulation and domestic room relationships without freezing their exact layout. - **Merchant manor:** a stone undercroft, an elevated entrance terrace and exterior stair, timber and pale infill above, steep dark roofs, tower or spire accents, and a market stall with trading and storage spaces. - **Red-roof farmstead:** a timber farmhouse with a steep red roof and pale trim, dormer or cupola details, a furnished loft, and a composed working plot with a path, well shelter, fields and a small windmill. - **Root house:** an organic dwelling integrated into a hill and spreading dark timber roots. Vary the trunk and root silhouette, exposed stone, entrance recess and hollowed room layout. It must read as an inhabited root formation, not a conventional rectangular house with decorative logs attached. - **Sandstone cottage:** a broad pale roof with dark timber ridge and eaves, framed walls and a projecting entrance bay, a stair climbing the slope, a partly buried lower floor, and a waterside approach or jetty. - **Stilt water cabin:** a compact timber dwelling raised on posts over visible shallow water, a low overhanging gable, a railed deck, steps to a landing and a mooring, with a functional fishing cabin interior. - **Stilted manor:** a recessed stone ground floor, a genuinely overhanging timber upper floor carried by posts and braces, tall windows, a very steep roof, dormers and a cupola, with usable stacked interiors. - **Stone cottage:** a small, restrained stone-and-timber dwelling with a simple pale gable, recessed entry, framed windows and planters, a furnished main room and an optional usable loft. Preserve compact examples. Keep scale, proportions and detail comparable to the relevant references. A compact cottage should remain compact; a manor may be taller and more complex. Preserve the distinction between posts over water and posts supporting an overhanging manor, and between an earth-sheltered home and an ordinary masonry cellar. Use the supplied code as implementation reference. You may reuse and adapt useful geometry routines, but extract a coherent library of parameterized rules and components. All eight references must inform the library's capabilities. Demonstrate their architectural characteristics with lightweight compositions of the same public API, and demonstrate new compositions beyond those eight examples. Choose abstractions that separate architectural intent from geometric implementation. Possible concepts include sites and terrain relationships, connected volumes, levels, room programs, circulation constraints, envelopes, roof systems, support systems, attachments, material roles and furnishing policies. Users should combine such concepts rather than choose a complete building by name. Specialized geometry algorithms for roots, pitched roofs, earth sheltering or stilt supports are appropriate reusable capabilities. For example, a client could describe connected volumes on a slope, assign living and workshop spaces, request a pale pitched roof and a supported waterside deck, then generate and validate with a chosen seed. Another client could compose a recessed masonry base, an overhanging timber level and a steep roof with usable attic space. The library must resolve dimensions, joins, supports, openings, stairs, furnishing and clearance. These describe API intent, not required class names or a prescribed framework. Compositions must remain architecturally coherent. Do not require arbitrary feature mixing or put every motif in every sample. Preserve the references' different identities, proportions and scales through component rules and constraints, without encoding each whole reference as a hidden fixed-building script. 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. Ignore property order only; changed names, values or explicit property sets must still fail. ## Objective: maximize valid architectural variety The quantity to maximize is the number of meaningfully different, valid building types expressible by the library's high-level compositions and 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, pergolas, decks, terraces, market stalls and other compatible extensions. - Root and hill envelopes, recessed or overhanging storeys, stilt arrangements and water relationships. - Site organization: paths, farmyards, fields, wells, windmills, pools, landings and working outdoor spaces. - 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. The public API must support both explicit architectural decisions and bounded seeded choices for unspecified or intentionally variable decisions. A lightweight client should be able to define a design space, not merely one fixed building with random texture. Seeded generation must exercise structural choices within that client's declared constraints; it must not silently discard explicit user intent. Document sampling domains and compatibility rules. The example collection must explore the breadth of the eight references and new coherent combinations, without relying on a family-selection switch. ## Public API and lightweight client code - Provide an importable Python package with a documented public API for design composition, seeded generation, validation and export. Calling it must not require the harness CLI or reference scripts. - Users express architectural intent: spatial relationships, room functions, scale or proportion ranges, roof and support rules, site conditions and desired extensions. Avoid requiring absolute block coordinates, voxel placement loops, blockstate manipulation, geometry repair or NBT handling in ordinary client code. - Put substantive planning, constraint resolution, geometry, furnishing and correctness checks in the shared library. Client programs should mostly declare a design and call generation, validation and export. Do not hide long building-specific implementations in example helper files and call the entrypoint thin. - Keep client code genuinely lightweight, but do not code-golf or impose an arbitrary line-count target. Favor a few understandable architectural declarations with sensible defaults over huge configuration dumps, opaque serialized plans or a parameter list that exposes every internal implementation detail. - A short call that selects a prebuilt house is not sufficient abstraction. The API must let users compose new spatial arrangements and combine reusable capabilities without rewriting geometry or validators. - Validation is a reusable public library capability, not assertions embedded in the example clients. It must inspect a generated build and its relevant design constraints and return useful diagnostics, including failed rules and affected components or locations. Support validation of reloaded exports with explicit design metadata where needed; do not rely on hardcoded coordinates for individual examples. - Make extension points clear: adding a reusable component or rule should integrate with shared planning, spatial reservations and validation. Choose abstractions that actually serve the supplied and novel examples; an elaborate framework with weak generated results does not satisfy the task. ## Program design Do not optimize for library code length or worry about how many files or lines its implementation needs. Write as much shared implementation as the result requires, while keeping user programs high-level and lightweight. 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: a high-level user specification and seed -> a resolved building plan -> structural geometry -> Minecraft blocks -> validation and export. Keep architectural intent, planning decisions and block placement separate, and retain enough metadata for diagnostics and reproduction. - 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 compositional architectural API or small embedded DSL: clients describe relationships and constraints, while reusable rules infer the detailed geometry. Support both concrete choices and bounded variation. - A shared component protocol: reusable roofs, root envelopes, supports and terrain adapters declare their inputs, attachment interfaces and validity rules, so users can combine capabilities without selecting a whole-building family or duplicating fixed-building scripts. - 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. ## Library and harness contract - `python generate.py` is a lightweight example client that uses the public library API to generate, validate and export 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. - Every example client lets the user supply a seed and uses the same shared generation and validation API. The default client does not need to represent the entire design space by itself; the library and its composable API must support the breadth demonstrated across clients. - Record each sample's client or design specification, seed and resolved architectural choices so the result can be inspected and reproduced. Document parameter domains and how users express relationships, constraints and seeded variation in their own code. - 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. For a supported, satisfiable client specification, the library's sampler must produce valid configurations within that specification's constraints. - 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 building for most seeds. Do not silently change the user's architectural requirements to recover from failure; reject contradictory specifications with actionable diagnostics. - Reused implementation should live in the delivered library modules. Running the finished clients 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 build must satisfy them. Architecture and aesthetics - Preserve the relevant references' recognizable architecture, balanced proportions and composed silhouettes. Frame, infill, foundation, roof, roots and terrain 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 dwelling. Layout must respond to the sampled building. - Compose the whole property: farmyard elements, market spaces, terraces and docks need appropriate space, access and visual hierarchy. An open pergola is distinct from an enclosed roof; a windmill needs clear space for its sails; roots and earth must leave a usable, sealed interior. Site features must adapt to the plan rather than occupying identical fixed coordinates in every sample. 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. For water sites, provide an accessible landing and a continuous usable deck route to the door. Terrain, terraces, supports and foundations must meet without floating joins. Stilt supports must reach the waterbed or ground, overhangs must be supported, and water or hillside material must not invade rooms. - 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 client or the easiest composition. Choose a finite, diverse seed corpus and targeted client specifications that cover every major architectural capability, domain boundaries and difficult component 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 the public API and shared validators: determinism, bounds, valid states, support and multi-block consistency, room and level reachability, headroom, envelope integrity and clear openings. Exercise the same library through multiple independent lightweight clients. - Verify that validators reject deliberately broken geometry, such as blocked stairs, unsupported features and mismatched door halves, with meaningful diagnostics. Passing checks on valid examples alone does not show that the validation library detects defects. - Demonstrate API composition by adding new lightweight clients after the shared abstractions are in place, combining existing capabilities into buildings beyond the eight references without changing library code. Check that these clients need no custom geometry routines, validator copies or block-level repairs. - 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. Include variation across seeds of one client specification and across distinct client compositions. Different client names alone are not evidence of procedural variation. Exclude material noise and incidental vegetation from structural 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. - Supply a lightweight client composition demonstrating the architectural characteristics of each of the eight references, with at least two seeds per client producing meaningful structural or layout changes. Also include novel compositions using the same library. Cover compact and large examples, difficult roof joins, roots around rooms, buried floors, stilt supports and indoor/outdoor circulation with targeted cases. - Render a representative spread covering all eight references and novel compositions 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`: - An importable Python package: the shared procedural generation and validation library. Choose a clear package name and module structure. Keep the public architectural API separate from implementation details. - `generate.py`: a lightweight default client using that public API, rerunnable from a clean directory with the library available as documented. The standard toolset seeds a writable `generate.py` with placement, export and reload helpers; move reusable implementation into the library as needed. - `examples/`: lightweight, runnable client programs demonstrating all eight reference architectures and additional new compositions. Each accepts a user-controlled seed. They must demonstrate the actual public abstractions rather than call hidden whole-building presets. Provide batch generation instructions. - `output.litematic`: the default client's default-seed build. This exact path remains the harness contract. - `GENERATOR.md`: library quickstart, public API, short client examples, parameter domains and dependencies, seed and sampling behavior, validation API and diagnostics, extension points and design rationale. Explain how the eight references motivated reusable abstractions and how users compose new buildings without modifying the library. Include validation commands and known limitations. Do not compute the total combination count. - `samples/`: a finite, representative collection of generated builds, with client/specification, seed and resolved parameters recorded in a manifest. Provide a rerunnable command or script for the sample batch. - `test/test_*.py`: passing tests covering the public library, shared validators and varied client compositions. - `previews/`: labeled exterior renders and cutaways for representative samples. Spend the budget on the shared library, clear abstractions, lightweight clients, 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`.

# A new composition: three connected masses frame a sheltered entrance court. from hearthwright import Attachment, Choice, Design, Join, Level, Materials, Roof, Site, Volume from hearthwright.cli import run DESIGN = Design( 'Three gables court', volumes=( Volume('hall', width=Choice(23, 25), depth=Choice(11, 13), levels=(Level( ('living', 'kitchen', 'study')), Level(('sleeping', 'storage'), layout='cross')), roof=Roof(ridge='x', pitch=.5)), Volume('work', width=9, depth=Choice(11, 13), join=Join('hall', 'south', 'front'), levels=(Level(('workshop', 'storage')),), roof=Roof(ridge='z', pitch=1.0)), Volume('guest', width=9, depth=Choice(11, 13), join=Join('hall', 'south', 'back'), levels=(Level(('sleeping', 'study')),), roof=Roof(ridge='z', pitch=1.0)), ), materials=Materials(wall='plaster', frame='spruce', roof='slate', accent='blue'), site=Site(margin=3, planting='sparse', paving='yard'), attachments=(Attachment('porch', 'hall', width=5, depth=3, cover='pergola'),), ) if __name__ == '__main__': run(DESIGN)