Trecs

A high-performance Entity Component System framework for Unity, designed for deterministic simulation, recording/playback, and Burst/Jobs integration.

Features

• High-performance storage — Components are stored in contiguous arrays (structure-of-arrays), grouped by explicit tags for cache-friendly iteration
• Serialization — Full world state serialization out of the box, including all entities, components, and heap data
• Bookmarks, Recording & Playback — Save and load snapshots of full game state, record and replay inputs deterministically with checksum-based desync detection, or use for network rollbacks
• Burst & Jobs — First-class support for Unity's job system and Burst compiler with automatic dependency tracking based on component access
• Source generation — Roslyn-powered code generation eliminates boilerplate for systems, aspects, and templates
• Aspects — Bundled component access that groups related read/write operations into a single reusable struct
• Sets — Dynamic entity subsets without group changes, for efficient sparse iteration and overlapping membership
• Interpolation — Built-in fixed-to-variable timestep interpolation for smooth rendering
• Heap & Pointers — SharedPtr, UniquePtr, and native variants for storing managed or large data outside of components
• Deterministic simulation — Fixed-timestep loop with deterministic RNG and isolated input handling, designed for networking and replay
• Template system — Composable entity type blueprints with tag-based grouping and inheritance

Quick Start

// Step 1: Define components
[Unwrap]
public partial struct Position : IEntityComponent
{
    public float3 Value;
}

// Step 2: Define entity tags
public struct PlayerTag : ITag { }

// Step 3: Define entity types
public partial class PlayerEntity : ITemplate, IHasTags<PlayerTag>
{
    public Position Position;
    public Velocity Velocity;
}

// Step 4: Define systems to operate on entities
public partial class MovementSystem : ISystem
{
    [ForEachEntity(Tag = typeof(PlayerTag))]
    void Execute(in Player player)
    {
        player.Position += player.Velocity * World.DeltaTime;
    }

    partial struct Player : IAspect, IRead<Velocity>, IWrite<Position> { }
}

// Step 5: Define, initialize, and run the world
var world = new WorldBuilder()
    .AddEntityType(PlayerEntity.Template)
    .Build();

world.AddSystem(new MovementSystem());
    
world.Initialize();

// Call this from a MonoBehaviour Update
world.Tick();

// Call this on MonoBehaviour OnDestroy or when complete
world.Dispose();

Installation

Requires Unity 6000.3+.

Via OpenUPM (recommended)

With the openupm-cli:

openupm add com.trecs.core
# Optional: serialization features (bookmarks, recording/playback, save/load)
openupm add com.trecs.serialization

Or add manually to Packages/manifest.json:

{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["com.trecs"]
    }
  ],
  "dependencies": {
    "com.trecs.core": "0.1.0",
    "com.trecs.serialization": "0.1.0"
  }
}

Via Git URL

Open Window > Package Manager, click + > Add package from git URL, and enter:

https://github.com/svermeulen/trecs.git?path=UnityProject/Trecs/Assets/com.trecs.core

For the optional serialization package:

https://github.com/svermeulen/trecs.git?path=UnityProject/Trecs/Assets/com.trecs.serialization

When using git URLs, add com.trecs.core before com.trecs.serialization (Unity can't resolve versioned dependencies from git URLs).

Documentation

See full documentation at svermeulen.github.io/trecs.

Samples

The project includes 13 samples covering everything from basic entity creation to complex simulations with Burst jobs. To try them, clone the repo, open UnityProject/Trecs in Unity 6000.3+, and run Assets/Samples/Main.unity.

Sample	Concepts
01 Hello Entity	Components, tags, templates, systems
02 Spawn & Destroy	Entity lifecycle, dynamic spawning
03 Aspects	Bundled component access for clean iteration
04 Predator Prey	Cross-entity references, template inheritance
05 Job System	Burst compilation, parallel jobs
06 Partitions	Template partitions, partition transitions
07 Feeding Frenzy	Complex multi-system simulation
08 Sets	Dynamic entity subsets, sparse iteration, overlapping membership
09 Interpolation	Fixed-to-variable timestep smoothing
10 Pointers	Storing memory outside of components
11 Snake	Complete game with recording/playback
12 Feeding Frenzy Benchmark	Exhaustive examples of the many Trecs patterns available
13 Save Game	Bookmark-based save/load slots with the serialization package

Acknowledgments

Trecs was originally based on Svelto.ECS by Sebastiano Mandalà

License

MIT