Manual

Manual

Entities, components and systems

Abyss keeps the state of your game as entities that carry components, and changes it with systems that run every frame. This page explains the three, the resources that sit beside them, how a frame runs its systems, and how a system changes what exists.

The model in one paragraph

An entity is an id and nothing else. A component is a plain struct of data that an entity carries: a place, a health value, a speed. A system is a function that runs every frame over every entity carrying a given set of components, reading some and writing others. Behavior never lives on the data: a component has no methods for the engine to call, and a system is the only thing that changes it.

Underneath, this is Bevy's ECS. Every entity is a Bevy entity, and the engine's own components, such as Transform, cameras and lights, are Bevy's own types. Components you declare in C# are registered with Bevy as the game starts and stored in Bevy's tables beside Bevy's own. A C# system reads that storage directly, with no copy, and a Rust system is an ordinary Bevy system.

Entities

In C# an entity is a ulong, the number Bevy's Entity converts to. It holds no data of its own: what it is called, where it is and what it looks like are all components. A parent and its children are components too: Bevy's ChildOf names the parent, and the engine sets it for you through commands (see Changing the world).

Because an entity is only an id, you can keep one in a component to point at another entity. An EntityRef field does that and shows as a slot in the Inspector.

Components

A component is a struct of plain values: numbers, booleans, vectors, enums, fixed-size lists and text, and references to assets or other entities. It can hold no class, string or array, because the engine stores it in memory that .NET does not manage and never runs a destructor for it. In C# the compiler enforces this: a component must be an unmanaged struct.

[AbyssComponent][StructLayout(LayoutKind.Sequential)]public partial struct Wobble{    [Range(0f, 2f)] public float Height;    [Range(0f, 10f)] public float Speed;    [HideInInspector] public float Phase;}

Bevy groups entities that carry the same set of components, called an archetype, into one table, each component a contiguous column. When a system asks for Transform and Wobble, the engine finds every table that has both and hands the system each table's columns as a chunk. Adding or removing a component moves an entity to another table.

The Inspector shows a component from Bevy, from a package or from your own code the same way. C# in a game and Rust in a game show how to declare components in each language.

No component is required

An entity can carry any set of components, including none. Even Transform is optional: an entity that only plays music, or only holds a game's state, needs no place in the world, and Remove Component takes a Transform off like anything else.

The one rule is Bevy's required components. A component can say that it needs another, and adding it brings that one too: a Rust component marked #[require(Transform)] brings a Transform, and a mesh brings what Bevy needs to draw it. The Inspector will not remove a component that another component on the entity requires, and says which one.

Systems

A system declares which components it reads and which it writes, and the schedule runs it over every entity that has them. In C#, mark a static method [AbyssSystem] and its signature is the declaration: ref means write, in means read.

public static partial class Wobbling{    [AbyssSystem]    [MethodImpl(MethodImplOptions.AggressiveInlining)]    private static void Bob(ref Transform transform, ref Wobble wobble, in SystemContext context)    {        wobble.Phase = (wobble.Phase + (wobble.Speed * context.DeltaTime)) % MathF.Tau;        transform.TranslationY = wobble.Height * MathF.Sin(wobble.Phase);    }}

This system runs once for every entity that has both a Transform and a Wobble, and skips everything else. An entity that loses its Wobble stops bobbing; one that gains it starts. That is how behavior is switched on and off: by the data an entity carries, not by a flag in an object.

A system can narrow its query further with filters, such as entities that have a Player component or lack an Enemy one, without reading them. Systems are added to the game by plugins, which C# in a game covers.

Resources

Some data belongs to no entity: a score, a clock, a gravity constant. That is a resource, a single struct the world holds once. A system declares a resource it reads as Res<T> and one it writes as ResMut<T>, and the schedule orders it by those just as it does by components. A system that touches only resources runs once a frame.

[AbyssSystem]private static void Count(ResMut<Score> score, in SystemContext context){    score.Value.Seconds += context.DeltaTime;}

A project's settings declared in code are resources too, there from the first frame. When you stop the game in the editor, your game's resources go back to what they were when you pressed Play, along with every entity.

How a frame runs

Bevy runs a frame as a series of schedules, and Abyss puts your systems into them:

  1. Fixed steps. Systems marked to run at a fixed rate run once for each step of the game's fixed clock, inside Bevy's FixedUpdate. That can be zero, one or several steps in a frame.
  2. Your frame's systems, inside Bevy's Update. Code waiting in an await resumes just before them.
  3. Commands are applied: the entities your systems spawned, changed and removed this frame.
  4. Bevy's PostUpdate, where Bevy works out each entity's GlobalTransform from its Transform and its parents'.
  5. Drawing.

