Blacksite/docs/editor/material-system.md

Material System

Blacksite uses shared project materials and renderable-owned material slots. Primitives, static meshes, and skinned meshes expose the same assignment workflow, but retain separate geometry and hydration ownership. The permanent contracts are ADR 0035, ADR 0036, ADR 0046, and ADR 0047. Material authoring presentation follows the shared editor design system and ADR 0049.

Mental model

Concept	Owns	Saved?
Material asset	Reusable shader choice, render state, parameters, and textures	Yes, anywhere under assets/
Material instance	Overrides over one direct base material	Yes, anywhere under assets/
Material slot assignment	Only the actor/prefab override for a stable primitive or renderer slot	Yes, in scenes/prefabs
Imported source material	Read-only default supplied by model import	Yes, as the slot fallback
Model material selection	Source, project Material/Instance, or Default for one stable imported slot	Yes, in registry import metadata
Property block	Per-owner/per-slot runtime parameter and texture overrides	No
DefaultGrid	Immutable engine fallback for missing or unassigned surfaces	Engine built-in

A material slot assignment stores a MaterialRef, not a copy of the material. Model defaults and imported source selections stay asset-owned in import metadata and runtime manifests instead of being copied into actor overrides. Every primitive has one stable slot:primitive:surface; mesh renderers use imported stable slot IDs. The registry UUID and subasset ID identify the target; the cached path is only a loading hint. A material instance may reference a material, but may not reference another instance.

Resolution is strongest-first: property block, scene/prefab slot, model default, imported source, project default, then engine DefaultGrid. A broken explicit reference reports a diagnostic and uses DefaultGrid; it does not silently expose a weaker source assignment. Clearing an assignment is the explicit way to return to the next layer.

Property blocks are applied after base resolution and cached per owner/slot for both Standard and Surface materials, including above any sparse values already present on a selected Material Instance. They never mutate a shared Material asset and remain excluded from scene/prefab persistence. Unknown properties, schema/type/range mismatches, duplicate names, and broken texture references reject the complete block with a diagnostic while the resolved base stays visible. DefaultGrid cannot be edited, instanced, or used as a promotion base.

The editor registers this runtime-only component with Bevy reflection so trusted local BRP tooling can inject a block for debugging, gameplay integration, and promotion acceptance. Reflection does not make the component an authoring component: it remains absent from Add Component, excluded from scene/prefab serialization, and is never published by an asset save.

Surface evaluators specialize forward and deferred material fragments only. Bevy's standard shader remains authoritative for depth, normal, and motion-vector-only prepasses, so those passes never try to write a deferred G-buffer attachment that is not present.

When a selected primitive, static renderer, or skinned renderer has a runtime block, its exact material-slot card shows the override counts and Promote to Material Instance. Promotion requires an explicit project Material or direct-base Material Instance; imported source and DefaultGrid are intentionally rejected. Promote to Material Instance opens a review showing the selected/direct base, exact slot, sparse override counts, and collision-safe target path. The editor fingerprints the selected asset, direct base, schema, runtime block, slot assignment, and absent target while the review is open. Commit merges an existing instance's sparse values with the runtime block, creates one direct-base Material Instance in the current Content Browser folder, assigns it to that exact scene slot through one history transaction, and clears the runtime block only after file, registry, and assignment publication succeed. Cancel or any conflict leaves the block, registry, scene, and history unchanged.

Assign materials

Open Window > Material Library for the cross-folder Material/Material Instance catalog. It supports search, Material/Instance/scene-usage filters, grid/list thumbnails, dependency health, scene-reference counts, creation, drag sources, and the guarded shared-asset editor. It lives in the existing bottom dock and does not add permanent viewport chrome. Scene-usage rows select the exact actor, focus the viewport, and identify its renderer slot, primitive surface, or brush face.

Assign through either exact workflow:

1. Drag a Material or Material Instance from the Material Library or Asset Browser onto the desired viewport surface. A hydrated static/skinned draw targets its exact stable renderer slot, a primitive targets its stable surface slot, and a brush targets the exact face under the pointer.
2. Check the pointer card and target visual. Green names a valid actor/slot/face; red gives the blocking reason. Release commits one undoable assignment. Move away, leave the viewport, press Escape, or right-click to restore the pre-drag state without history or dirtying the scene.
3. Alternatively, select a primitive, static-mesh, or skinned-mesh actor and use its ordered Materials section. Each 82 px expanded or 52 px collapsed slot header is an assignment target; there is no adjacent drop box. A valid Material/Instance drag uses the active theme's selection highlight. A Texture drag highlights the target as invalid and explains that textures must be authored inside a Material. Locate reveals the current asset; Clear removes only the explicit assignment and restores the inherited model source, project default, or DefaultGrid.

