Reusable animation and cosmetic core

Original engine-independent Java source · compiled and tested on Java 17/21 · native integration pending.

Download current v4 source and tests · Historical v2 test output and archive hash.

This brings four reusable presentation primitives into one package. It does not contain a Minecraft mod entry point or native hooks, and is not a file to put in the Mods folder. Earlier standalone studies remain available for provenance.

Component	What is implemented	Boundary
SoulSightFrame	Reusable atlas-frame output, explicit Flame/Candle/Gem and display-pass gates, reduced-motion frame	Actual textures, bone transforms, buffers and native game clock still need an adapter
ImpactVisualLedger	Bounded cosmetic event identity with separate weapon/projectile branches, actor/weapon/world separation	Finite window; evicted events can be accepted again; never server damage validation
EmissionClock	Per-emitter game-time scheduling, duplicate-timestamp suppression, visibility rebasing and bounded stall recovery	Cosmetic requests only; production visual budgets and native particle pools remain unvalidated
FrameVisibilitySet	Pre-bound discrete frame visibility, duplicate-part validation, no-op repeated selections and explicit disposal	Native bone binding and pass ownership remain adapter responsibilities; discrete frames do not implement crossfade

v4: verified authoring timing

Current source, tests and timing receipt. Inspection of the actual Soul Storm scene confirms 60 fps with fps_base 1, and the atlas index changes every four authoring frames. The correct sixteen-cell rate is 15 cells/second, with a 16/15-second cycle. All 64 sampled indices match the expected four-frame holds.

The earlier v3 six-cell/second duration was an assumption and did not match this scene. v4 corrects that default; the legacy fifteen-frame/two-second option stays unchanged. The JVM timing test now receives the expected cycle from the actual authoring receipt. All five suites pass on Java17/21, including a clean ZIP extraction. Native rendering, game-clock binding and artistic loop review remain open.

v3: explicit atlas layouts, including the new rooted fire

Download v3 source and tests. The legacy fifteen-frame/two-second default is retained. A validated immutable Atlas contract adds the sixteen-frame four-by-four rooted-fire layout, six frames per second, a 2048-square half-texel inset and an explicit top-origin UV convention. The native renderer must handle its own coordinate orientation and texture binding; Candle is not silently switched to the new flame asset.

The new test covers 100,000 samples, all sixteen frames, loop boundaries including the preceding representable double, stable paused timestamps, reduced motion, invalid contracts and large finite times. All four prior component suites remain passing. Clean ZIP extraction, compilation with Java17 target and execution on Java17 and Java21 pass. The float blend factor is capped below one to avoid a rounded out-of-contract endpoint.

This fixes a reusable source-level atlas mismatch. It does not implement the native focus morph, shader, crossfade, hands, alignment, game hooks or GPU path. No native FPS or visual acceptance is claimed.

Visibility is different from zero scale

The pinned TaCZ BedrockPart render path checks its visibility flag and then transforms/compiles nonempty parts. The inspected path has no equivalent early-out for a zero scale alone. A frame-bone effect should not assume that collapsing unused planes removes their CPU submission work.

The new helper validates a complete set of actual part identities before changing visibility. It hides all frame targets once on binding. Repeatedly selecting the same frame performs no writes; a frame change touches only the old and new targets. It hides on invalid selection/disposal and rejects use after disposal. Bindings must belong exclusively to this owner and must be rebuilt after resource reloads. Callbacks must be nonthrowing cosmetic assignments.

Tests cover 15 parts, repeated selections, changing frames, bad indices, duplicate native identities through distinct callback wrappers, null bindings, disposal and separate instances. These tests count visibility writes; they do not measure TaCZ frame time or certify native integration.

A further source detail matters for future effect exports: the presence of a standalone Step interpolator class does not mean Bedrock lerp_mode: step is supported. The pinned LerpMode enum does not include STEP, and the inspected scale-channel conversion falls back to linear for unknown values. Validate the actual import/playback path instead of trusting an exporter label.

Why timing is separate from rendering

The released Hive Blaster renderer requests particles inside its render method and keeps its color counter on the renderer. The new clock is intended to avoid copying render-invocation-dependent emission into the upgraded presentation.

The scheduler test supplies the same ten seconds of game time at 20, 30, 60, 144, 240, 1000 and 2000 updates per second. Each schedule produces 400 requests using a 40-per-second test rate. Repeating a timestamp emits nothing. Paused time, two emitters, hidden/resume transitions, clock rollback, invalid values and long stalls are also exercised.

These are simulated input cadences, not achieved game FPS. The rate 40 is a math fixture, not the chosen particle density for any weapon. Long stalls and configured caps intentionally drop excess cosmetic requests rather than accumulating a backlog; that tradeoff needs visual acceptance.

Safe integration contract

• Drive updates from the appropriate paused game/presentation clock, not wall time.
• Own state per emitter/render owner. Notify the clock when emission stops; it cannot infer invisibility from silence alone.
• Apply the event ledger once per logical branch notification, then fan out to configured effects. Do not use it once per particle, camera or shader pass.
• Keep gameplay projectiles, damage, resource costs and authority outside this package.
• Treat world generations and event identities as adapter responsibilities. The ledger is not authentication or permanent replay protection.
• Draw existing effects across supported views/passes without spawning them again.

Verification and remaining work

The source compiled with an actual Corretto 17 JDK and ran its four test mains on that runtime and OpenJDK 21. This establishes pure-core JVM checks, not Minecraft 1.20.1/1.21.1 API compatibility.

Native hook placement, original-versus-upgraded visual comparison, real hands/aim, interruption, shader/Vulkan behavior, networking, saves, allocations and frame/tick measurements remain open. No numeric source test substitutes for those gates.

Sight integration plan · Customization · Authoring reproducibility

Earlier consolidated v1 source remains available.