Skip to content

v1.0.0-alpha.3

Pre-release
Pre-release

Choose a tag to compare

@IAFahim IAFahim released this 11 Sep 04:57
· 1108 commits to main since this release
628ebc6

v1.0.0-alpha.3

Alpha.3 replaces per-timeline playback facades and runtime IDs with generated catalog queries over borrowed component columns. One timeline can contain heterogeneous track and clip pairs. Each authored track binds one typed operation, and every row retains independent asset, position, and loop cycle while sharing the caller's game clock.

Public model

public readonly struct DamageJob : ITimelineJob<DamageTrack, DamageClip>
{
    public static void Execute(
        in Frame<DamageTrack, DamageClip> frame,
        in Resistance resistance,
        ref Health health)
        => health = new(health.Value - frame.Direction * frame.Clip.Amount
            * frame.Track.Multiplier * resistance.Scale);
}

public readonly partial struct Attack : ITimeline
{
    public static void Define(scoped Builder builder)
    {
        var damage = builder.Track(new DamageTrack(2f)).Use<DamageJob>();
        builder.Clip(damage, new DamageClip(10f), 5u, 6u);
    }
}

public readonly struct CombatRows;

public readonly partial struct Combat : ITimelineCatalog
{
    public static void Define(scoped CatalogBuilder builder)
        => builder.Schema<CombatRows>().Asset<Attack>();
}

var states = new[] { new Combat.State(Combat.Asset.Attack) };
var query = new Combat.Query().CombatRows(states, resistance, health);
query.Tick(200_000u, 3);
query.Tick(200_003u, -3);

Normal Roslyn and supporting IDE builds generate timelines and catalogs automatically. The execution API has no Build, Compile, InMemory, Bind, registration ID, Start, Stop, TrySeek, or per-tick failure value.

Semantics

  • A requested step selects each row without effects, executes typed stages in authored order, then commits each selected row once.
  • Reverse movement executes the exact reversed occurrence order.
  • Tick(G,+N) emits G..G+N-1; Tick(G,-N) emits G-1..G-N.
  • Finite assets clamp independently. Empty routes, gaps, empty definitions, completion, and zero delta are no-ops.
  • Nonempty loops use unsigned local position and signed cycle with explicit wrapping arithmetic.
  • One active clip is borrowed; two active clips resolve through Blend into one frame.
  • Jobs borrow unmanaged in and ref columns. Alpha.3 rejects out.
  • Schema construction rejects mismatched lengths, invalid routes, and prohibited writable aliases before effects.
  • A user exception preserves its executed effect prefix and prevents commit for that selected step.

See the complete API and execution semantics.

Packages

The GitHub prerelease contains five runtime/build packages, three symbol packages, a deterministic Unity UPM archive, a NativeAOT smoke archive, a generation report, a release manifest, and SHA-256 checksums. NuGet publication is disabled; install the .nupkg files from a local source.

Tl.CSharp is the recommended C# install. It depends on Tl.Runtime at application runtime and embeds Tl.Gen.CSharp.dll plus the compatible Tl.Compiler.dll as build-only analyzer/tool assets. Package-only JIT and NativeAOT receipts prove those toolchain assemblies do not enter application output.

The UPM package contains the Unity runtime boundary only. A package-only .NET authoring project materializes deterministic Unity-compatible C# before Unity compilation; compiler and Roslyn assets stay outside the player graph.

Tl.Gen.C retains its qualified C ABI v2 backend. It does not yet emit alpha.3 heterogeneous catalogs.

Verification

Exact production coverage at commit 9b1807686b9035b19a63133cd4f416ab1721e29b uses Microsoft dotnet-coverage 18.11.0 and eng/coverage.settings.xml:

Assembly Lines Branches
Tl.Core 100% 100%
Tl.Compiler 100% 100%
Tl.Gen.C 100% 100%
Tl.Gen.CSharp 100% 100%
Total 2,740 / 2,740 1,628 / 1,628

All 221 tests passed. The Cobertura report SHA-256 is ddf400d7341d8f92359d2d6ba250aadc22550f7aab069c628d5131f40243d544; the settings SHA-256 is ac6f6eaa04abe0f4929219523d0f2c0c204cef68e0ffc4f0ce87696fdaa63aa2. Coverage establishes executed source paths, not correctness by itself; oracle, boundary, allocation, package, AOT, and Unity receipts remain distinct gates.

The retained three-process full-query medians are 1.804 ns for one track, 3.754 ns for A-B-A, 21.230 ns for 16 tracks, 34,250.868 ns for 256 tracks, 1.997 ns for a gap, 2.555 ns for a blend, 2.256 ns for three inputs, and 34.650 ns/entity-tick for 256 mixed rows. Every arm reports 0 B. The <3 ns result applies only to the one-track, gap, blend, and three-input fixtures. The 256-track staged fallback remains open in issue #10.

Unity qualification covers stable Unity 6000.0.83f1, Entities 1.4.3, Burst 1.8.30 and the preview Unity 6000.7.0a5 lane. Both pass 4/4 EditMode and 4/4 PlayMode tests. Stable Mono and IL2CPP players execute Burst jobs, pass native leak scans, and exclude compiler/generator/Roslyn assemblies. The stable 10,000-row fixture measures 18.006 ns/entity-step, 20 jobs/step, and 0 main-thread managed B.

Production source plus paths is 231,796/250,000 B at coverage commit 9b1807686b9035b19a63133cd4f416ab1721e29b. Deterministic release artifacts are built twice, compared byte for byte, verified against fixed contents and identities, and recorded in one manifest and checksum set. The exact tagged artifact receipt belongs to release issue #35.

License selection and NuGet publication remain separate owner decisions and are not performed by the GitHub prerelease workflow.

See the migration guide, Unity guide, performance report, and release procedure.