From the Asset Browser, Apply Material assigns the selected material to a primitive surface or every material slot on each selected static/skinned renderer. This is the explicit bulk path. A viewport hit never silently broadens to all slots.

Direct Texture drops on primitive or mesh slots are rejected because slots store Material references. Brush faces retain their specialized direct texture path. Create or edit a Material or Material Instance, assign the texture there, then assign that asset to the slot.

Expand any shared slot to inspect the actual effective material. At the current 620 px wide reference the slot/body are 596/569 px; at the hard 420 px Inspector floor they are 396/369 px and six parameter rows reflow to 58 px two-line rows. Project Materials and Instances open the same asset-keyed editor used by the Content Browser. Valid parameter changes update blacksite_surface's live document overlay on every interaction frame; its single cache mutates the shared Standard or Surface handle in place, and there are no Apply/Revert buttons. The asset-keyed authored document becomes UNSAVED, survives selection changes, and performs no source write, Git refresh, watcher work, thumbnail invalidation, or processing when the pointer is released. Ctrl+S publishes the last edited context; Ctrl+Shift+S publishes every dirty editor document. Scalar, color, label, shader-value, emissive, and render-state saves queue no derived work; ARM/ORM binding changes queue one coalesced packing job. Create Instance and Assign transactionally publishes a direct-base instance and assigns only the current actor slot for local variation. Imported source parameters remain read-only; Extract Editable… opens extraction for that single source and assigns the resulting project Material only to the selected actor slot. The project default is expandable as inherited shared content. DefaultGrid is visible but read-only.

The final panel shows only Shader, Surface, Inputs, shared UV, and supported Advanced Inputs. Standard Lit stores seven inputs but reports six visible bindings: Emissive Intensity is a companion of Emissive color and is edited/restored through the same popup. Offset/Tiling changes affect every texture sampler on the Material in both Standard and Surface rendering; Material Instances may override them sparsely and Reset restores the base values. Texture fields open their picker on field click and expose Locate and Clear without a redundant folder action. Direct actor assignments do not receive an “Explicit” label. Source paths, fingerprints, stable IDs, orphan state, and provenance are secondary diagnostics in overflow rather than material parameters. The sphere preview and bounded 229.5 px reference identity live in the 82 px assignment block; preview, identity, and Browse open the compact current/recent Material menu without making Shader or action clicks assign anything. No second preview, drop box, or material-slot list is rendered.

Project textures are loaded from runtime-catalog sampling data rather than Bevy's default sampler. Repeat, Clamp, and Mirror map to Repeat, Clamp-to-edge, and Mirror-repeat for U/V/W; authored filtering and anisotropy apply to Standard, Surface/Solari, property-block bases, and project material previews. Packed AO/roughness/metallic sources must agree on filter, wrap, and anisotropy because their canonical ARM artifact has one sampler. A mismatch retains the previous valid material and reports a processing diagnostic. Imported glTF/FBX materials keep their loader-owned samplers.

See the Material Library and targeted-drop evaluation for the live preview, commit/undo, cancel, and source-verification record.

Static draw slots and material slots are separate. Removing a static draw retains its explicit material assignment as an orphan rather than guessing a replacement. Reimport also reconciles slots by stable ID, never by display name. Model Details can Locate the preserved project Material/Instance or Clear Orphan before applying the import settings; active project/default model selections likewise expose Locate and Clear, with Clear restoring Source.

Author shared assets

Material files and material-instance files are typed RON documents anywhere under assets/. The Material Library and Asset Browser identify the document kind, expose the same guarded schema-driven editor and texture bindings, and use stable subasset IDs (material:source or material:instance). Material Instance thumbnails resolve the direct base plus sparse overrides. Built-in shader schemas live under assets/shaders/.

Select a Material and use Create Instance to create a direct-base variant beside it. The instance inspector exposes its base Material plus sparse property and texture override checkboxes; unchecked values continue to inherit. Material instances cannot inherit from other instances. Material render state exposes Opaque/Cutout, alpha cutoff, and Double Sided in the base Material inspector.

