smontlouis/bible-strong-avatar-lab

Bible Strong Avatar Lab is a browser-based authoring studio for procedural 2D avatars. It combines 3D-inspired geometry with SVG rendering so you can construct a character, define its neutral appearance, create expressions, compose reusable animations, and export the result without depending on the Studio UI.

Website: avatars.bible-strong.app · Source: GitHub

The application runs entirely in the browser. Projects are stored locally and can be moved between browsers with JSON export/import; no account or backend is required.

• Create, rename, duplicate, reorder, and delete avatars.
• Build a body from a primary facial surface and additional 3D-inspired primitives.
• Adjust dimensions, roundness, position, local rotation, perspective, colors, and wireframe guides.
• Edit each eye independently or link their size, proportions, and position.
• Manipulate the avatar directly on the canvas with translation and rotation controls.
• Save, duplicate, reorder, and delete reusable expressions.
• Add temporary body and eye color overrides to an expression.
• Add subtle ambient movement to the body and eyes.
• Build animations from expression steps with custom hold times and transitions.
• Choose loop, play-once, or ping-pong playback and configure automatic blinking.
• Preview, play, pause, and stop animations inside the Studio.
• Take SVG or PNG snapshots with transparent, solid, linear-gradient, or radial-gradient backgrounds.
• Export one portable .avatar.json definition for React or framework-free JavaScript/ESM.
• Export and import the complete Studio project as JSON.
• Use the interface in English, French, or Simplified Chinese.

The workspace has a live canvas on the left and an inspector on the right. Start by selecting an avatar, then move through the four main areas:

1. Pose — inspect a temporary pose or open the avatar editor to change the character's durable body, colors, and neutral eyes.
2. Expressions — create named visual presets. Expression eye values are relative to the avatar's neutral appearance, so the same behavior remains compatible with different body surfaces.
3. Animations — arrange expressions on a timeline, tune step duration and transition style, choose a playback mode, and configure blinking.
4. Export — choose animations to include, download an integration package, configure Photo Mode, or back up the full Studio project.

Changes to the Studio document are saved automatically in browser local storage. Unsaved edits inside an avatar, expression, or animation editor can still be cancelled. Use Export → Studio project to create a portable JSON backup before clearing browser data or moving to another device.

An avatar owns its body geometry, colors, and neutral eye appearance. Expressions and animations initially come from the bundled base behavior library.

When an avatar's expressions or animations are edited for the first time, the Studio copies both collections into an avatar-specific behavior library. From that point on, behavior changes affect only that avatar. Duplicating an avatar also duplicates its custom behavior, and transferring an animation includes every expression it references.

This copy-on-write model lets multiple avatars share the defaults without accidental cross-avatar edits while keeping customized characters fully independent.

The selected avatar and animations are stored in one portable .avatar.json definition. React and JavaScript use this exact same file, so visual behavior does not diverge between renderers.

Install @bible-strong/avatar-react, import the JSON and pass it to createAvatar. The React package depends on @bible-strong/avatar-core for validation, playback and geometry.

Install @bible-strong/avatar-web for a DOM renderer without React. The integration ZIP contains the same .avatar.json, a lightweight ESM wrapper and usage instructions; it does not copy the rendering engine into every avatar export. avatar-web also depends on avatar-core.

Photo Mode exports the currently rendered avatar as SVG or PNG. You can choose the resolution and use a transparent, solid, linear-gradient, or radial-gradient background.

The JSON project file contains the complete current document: avatars, base and avatar-specific behavior libraries, expressions, animations, and playback selection. Importing a project replaces the current local document after confirmation.

• Node.js 22.12 or newer
• pnpm 10.34 (declared by the repository's packageManager field)

pnpm install
pnpm dev

Open http://localhost:5173.

Before opening a pull request, run the complete local check:

pnpm check

The GitHub Actions workflow runs the same command on every push and pull request.

Create the static production bundle:

pnpm build

The deployable site is written to dist/. Serve it locally before publishing:

pnpm preview

The application is a client-only Vite site with no server runtime or environment variables. The build uses relative asset paths, so the contents of dist/ can be hosted at a domain root or a subpath, including a GitHub Pages project URL. Any static host that serves index.html can deploy it.

Vercel Web Analytics and Speed Insights are integrated in the React entry point. Enable both products in the Vercel project dashboard, then redeploy so their collection routes become available.

• React 19 coordinates the editor UI and durable application state.
• TypeScript is configured in strict mode.
• Vite 8 provides the development server and production build.
• Motion owns high-frequency rendering and playback values.
• SVG renders the procedural avatar geometry.
• Tailwind CSS 4 and reusable components under src/components/ui/ provide the interface layer.
• Vitest covers geometry, playback, editing, persistence, rendering, and export behavior.

Geometry, playback, document operations, and the standalone runtime remain framework-independent. React state stores durable editor data; Motion values handle frame-by-frame visual updates without forcing React renders.

There is no remote backend in this repository. The complete Studio document and interface language preference are stored in the browser's local storage. Exported files are generated locally in the browser. Clearing site data removes the local project, so JSON export is the recommended backup mechanism.

The current project format is a pre-release schema. Compatibility is maintained with the current schema only unless an explicit migration is introduced.

Keep domain calculations outside React components, preserve the separation between durable React state and high-frequency Motion values, and add focused tests for domain changes. Do not edit src/features/export/standaloneEngine.generated.ts directly; run pnpm engine after changing its source modules.

English, French, and Simplified Chinese interface copy must stay synchronized across src/i18n/index.ts and src/i18n/zh.ts.

For the domain vocabulary, invariants, and architecture boundaries, read CONTEXT.md.

Bible Strong Avatar Lab is licensed under the GNU Affero General Public License v3.0.

You may use, study, modify, and redistribute the project. If you distribute the application or a modified version, you must notably:

• make the corresponding source code available;
• preserve the copyright and license notices;
• distribute derivative work under the GNU AGPL v3.0;
• make the corresponding source available when a modified version is offered to users over a network, including as a hosted web service;
• document significant changes made to the project.

See the LICENSE file for the complete and legally authoritative terms.