BS-JD-201 - Material Browser and shared material catalog #16

New Issue

Rbanh · 2026-06-06T01:47:18-04:00

Rbanh commented

2026-06-06 01:47:18 -04:00

Summary

Create a dedicated Material Library for project-wide Material assets, direct-base Material Instances, and exact scene usage.

Why

The general Asset Browser supports materials, but production authoring needs a focused searchable catalog, reliable previews, explicit shared editing, and clear assignment ownership.

Implementation notes

Add a docked Material Library with project Material/Instance catalog and renderer-slot, primitive, and brush-face scene usage.
Reuse MaterialAsset, MaterialInstanceAsset, and shader-schema-aware MaterialDesc editing.
Add resolved thumbnails, search/type/usage filters, grid/list views, creation, reveal actions, and drag sources.
Keep shared Material edits distinct from scene assignments and transient runtime property blocks; do not create hidden scene-local clones.

Acceptance criteria

User can browse project-wide Materials, Material Instances, and their exact scene users.
Material and Material Instance thumbnails render reliably.
Shared edits are explicit; scene assignment changes use one undoable history action.
Dragging a Material or Material Instance exposes valid exact drop targets and explicit invalid reasons.

Tests/docs

Material catalog, usage, filter, instance-resolution, and target-kind tests pass. README, editor docs, implementation plan, and live screenshot evidence are published.

## Summary Create a dedicated Material Library for project-wide Material assets, direct-base Material Instances, and exact scene usage. ## Why The general Asset Browser supports materials, but production authoring needs a focused searchable catalog, reliable previews, explicit shared editing, and clear assignment ownership. ## Implementation notes - Add a docked Material Library with project Material/Instance catalog and renderer-slot, primitive, and brush-face scene usage. - Reuse `MaterialAsset`, `MaterialInstanceAsset`, and shader-schema-aware `MaterialDesc` editing. - Add resolved thumbnails, search/type/usage filters, grid/list views, creation, reveal actions, and drag sources. - Keep shared Material edits distinct from scene assignments and transient runtime property blocks; do not create hidden scene-local clones. ## Acceptance criteria - [x] User can browse project-wide Materials, Material Instances, and their exact scene users. - [x] Material and Material Instance thumbnails render reliably. - [x] Shared edits are explicit; scene assignment changes use one undoable history action. - [x] Dragging a Material or Material Instance exposes valid exact drop targets and explicit invalid reasons. ## Tests/docs Material catalog, usage, filter, instance-resolution, and target-kind tests pass. README, editor docs, implementation plan, and live screenshot evidence are published.

material-instance-surface-preview.png

2.1 MiB

Rbanh added this to the M2 - Content workspace and asset pipeline milestone 2026-06-06 01:47:18 -04:00

Rbanh added the

labels 2026-06-06 01:47:18 -04:00

Rbanh referenced this issue

2026-06-06 01:49:27 -04:00

BS-JD-ROADMAP - Jackdaw-inspired editor production roadmap #1

~~Rbanh referenced this issue 2026-07-11 18:49:46 -04:00~~

BS-JD-207 — Renderer material slots, material instances, and exact custom shader surfaces #51

Rbanh referenced this issue

2026-07-11 18:50:23 -04:00

BS-JD-ROADMAP - Jackdaw-inspired editor production roadmap #1

Rbanh commented

2026-07-11 18:50:24 -04:00

Foundation dependency: #51

The catalog should be implemented on the asset contract introduced by #51:

Browse shared project Material assets and explicit reusable Material Instance assets.
Do not create hidden scene-local material clones. Per-renderer runtime property blocks are transient and can be promoted explicitly to a Material Instance.
Make shared edits visibly affect all users; instance edits affect only users of that instance.
Drive assignment through stable named renderer slots shared by static and skinned renderers.
Surface missing bases, cycles, type-invalid overrides, and orphaned reimport assignments before build.

This supersedes the ambiguous “scene-local materials” wording with explicit instances/property blocks. #16 remains open until the browser, thumbnails, search/filter, drag sources, history behavior, tests, and docs pass against that contract.

### Foundation dependency: #51 The catalog should be implemented on the asset contract introduced by #51: - Browse shared project Material assets and explicit reusable Material Instance assets. - Do not create hidden scene-local material clones. Per-renderer runtime property blocks are transient and can be promoted explicitly to a Material Instance. - Make shared edits visibly affect all users; instance edits affect only users of that instance. - Drive assignment through stable named renderer slots shared by static and skinned renderers. - Surface missing bases, cycles, type-invalid overrides, and orphaned reimport assignments before build. This supersedes the ambiguous “scene-local materials” wording with explicit instances/property blocks. #16 remains open until the browser, thumbnails, search/filter, drag sources, history behavior, tests, and docs pass against that contract.

Rbanh commented

2026-07-12 00:12:24 -04:00

Local Material catalog/instance progress

The #51 foundation now supplies the catalog contract requested here:

project Material and direct-base Material Instance assets;
sparse instance property and texture overrides;
Apply/Revert/Create Instance workflow;
shader-schema-aware editing and live shared-handle propagation;
reliable sphere thumbnails with tighter 78–81% framing;
project-wide texture picker including imported model texture subassets;
direct texture drag/drop and clear-to-inherit behavior.

The implementation, screenshot paths, docs, and 171-test editor result are linked in #51 comment 865. #16 remains open for its final published/committed evidence and any remaining dedicated-panel UX polish.

