Skip to content

1.0.0-alpha.7

Choose a tag to compare

@IAFahim IAFahim released this 17 Sep 03:41
· 925 commits to main since this release

1.0.0-alpha.7

Performance and ABI release over the data-authored surface: the typed playback lane becomes the only playback path, the frame view slims to ushort positions, and the authoring toolchain fuses parse with bake.

Playback lane

  • Timeline<T>.Seek(positions, forward).Apply(effects) over BakedLane<TTrack,TClip>.Bind(asset) measured tables is the single warm path (issue #104, PR #106). The Timeline.Rows(...) facade, TimelineKernels catalog, TickUnmanaged walk, and tlbake --kernel are removed; there is one execution path and no interpreter tier.
  • Single-dispatch mixed loops and finite gather: 1M-row set numbers per shape — static staggered up to 22.9x over the alpha.6 facade lane, finite staggered 2x, mixed ids 1.3-1.4x; every shape bit-exact against per-asset static lanes, forward and backward, 0 B warm.
  • Catch-up is repeated single-frame calls; rewind is forward: false. There is deliberately no multi-frame step parameter.

Frame ABI (breaking, issue #113)

  • Timeline-domain positions and ticks are ushort under a single 65,535-tick cap; TLB1 load and tlbake reject larger durations with a diagnostic naming both numbers.
  • Cycle and GameTick are removed from the engine, Frame, TickFrame, TimelineState, TimelineComponent, and the consumer Execute/Range seam; Frame.ClipLength and Frame.WithinClip expose the slot window instead.
  • Movement records halve to 8 B, TimelineState 16 -> 8 B, TimelineComponent 24 -> 16 B, set tables 44 -> 28 B/tick; the #113 A/B re-measured affected shapes at parity or better (finite staggered 0.38 -> 0.19 ns/row, static staggered 0.19 -> 0.15-0.17, alternating ids 1.67 -> 1.22).

Binding and sets

  • MeasuredLanes.Measure(asset) folds each position once per direction and shares the tables across every set bind (issue #108): repeated binds run 21.6x faster; TimelineSet.Add(asset, measured) reuses one measurement.
  • New TickPurity enum and the PairRuntime<TTrack,TClip>.Consume(execute, bind, TickPurity.WindowConstant) overload: declared window-constant consumers let the measurer fill each constant clip window from one evaluation — 3.81 -> 0.92 ms on the #108 corpus — bit-identically to per-tick evaluation by construction. The default stays exact per-tick fill.

Authoring and tooling

  • Fused authoring JSON parse+populate (issue #108, PR #110): parse+bake 5.9x with diagnostics identical to the retained legacy oracle.
  • tlbake --json introspects the authoring schema (schemaVersion 1, golden-filed), --watch re-bakes on save, and test configs are JSON-driven (issue #115).
  • Blender bridge addon tools/Tl.Blender exports NLA scenes to authoring JSON and auto-fills type pairs from tlbake --json (issue #111).

Repository

  • The interactive cookbook site is live on Pages with embeddable recipes, linked from the README (issue #116).
  • The README documents the ECS-hosted execution shape and integration cost ladder (issue #102).
  • The scheduled benchmark workflow ran the removed Alpha --filter '*' --artifacts collector and failed on every push since the harness reduced to --verify; it now runs the supported verification invocation and no longer needs write permission.

Migrating from 1.0.0-alpha.6

Playback

alpha.6 alpha.7
var query = Timeline.Rows(rows).Write(health); query.Tick(gameTick, delta); BakedLane<TTrack,TClip>.Bind(asset); once per asset, then Timeline<BakedLane<TTrack,TClip>>.Seek(positions, forward).Apply(effects); once per frame
Timeline.TickUnmanaged(...) over UnmanagedTickState the same lane over caller-owned ushort position and float effect columns; UnmanagedTickState is gone
TimelineKernels.Register/Chain/Range, tlbake --kernel Kernels.g.cs removed without replacement; BakedLane.Bind measured tables are the only execution path; tlbake flags are now bake, --json, --watch, --strip, --cache, --report
multi-frame Tick(gameTick, delta) repeated single-frame Seek(...).Apply(...) calls (lag catch-up); no game clock exists anymore

The effect column is a plain caller-owned float[]/Span<float>; a lane consumer writes exactly one ref float and self-inverts through Frame.Direction, so rewind replays the negated fold.

Frame and state

alpha.6 alpha.7
Frame.GameTick (uint) removed; the engine has no game clock
Frame.Cycle (long) removed; count wraps from movement flags (recipe below)
Frame.TimelineTick (uint) ushort
— Frame.ClipLength, Frame.WithinClip (ushort window metadata)
TickFrame.GameTick, TickFrame.Cycle, TickFrame.TimelineTick (uint/long) TickFrame.TimelineTick (ushort) plus Flags; ToFrame(slot, tick, flags, ref scratch)
TimelineState.Cycle (long), TimelineState.Position (uint) TimelineState(ushort position) — 8 B; Select(..., ushort duration, ..., out ushort tick, out FrameFlags flags)
TimelineComponent.Position (uint) ushort
PairRuntime.Consume execute/range pointers (byte*, uint, uint, long, FrameFlags, void**, int) (byte*, ushort, FrameFlags, void**, int); the separate ConsumeUnmanaged overload is folded into Consume
Apply(Span<float>, Span<long>) cycle records Apply(Span<float>)

Durations above 65,535 ticks fail at bake and at TimelineAsset.Load with a diagnostic; split the asset or shorten the timeline.

Wrap counting from flags

The removed Cycle column counted completed loops per row. Reconstruct it on the host from the movement flags returned by TimelineMovement.Select, once per row per frame — exactly what the movement law exposes to the lane:

if (!TimelineMovement.Select(new TimelineState(asset, position), duration, looping, reverse, out var next, out _, out var flags))
    return;
if ((flags & FrameFlags.TimelineEnd) != 0)
    loops += (flags & FrameFlags.Reverse) != 0 ? -1 : 1;
position = next.Position;

Forward wraps set TimelineEnd with Reverse clear; backward wraps set both; finite completions carry CompletedAfter/CompletedBefore. The recipe is receipted against a randomized 48-row, 400-step schedule in tests/Tl.Alpha (WrapCounts), where flag-reconstructed counts equal the removed engine cycle.

Optional: window-constant consumers

Registering a consumer with PairRuntime<TTrack,TClip>.Consume(execute, bind, TickPurity.WindowConstant) declares its per-tick output depends only on the slot's track and clip data — never on Frame.TimelineTick, Frame.WithinClip, or flags. MeasuredLanes.Measure then fills each constant clip window from one evaluation, bit-identically to per-tick evaluation by construction. A declaration that lies is not detected: the table deterministically carries the window's first-tick evaluation, so only declare consumers you control. The default remains exact per-tick fill.

Artifacts

release-artifacts builds four packages (Tl.Runtime, Tl.Gen.CSharp, Tl.CSharp, Tl.Bake) plus the Tl.Runtime symbol package, a package-only NativeAOT smoke archive, the generation report, RELEASE-MANIFEST.json, and SHA256SUMS. The GitHub Release carries the artifact run's SHA-256 table; the publish job runs only through the protected nuget-production environment on the owner's explicit dispatch.