feat(pbs): add sprite animation and shared Studio authoring
Implement DEC-0084 with factory-only Sprite/Animator structs, complete result lowering, validated animation sidecars, generated PBS factories and JavaFX/MCP authoring through shared services. Qualify native dev/release with ordinary and optimized producers, zero-allocation playback, private-cycle reclamation, canonical Composer pixels, installed JARs and JavaFX lifecycle. Preserve the runtime checkout and existing host ABI.
This commit is contained in:
@@ -0,0 +1,142 @@
|
||||
# Animation Authoring Specification
|
||||
|
||||
Status: Normative v1. Owner: studio. PBS projection owner: compiler/pbs.
|
||||
Packer owns registered assets, composition, effective glyph indices and fingerprints.
|
||||
|
||||
## Purpose
|
||||
|
||||
JavaFX, AI tools and compiler consumers share one versioned editorial document,
|
||||
validator and bank-layout identity contract. This sidecar is neither a runtime
|
||||
asset nor generated editable PBS. The entire authoring/projection contract is
|
||||
specified below.
|
||||
|
||||
## Canonical document and services
|
||||
|
||||
Each registered glyph bank can contain animations.studio.json, a JSON UTF-8
|
||||
sidecar distinct from asset.json and studio.asset.json. Its strict schema is:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"bank_asset_uuid": "<containing bank UUID>",
|
||||
"bindings": [{"artifact_id": "<stable selected artifact>", "glyph_id": 7,
|
||||
"fingerprint": "<sha256>"}],
|
||||
"animators": [{"id": "hero", "initial_clip": "idle", "clips": [
|
||||
{"name": "idle", "mode": "loop", "frames": [
|
||||
{"artifact_id": "<stable selected artifact>", "duration_ticks": 4}
|
||||
]}
|
||||
]}]
|
||||
}
|
||||
```
|
||||
|
||||
Animator IDs are unique PBS identifiers matching [A-Za-z_][A-Za-z0-9_]*. Modes
|
||||
are once/loop; frame order matters. Each animator has nonempty named clips;
|
||||
zero animator definitions is allowed. Decode long integers exactly. No palette,
|
||||
position or runtime bank slot is stored. Unknown fields/versions and malformed
|
||||
or duplicate bindings/JSON keys are errors, not fallback triggers.
|
||||
|
||||
Every referenced artifact must match the containing bank UUID and Packer's current
|
||||
effective glyph ID/fingerprint. Reordering, removal and content replacement produce
|
||||
blocking drift diagnostics. Explicit prepare/apply rebind presents old/new bindings
|
||||
and affected frames, validates the result and requires the expected revision.
|
||||
Never silently retarget by list order or path. Save validates the whole candidate
|
||||
against the current snapshot and uses a revision check plus atomic replacement;
|
||||
failed validation/conflict preserves the canonical file and editable draft.
|
||||
Perform revision verification and publication under the same project exclusion;
|
||||
replace atomically within the same filesystem. Read/validate may expose an invalid
|
||||
document with diagnostics for repair; preview/build/projection must not fall back
|
||||
to an older valid document or another schema version.
|
||||
|
||||
The new neutral prometeu-animation library (p.animation) owns immutable DTOs,
|
||||
strict codec, shared validator, revisions and editorial preview timeline. It has
|
||||
no JavaFX/Spring/compiler/concrete-packer dependency. Packer exposes effective
|
||||
layout snapshots, and app supplies the neutral GlyphBankLayoutSource port. Both
|
||||
Studio services and the build context loader use this shared validator. A build
|
||||
with included definitions but no configured resolver fails explicitly. Existing
|
||||
projects without definitions retain an empty context and compatible entry points.
|
||||
|
||||
FESurfaceContext carries language-neutral validated snapshots; PBS alone emits
|
||||
virtual modules at @<project-name>:generated/animations/b_<uuid-without-hyphens>.
|
||||
Factories are create_<animator_id>(bank_id: int) -> result<AnimationError> Animator.
|
||||
Reserve generated/animations and reject physical-module collisions. Only registered,
|
||||
build-included banks publish factories. Invalid included definitions block build;
|
||||
never reuse stale generated text. Sort factories by ID, preserve clip/frame order,
|
||||
escape PBS literals and exclude timestamps/absolute paths. Keep generated modules
|
||||
read-only through FrontendSourceDocument and revision-scoped ExternalSourceRegistry
|
||||
URIs, with generated spans mapped to original JSON fields. No generated source
|
||||
becomes a second editable persistence surface.
|
||||
Generated revision includes the document, resolved bindings and generator version.
|
||||
Invalidate old origins after changes/reconnect, reject generated save/rename, and
|
||||
let the UI open the original JSON field through the authoring service.
|
||||
|
||||
Studio API/core provides list/read, draft validation, save/delete, prepare/apply
|
||||
rebind and preview. JavaFX provides complete animator/clip/frame authoring, initial
|
||||
clip/mode, durations, ordering, diagnostics, save and drift repair. Preview has
|
||||
play/pause, explicit ticks and palette input. Shared neutral rendering returns
|
||||
canonical image plus observed bank/glyph/state/ticks; its timeline must match PBS
|
||||
native execution. No palette/position is persisted in the animation definition.
|
||||
|
||||
MCP adds task-authorized studio_animation_query (list/get/validate/preview) and
|
||||
studio_animation_update (save/delete/prepare_rebind/apply_rebind), with strict
|
||||
schemas, expected revisions and the same services as UI. Reuse existing authority,
|
||||
operations, cancellation, revocation, conflict handling and document handoff.
|
||||
|
||||
Both tools take projectRoot, taskId and operation, plus these exact domain fields:
|
||||
|
||||
| Operation | Fields and behavior |
|
||||
| --- | --- |
|
||||
| query/list | Optional assetUuid filter; project definitions/diagnostics. |
|
||||
| query/get | assetUuid; current document, revision, diagnostics. |
|
||||
| query/validate | assetUuid, optional candidate document; no persistence. |
|
||||
| query/preview | assetUuid, animatorId, clipName, nonnegative long elapsedTicks, paletteId, optional candidate document; sample from clip start. |
|
||||
| update/save | assetUuid, expectedRevision, complete document; explicit null revision only for create, never overwrite an existing file on create. |
|
||||
| update/delete | assetUuid, expectedRevision, animatorId; preserve other definitions. |
|
||||
| update/prepare_rebind | assetUuid, expectedRevision; return diff, candidate document/hash and bank snapshot revision, without writing. |
|
||||
| update/apply_rebind | assetUuid, expectedRevision, document, proposalHash, expectedBankRevision; validate the same proposed binding-only change against the current bank. |
|
||||
|
||||
Reject fields belonging to a different operation. Use the existing typed result
|
||||
envelope and image contract. Proposal hashes correlate content, not a new grant or
|
||||
approval workflow. UI autoplay schedules explicit tick updates with a transient
|
||||
preview rate; preview never persists an animation clock.
|
||||
|
||||
|
||||
## Persistence and authority
|
||||
|
||||
Operations use project identity, asset UUID, animator ID and expected revision;
|
||||
arbitrary caller-provided file paths are not definition addresses. Resolve authority
|
||||
before cache lookup. Manual, Agent and Debug use existing project exclusion,
|
||||
cancellation/revocation and document handoff; no parallel grant or approval flow
|
||||
is introduced. Save validates the whole document against the current layout,
|
||||
checks expected revision under project exclusion and atomically replaces the file
|
||||
on the same filesystem. Conflict or recoverable failure preserves canonical bytes
|
||||
and the editable draft.
|
||||
|
||||
Rebind is the only binding migration operation: preparation returns old/new IDs,
|
||||
fingerprints and affected frames without persisting; application validates the
|
||||
same proposal hash, document revision and bank revision before replacement.
|
||||
Read, preview, analysis and build never silently repair or reuse stale sources.
|
||||
|
||||
## Preview and UI
|
||||
|
||||
The editor integrates glyph-bank details and supports create/rename/delete of
|
||||
animators and clips, initial-clip/mode selection, frame addition/removal/reordering,
|
||||
exact long-duration entry, diagnostics, save conflicts and explicit drift repair.
|
||||
Palette and position are transient viewing inputs. Play schedules explicit ticks
|
||||
using a transient preview rate; no clock is persisted in animation definitions.
|
||||
The renderer returns canonical pixels and observed bank/glyph/state/ticks without
|
||||
JavaFX and must reject invalid bank/references instead of simulating success.
|
||||
|
||||
The timeline follows the complete state/interval table in
|
||||
[Core Sprite and Animation](../compiler-languages/pbs/27.%20Core%20Sprite%20and%20Animation%20Specification.md).
|
||||
Production-native conformance must compare those observations for identical input
|
||||
timelines, direct/generated factories and both producer/runtime profiles.
|
||||
|
||||
## Dependencies and distribution
|
||||
|
||||
`prometeu-animation` (`p.animation`) contains immutable DTOs, strict JSON codec,
|
||||
structural/snapshot validation, revisions and preview timeline. It depends on no
|
||||
JavaFX, Spring, HTTP, compiler or concrete Packer implementation. Studio core
|
||||
orchestrates persistence/layout/rendering; app composes the Packer API adapter.
|
||||
PBS alone generates PBS source; compiler/backend stay independent of Studio core.
|
||||
|
||||
Installed references, examples and MCP schemas must expose this same contract.
|
||||
Reference in New Issue
Block a user