3b2e134169
Add distribution metadata, Strobi app icons, CI, and comprehensive documentation. Migrate the project to pnpm and reorganize the Studio into domain-focused modules and components.
79 lines
3.4 KiB
Markdown
79 lines
3.4 KiB
Markdown
# Avatar Lab Context
|
|
|
|
## Purpose
|
|
|
|
Bible Strong Avatar Lab is a browser-based authoring tool for procedural 2D avatars. It combines
|
|
3D-inspired geometry with SVG rendering so creators can build a body from primitives, define a
|
|
neutral face, author expressions and compose reusable animations. Generated packages do not depend
|
|
on the Studio UI.
|
|
|
|
## Ubiquitous language
|
|
|
|
### Avatar
|
|
|
|
A reusable character whose body, colors and neutral eyes define its persistent visual identity.
|
|
|
|
### Neutral appearance
|
|
|
|
The persistent visual base of an Avatar before an Expression is applied. Avoid “default pose”.
|
|
|
|
### Pose
|
|
|
|
The Avatar's current temporary visual configuration. A Pose is not persisted directly.
|
|
|
|
### Base behavior library
|
|
|
|
The immutable bundled collection of Expressions and Animations inherited by an Avatar that has not
|
|
customized its behavior.
|
|
|
|
### Avatar behavior library
|
|
|
|
The Avatar-owned collection of Expressions and Animations created atomically from the Base behavior
|
|
library on that Avatar's first behavior mutation.
|
|
|
|
### Expression
|
|
|
|
A saved visual preset within the Base behavior library or one Avatar behavior library. Eye values
|
|
are relative to the owning Avatar's Neutral appearance. Optional color overrides are temporary.
|
|
|
|
### Animation
|
|
|
|
A saved sequence of Expressions from the same behavior library, including transitions and blink
|
|
behavior. Avoid “state” in user-facing copy.
|
|
|
|
### Playback
|
|
|
|
The active execution of one Animation. It exclusively controls the animated Pose until direct user
|
|
manipulation pauses it.
|
|
|
|
## Invariants
|
|
|
|
- An Avatar inherits the Base behavior library until its first Expression or Animation mutation.
|
|
- The first behavior mutation copies Expressions and Animations together so references stay valid.
|
|
- Subsequent behavior mutations affect only the owning Avatar.
|
|
- Duplicating an Avatar duplicates its Avatar behavior library when one exists.
|
|
- Transferring an Animation must also transfer every Expression it references.
|
|
- The primary body shape carries the facial coordinate system and eyes.
|
|
- Secondary primitives have independent local dimensions, position and rotation.
|
|
- Expressions remain compatible across body surfaces because they operate in the common facial frame.
|
|
- `features/avatar/geometry.ts` and the exported procedural engine stay independent from React.
|
|
- `features/studio/defaultStudioDocument.json` is the current schema baseline; pre-release legacy migrations are not required.
|
|
- Live editing may update the preview, but unsaved avatar/expression edits must remain reversible.
|
|
|
|
## Architecture boundaries
|
|
|
|
- Pure geometry and document logic live in framework-independent TypeScript modules.
|
|
- `features/studio/useStudioController.ts` coordinates durable UI state and application operations.
|
|
- `features/studio/components/StudioView.tsx` composes the stage, inspector and dialogs.
|
|
- Keep domain calculations out of React components and controller hooks.
|
|
- Motion values own frame-by-frame visual updates; React state owns durable editor state.
|
|
- Exports receive explicit avatar, expression and animation data rather than reading browser storage.
|
|
- The generated standalone engine is committed and checked for freshness in local validation.
|
|
|
|
## Current persistence
|
|
|
|
The complete Studio document is persisted in browser local storage. JSON project export/import is the
|
|
portable backup mechanism. There is no remote backend in this repository.
|
|
|
|
Accepted architecture decisions live under `docs/adr/`.
|