So a system that reads GlobalTransform sees the world positions Bevy worked out at the end of the previous frame, before any of this frame's writes to Transform.

The order of systems

Within a schedule, systems run in the order your plugins add them. When two systems touch different data, add an explicit order if one must come first, such as reading input before moving:

SystemId input = schedule.Add("Read input", [player.Write()], ReadInput);SystemId move = schedule.Add("Move", [transform.Write(), player.Read()], Move);schedule.RunBefore(input, move);

A set of orders that contradicts itself is rejected when the schedule is built, with an error naming the systems in the cycle.

Your C# systems run one after another on the engine thread, in that order, the same every frame. Bevy runs Rust systems on its own multithreaded executor.

Systems at a fixed rate

Physics, and anything that pushes on it, must move the same at 30 frames a second as at 144. Mark such a system [AbyssSystem(Fixed = true)], or add it to schedule.Fixed, and its context.DeltaTime is the fixed step: a sixtieth of a second unless Project Settings ▸ Time says otherwise.

Every system runs on the game's time. It stands still while the game is paused, can be slowed with world.Time.Scale, and never advances by more than the Maximum Allowed Timestep in one frame, so a slow frame is not followed by a burst of catch-up steps.

One system on every core

A system over many entities can split its own loop across the machine's cores. Mark it [AbyssSystem(Parallel = true)] and its chunks are cut into slices that several threads run at once, with the same result as one thread as long as each entity's row is written only from that row. A parallel system cannot record commands, draw gizmos or write resources, and the build or the system's context refuses them; do that work in a separate system after it.

A failing system does not stop the frame

A system that throws is reported in the editor's Logs panel, and the rest of the frame runs. A system that throws every frame is reported in full once, then with one line every hundred failures, so the log stays readable.

Changing the world

A system cannot create or remove entities while it runs, because that would move entities between tables under the very chunks it is reading. Instead it records commands, and the engine applies them once every system in the schedule has run, in the order the systems ran.

A system declares what it may change, separately from what it reads, with structural:. Recording anything it did not declare is refused at the call.

schedule.Add("Fall", [transform.Write(), falling.Read()], static context =>{    foreach (Chunk chunk in context.Chunks)    {        Span<Transform> transforms = chunk.GetSpan<Transform>(0);        ReadOnlySpan<Falling> falls = chunk.GetReadOnlySpan<Falling>(1);        ReadOnlySpan<ulong> entities = chunk.Entities;
        for (int i = 0; i < transforms.Length; i++)        {            transforms[i].TranslationY -= falls[i].Speed * context.DeltaTime;            if (transforms[i].TranslationY < -3f)            {                context.Commands.Despawn(entities[i]);            }        }    }}, structural: StructuralAccess.None.AndDespawn);

context.Commands can:

  • Instantiate a prefab at a position: Instantiate(prefab, position, rotation). This is the usual way to create something the player sees.
  • Spawn entities of an archetype, many at once, with their first values written through spans: Spawn(archetype, count).
  • Add and remove components: AddComponents(archetype, entities) and RemoveComponents(archetype, entity). Adding a component an entity already has overwrites it, and removing one it lacks does nothing.
  • Despawn an entity, and set or clear its parent.

The ids of entities a command creates are available at once, before the command is applied, so you can record more commands for them in the same frame:

ulong pyramid = context.Commands.Instantiate(prefab, where, Quaternion.Identity);ComponentBatch given = context.Commands.AddComponents(fall, [pyramid]);given.GetSpan<Falling>(0)[0] = new Falling { Speed = 3f };

Another system may destroy an entity in the same frame you record a command for it. Such commands are skipped rather than treated as errors.

A spawned component starts zeroed, or at the values its field initializers give. A zeroed Transform has zero scale and is not a rotation, so fill a spawn batch's transforms with Transform.Identity.

Data and behavior kept apart

If you are used to objects that carry their own update methods, the main difference is where behavior lives: nothing calls into a component. A system moves every entity that qualifies in one loop over contiguous memory. In the engine's own benchmark, a C# system adding a velocity to the positions of half a million entities takes under half a millisecond a frame.

This also changes how you structure a game:

  • Behaviors combine by components. An entity that can bob and burn carries Wobble and Burning, and two independent systems handle them. There is no class hierarchy to design.
  • Every change has a name. What writes Transform is a named system, which the Profiler times and the Logs panel names when it fails.
  • Editor-only behavior is a system too. A line drawn over the Scene panel for a selected entity comes from a system in a plugin marked [EditorOnly], not from a method on the component, and a built game never runs it.

To put these ideas into practice, continue with C# in a game, or with Scenes and prefabs to see how entities are saved and placed.

In the Scripting API