solvecraft/docs/render-materials

SolidCraft rendering and appearance catalog — v0.2

An English, clean-room product specification for the personal render/materials fork.

This contribution defines what to build and how to verify it: 600 appearance concepts, 280 lighting recipes, 280 environments, 120 renderer capabilities, 56 UX requirements and 36 requirements for a future animation and dynamics module. It also supplies numeric preset specifications, scene combinations, current-contract setup examples, and native SELENE reconstruction and validation tools.

The preset set contains 82 future specifications: 10 quality profiles, 24 studio rigs, 24 environment recipes and 24 complete scene combinations. Six additional current-contract setup examples and six analytic physics fixtures support integration and review.

The catalog is a content and implementation backlog. Its entries are not installed shaders, HDR maps, measured materials, completed terrain assets or evidence of renderer support. The numeric recipes have the status specified_unbound: an executor adapter, resources and validation are still required. No production renderer or animation code is changed by this package.

Start here

Document	Purpose
Catalog index	Browse every material, lighting recipe and environment by stable ID and family.
Materials guide	Domain coverage, appearance authoring and SELENE material roles.
Lighting guide	Light recipes, contribution ownership and studio presets.
Environments guide	Procedural stages, lunar environments and environment presets.
Preset contract	Quality tiers, composition rules, units and runtime availability.
UX plan	A few-click workflow with deeper controls available in context.
UI integration	Exact alignment with the implemented SolidCraft redesign: ribbon groups, existing icons/tokens, library, inspector, responsiveness and accessibility.
Renderer plan	Quality foundations, expensive features and evidence for competitive claims.
SELENE	Improved showcase source selection, lunar stills, model upgrades and future sample-handling dynamics.
Native SELENE package	Pinned source, functional derivative, native verification and render preparation, plus the broader appearance/scene specifications.
Implementation handoff	Integration tasks, boundaries, priorities and acceptance gates.
Clean-room record	Authorship, sources, exclusions and future asset-admission rules.
Sources	Public specifications, scientific facts and pinned project references.

Machine-readable source of truth

materials.json, lighting.json and environments.json hold the concept inventory. capabilities.json, ux.json, simulation-requirements.json and roadmap.json hold requirements and sequencing. quality-presets.json, studio-presets.json, environment-presets.json and scene-presets.json hold future preset intent. baseline-setup-commands.json contains six examples using the already documented render.settings.set shape. selene-bindings.json retains the historical v7 inventory only; the active improved source is selected by assets/render/selene/source-lock.json. Meanwhile, lunar-physics-fixtures.json contains analytic checks for future simulation work.

The UI integration contract pins 21 project source files across the fixed integration base and the observed 0.18.4 design reference. It records current command/icon mappings, proposed groups, disclosure, quality recommendations and twelve acceptance cases. It registers no UI or commands.

JSON is authoritative for identifiers, counts and recipe values. Markdown explains policy and provides a readable index. Python scripts are optional development tooling for authoring and validation; they are not an application runtime or a proposed replacement for SolidCraft's Rust implementation.

Run the package validator from the repository root:

python3 docs/render-materials/validate_catalog.py

It checks data and specification consistency. It does not execute the render engine, measure a material, simulate granular mechanics or establish photorealism.

Identity and scope

Existing MAT-001–MAT-200, LUZ-001–LUZ-200 and ENV-001–ENV-200 retain their semantic identity from the earlier planning inventory. The LUZ prefix is retained as a stable identifier; all names, descriptions, documentation and UI wording in this package are English. New material families occupy MAT-201–MAT-600; lighting and environments extend through 280.

P0 means foundational or first-pack candidate, P1 means expansion after the foundation, and P2 means specialized or later work. Priority is a planning judgment, not availability. Low/Medium/High cost is a relative authoring/rendering estimate, not a hardware benchmark. Dependency lists express minimum intended capabilities and must be refined when a recipe is bound to a concrete executor.

The first shipped pack should be smaller than the full inventory: select approximately 40–60 verified appearances, 20–30 rigs and 20–30 environments, then expand by validated family. The catalog target of 1,160 content concepts must never be presented as 1,160 production-ready assets.

Design decisions

• Keep engineering material, render appearance, and simulation/contact properties independent and explicitly linked when appropriate.
• Preserve real CAD dimensions in millimeters, angles in radians and Z-up orientation. Convert once at a documented SI physics boundary.
• Use one scene description across preview, final output and automation, with visible differences when an executor supports less.
• Give each lighting contribution one owner. A luminous surface and a sampling proxy must not emit twice.
• Save recipes as versioned resources, instance overrides and an immutable resolved render request.
• Prefer procedural, original assets for the foundation. AI can propose source maps or backgrounds; each output still needs provenance, material reconstruction and validation.
• Build the SELENE still before the animation module. A strong still provides a material, geometry, color and light reference for later frames.

Repository placement

The requested integration base is 0xlillith/solidcraft, branch lab/render-materials, inspected at 93a2922c5ee272fb605703ae84c05825b4a74607. The catalog work is isolated in docs/render-catalog-selene, tracked by issue #2 and PR #3. The native SELENE continuation is isolated in showcase/selene-functional, based on catalog commit 10ada1b45a4eb285ce752ac72f9aaa968ff8b5c4.

The implementation already under way in the other thread remains the authority for runtime behavior. Resolve this specification against the code that actually lands there; do not infer support from the existence of a catalog row.

Prepared resource continuation

The SELENE package contains original numerical appearance recipes, reviewable scene configuration and the current native reconstruction workflow. Its opaque PBR projections can be inspected through the supplied swatch command script. Advanced optics, terrain generators and final-quality output remain gated on actual executor support and validation.

The owner supplied the improved SELENE-showcase.solidcraft. The source lock is now pinned_native; SOURCE.md records its exact hash, author provenance, retained notices and runtime compatibility. The current native work adds mechanism improvements and a Raspberry Pi 5 visual reconstruction through reproducible SolidCraft commands. The native validation record identifies the saved derivative, executor, completed checks and remaining limits. The broader catalog remains unbound, and historical v7 remains excluded as a substitute.