svc-sandbox/bible-strong-avatar-lab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
767f5191e9
bible-strong-avatar-lab/CONTEXT.md
PhilippeMaillot 767f5191e9 feat(studio): independent body-part colors and double-click to edit body 
- Add an optional per-node color so each shape added to the body can be
  colored independently from the body color.
- Surface the color picker in the body construction panel, with a reset to
  inherit the body color.
- Paint secondary primitive fills as motion values so they stay in sync with
  the geometry while the camera rotates, across avatar switches and on the
  exported snapshot / runtime renderers.
- Preserve the node color through export and import of .avatar.json.
- Double-click the 3D model to enter body construction editing (when not
  already editing).
2026-09-08 16:53:42 +02:00

3.4 KiB
Raw Blame History

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, rotation and color.
  • 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/.