feat: complete M2 content workspace and inspector
This commit is contained in:
1 parent
931f561e7f
commit
cf6eaba534
438 files changed
+59749
-19043
No files matched your search
@@ -23,6 +23,12 @@ The editor has one primary **Viewport** tab backed by one HDR `ViewportRenderTar
|
||||
transform gizmos, visualizers, and selectable proxies without changing camera ownership.
|
||||
- `Ctrl+G` toggles the grid.
|
||||
- Saved dock layouts containing the old Game View tab are migrated to one Viewport tab.
|
||||
- Ordinary dock and Inspector resizing mutates the existing HDR Image asset's extent while keeping
|
||||
its stable asset ID. Egui owns exactly one strong registration for that ID; an exceptional target
|
||||
replacement or absent/collapsed target explicitly unregisters the previous image.
|
||||
- The editor host window prefers a non-FIFO presentation path (`AutoNoVsync`) so interactive
|
||||
NVIDIA/Wayland window resizing cannot wedge the UI behind repeated one-second swapchain-acquire
|
||||
timeouts. Packaged game windows retain `AutoVsync`.
|
||||
- Multi-viewport support is represented as future-facing state/API shape only; secondary visible
|
||||
viewports remain future work.
|
||||
|
||||
@@ -32,6 +38,10 @@ The editor has one primary **Viewport** tab backed by one HDR `ViewportRenderTar
|
||||
- Camera ownership is explicit: F8 possession selects player camera vs editor camera; G only hides
|
||||
editor overlays.
|
||||
- The HDR/swapchain invariant remains centralized around one offscreen viewport target.
|
||||
- Repeated splitter movement has bounded render-target ownership instead of retaining one
|
||||
full-resolution HDR image per intermediate panel width.
|
||||
- Repeated native-window resizing remains interactive even when the compositor cannot immediately
|
||||
supply a FIFO swapchain image; this editor-specific latency choice does not change game VSync.
|
||||
- Future secondary viewports should add viewport-id keyed rects, targets, cameras, and overlay state
|
||||
rather than reintroducing a Scene View/Game View split.
|
||||
- Post-FX and GI on the active viewport camera are owned by `game_hot::rendering::viewport_camera`
|
||||
|
||||
@@ -12,51 +12,81 @@ copies per actor, and left rigged geometry without the same assignment model as
|
||||
Matching imported materials by a display name was also unsafe: names are neither unique nor stable
|
||||
when a model is reimported.
|
||||
|
||||
Static and skinned renderers need the same Unity-like authoring contract without sharing their mesh
|
||||
or hydration components. A project material must be reusable, an instance must express explicit
|
||||
overrides over one base material, and each renderer must expose stable material slots independently
|
||||
from its draw or skeleton representation.
|
||||
Primitives, static renderers, and skinned renderers need the same Unity-like authoring contract
|
||||
without sharing their geometry or hydration components. A project material must be reusable, an
|
||||
instance must express explicit overrides over one base material, and every renderable surface must
|
||||
expose stable material slots independently from its draw or skeleton representation.
|
||||
|
||||
## Decision
|
||||
|
||||
- Project materials use versioned `MaterialAsset` documents. A `MaterialInstanceAsset` references
|
||||
one direct base `MaterialAsset` and stores parameter and texture overrides. Nested material
|
||||
instances are invalid.
|
||||
instances are invalid. Schema-driven input storage and processed Texture bindings are defined by
|
||||
[ADR 0046](0046-schema-driven-material-inputs-and-processed-textures.md).
|
||||
- `MaterialRef` is the assignment type. Its registry UUID and subasset ID are authoritative;
|
||||
`source_path` is a cached loading hint that validation or migration may repair after a move.
|
||||
- `StaticMeshRenderer` and `SkinnedMeshRenderer` each own a `RendererMaterialSet`. They do not share
|
||||
a mesh component or hydration path. Each `RendererMaterialSlot` has a stable ID, a presentation
|
||||
name, a read-only imported `source_material`, and an optional explicit `material` assignment.
|
||||
Explicit assignment wins; clearing it returns to the imported source material.
|
||||
- `Primitive`, `StaticMeshRenderer`, and `SkinnedMeshRenderer` own `MaterialSlot` values. Mesh
|
||||
renderers use a `MaterialSlotSet`; a primitive owns one stable `surface` slot with ID
|
||||
`slot:primitive:surface`. They do not share a geometry component or hydration path. Each saved
|
||||
slot has a stable ID, a presentation name, and only an optional actor/prefab `material`
|
||||
assignment. Model defaults and imported source materials remain asset-owned in model import
|
||||
metadata and runtime manifests. Clearing an actor assignment returns resolution to those weaker
|
||||
model-owned layers.
|
||||
- Static draw parts and imported skinned-hierarchy draws bind to material slots by stable IDs.
|
||||
Reimport reconciles by ID only. An explicit assignment whose source slot disappears is retained as
|
||||
an `OrphanedMaterialAssignment`; the editor never silently reconnects it by display name.
|
||||
- Asset Browser **Apply Material** assigns a shared material or material instance to every material
|
||||
slot on each selected static or skinned renderer. Renderer inspectors provide per-slot
|
||||
Browse/Select/Locate/Clear controls and expose orphan warnings.
|
||||
- `HydratedRendererMaterialBinding` identifies each runtime draw's owner, slot, and effective
|
||||
material. A skinned renderer material-only edit patches the instantiated hierarchy without
|
||||
reloading its source hierarchy or joints.
|
||||
- Asset Browser **Apply Material** assigns a shared material or material instance to a selected
|
||||
primitive surface or every material slot on each selected static/skinned renderer. One inspector
|
||||
widget provides drag/drop, Browse/Locate/Clear, inherited status, expandable shared parameters,
|
||||
exact-slot extraction, and orphan diagnostics.
|
||||
- `HydratedMaterialSlotBinding` identifies each runtime draw's owner and exact slot.
|
||||
`HydratedMaterialSelection` carries Project Actor, Project Model, Imported Source, or Inherit
|
||||
ownership without copying model defaults into the scene. A skinned renderer material-only edit
|
||||
patches the instantiated hierarchy without reloading its source hierarchy or joints.
|
||||
- `MaterialPropertyBlocks` are runtime-only, per-slot overrides. They do not mutate a shared asset
|
||||
and are excluded from scene and prefab persistence. Persisting a reusable variation requires an
|
||||
explicit material instance.
|
||||
- Scene schema v4 migrates legacy renderer assignments into `RendererMaterialSet`. Project material,
|
||||
material-instance, shader-schema, and scene rewrites are performed by the explicit transactional
|
||||
`cargo upgrade-project` command; ordinary loading remains read-only.
|
||||
- Model assets may provide a project Material/Instance default between their imported source and a
|
||||
scene/prefab assignment. The terminal fallback chain and immutable DefaultGrid contract are owned
|
||||
by [ADR 0045](0045-content-workspace-and-material-fallback-contract.md).
|
||||
- Effective precedence is runtime MaterialPropertyBlock, scene/prefab assignment, model-asset
|
||||
default, imported source, project default, then built-in DefaultGrid. A configured but broken
|
||||
authored reference uses the fallback with diagnostics instead of silently exposing another
|
||||
authored layer.
|
||||
- Repository scenes use schema v6, where renderable slots persist actor/prefab assignments only.
|
||||
This pre-production project updates its fixtures directly. The explicit project upgrader remains
|
||||
available for legacy primitive `MaterialDesc`, mesh-wide descriptors, and per-slot
|
||||
`MaterialOverride` values: it deduplicates canonical descriptors as deterministic project
|
||||
Materials under `assets/materials/migrated/` and rewrites project references transactionally.
|
||||
Ordinary loading remains non-writing.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Static and skinned renderers have a consistent material-slot workflow while retaining distinct
|
||||
geometry ownership and hydration behavior.
|
||||
- Primitives, static renderers, and skinned renderers have one material-slot workflow while
|
||||
retaining distinct geometry ownership and hydration behavior.
|
||||
- An assignment remains a reference rather than a copied material value, so editing or replacing a
|
||||
shared asset does not create actor-local material copies. Material/base/schema/evaluator
|
||||
dependency revisions update the shared runtime handle in place across all assigned slots.
|
||||
- Source reimport cannot silently move an override to the wrong draw. Orphans require an explicit
|
||||
user decision to reassign or discard.
|
||||
- Legacy primitive/actor `MaterialDesc` paths remain compatibility paths until their consumers move
|
||||
to renderer slots; new mesh-renderer work uses shared references.
|
||||
- `MaterialPropertyBlocks` currently define the runtime-only schema and persistence exclusion, but
|
||||
renderer application and the editor promote-to-instance transaction are not implemented. Gitea
|
||||
#53 owns that complete workflow; callers must not treat the component as visibly applied yet.
|
||||
- Material graph authoring, nested instances, blended/transmissive materials, and a generalized
|
||||
per-renderer property-block inspector are outside this decision.
|
||||
- Component-form `MaterialDesc` is restricted to the brush fallback compatibility path. It is not
|
||||
addable to primitives or mesh renderers, does not override their slots, and never causes a
|
||||
primitive-local runtime material allocation. Unmigrated actor material components produce an
|
||||
upgrade diagnostic and visible fallback.
|
||||
- `MaterialPropertyBlocks` define the runtime-only schema and persistence exclusion. Runtime
|
||||
application clones and caches the resolved Standard or Surface material per owner/slot, above
|
||||
direct-base Material Instance values. An invalid block leaves the resolved base visible and emits
|
||||
a deduplicated diagnostic instead of applying a partial override. Promotion to a reusable
|
||||
instance uses an explicit target-path review and source/target fingerprint guards, assigns one
|
||||
exact slot through history, and clears the block only after the file, registry, and scene
|
||||
transaction succeeds. It may never use DefaultGrid as its base. The editor registers the
|
||||
component with reflection for trusted local BRP runtime injection and native promotion testing;
|
||||
that registration does not add it to authoring persistence or the Inspector component registry.
|
||||
- Material graph authoring, nested instances, and blended/transmissive materials are outside this
|
||||
decision.
|
||||
|
||||
Scene schema v6 stores only the actor/prefab assignment in a renderable slot. Model defaults and
|
||||
imported source selections remain model-owned, and hydration carries their origin through
|
||||
`HydratedMaterialSelection`. Live project resolution is owned solely by the overlay/cache boundary
|
||||
in [ADR 0047](0047-editor-authored-asset-documents.md); shared slot presentation follows
|
||||
[ADR 0048](0048-modular-editor-composition-and-debt-ratchet.md).
|
||||
@@ -31,6 +31,8 @@ lighting, fog, shadows, and render-pipeline bindings under engine ownership.
|
||||
`SurfaceInput` provides UV0, world position, and world normal. `Surface` returns base color,
|
||||
tangent-space normal, emissive, metallic, perceptual roughness, reflectance, occlusion, alpha,
|
||||
and lit/unlit model selection.
|
||||
- The schema-driven authoring inputs and canonical processed Texture/ARM artifacts feeding this ABI
|
||||
are defined by [ADR 0046](0046-schema-driven-material-inputs-and-processed-textures.md).
|
||||
- The ABI has 16 `vec4` parameter lanes, eight sampled 2D texture slots with UV transforms, and a
|
||||
400-byte `SurfaceUniform`. Shader schemas map typed Bool/Float/Vec2/Vec3/Color/Enum properties and
|
||||
texture properties into that fixed layout. Exceeding either limit is a validation error.
|
||||
|
||||
@@ -51,3 +51,5 @@ provider.
|
||||
- Native filesystem replacement cannot coordinate with unrelated writers that ignore advisory
|
||||
conventions after Blacksite's final revision check; the narrow check-to-rename interval is the
|
||||
platform boundary, and deterministic race hooks cover the editor-controlled interval.
|
||||
- [ADR 0047](0047-editor-authored-asset-documents.md) applies these guards at explicit asset Save
|
||||
boundaries; interactive parameter edits never enter the authored-file publication path.
|
||||
@@ -55,3 +55,5 @@ tabs switch, while saves may establish a clean point in the middle of a timeline
|
||||
direct non-history repairs, entity respawns, and tab switches.
|
||||
- Operating-system process kill and power loss cannot be confirmed; recovery and abnormal-session
|
||||
handling remain the safety boundary for those cases.
|
||||
- [ADR 0047](0047-editor-authored-asset-documents.md) extends the guarded decision to dirty asset
|
||||
documents and project settings while derived processing remains resumable after source save.
|
||||
@@ -16,8 +16,8 @@ paths more than once.
|
||||
Import, manifest generation, project validation, editor previews, and the runtime loader must agree
|
||||
on one dependency graph. That graph also crosses a security boundary: an imported source must not
|
||||
read or copy a parent-traversing path or an arbitrary absolute path outside its bundle. A missing
|
||||
source texture is required when Source Materials is active, but it can be an intentional authoring
|
||||
condition when an asset explicitly uses Authoring Override.
|
||||
source texture is required when any stable model slot selects Source, but it can be an intentional
|
||||
authoring condition when every slot selects a project Material/Instance or Default.
|
||||
|
||||
## Decision
|
||||
|
||||
@@ -36,8 +36,10 @@ loader warning instead of deferred asset-server requests.
|
||||
Static-mesh manifests are the authoritative model import dependency graph. Their existing
|
||||
`source.dependencies` list records every parsed FBX external texture, including unavailable files.
|
||||
Project validation checks that list without loading native assets. Missing FBX textures are a
|
||||
blocking consolidated finding under Source Materials and an informational consolidated finding
|
||||
under Authoring Override. Unsafe paths remain blocking under either policy. Model registry records
|
||||
blocking consolidated finding while any slot selects Source and an informational consolidated
|
||||
finding when every slot selects Project/Default. The former whole-model Authoring Override value is
|
||||
accepted only as registry-v1 migration input and expands to explicit Default selections. Unsafe
|
||||
paths remain blocking under either selection state. Model registry records
|
||||
mirror the list for editor details, but validation does not duplicate it when a generated static
|
||||
manifest exists.
|
||||
|
||||
@@ -50,16 +52,17 @@ Unreferenced `.fbm` contents are not copied.
|
||||
The Asset Browser renders FBX model and mesh thumbnails through the neutral direct mesh path.
|
||||
Source-material thumbnails preflight the authoritative dependency resolver first and cache one
|
||||
non-retryable actionable failure when required textures are unavailable. Dependency rows expose
|
||||
present/missing state. The committed painted-chair fixture uses Authoring Override deliberately and
|
||||
remains untextured; its three source paths stay visible in manifests, validation, and asset details.
|
||||
present/missing state. The committed painted-chair fixture's legacy Authoring Override migrates to
|
||||
per-slot Default selections and remains untextured; its three source paths stay visible in
|
||||
manifests, validation, and asset details.
|
||||
|
||||
## Consequences
|
||||
|
||||
- FBX sibling `textures/` and `.fbm/` bundles import and validate with identical normalized paths.
|
||||
- Missing texture files are visible before native loading and cannot create repeated Bevy
|
||||
asset-server errors.
|
||||
- Source Materials fails release validation when its FBX textures are absent. Authoring Override
|
||||
remains release-valid but retains an informational dependency finding.
|
||||
- Any Source slot fails release validation when its FBX textures are absent. An all-Project/Default
|
||||
model remains release-valid but retains an informational dependency finding.
|
||||
- Absolute exporter paths, traversal attempts, and destination symlink redirects cannot read or
|
||||
copy arbitrary host files.
|
||||
- FBX files with external textures are parsed twice during loading so no non-`Send` ufbx scene
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
# ADR 0045: Content Workspace and Material Fallback Contract
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Blacksite's Content Browser scans the project `assets/` tree, but authored RON type detection and
|
||||
import destinations still depend on conventional folders. The asset registry is editor-owned and
|
||||
serialized as an unversioned record list, so validation, packaging, runtime hydration, and future
|
||||
headless processing duplicate parts of its contract. Imported model materials are either read-only
|
||||
source defaults or scene-level assignments; a model asset cannot own editable project defaults.
|
||||
|
||||
Missing renderer materials currently create separate magenta `StandardMaterial` values, while
|
||||
skinned, primitive, brush, terrain, thumbnail, raster, and Solari paths use different fallback
|
||||
rules. A missing or broken material therefore does not have one predictable, production-safe
|
||||
result.
|
||||
|
||||
## Decision
|
||||
|
||||
- User-authored content may live in any normal nested folder beneath the project `assets/` root.
|
||||
Folder names are organizational only. External absolute linked assets are not supported.
|
||||
- `AssetId` is authoritative identity. Project-relative paths and labels are repairable cached
|
||||
metadata. Moves and reimports reconcile by stable IDs and never by display name.
|
||||
- Registry contracts move to `shared::content`: typed asset kinds, versioned registry documents,
|
||||
project content defaults, import settings, model material policies, and runtime catalog records.
|
||||
UI-independent filesystem scanning, classification, transaction planning, import/reimport, and
|
||||
processing live in a `content_pipeline` crate used by the editor, validator, watcher, and xtask.
|
||||
- Registry schema v3 is `AssetRegistryDocument { schema_version, defaults, records }` with typed
|
||||
Model/Texture import settings as extended by [ADR 0046](0046-schema-driven-material-inputs-and-processed-textures.md). The source
|
||||
registry remains editor-managed under `assets/.index/`; packages receive a stripped runtime
|
||||
catalog without editor import provenance or source-only dependencies.
|
||||
- Project content roots normalize to `assets/`. `.index`, `.trash`, thumbnails, recovery data, and
|
||||
implementation-owned derived artifacts are hidden and protected from normal file operations.
|
||||
- Fixed-folder consumers are retired or explicitly constrained as follows:
|
||||
|
||||
| Consumer | Current contract / migration |
|
||||
|----------|------------------------------|
|
||||
| Project settings and templates | `asset_roots` upgrades to exactly `["assets"]`; the explicit project upgrader performs the write. |
|
||||
| Content Browser and registry scanner | Walk all user-managed descendants and classify by extension plus document schema, never by parent folder. |
|
||||
| Material, shader, model, audio, level, and prefab lookup | Resolve the registry's stable ID to its current path; a cached path is a repair hint only. |
|
||||
| Scene/prefab validation and hydration | Consume registry/runtime-catalog resolution rather than conventional authoring directories. |
|
||||
| Packaging and headless processing | Scan the same content root and publish the same stripped catalog and normalized model manifests. |
|
||||
| Material creation UX | The current browser folder is authoritative; `assets/materials/` remains only a Material Library convenience default. |
|
||||
| Generated mesh, animation, navigation, thumbnail, trash, and index data | Their fixed implementation-owned locations remain hidden managed storage, excluded from user classification and ordinary file operations. |
|
||||
|
||||
- Model material selections are per stable slot: Source, Project Material/Instance, or Default.
|
||||
Extracting a source material creates an ordinary project Material and then stores a Project
|
||||
selection. Re-extraction may replace a provenance-matched Material only after an explicit diff
|
||||
and fingerprint-guarded Apply decision; Create New remains available and unrelated provenance is
|
||||
never overwritten. Reimport retains removed project assignments as explicit orphans.
|
||||
- Effective material precedence, strongest first, is: runtime MaterialPropertyBlock, scene/prefab
|
||||
assignment, model-asset default, imported source, project default, built-in DefaultGrid. Missing
|
||||
layers inherit downward. A configured but broken authored reference renders the fallback and
|
||||
reports the broken layer rather than silently revealing a different authored layer.
|
||||
- Primitive surfaces participate in that same chain through their saved
|
||||
`slot:primitive:surface`; they no longer hydrate from a separate actor-local descriptor. Static
|
||||
and skinned draws bind their exact saved slot IDs through the same runtime binding contract.
|
||||
- DefaultGrid is immutable engine content compiled into the renderer. It is a shared,
|
||||
UV-independent world-space checker with raster/Solari parity and a neutral StandardMaterial
|
||||
emergency path. A project may choose a Material/Instance fallback; clearing or breaking it
|
||||
returns to DefaultGrid. Terrain retains its specialized layer fallback.
|
||||
- Built-in DefaultGrid is not editable, instanceable, or a valid MaterialPropertyBlock promotion
|
||||
base. Promotion requires a resolved project or imported Material base.
|
||||
- Ordinary editor/runtime loading is read-only. Registry, project-settings, and scene migrations
|
||||
run only through the explicit transactional project upgrader.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Editor, runtime, validation, packaging, watcher, and headless processing share one content model
|
||||
and one stable-ID resolver.
|
||||
- Arbitrary organization no longer changes asset type, runtime behavior, or package inclusion.
|
||||
- The content pipeline becomes a reusable crate boundary instead of an editor implementation
|
||||
detail; this adds one workspace crate and moves registry types out of `editor`.
|
||||
- Older registries, conventional asset roots, global model material policy, and legacy mesh material
|
||||
overrides require the explicit transactional upgrader; normal loading accepts current schemas.
|
||||
- Broken assignments stay visible and diagnosable, but may look different from their previous
|
||||
imported source because failure uses the project/engine fallback deliberately.
|
||||
- One cached DefaultGrid/emergency handle covers repeated primitive and mesh hydration, so missing
|
||||
assignments do not grow the material asset stores.
|
||||
- Thumbnail cache ownership includes the backing Egui image registration. Replacement, retry, and
|
||||
catalog invalidation explicitly release the last registration before a new studio render owns
|
||||
the key, preventing refresh-driven GPU resource growth.
|
||||
- File operations and imports must be staged transactions that update authored references,
|
||||
registry state, derived manifests, and runtime catalogs together.
|
||||
- Ordinary asset-property edits use the explicit dirty-document and two-phase publication boundary
|
||||
defined by [ADR 0047](0047-editor-authored-asset-documents.md); topology transactions remain immediate.
|
||||
- Scene schema v6 carries actor/model/imported/inherit origin explicitly at hydration time, so a
|
||||
broken authored layer uses DefaultGrid instead of accidentally revealing a weaker layer.
|
||||
@@ -0,0 +1,55 @@
|
||||
# ADR 0046: Schema-driven material inputs and processed textures
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
The first Material asset format stored a resolved `MaterialDesc` plus a second generic parameter
|
||||
list. The editor consequently rendered Standard Lit twice, could not pair a scalar or color with its
|
||||
texture, and had no stable place to describe future shader-graph inputs. Texture files also carried
|
||||
no import intent, so color maps, normals, and packed mask data could be sampled interchangeably.
|
||||
|
||||
## Decision
|
||||
|
||||
Material, direct-base Material Instance, and Shader Schema documents use schema v2.
|
||||
`MaterialInputSchema` is the presentation and validation contract for built-in Standard Lit,
|
||||
custom Surface evaluators, and future generated shaders. `MaterialInputSet` is the only authored
|
||||
value/texture store; instance sets remain sparse. Scalar texture bindings select R, G, B, or A,
|
||||
and scalar values multiply the sampled value. Standard Lit pairs Base Color with albedo, Metallic
|
||||
and Roughness with scalar maps, Occlusion with a scalar map, and Emissive Color/Intensity with an
|
||||
emissive map.
|
||||
|
||||
The registry uses v3 `AssetImportSettings`, with typed Model and Texture settings. Texture settings
|
||||
own semantic, color space, mip policy, compression, size limit, filtering, wrapping, anisotropy,
|
||||
and normal convention. One GPU-free processor is called by editor publication, imports, the
|
||||
watcher refresh path, and `cargo process-assets`. It writes content-addressed UASTC Basis or
|
||||
uncompressed KTX2 artifacts below `assets/.import-cache/runtime/`, records sampler/color-space data
|
||||
in runtime catalog v2, and canonicalizes authored AO/Roughness/Metallic selections to R/G/B ARM.
|
||||
Source images remain editable and unchanged. Processing computes the normalized content key before
|
||||
image decode or compression. An existing artifact at that key is reused directly, so validation and
|
||||
catalog repair do not recompress unchanged Texture or packed-Material inputs.
|
||||
|
||||
The actor inspector and asset editors consume the same schema-driven controls. A renderable owns
|
||||
one compact material-slot header; expanding it edits the resolved shared Material or Instance.
|
||||
Slot provenance and diagnostics live outside parameter rows. Valid authoring changes refresh the
|
||||
shared runtime handle immediately but only mark the asset document dirty. Explicit save uses the
|
||||
two-phase source/derived boundary from [ADR 0047](0047-editor-authored-asset-documents.md), without
|
||||
recompiling an unchanged Surface evaluator or scheduling a project-wide watcher pass.
|
||||
|
||||
This is an intentional foundation break. Normal loading accepts current documents only; explicit
|
||||
`cargo upgrade-project --project <root> --apply` converts the repository's v1/v2 documents and
|
||||
backs up every replaced file transactionally.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Shader additions no longer require bespoke inspector layout code when their schema can describe
|
||||
the input.
|
||||
- Color-space and packed-channel choices are deterministic in editor, CI, and packages.
|
||||
- Cached content-addressed artifacts keep `process-assets --check` and unchanged dependency refreshes
|
||||
on the source-hash/catalog path instead of the image-compression path.
|
||||
- Runtime and Solari receive the same canonical input mapping.
|
||||
- Changing a Texture setting can invalidate dependent packed Material artifacts.
|
||||
- The future node-graph compiler must emit this schema and Surface WGSL; graph authoring itself is
|
||||
outside this decision.
|
||||
@@ -0,0 +1,71 @@
|
||||
# ADR 0047: Editor Authored-Asset Documents and Two-Phase Publication
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Material controls previously updated the viewport immediately but also wrote source when a pointer
|
||||
interaction ended. That publication could trigger file guards, Git refresh, watcher work,
|
||||
thumbnail invalidation, and whole-project processing on the editor frame thread. A slider release
|
||||
therefore behaved like an implicit save and could freeze the editor.
|
||||
|
||||
Project RON files and registry metadata are already suitable authoritative source documents. The
|
||||
editor needs a fast, durable edit boundary without adding an opaque asset database or conflating
|
||||
editor-dirty documents with source-control status.
|
||||
|
||||
## Decision
|
||||
|
||||
The editor owns an `AuthoredAssetDocumentStore` keyed by stable asset ID and document kind. It
|
||||
holds clean and current values, source path, loaded file revision, editor revision, publication
|
||||
error, recovery state, and derived-processing state for Materials, Material Instances, model import
|
||||
settings, Texture import settings, and project content defaults.
|
||||
|
||||
Interactive controls mutate the current document and `blacksite_surface`'s stable-ID-keyed
|
||||
`LiveMaterialDocumentOverlay` in the same tick. `SurfaceMaterialCache` is the sole owner of project
|
||||
Material and Material Instance handles; resolution is overlay-first and disk-second. Controls
|
||||
perform no source write, watcher refresh, Git query, thumbnail invalidation, or derived processing,
|
||||
including when the pointer is released. Dirtiness is derived from `current != clean` and remains
|
||||
distinct from Git `MODIFIED`, `UNTRACKED`, and `CONFLICT` state.
|
||||
|
||||
The cache never polls file metadata or reparses a project Material for every bound entity. Explicit
|
||||
Save and accepted watcher events invalidate the disk generation once; interactive overlay
|
||||
revisions mutate the existing cached handle in place. Imported glTF/FBX source materials stay on
|
||||
their AssetServer-owned path and do not enter the project-material resolver.
|
||||
|
||||
`Ctrl+S` saves the last edited context. `Ctrl+Shift+S` and **File > Save All** save every dirty
|
||||
scene, authored asset document, and project setting. Source publication remains guarded and atomic.
|
||||
Registry-backed documents use a clean registry baseline plus per-document overlays so saving one
|
||||
setting cannot publish another unsaved setting.
|
||||
|
||||
Successful source publication advances the clean value, then classifies its
|
||||
`DerivedProcessingImpact`. Scalar, color, emissive, shader-value, label, and render-state Material
|
||||
changes queue no derived work. ARM/ORM texture or channel changes queue material packing; Texture
|
||||
settings, model settings, and project defaults queue only their exact dependency closure. Packing
|
||||
signatures exclude scalar multipliers and are checked before image decoding so an existing
|
||||
content-addressed artifact can be reused. The previous valid runtime artifact remains authoritative until replacement
|
||||
publication succeeds; a processing failure is reported separately and does not make saved source
|
||||
dirty again. Stale job completions are ignored.
|
||||
|
||||
Dirty asset documents receive editor-local recovery snapshots after two seconds of inactivity,
|
||||
with five generations retained outside `assets/`. Startup restoration never overwrites source: a
|
||||
changed source fingerprint restores the document as an external conflict. Guarded shutdown and
|
||||
project switching count scenes, assets, and project settings in the same Save All / Discard /
|
||||
Cancel decision. Returning a document exactly to its clean value retires any older recovery
|
||||
generation on the next editor tick. Startup also discards a recovery envelope whose value already
|
||||
matches authoritative source, covering a crash between the clean edit and that cleanup tick.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Parameter editing and pointer release stay frame-local and responsive.
|
||||
- Material and direct-base Instance users share one stable live handle authority instead of
|
||||
competing editor and renderer caches.
|
||||
- Saving source and generating derived artifacts are observable, independent phases.
|
||||
- The project remains plain, reviewable RON plus source assets; no asset binary database is added.
|
||||
- Unsaved editor state survives selection changes and can be recovered after a crash without
|
||||
affecting Git until the user saves.
|
||||
- Packaging and read-only processing validation must reject required pending or failed derived
|
||||
work rather than silently packaging stale content.
|
||||
- Import, extract, create, rename, move, and delete remain explicit immediate transactions because
|
||||
they create or remove project identity.
|
||||
@@ -0,0 +1,52 @@
|
||||
# ADR 0048: Modular Editor Composition and Architecture-Debt Ratchet
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
The Content Browser and Inspector accumulated unrelated navigation, rendering, import, material,
|
||||
transaction, and component-card behavior in files thousands of lines long. That made small changes
|
||||
high-risk, encouraged duplicate UI, and obscured ownership. ADR 0012 states a zero-debt intent but
|
||||
did not provide an enforceable point-of-change budget.
|
||||
|
||||
## Decision
|
||||
|
||||
Editor panels are composed from thin shells, domain modules, and UI-independent services. The
|
||||
Inspector delegates every visible built-in component through `EditorComponentRegistry`; a
|
||||
hard-coded type dispatcher is not a second authority. Material slot presentation uses a shared
|
||||
view-model/action contract, and Content Browser and Material Library cards use one bounded asset
|
||||
card/status model.
|
||||
|
||||
The machine-readable policy is `.codex/architecture.toml`. Its audit enforces 500 nonblank lines
|
||||
for UI shells, 800 for other UI modules, and 1,200 for other production Rust modules. Existing
|
||||
over-limit modules have frozen ceilings. A temporary exception requires a tracker issue, rationale,
|
||||
hard maximum, extraction target, and expiry milestone. Selective verification and candidate CI run
|
||||
the audit.
|
||||
|
||||
The M2 extraction is tracked by Gitea #68. The Content Browser and Inspector shells are now below
|
||||
the 500-line budget, their domain behavior lives in bounded submodules, and no temporary #68
|
||||
exception is active. Closing the issue still requires the selective and native acceptance evidence
|
||||
defined by the milestone.
|
||||
|
||||
The Penpot-led material-inspector refinement remains inside #68's shared-UI scope. The reusable
|
||||
visual primitives live in `ui/design_system`, while `ui/materials` owns the action-returning domain
|
||||
panel. This keeps authored visual policy separate from Inspector world access and prevents the
|
||||
first design-system migration from rebuilding a panel monolith. ADR 0049 owns the visual contract.
|
||||
|
||||
## Consequences
|
||||
|
||||
- New behavior is added through a sustainable extension seam instead of enlarging a monolith.
|
||||
- Shrinking an over-limit module is always accepted; regrowth above its frozen baseline fails.
|
||||
- Passing the audit is a no-regression statement; issue closure additionally requires functional
|
||||
and native evidence for the extracted seams.
|
||||
- Architecture work remains visible in the same tracker and milestone as the feature that exposes
|
||||
it.
|
||||
- ADR 0034 owns registry-driven component semantics; this ADR owns editor composition and the
|
||||
mechanical debt guard.
|
||||
|
||||
Related decisions: [ADR 0012](0012-zero-tech-debt-editor.md),
|
||||
[ADR 0034](0034-registry-driven-authoring-components.md), and
|
||||
[ADR 0047](0047-editor-authored-asset-documents.md), and
|
||||
[ADR 0049](0049-penpot-led-editor-visual-system.md).
|
||||
@@ -0,0 +1,119 @@
|
||||
# ADR 0049: Penpot-Led Editor Visual System
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Blacksite's editor controls evolved inside individual panels. Even after the material data and
|
||||
Inspector composition became shared, local egui styling still produced inconsistent spacing,
|
||||
typography, interaction states, and narrow-panel behavior. The Penpot **Inspector Material Slot**
|
||||
provides an authored reference for the visual language rather than another implementation-specific
|
||||
mock-up.
|
||||
|
||||
## Decision
|
||||
|
||||
The Penpot **Inspector Material Slot** is the source of truth for geometry, type roles, control
|
||||
heights, radii, spacing, property-column geometry, and interaction states. Color is semantic rather
|
||||
than panel-owned: Penpot's Assets / Colors library and `editor::ui::theme::EditorVisualPalette`
|
||||
name the same roles, with Blacksite's existing palette as the default. A later Editor Settings slice
|
||||
may select or override that palette without changing widgets or material behavior. At the 620 px
|
||||
reference width, implementations match the documented geometry. Below that width, controls deliberately
|
||||
reflow instead of shrinking, clipping, scrolling horizontally, or hiding required state.
|
||||
|
||||
Fixed Penpot sections use deterministic geometry models rather than nested egui flow layouts.
|
||||
Surface, parameter rows, texture fields, UV groups, and Advanced each receive an owning rectangle;
|
||||
every child rectangle is derived from it and clipped to it. The 569 px and 369 px section widths
|
||||
encode the exported wide and compact references. A bounded transient mode below 372 px keeps all
|
||||
rectangles finite, stacks the row, and collapses low-frequency texture actions into overflow while
|
||||
the Inspector restores its 420 px minimum.
|
||||
|
||||
The reusable implementation lives under `editor::ui::design_system`. It consumes the editor-owned
|
||||
semantic palette and owns spacing tokens, Source Sans Pro Regular/Bold typography roles, section chrome, property grids,
|
||||
asset and texture fields, segmented controls, switches, status presentation, and the Blacksite
|
||||
color picker. Domain widgets consume these primitives instead of copying raw colors or absolute
|
||||
Penpot coordinates.
|
||||
|
||||
Material authoring is the first migrated domain. One action-returning `MaterialsSection` is used by
|
||||
primitive, static-mesh, and skinned-mesh inspectors. It owns an ordered list of collapsible
|
||||
`MaterialSlotPanel` models, and every returned action carries its stable slot ID. The widgets do not
|
||||
query or mutate arbitrary world state.
|
||||
Supported material behavior only is shown. Asset identity, health, inheritance, dirty state, and
|
||||
read-only state share one geometry, while stable IDs and fingerprints remain in secondary
|
||||
diagnostics.
|
||||
|
||||
The final Penpot component supersedes the earlier v2.2/v2.3 geometry. A 32 px **Materials** heading
|
||||
precedes repeated slots. Expanded slot headers are 82 px with a 64 px preview; collapsed headers
|
||||
are 52 px with a 32 px preview. A cyan disclosure spine and **PARAMETERS** ownership label inset the
|
||||
Surface, Inputs, UV, and Advanced body. The asset identity block owns the single Shader selector. Penpot's former duplicate Surface
|
||||
"Shading Model" selector was removed from the component and every state reference in handoff
|
||||
v2.3.1. Surface contains blend mode, Separate/ORM selection, and Double Sided. UV
|
||||
precedes Advanced with
|
||||
an explicit 8 px section gap. Advanced render controls
|
||||
that do not yet have renderer contracts are shown only as a clearly disabled preview: they emit no
|
||||
actions and create no authored or runtime state.
|
||||
|
||||
The Material slot header is one assignment interaction, not an identity block beside a second drop
|
||||
box. Its whole 596 x 82 px wide reference area accepts valid Material/Instance drops. Preview and
|
||||
identity clicks plus the first-class Browse action open the compact current/recent Penpot menu;
|
||||
Shader, Locate, Clear,
|
||||
and overflow actions are isolated and cannot accidentally open it. The picker returns a stable
|
||||
asset reference to the owning Inspector instead of mutating scene or world state.
|
||||
|
||||
The custom 420 x 350 color popup is a fixed modal centered over its owning Inspector clip, with an
|
||||
Inspector-local dim layer rather than application- or viewport-relative placement. Its header,
|
||||
mode tabs, wheel and values regions, RGBA byte fields, HSV degree/percentage fields, HEX copy,
|
||||
checkerboard alpha control, recents, and footer use the exported Penpot coordinates. The exported
|
||||
eyedropper lane remains a tooltip-labelled disabled preview until screen sampling has an owned
|
||||
runtime contract. Apply keeps the in-memory dirty value and closes; Cancel, Escape, Close, or
|
||||
outside dismissal restores the exact pre-open value. Neither path saves source or schedules derived
|
||||
processing.
|
||||
|
||||
Standard Lit declares seven independently stored inputs but six primary presentation rows.
|
||||
`emissive_intensity` is a schema companion of `emissive_color`; the Emissive popup previews and
|
||||
restores both values as one interaction without merging their authored/runtime identities. Custom
|
||||
shader binding counts likewise count primary rows while rendering companions through their owner.
|
||||
|
||||
Bounded scalar material inputs use one 132 px control composed from a 78 px track, 6 px gap, and
|
||||
48 x 22 numeric field. Expanding the 178 px Advanced preview requests a bounded
|
||||
Inspector scroll reveal so its note and lower boundary are visible. The same no-implicit-persistence
|
||||
rule applies to sliders, texture assignments, and shader controls.
|
||||
|
||||
Inspector overflow is part of the shared visual contract. A floating scrollbar keeps component
|
||||
width stable as content crosses the vertical overflow threshold, and every nested component clip is
|
||||
an intersection with the owning Inspector body. Ready texture fields use the typed thumbnail as
|
||||
their sole leading identity; generic image glyphs are reserved for empty states.
|
||||
|
||||
Standard Lit exposes one shared UV Offset/Tiling transform through the same schema-driven input
|
||||
document. The renderer maps it to Bevy StandardMaterial UV transforms and to every Surface ABI
|
||||
texture lane. Material Instances may override it sparsely; resetting an instance restores its base.
|
||||
|
||||
Penpot's `CODEGEN MAP` and handoff annotations are design documentation. Runtime egui layout remains
|
||||
responsive and semantic; generated SVG or code is not copied into production. Reviewed numeric
|
||||
geometry is represented by small testable layout models instead of ad hoc child flow or generated
|
||||
widget trees.
|
||||
The same release slice applies the active Inspector Header, Array Header, renderer-panel, asset
|
||||
field, vector, selection, and overlay components across the Inspector. Built-in component cards
|
||||
dispatch through the registry and share one clipped actor-body scroll owner; domain behavior stays
|
||||
outside the visual primitives.
|
||||
|
||||
## Consequences
|
||||
|
||||
- New editor UI has one reviewed visual vocabulary rather than panel-local approximations.
|
||||
- Theme colors have one runtime owner and one design-side asset vocabulary; the material panel does
|
||||
not carry a private blue/teal palette.
|
||||
- The 620 px and 420 px geometries are deterministic and unit-testable. The Inspector has a 420 px
|
||||
floor and one actor-body scroll region; material slots never introduce nested scrolling.
|
||||
- Unsupported prototype controls are omitted until their runtime contracts exist.
|
||||
- The explicitly approved Advanced preview is the sole exception: it is disabled, muted, and
|
||||
labelled as planned work rather than functioning authoring state.
|
||||
- Native acceptance compares rendered geometry, typography, states, and interaction behavior with
|
||||
the Penpot reference; compile-only evidence is insufficient.
|
||||
- Source Sans Pro and its SIL Open Font License are bundled with the editor.
|
||||
- ADR 0048 continues to own composition and module-size policy. This ADR owns visual tokens,
|
||||
responsive component geometry, and interaction presentation.
|
||||
|
||||
Related decisions: [ADR 0035](0035-shared-material-assets-and-renderer-slots.md),
|
||||
[ADR 0047](0047-editor-authored-asset-documents.md), and
|
||||
[ADR 0048](0048-modular-editor-composition-and-debt-ratchet.md).
|
||||
Reference in new issue
Block a user