### Local Material catalog/instance progress The #51 foundation now supplies the catalog contract requested here: - project Material and direct-base Material Instance assets; - sparse instance property and texture overrides; - Apply/Revert/Create Instance workflow; - shader-schema-aware editing and live shared-handle propagation; - reliable sphere thumbnails with tighter 78–81% framing; - project-wide texture picker including imported model texture subassets; - direct texture drag/drop and clear-to-inherit behavior. The implementation, screenshot paths, docs, and 171-test editor result are linked in [#51 comment 865](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/51#issuecomment-865). #16 remains open for its final published/committed evidence and any remaining dedicated-panel UX polish.

Rbanh referenced this issue

2026-07-12 11:16:28 -04:00

BS-PR-707 - Production-readiness acceptance gate and release checklist #50

Rbanh commented

2026-07-12 11:19:56 -04:00

Production workflow audit and implementation boundary

The shared Material/Material Instance, thumbnail, renderer-slot, and guarded authored-file foundations now exist, but the dedicated user-facing catalog acceptance here is still incomplete.

The next clean implementation slice is planned locally in .cursor/plans/material_library_and_targeted_drop_2026-07-12.plan.md:

dockable Material Library opened from Window and placed in the existing bottom dock, with no new permanent toolbar;
project Material/Instance search, filters, thumbnail grid/list, dependency/base health, and collaboration status;
scene-usage counts for renderer slots, primitives, and brush faces, with select/locate actions;
reuse of guarded Apply/Revert/Create Instance editing rather than hidden scene-local clones;
first-class Material/Instance drag sources;
source/headless tests plus live visual acceptance before closure.

Implementation waits until the verified #49 worktree is committed so the overlapping Asset Browser changes remain independently reviewable. This issue remains open.

## Production workflow audit and implementation boundary The shared Material/Material Instance, thumbnail, renderer-slot, and guarded authored-file foundations now exist, but the dedicated user-facing catalog acceptance here is still incomplete. The next clean implementation slice is planned locally in `.cursor/plans/material_library_and_targeted_drop_2026-07-12.plan.md`: - dockable **Material Library** opened from Window and placed in the existing bottom dock, with no new permanent toolbar; - project Material/Instance search, filters, thumbnail grid/list, dependency/base health, and collaboration status; - scene-usage counts for renderer slots, primitives, and brush faces, with select/locate actions; - reuse of guarded Apply/Revert/Create Instance editing rather than hidden scene-local clones; - first-class Material/Instance drag sources; - source/headless tests plus live visual acceptance before closure. Implementation waits until the verified #49 worktree is committed so the overlapping Asset Browser changes remain independently reviewable. This issue remains open.

Rbanh commented

2026-07-12 13:19:56 -04:00

Production acceptance complete

Implemented and published on codex/material-library-targeted-drop:

02247f0 adds the docked Material Library, shared Material/Material Instance resolver, scene-usage model, creation/edit/reveal actions, resolved instance thumbnails, and first-class drag sources.
3794faa records the indexed live acceptance evidence.

Acceptance against the superseding #51 contract:

project Material and direct-base Material Instance catalog across folders;
search plus Material/Instance/Used/Unused filters;
grid/list views with reliable resolved Material Instance sphere thumbnails;
dependency/base health, dependent-instance counts, and exact renderer-slot/primitive/brush-face scene users;
usage rows select the actor and focus the viewport;
guarded shared-asset details editing and explicit Create Material/Create Instance paths;
no hidden scene-local clones; reusable instances and transient property blocks remain the explicit model;
drag sources expose exact green/red viewport feedback.

Full live and automated verification record

Verification passed: workspace all-target check, strict workspace Clippy, all workspace tests, strict editor Clippy with dev and hot-reload, level validation with 0 blockers, navigation freshness, and live Wayland QA. Packaged testing remains deferred by project-owner direction and is not claimed here.

## Production acceptance complete Implemented and published on `codex/material-library-targeted-drop`: - [`02247f0`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/commit/02247f0) adds the docked **Material Library**, shared Material/Material Instance resolver, scene-usage model, creation/edit/reveal actions, resolved instance thumbnails, and first-class drag sources. - [`3794faa`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/commit/3794faa) records the indexed live acceptance evidence. Acceptance against the superseding #51 contract: - project Material and direct-base Material Instance catalog across folders; - search plus Material/Instance/Used/Unused filters; - grid/list views with reliable resolved Material Instance sphere thumbnails; - dependency/base health, dependent-instance counts, and exact renderer-slot/primitive/brush-face scene users; - usage rows select the actor and focus the viewport; - guarded shared-asset details editing and explicit Create Material/Create Instance paths; - no hidden scene-local clones; reusable instances and transient property blocks remain the explicit model; - drag sources expose exact green/red viewport feedback. ![Live Material Library and exact surface preview](https://git.spacetrainclubhouse.com/attachments/dfca7917-a612-468f-a055-b9d3f380ffdd) [Full live and automated verification record](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/branch/codex/material-library-targeted-drop/docs/editor/evaluations/material-library-targeted-drop/README.md) Verification passed: workspace all-target check, strict workspace Clippy, all workspace tests, strict editor Clippy with `dev` and `hot-reload`, level validation with 0 blockers, navigation freshness, and live Wayland QA. Packaged testing remains deferred by project-owner direction and is not claimed here.

Rbanh closed this issue

2026-07-12 13:20:28 -04:00

Rbanh referenced this issue

2026-07-12 13:23:37 -04:00

BS-PR-707 - Production-readiness acceptance gate and release checklist #50

Rbanh referenced this issue

2026-07-12 13:24:04 -04:00

BS-JD-ROADMAP - Jackdaw-inspired editor production roadmap #1

Rbanh referenced this issue

2026-07-12 13:27:00 -04:00

BS-JD-504 - Documentation and issue board structure #35

Rbanh referenced this issue