mirror of
https://github.com/storytold/AniCraft.git
synced 2026-11-19 17:12:19 +01:00
9.8 KiB
9.8 KiB
AniCraft: technology and requirements
AniCraft is an open-source, native, clean-room 2D vector animation studio in the class of
Adobe Animate, written in Rust only. It is a sibling of PhotoCraft, LightCraft, WordCraft and
the other {Function}Craft apps and follows the same house rules (Rust only, no webview shells,
everything is a command, never crash, tests are the gate).
This document fixes what we build and with what. architecture.md says how the pieces fit,
roadmap.md says in which order.
1. Product scope
1.1 Users and jobs
| User | Job to be done |
|---|---|
| Motion designer / animator | Draw vector art, animate it on a timeline with keyframes, tweens and symbols, preview at the target frame rate, export video/GIF/web. |
| Game / web developer | Author sprite animations and UI motion, export sprite sheets, Lottie or HTML canvas, script interactivity. |
| Educator / hobbyist | A free, fast, cross-platform replacement for an abandoned or subscription-only tool. |
| Agent / pipeline | Create, edit, render and validate documents with no window (CLI, JSON-lines, MCP), in CI or a render farm. |
1.2 Functional requirements (feature areas)
Priority: P0 = M0–M2 skeleton must have, P1 = parity core, P2 = long tail.
| Area | Requirement | Pri |
|---|---|---|
| Document | Stage size, frame rate, background colour; multiple scenes; library of symbols and assets. | P0 |
| Timeline | Layers (normal, guide, mask, folder), frames, keyframes, blank keyframes, frame spans, labels, playhead, scrubbing, looping playback at document fps. | P0 |
| Tweens | Classic tween with easing presets and custom cubic-Bézier ease; shape tween; motion tween with property curves (Motion Editor); motion guides. | P0 / P1 |
| Symbols | Graphic (timeline-synced), Movie Clip (independent timeline), Button (Up/Over/Down/Hit); instances with transform, colour effect (alpha, tint, brightness, advanced), loop modes and first frame. | P0 / P1 |
| Drawing | Selection, Subselection, Free transform, Rectangle, Oval, PolyStar, Line, Pen, Pencil, Brush (variable width), Paint bucket, Ink bottle, Eraser, Eyedropper, Hand, Zoom; object drawing and merge drawing models. | P0 / P1 |
| Fills and strokes | Solid, linear and radial gradients, bitmap fills; stroke width, caps, joins, miter limit, variable width profiles, dashes. | P0 / P1 |
| Text | Static, dynamic and input text with font embedding policy; text on stage animates like any element. | P1 |
| Onion skin | Before/after range, tint, outlines. | P1 |
| Camera | Layer-depth camera with pan, zoom, rotate. | P2 |
| Bones / IK | Bone tool, armature poses. | P2 |
| Audio | Import WAV/OGG/MP3, stream vs event sync, waveform on timeline, scrub audio. | P1 |
| Filters / blend | Blend modes, drop shadow, blur, glow, bevel, colour adjust on Movie Clips. | P1 |
| Scripting | Frame scripts and automation (see open question U2 below). ActionScript compatibility for imported Animate projects: keep scripts, then run the ActionScript 3 timeline subset (ADR 0013). | P2 |
| Import | SVG, PNG/JPEG sequences, XFL (uncompressed FLA XML), then binary FLA as a stretch goal. | P1 |
| Export | PNG / PNG sequence, animated GIF, sprite sheet + JSON, SVG (static frame), Lottie JSON, HTML canvas, MP4/WebM via a system encoder (ffmpeg pipe), optionally SWF. | P0 (PNG) / P1 |
| History | Unlimited undo/redo, named history entries, history is per document. | P0 |
| Headless | Every action available from the CLI, a JSON-lines control channel and an MCP server; deterministic renders. | P0 |
1.3 Non-functional requirements
| Quality | Requirement (measurable where possible) |
|---|---|
| Never crash | No panics in non-test code. Malformed files, bad command params and odd input return actionable errors. Every command is fuzzed with adversarial params (panic_hunt test). |
| Determinism | The same document + frame renders byte-identical PNGs on every platform with the CPU renderer (fixed-point-free f32 path, no time or thread-order dependence). This is the oracle for tests and agents. |
| Performance | Stage playback at document fps (24/30/60) for 1920×1080 with ≥1,000 visible shapes; scrub latency < 16 ms; open a 50 MB document < 1 s; render a 1080p frame headless < 20 ms on 8 cores. Budgets live in perf/budgets.toml from M2. |
| Memory | Documents are structurally shared (copy-on-write); an undo step costs proportional to what changed, not the document size. |
| Fidelity | Analytic anti-aliasing (exact area coverage), correct non-zero and even-odd fill rules, gradient spread modes, premultiplied-alpha compositing. |
| Portability | Windows, macOS, Linux desktop; the engine layers (L0–L5) also build for wasm32-unknown-unknown. |
| Accessibility | Keyboard reachable commands, scalable UI, high-contrast theme, screen-reader labels via AccessKit. |
| Localisation | Every interface string translatable, keyed by its English text (ADR 0040); catalogs from the Craft family's craft-i18n; a missing translation shows English, never an error. The command registry, CLI, MCP and file format stay English. |
| Clean room | Behaviour and look learned only from public documentation, public specs and observation. No proprietary code, shaders, presets or assets. |
| Licensing | MIT OR Apache-2.0. Every third-party asset is permissively licensed and listed in ATTRIBUTION.md. |
2. Technology choices
| Concern | Choice | Why |
|---|---|---|
| Language | Rust 2024 edition, stable toolchain (MSRV 1.90) | Memory safety, fearless parallelism, one language for engine, UI, CLI and web. |
| UI | egui / eframe 0.36 (wgpu backend) | Immediate mode keeps the UI a thin function of state, matches PhotoCraft, runs native and on the web. |
| Rendering (oracle) | In-house CPU rasterizer: Bézier flattening + signed-area coverage accumulation, rayon row parallelism | Deterministic, testable, headless; the reference every other renderer is compared against. |
| Rendering (interactive, M3) | wgpu compute/fragment renderer (sparse strips or tile binning in the style of public Vello/Pathfinder papers), compared per-pixel against the CPU oracle | Fast stage at high zoom and 4K; GPU and CPU must agree within a tolerance in tests. |
| Geometry | In-house geom crate (affine, Bézier, flattening, hit test); kurbo-compatible API shape |
Small, no_std-friendly, full control over tolerance and determinism. |
| Serialization | serde + serde_json for .anicraft (JSON manifest), zip container from M2 for embedded media |
Human-diffable, agent-friendly, versioned with #[serde(default)]. |
| Images | png crate for encode/decode; GIF encoder from M1 |
Minimal dependencies. |
| Parallelism | rayon | Row and tile parallelism in the renderer, batch export. |
| Errors | thiserror per crate | Typed, propagatable, no panics. |
| Audio (M5) | cpal for output; own WAV reader, lewton (Ogg Vorbis) and nanomp3 (MP3) for decoding (ADR 0020) |
Pure Rust, cross-platform, permissive (symphonia is MPL-2.0, not allowed). |
| Video export (M4) | ffmpeg as an external process (pipe raw frames) | No codec licensing in the binary. |
| Testing | cargo test, golden-image tests, property tests (proptest), adversarial command fuzz, criterion benches |
Tests are the gate. |
| Automation | CLI (anicraft-cli), JSON-lines serve mode, MCP server (M2) over the same command registry |
Headless parity with the UI by construction. |
Rejected options
- Tauri / Electron / any webview UI: violates the Rust-only rule of the Craft family.
- Skia / tiny-skia as the renderer of record: good libraries, but owning the rasterizer is central to the project's rendering and performance goals and to cross-renderer determinism. tiny-skia stays acceptable as a test-only cross-check.
- A retained-mode UI toolkit: more state to keep in sync with the document; egui's immediate mode plus a command engine gives one source of truth.
3. Constraints and rules (inherited from the Craft family)
- Rust only; no unsafe (
unsafe_code = "forbid"workspace-wide). - Everything a user can do is a command with an id, label, menu path, shortcut, params schema and tests. UI, CLI, JSON-lines and MCP all dispatch by id.
- The UI is thin: no document logic in
ui. - Input-derived numbers are hostile: checked arithmetic, bounded allocation, bounded recursion (symbols can nest and can be cyclic in malformed files).
- Layering is enforced; lower layers never depend on egui/eframe/winit.
- Every change comes with tests; renderer changes come with golden images.
4. Open questions
| Id | Question | Current decision (until settled) |
|---|---|---|
| U1 | Which interchange format first? | Own .anicraft + PNG/GIF first (headless verification needs it), then XFL import (migration path for existing projects), then Lottie/SVG export. Chosen by the builder in auto mode. |
| U2 | Scripting surface replacing ActionScript/JSFL? | Settled by the project lead: use the sibling apps' plug-in system. As in PhotoCraft (docs/plugins.md there): sandboxed WebAssembly plug-ins run by wasmi (pure Rust, MIT OR Apache-2.0, works in the web build), with no host imports, fuel/memory/time limits, plugin.install/list/run/remove/reload commands, and one undo step per run. AniCraft's ABI targets vector/timeline work (shape generators, selection transforms, easing presets, exporters) and calls the same command registry. Commands-only scripting (CLI/JSON-lines) stays available. ActionScript (asked for by the project lead, low priority) is a compatibility front end on top, not a second engine: ADR 0013. Built (first slice, ADR 0017, docs/plugins.md): command plug-ins that call the registry through a two-import JSON ABI. |
| U3 | When does the GPU renderer become primary on stage? | CPU oracle drives the stage until the GPU renderer passes golden parity tests (M3). |