2386b78817
Add shared core-backed React and browser runtimes, continuous playback transitions, export previews and API documentation. Package the JavaScript export as a CDN-powered demo with the portable avatar definition.
81 lines
3.2 KiB
Markdown
81 lines
3.2 KiB
Markdown
# @bible-strong/avatar-core
|
|
|
|
Framework-independent validation, semantic playback and renderer-neutral SVG scene generation for
|
|
Bible Strong procedural avatars. The package has no React, DOM, Motion or browser-storage
|
|
dependency.
|
|
|
|
## Install and validate
|
|
|
|
```sh
|
|
pnpm add @bible-strong/avatar-core
|
|
```
|
|
|
|
Use `parseAvatarDefinition` for untrusted JSON text. It enforces the 256 KiB/depth limits and
|
|
detects duplicate object keys before validating against the v1 schema. Use
|
|
`validateAvatarDefinition` when the value is already materialized.
|
|
|
|
```ts
|
|
import { parseAvatarDefinition } from '@bible-strong/avatar-core'
|
|
|
|
const parsed = parseAvatarDefinition(jsonText)
|
|
if (!parsed.ok) {
|
|
throw new Error(`${parsed.errors[0].path}: ${parsed.errors[0].message}`)
|
|
}
|
|
const definition = parsed.value
|
|
```
|
|
|
|
Both functions return a non-mutating discriminated result. Successful values are deeply frozen;
|
|
errors include an RFC 6901 JSON Pointer, code and message. The committed JSON Schema is exported as
|
|
`@bible-strong/avatar-core/schema`.
|
|
|
|
Definitions from the earlier pre-release runtime export may still contain
|
|
`standardAnimationSet: 1`; the marker is accepted for compatibility but does not add any
|
|
implicit animations.
|
|
|
|
## Semantic lookup and playback
|
|
|
|
Public calls use semantic keys only. `resolveExpression` and `resolveAnimation` return typed errors
|
|
for keys that are not present in the validated definition. Every animation is explicit in the
|
|
definition, so the JSON remains the single source of truth for what an avatar can play.
|
|
|
|
```ts
|
|
import {
|
|
advanceAvatarPlayback,
|
|
playAvatarAnimation,
|
|
renderAvatarFrame,
|
|
} from '@bible-strong/avatar-core'
|
|
|
|
const started = playAvatarAnimation(definition, 'idle', 0)
|
|
if (!started.ok) throw new Error(started.error.message)
|
|
|
|
const state = advanceAvatarPlayback(definition, started.value, 500, {
|
|
random: () => 0.5,
|
|
})
|
|
const scene = renderAvatarFrame(definition, state, 500, {
|
|
random: () => 0.5,
|
|
reduceMotion: false,
|
|
})
|
|
```
|
|
|
|
`advanceAvatarPlayback` is a pure state transition driven by a monotonic timestamp and injected
|
|
random source. The timeline for each step is transition then hold. `pauseAvatarPlayback` and
|
|
`resumeAvatarPlayback` preserve exact progress. With `reduceMotion: true`, transitions and ambient
|
|
motion jump deterministically to their target while configured blinks remain active.
|
|
|
|
`renderAvatarDefinition` renders a static semantic expression. `renderAvatarFrame` renders an
|
|
animated frame. Both return paths, visibility and resolved colors without creating DOM nodes.
|
|
|
|
## Entry points
|
|
|
|
- `@bible-strong/avatar-core`: contract, validation, semantic catalog, playback and scene APIs.
|
|
- `@bible-strong/avatar-core/schema`: the v1 Draft 2020-12 JSON Schema.
|
|
- `@bible-strong/avatar-core/geometry`, `/body`, `/surfaces`, `/ambient-motion`: advanced pure
|
|
primitives for renderer authors.
|
|
|
|
Application integrations are kept in separate packages: `@bible-strong/avatar-react` renders with
|
|
React 19, while `@bible-strong/avatar-web` mounts the same definition directly into the DOM. Both
|
|
depend on this package and use the same playback and scene implementation.
|
|
|
|
This package is private while copyright ownership, Apache-2.0 relicensing and repository metadata
|
|
are confirmed. Local tarballs are for verification only and must not be published.
|