|
|
|
@@ -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.
|