docs/GOALS.md

# Goals and completion criteria

Baseline: 2026-10-21. All implementation statements below are targets.

## Product goal

Build Nanobrush: a native desktop brush modeler and level editor in Rust, using Bevy for application/render integration and Solari for raytraced lighting where supported. It must work on macOS and Linux, preserve the reference editor's workflows, read and write its supported formats, and operate without Windows, Wine, .NET, IXPL.exe, or the original editor at runtime.

The compatibility baseline is `Microbrush-3-wip-2016-03-10-c.zip`. Study all four older builds to explain regressions, behavior changes, and legacy formats. Microbrush 2 is a separately tracked recovery gap: no MB2 executable or converter source package is present. Do not claim MB2 compatibility based on MB3 evidence.

## Scope of “entire software”

Account for every archive member, externally visible command, configurable setting, public plugin API, data format, renderer mode, and shipped auxiliary tool. Write a specification and a disposition for each: equivalent implementation, deliberately improved behavior, replacement asset, retained reference only, or explicit unresolved gap. A disposition is not permission to silently drop a feature.

Include:

- Brush world representation and computed geometry; Patch9 curved surfaces; selection and visibility; all editing tools and undo/redo.
- Multiple independent worlds and multiple views of the same world; cameras, projections, layout, input routing, and focus.
- Rectangular and circular grids, transformed grid bases, snapping, secondary snapping, cursor placement, and saved presets.
- File workflows and converters: MB3 TXT/DAT, HL1 MAP, HL2 VMF, Q3 MAP, and Wavefront OBJ export.
- Akula UI behavior: toolbars, menus, help/text markup, configuration, localization, notes, log, layout designer, plugin discovery, and task ordering.
- Core APIs used by the bundled IXPL plugins, file/model utilities, procedural model generation, shader behavior, and all experimental plugins.
- Asset unpacking, inspection, conversion, validation, storage, packaging, and reproducible development tooling.

Reimplement observable semantics and data compatibility. Decide separately whether third-party IXPL source or compiled-plugin compatibility is required; bundled tool functionality is required regardless. A legacy VM/compiler is not automatically necessary to deliver a native rewrite, but it must have a documented disposition before calling the reconstruction complete.

The original engine's internal implementation need not be duplicated instruction for instruction. Every subsystem visible in the supplied API still needs a documented behavioral contract. Unsupported speculation such as an unobserved general CSG subtraction feature must remain a research question, not a fabricated compatibility promise.

## Platform and rendering goal

| Target | Required outcome |
| --- | --- |
| macOS Apple Silicon, Metal | Native editing, import/export, packaging, and ordinary Bevy rendering; exercise Solari on an independently verified capable adapter |
| Linux x86_64, Vulkan | Native editing on Wayland and X11; Solari exercised on a capable adapter |
| macOS Intel / Linux aarch64 | Evaluate build and runtime feasibility; explicitly declare support or defer with evidence before release |
| Non-raytracing adapters | Full editing through ordinary rendering; clear renderer capability information |
| Solari-capable adapters | Lighting mode that survives interactive geometry edits, material changes, viewport changes, undo, and reload |

Proposed minimum product policy: portable editing and diagnostic render modes are always available; Solari is selected by a validated capability probe. If “Solari on every supported machine” is required, the minimum GPU/OS requirements must be narrowed after the spike. Do not equate successful compilation with GPU support.

## Repository and preservation goal

- Use direnv and a pinned Nix flake based on the current `my-nix` patterns in nearby repositories.
- Name the Hugging Face code repository `nanobrush`; keep source code and original documentation in ordinary Git.
- Use one HF repository, following the inspected `urban-terror-rs` pattern: `assets/**` and every `references/` directory use Xet-backed LFS pointers; source and tests remain ordinary Git.
- All reference payloads belong under `assets/references/`, including binaries, IXPL source, shaders, configuration, and historical text. A text extension does not make preserved third-party content project code.
- Preserve original ZIP bytes, names, hashes, provenance, and licenses. Extraction and recoding create separately identified derivatives.
- Pin asset identities with LFS pointers in the same Git commit as code; verify fresh-clone recovery without relying on local caches.

## Definition of done

1. Every shipped file and discovered behavior has an evidence record, specification/disposition, and validation coverage or a clearly unresolved limitation. “Complete” cannot hide unchecked parity tasks.
2. Every observed editing tool passes deterministic command-level tests and representative interactive replays, including cancel, focus loss, undo, redo, and multiple views.
3. Native file save/reload preserves the canonical document; each legacy converter has an explicit supported subset, round-trip tests, malformed-input tests, and loss reporting. Match reference quirks only in a documented compatibility mode when appropriate.
4. Both required operating systems pass real window/input/file-dialog and GPU tests; Solari and ordinary rendering each have measured results on named hardware/drivers.
5. Native release packages launch on a clean machine without the original binaries or a development checkout. Runtime assets and required notices are included.
6. Asset hydration, extraction, conversion, and packaging are reproducible from pinned inputs, with checksums and transformation recipes.
7. Reference-use and redistribution questions identified in the actual bundled license are resolved for the chosen distribution model; original and rewritten code licenses are kept distinct.
8. A user manual, format specifications, architecture notes, build instructions, troubleshooting guide, and final parity report are delivered.

## Decisions to resolve during the corresponding phase

- Resolved setup identity: `nmarshall/nanobrush`, one Git repository; see SETUP.md for storage and verification. Hosting visibility and any future redistribution policy remain explicit decisions.
- Exact supported CPU/GPU/OS matrix and minimum Bevy/Rust versions after the capability spike.
- Whether extensibility means native Rust plugins, a sandboxed scripting interface, IXPL source translation, or legacy bytecode compatibility.
- Canonical native document schema, numeric precision, unknown-field preservation, and migration policy.
- Expected parity for experimental tools and the historical GUI layout designer; full coverage remains planned unless a change is explicitly recorded.
- Original-content reuse versus newly authored replacement assets; resolve the missing font notice and archive restrictions before redistribution.
- Performance budgets, reference-scene sizes, and acceptable geometry/render tolerances, established from measurements rather than guessed now.