Materials extracted from textual glTF remain ordinary editable project assets. The extraction review previews and can exclude each source material, shows converted PBR/render-state/texture coverage, and permits collision-checked project-path edits before one atomic publication. The same transaction assigns each affected stable model slot to the newly registered project Material; this is an explicit model default, not a live source link. Their Details card also shows read-only provenance: source asset path, source material label/stable index, and a BLAKE3 source fingerprint. A later extraction detects that stable provenance, shows whether the source revision, shader selection, render state, or converted PBR values differ, and requires Apply Reviewed Update or Create New Copy. Apply replaces the file only while its reviewed fingerprint still matches and rolls back exact prior bytes if the dependent model mapping cannot publish. Provenance is not a live link and never authorizes an automatic overwrite.

Every standard and shader-schema texture slot uses the project texture picker. Browse lists texture assets across the project, including imported model texture subassets, and a texture can be dragged from the Asset Browser directly onto a slot. Non-texture drops are ignored. Clear removes the base Material value; on a Material Instance it removes the sparse override so the slot inherits from its base again. Dropping or browsing a texture onto an unchecked instance slot creates the override automatically.

Schema-driven inputs and packed maps

Material schema v2 stores one canonical MaterialInputSet. Standard Lit and custom Surface shaders both describe their controls with MaterialInputSchema, so primitive, static-mesh, skinned-mesh, Content Browser, and Material Library editors render the same responsive rows. The exported 569 px section uses one fixed label/value/channel line beside its texture field; the 369 px section stacks the texture field beneath that line. A bounded transient fallback below 369 px moves Locate/Clear into overflow instead of allowing negative or out-of-clip geometry. Slot IDs, source paths, fingerprints, and usage counts are diagnostics rather than material parameters.

Routine visual iteration uses python scripts/editor/ui_gallery.py watch, which renders these same production components against the direct 620/420 Penpot exports without loading material runtime state. The gallery is diagnostic; final behavior and persistence acceptance still runs in the full editor. Intentional mock/runtime differences are listed in the M2 UI gallery delta matrix.

In renderer arrays, collapsing Parameters does not have to erase material identity or assignment actions. The shared slot can retain its complete asset header while the parameter body is closed; secondary compact rows and genuinely empty drop targets are explicit states of that same component, not separate renderer-only material widgets.

Base Color is a multiplier over its albedo texture. Metallic and Roughness are scalar multipliers over their selected channel; Occlusion is a scalar texture input. The ARM / glTF ORM preset uses R=ambient occlusion, G=roughness, and B=metallic. Separate Maps samples each map's R channel, while the adjacent channel selectors support custom packed layouts. Publication repacks those choices into one canonical linear R/G/B ARM artifact used by Standard and Surface/Solari paths.

Select a Texture asset to edit its semantic, color space, mipmaps, compression, maximum size, filtering, wrapping, anisotropy, and normal convention. Auto treats color/emissive maps as sRGB and normal/mask/ARM data as Linear. DirectX normals are converted to OpenGL +Y during processing. Texture property changes use the same UNSAVED document state. Saving preserves the source image and queues a content-addressed UASTC Basis or uncompressed KTX2 artifact below managed .import-cache/runtime/ storage. The processor derives the output key from source bytes and normalized settings before decoding; if that exact artifact already exists, editor refresh, packaging, and process-assets --check reuse it without recompression.

Loose PBR image sets can be turned into editable Material assets from the Content Browser with Create Materials From Folder. The preview groups filename suffixes, reports confidence, and lets authors correct roles or edit a target name to merge/split sets before publication. Base-color, normal, and packed ORM/ARM maps populate the Standard material fields; occlusion and separately authored roughness, metallic, or height maps are also retained as named Surface texture bindings. The batch is transactional and never overwrites an existing Material file. See the content-workspace guide for the full workflow.

The supported render states are:

• Opaque — no alpha candidate test.
• Cutout — alpha is compared with the material's cutoff in raster and, for eligible geometry, at Solari ray candidates.
• Double sided — stored on the shared material render state.

Editing a shared asset never writes copies into renderer components. The runtime watches the Material, direct base, shader schema, and evaluator dependencies and updates the shared hydrated handle in place. Standard and custom Surface changes therefore propagate to every assigned static or skinned renderer slot without reloading geometry, joints, or the current animation pose. Invalid Surface edits retain the last-good evaluator generation and emit diagnostics. The neutral StandardMaterial attached during hydration is only a singleton emergency visibility handle. It is never reused for an assigned asset: the resolver caches one live handle per MaterialRef, so users of the same Material share updates while unrelated Materials cannot overwrite one another.

