Prepared 2026-07-26 from the current source tree, the format specification, the test/build configuration, and the current Release build.
Status note (SYS-W13-03): this is a point-in-time proposal snapshot,
not live planning — plan.md is authoritative for current work. Its
recommended "event bindings for Areas/triggers" feature has since shipped as
bounded Event Preview/Play (SYS-W14-40, [DONE] in plan.md): timer
bindings, Walk Mode Area enter/exit, and viewport-picked object clicks all
dispatch automatically now. Treat the rest of this analysis as historical
context, not a current gap list.
MeshCraft is already a substantial, safety-conscious 3D scene editor rather
than an early prototype. Its strongest property is a well-defined canonical
scene model (Mc3Document) that drives XML, JSON, MCB, the live editor, and a
glTF/GLB exporter. The project supports parametric primitives, hierarchy,
PBR-oriented materials, CSG, path extrusion, reusable definitions/instances,
animation, scripts, triggers, scene states, import libraries, and several
asset-metadata concepts. It also has an unusually broad regression suite for a
project of this size.
The main product opportunity is not to add isolated primitive types or more panels. It is to make the already-authored semantics operational end-to-end:
- turn editable library and asset metadata into a real reusable-asset workflow;
- turn manually fired triggers and manually applied states into controlled scene events;
- close the most important viewport/export contract gaps; and
- broaden exchange and deployment only after the release gate is reliable.
This order gives users a stronger authoring loop without prematurely turning the editor into a general-purpose game engine. The recommended first new feature is native MC3 library authoring and publishing, followed by metadata-driven LOD/culling and event bindings for Areas/triggers. Those features reuse existing model fields and mostly stay within this repository's ownership boundary.
There is one immediate quality finding that should be treated as a release gate before feature work:
- In the current
b-releasebuild,ctest -R '^mc3_ai$'previously reached its 30-second CTest timeout because the mock-HTTP test helper waited forever for a loopback listener. The untrusted traversal-shaped<include>response is correctly ignored; its adjacent assertion was merely buffered while the later mock-server setup hung. This is fixed by a bounded readiness probe and a precise skip of only the loopback-dependent tests where such listeners are unavailable.
The render-test result needs a configuration caveat: a fresh CMake configure
correctly detects the unusable Xvfb display and disables the 35
render-dependent tests while leaving render_display_preflight as a skip.
An earlier run used stale generated CTest metadata and therefore launched the
disabled tests. This is covered by the existing completed AUD-090 task, not
a new renderer defect.
The AI finding matters because the project rightly treats its test suite as a major product asset. It should be resolved or explicitly quarantined before claiming a clean release baseline.
MeshCraft is best described as a scene-authoring and asset-compilation tool for the MC3 ecosystem. MC3 stores editable constructive intent rather than only final triangles. That lets a scene retain primitives, CSG operands, extrude paths, definitions, material relationships, and selected gameplay metadata after save/load.
The core pipeline is:
.mc3.xml / .mc3.json / .mcb
|
Mc3Document
_________|______________
| | |
Editor viewport MCB glTF / GLB
+ authoring UI runtime export
mc3/ deliberately has no graphics dependency. mcb/, mc3tomcb/, and
mc3togltf/ can build independently. The editor adds Dear ImGui, CNA/SDL
graphics, scene preview, commands, animation playback, auto-save, registry,
and optional AI/Lua features.
| Area | Current capability | Assessment |
|---|---|---|
| Scene model | XML and semantic JSON, MCB, schema, validation, input budgets, include/import policies, library hashes | Strong foundation for durable content |
| Geometry | Box/cube, sphere, cylinder, cone, plane, torus, capsule, disk, grid, icosphere, OBJ, embedded self-contained GLB, extrude, CSG | Rich procedural authoring set |
| Editing | Hierarchy, multi-selection, transform gizmos, snapping, property editing, grouping, arrays/scatter, rename/find-replace, macros, undo/redo, backups | Good desktop-editor baseline |
| Materials | PBR factors and texture slots, SVG rasterization, sampler metadata, normal-map tangents, texture browsing | More complete than a typical internal tool |
| Interchange | Deterministic glTF/GLB export, geometry caching, CSG evaluation, lights/cameras, transform animation, MCB conversion | Export is a first-class product surface |
| Runtime-style data | Lua sandbox, scripts, manual trigger fire, manual scene-state apply, sounds/music, sockets, reusable definitions | Useful base, but several concepts are still authoring-only |
| Quality | 185 CTest registrations in the current Release tree; fuzzing, hostile-input, round-trip, determinism, Blender import, and pixel tests | Excellent intent and broad coverage |
- The canonical
Mc3Documentkeeps the file formats and consumers aligned much better than a UI-owned scene model would. - Parsers are deliberately hardened: input-size and complexity budgets, numerical clamps, include policy controls, and MCB corruption defenses are visible throughout the code and tests.
- The glTF exporter has useful professional qualities: deterministic output, no partial output on failure, geometry caching, texture safety checks, tangent generation, UV generation, and real Blender-import checks.
- The editor has already separated several narrow subsystems (selection, locking, bookmarks, walk controller, status, overlays, UI contexts). This makes focused new work safer than a monolithic application would.
- Dependency boundaries are explicit. In particular, CNA and sharp-runtime are sibling repositories and should not be changed here without owner permission.
This is the largest functional theme in the codebase.
| Authored capability | Current behavior | Product consequence |
|---|---|---|
coordinate_system=right_handed_z_up |
Stored, edited, and warned about, but not applied by the editor or exporter | A valid document can visibly mean something different from its declaration |
Ordinary-object uv_mapping |
Box/sphere projection and transforms are honored by mc3togltf; ordinary live viewport geometry uses default UVs. CSG roots have better parity |
The editor preview can disagree with the exported asset |
| Point/spot lights | Exported, but the live BasicEffect preview only has directional/ambient lighting; point/spot remain largely gizmo-only | Lighting design cannot be judged faithfully in the editor |
| CSG child materials | Exporter preserves child-material primitives when the CSG root has no override; the viewport uses the root material | Preview does not show final material composition |
| Asset metadata LOD references / max visibility distance | Serialized and edited. The renderer has separate procedural tessellation LOD, but metadata definition references and visibility-distance hints are not the scene-selection contract | The format promises reusable asset tiers that authoring does not yet exploit |
| Triggers and states | Explicit bindings now connect objects/Areas to trigger or state targets and have safe dry-run enter/exit/timer simulation; viewport collisions/picking still do not emit live events | Authoring semantics are present without claiming a full game runtime |
| Collision labels | Walk mode supports explicit collision="box"; other declared proxy modes are not simulated |
Walkthrough scenes cannot use their richer collision intent |
These are not all bugs. Several are documented scope choices. Together, however, they show the correct direction for new work: complete meaningful vertical slices from authoring through preview/export/runtime semantics.
The exporter is sophisticated, but incoming geometry remains intentionally limited:
- OBJ is supported, but its per-face/material-group information is flattened to one MC3 material.
embed:accepts bounded self-contained GLB triangle geometry with MC3 retaining material authority; it is intentionally not a full glTF importer.- There is no editing workflow that converts a common multi-material glTF/GLB asset into native MC3 objects/materials/definitions.
This is the biggest adoption barrier for artists who start in Blender or other DCC tools. It is also an opportunity to make MeshCraft the canonical editor for existing content rather than only new parametric scenes.
Linux/EASYGL is the verified editor route. Windows, Web, and Android are partly blocked by sibling-runtime/toolchain issues. Web currently crashes on its first resize event; Android lacks NDK/package/device validation; Windows is blocked before the complete editor links. These are real product risks but must be coordinated with the owners of CNA and sharp-runtime rather than worked around by MeshCraft-only source changes.
The live renderer and mc3togltf generate geometry separately except for a
small shared path for torus/capsule/icosphere. The code intentionally has
different triangle winding in preview and export. This design is workable, but
every new geometric semantic has a parity cost: transforms, UVs, CSG, LOD,
deformation, units, coordinate conventions, and material assignment must be
validated in both consumers.
The answer is not an unsafe wholesale rewrite. The answer is a small shared semantic-evaluation layer and focused differential tests whenever a feature needs both paths.
This is not new user functionality, but it is the correct first priority.
- Diagnose and fix or isolate the
mc3_aitimeout. Add a narrow regression test that identifies the actual hanging boundary and has a short, meaningful timeout rather than letting the entire AI test become opaque. - Preserve the existing render-test gating contract. A fresh configure must mark render-dependent tests disabled when Xvfb/display preflight fails; a valid display must cause the full set to run.
- Keep the current two-part verification contract: CNA-free/non-render tests and an explicit Xvfb render partition. Do not treat display-less failures as product rendering failures.
Acceptance criteria: a clean Release run has deterministic pass/skip behavior, reports why a platform-dependent partition was skipped, and does not hide a real failure behind environmental noise.
Status (implemented as SYS-W14-28, 2026-07-26): the model and core API
were already present; the editor workflow is now complete around them. The
remaining deliberate limit is visual thumbnails: discovery is text-first and
does not require a new rendering/cache subsystem.
Feature scope:
- Open Library / Save as Library actions cover
.mc3lib.xmland.mc3lib.json, use the dedicated library I/O, validate identity, and refresh the content hash. - “Create Definition from Selection” and “Publish Definition” validate the definition id, namespace, and semantic version; publishing retains dependent materials and textures in a self-contained library.
- The import browser shows source, resolved file, declared version/hash, definition count, and missing/hash/cycle/identity/collision errors.
- The definition picker places imported assets with text, category, style, and semantic-tag filtering. Thumbnails remain later scope.
- Imported definitions stay external on scene save; a local edit that shadows a source definition produces a visible warning.
Why it fits the architecture: it primarily touches FileOps, MenuBar/UI,
Mc3ImportResolver, and existing library APIs. It does not need a CNA change
or a new geometry format.
Tests: library_workflow covers XML/JSON publication, content hashes,
successful/failing health resolution, collision/identity diagnostics, named
selection-to-definition conversion, and external-definition save markers.
The renderer already has a useful procedural three-tier tessellation LOD for
some primitives. Separately, assetMetadata.lods maps named tiers to
definition ids and max_visibility_distance exists in the format. These
should become one explicit asset-level system.
Status (implemented as SYS-W14-29, 2026-07-26): Instances now resolve a
portable FNV-1a identity-derived variant, then select the source definition's
near/mid/far asset tier with configurable 25 m/75 m thresholds and 2 m
hysteresis. A positive visibility maximum culls the viewport and the selected
Instance panel states its tier, resolved definition, and fallback/cull reason.
The source-definition choice is reused by normal, depth, emissive, and edge
passes, while the pre-existing primitive tessellation LOD remains distinct.
glTF/GLB and CSG export deliberately bake the explicit near/default tier (no
camera context, no provisional LOD extension). Focused CNA-free, glTF, and
display-gated viewport tests cover the contract.
Feature scope:
- Resolve an instance’s definition metadata into near/mid/far definitions.
- Choose a tier from camera distance with configurable thresholds and hysteresis, so objects do not flicker at boundaries.
- Respect
max_visibility_distanceas a distance-culling hint, with an editor debug overlay that shows selected tier, distance, and cull reason. - Preserve deterministic instance variants: use a stable seed derived from document/object identity rather than per-frame random selection.
- Add an optional glTF export policy: export the selected/default tier for maximum compatibility first; add a glTF LOD extension only as an explicit advanced option after target viewers are tested.
Value: large towns, forests, interiors, and imported libraries can become fast enough to edit and preview without destroying authoring detail.
Important constraint: do not conflate this with the existing primitive tessellation LOD. Asset LOD changes the selected definition; primitive LOD changes triangle density. Both may coexist and need clear UI labels.
Extend walk-mode collision from box-only to selected, explicit proxy modes:
- sphere/capsule for characters and rounded props;
- simple triangle-mesh or convex proxy for static floors/walls, with a strict triangle budget and explicit opt-in;
- visual debug rendering of active collision shapes;
- a “Generate simple proxy” command for supported primitives.
This makes the existing walkthrough mode useful for level validation while maintaining the project’s principle of not silently approximating authored collision semantics.
Today an Area is visually a box-shaped marker and triggers can be fired only manually. This is enough for testing scripts/actions but not enough to author an actual interactive scene.
Recommended design: introduce a small explicit event-binding model rather
than relying on name matching. A binding should identify a source object or
Area, an event (enter, exit, click, timer, perhaps action-finished),
and a target trigger or scene state.
First slice:
on_enter/on_exitfor Area volumes and a timer binding;- per-binding enabled flag, cooldown/debounce, and a deterministic one-shot option;
- visual overlay for activated volumes and a test/simulate button;
- trigger execution remains ordered and uses the existing Lua sandbox;
- applying a state should be a named action in the same binding system.
Safety and semantics: event dispatch must have a frame-local recursion guard, an execution budget, clear errors for dangling target ids, and an undo-free play/simulate mode so testing a scene does not accidentally rewrite the authored document. Persisting mutable gameplay state should be a separate decision.
Export note: this is MC3/MCB runtime semantics; glTF has no equivalent. The exporter should preserve its current explicit warning/omission behavior.
Implemented (SYS-W14-31, 2026-07-26): XML/XSD, semantic JSON, and MCB now preserve bindings with source, event, target kind/id, enabled, cooldown, one-shot, and timer interval. The editor exposes an Events tab and dry-run timer/manual simulation report. Its CNA-free dispatcher limits each call to 32 successful dispatches, blocks nested dispatch, reports dangling sources and targets, and never executes trigger/state effects or mutates the document or undo history. glTF prints one omission warning instead of silently losing the semantics. Live collision/picking event production remains intentionally outside this first slice.
right_handed_z_up should either become operational or be removed from the
authoring UI; the better product choice is to support it.
Implement one well-tested scene-convention transform at the semantic boundary, then apply it consistently to rendering, picking, gizmos, camera views, world-position UI, CSG, walk collision, and glTF node transforms. Include a clear import/open notice and an optional one-way “normalize to Y-up” command for teams that want a fixed house convention.
The risk is high because transform paths currently live in more than one consumer. Mitigate it with a small shared convention helper and fixtures whose world positions, screenshot orientation, picking, and glTF transforms are all checked together.
Deliver this as small vertical slices, not as a renderer rewrite:
- ordinary primitive UV mapping in the viewport, including box/sphere projection, scale, offset, and rotation;
- point and spot light preview with attenuation/cones, using the authored light values rather than only gizmos;
- CSG child-material display parity when no root override is authored;
- a material-preview/viewport mode that makes normal, occlusion, emissive, alpha, and sampler choices visible enough for authors to trust the result.
The preferred implementation is a capability-gated CNA ShaderEffect path
with a clearly documented fallback on unqualified backends. It should not
reintroduce raw OpenGL calls or overpromise Vulkan/WebGPU parity before those
backends are pixel-qualified.
Start with a narrow problem that users hit immediately: preserve OBJ groups and material assignments as multiple MC3 mesh objects/materials instead of flattening the asset to one material. Then add a deliberate glTF/GLB import workflow:
- import self-contained GLB first; make external-resource glTF an explicit trusted-mode capability;
- map nodes, meshes, cameras, punctual lights, material factors, images, and transforms to native MC3; report unsupported skins/morphs/animations rather than silently deleting them;
- offer two modes: editable imported objects, or a bounded embedded mesh for fast/reference use;
- use the current safe embedded-GLB loader as a starting point, but do not mistake it for a full importer.
This feature has high adoption value and should arrive after the library workflow, because an imported object is much more useful when it can be published as a reusable MC3 definition.
The Export dialog visibly exposes disabled “Quantize meshes” and texture embedding options. Make advanced controls truthful and useful:
- add opt-in
KHR_mesh_quantizationwith documented precision/error bounds and a structural GLB test; - clearly state the texture behavior for
.gltfversus.glb, then expose only controls that the exporter actually honors; - add mesh/texture/output-size estimates before export;
- provide an export report with unsupported/downgraded feature counts and direct object ids.
Compression must be opt-in and deterministic. Avoid adding Draco or other heavy codecs until there is a distribution and compatibility decision.
The timeline supports transform, visibility, material, and deform channels, but glTF core only receives transform animation. A pragmatic expansion is:
- named clip ranges, playback speed, reverse/loop and transition previews;
- a non-destructive “bake for export” command that samples unsupported animation into an explicitly chosen compatible representation where viable;
- optional
KHR_animation_pointerexport for material/visibility-like channels only when the user accepts limited viewer support; - clear per-channel export diagnostics rather than silently skipping data.
Do not claim that every MC3 animation has a universal glTF equivalent. The editor can remain the full-fidelity authoring surface while exporting a well-documented subset.
The local SQLite registry is useful but intentionally lacks thumbnails and sync. A practical next version would add generated thumbnail caching, metadata/tag search, dependency-aware pack export, license/provenance views, and duplicate/unused-material reports. Cloud synchronization should be a separate product and security decision, not an incidental SQLite change.
The current 20-entry whole-document deep-copy undo stack is safe and simple, but it limits long authoring sessions. A future user-facing productivity feature could add memory-budgeted history, named checkpoints, scene diff, and restore points. Implement it as a dedicated subsystem; it should not weaken the existing reliable undo semantics merely to store more entries.
Do not immediately merge the renderer and exporter into a giant shared mesh library. Their output requirements differ, including intentional winding. Instead, introduce small CNA-free helpers for concepts that must agree:
- document coordinate convention;
- object/instance transform accumulation;
- definition/variant/LOD resolution;
- effective visibility and material resolution;
- stable object identity for diagnostics and deterministic random choices.
Each helper should have direct tests and at least one differential editor versus export fixture when its result affects geometry.
Unknown XML attributes/elements are currently silently dropped by a load/save cycle. New event bindings, LOD policy, importer provenance, and advanced export metadata should therefore be versioned deliberately. Before adding any new MC3 field:
- update the AST, XML/XSD, JSON, and MCB surfaces together;
- define old-reader behavior and a user-visible warning where data could be lost;
- add XML/JSON/MCB round-trip and malformed-input tests; and
- update
mc3togltf/editor support matrices honestly.
The project already makes good security choices for untrusted paths, embeds, SVGs, and scripts. New import, event, and library features should retain this posture: trusted-mode toggles must be explicit, resource budgets must be enforced before allocation, and scripts/events need bounded execution.
Feature work that needs new CNA behavior should be proposed to the CNA owner with a minimal required API and a testable acceptance case. MeshCraft should not duplicate raw graphics code to bypass an unqualified backend. Web and Android packaging are valuable delivery milestones, but are separate from a MeshCraft-only feature implementation until their sibling blockers are fixed.
| Milestone | Deliverable | Why this order |
|---|---|---|
| 0 | Fix AI-test timeout and robust render-test gating | Restores trustworthy evidence for later work |
| 1 | Native library publish/open/import-health workflow | High user value, leverages stable existing APIs, low graphics risk |
| 2 | Metadata-driven definition LOD and distance culling | Converts existing asset metadata into visible performance value |
| 3 | Event bindings for Areas/triggers/states | Implemented (SYS-W14-31) — controlled authored bindings plus safe simulation; live world input remains follow-up work |
| 4 | Coordinate convention plus first preview/export parity slices | Removes the most surprising correctness gaps before visual expansion |
| 5 | Multi-material OBJ and self-contained GLB import | Expands adoption once imported content can be published as libraries |
| 6 | Collision proxies, export optimization, richer animation/registry work | Valuable, but larger design/compatibility surface |
For the next implementation decision, choose Milestone 1. It has clear user-facing results, uses mature components already present in the repository, requires no CNA change, and creates a strong foundation for LOD, imported assets, and a better registry.
- A wholesale
MeshCraftApplicationrefactor. The current phased extraction strategy is safer and already has explicit boundaries. - CNA or sharp-runtime source changes without owner approval.
- A full game runtime/networking system. Event bindings should first serve authoring, preview, and MC3/MCB semantics.
- Generic modifier stacks, arbitrary mesh editing, skeletal animation, or collaboration sync in one release. Each would add a much larger data-model and compatibility commitment than the recommended milestones.
- Claiming Windows, Web, Android, Vulkan, or WebGPU feature parity without a platform build and pixel-qualified run.
MeshCraft has the ingredients of a focused, high-quality scene editor for an asset-driven game ecosystem: an expressive editable format, hardened parsers, strong export machinery, and a serious test culture. Its next stage should be defined by semantic completion, not feature count. Make reusable assets easy to publish and consume, make authored metadata affect preview/runtime, and make the preview reliably represent exported results. That sequence will make every later feature—imports, LOD-heavy worlds, interactive scenes, and platform delivery—more coherent and less expensive to maintain.