Renderer and terrain material bindings target generated draw entities. Scene switches may remove those entities between binding discovery and deferred command application, so binding replacement uses fallible entity commands and treats that stale-target race as normal lifecycle cleanup rather than an editor-fatal error.

Custom Surface evaluators

A custom shader schema may reference evaluator WGSL. Evaluators return material properties through one constrained entry point:

fn evaluate(
    input: SurfaceInput,
    params: SurfaceParams,
    samples: SurfaceSamples,
) -> Surface {
    var surface = surface_default();
    surface.base_color = samples.values[0];
    surface.perceptual_roughness = params.lanes[0].x;
    return surface;
}

Surface ABI v1 supplies UV0, world position, world normal, 16 parameter lanes, and eight sampled 2D textures. The evaluator returns base color/alpha, tangent-space normal, emissive, metallic, roughness, reflectance, occlusion, and lit/unlit model selection. Mesh tangents are required for a custom tangent-space normal to affect raster output and for Solari mesh compatibility.

Do not declare bindings or @vertex, @fragment, or @compute entry points. Storage resources, ray queries, derivatives, discard, barriers/subgroups, texture stores, and atomics are rejected. The engine owns the render stages and composes the same validated evaluator into raster and Solari.

Solari scope

For eligible non-deformed triangle geometry, Solari uses the same Surface evaluator, packed parameters, textures, normal, emissive/unlit choice, and cutout alpha decision as raster rendering. The standard material path remains unchanged for materials without a custom evaluator. See the rendering guide for GI selection and fallback diagnostics.

Skinned meshes and morph-deformed meshes are currently excluded from Solari. This prevents rays from tracing their undeformed source/bind pose while raster shows the animated pose. They remain visible in raster, and Rendering diagnostics report the deformed exclusion. Dynamic deformed vertex/BLAS updates are tracked independently by Gitea #54 with animation, ray-hit, fallback, memory, and update-cost acceptance.

Surface ABI v1 does not support blended transparency, transmission/refraction, custom vertex displacement, or arbitrary pipeline stages.

assets/materials/surface_tint.ron and assets/shaders/surface_tint.* are the committed minimal custom-Surface example used for editor and renderer verification.

Upgrade and validate a project

Normal project loading does not rewrite material or scene files. Preview the explicit transactional upgrade first:

cargo upgrade-project --project .
cargo upgrade-project --project . --apply

Repository scenes use schema v6 for actor-only slot ownership. This pre-production project updates fixtures directly rather than carrying a generalized v5 compatibility migrator. The explicit upgrade path converts legacy primitive/mesh descriptors and per-slot overrides into generalized saved slots, and deduplicates canonical descriptors into project Materials under assets/materials/migrated/. It stages the complete rewrite, creates a timestamped backup under .blacksite/backups/material-slot-v5-*, and rolls back on failure. Commit or otherwise back up the project before applying, inspect the diff afterward, then run:

cargo --locked validate-levels

Validation reports unresolved material/schema/texture references, nested or incompatible instance bases, and unsupported project content through the same editor/headless finding model.

Troubleshooting

Symptom	Check
Clearing a slot appears to do nothing	Clear removes the explicit override; the imported source material is still effective.
Assignment disappeared after reimport	Look for an orphaned assignment. Slots are intentionally not matched by name.
Skinned material edit resets the pose	This is a regression: material-only changes must patch the existing hierarchy rather than reload it.
Custom evaluator is rejected	Check the required evaluate signature, ABI lane/texture limits, and forbidden constructs.
Custom normal has no visible effect	Verify the mesh has tangents.
Animated actor is missing from Solari GI	Expected for current skinned/morph geometry; inspect the deformed-exclusion diagnostic.
Material reference is unresolved	Run project validation and repair/reselect the stable asset reference; do not hand-edit a display-name match.
Texture drop is red on an imported renderer	Renderer slots accept Materials, not loose textures. Create/edit a Material Instance, set its texture, then assign it.
Drag preview remains after leaving a target	This is a regression: target changes, viewport exit, Escape, right-click, and invalid release must restore the exact snapshot.