Byte Engine Docs

World and messages

Look up the scope, channel, listener, factory, and handle model, its ordering and retention guarantees, the routes the world scope opens, and the transform, name, scene, and deletion contracts.

Byte Engine systems communicate through messages on a shared bus. An application's world is a message scope on which it creates entities and the systems that follow them. This page specifies that model. The design reasons are in the actor pattern note.

Scopes

A message bus owns one pool of storage and a set of routes. A scope is a flat namespace over that pool: a route is keyed by the scope and the message type, and scopes have no parent or child relationship. A bus names each scope and gives it an ID that's never reused.

ScopePurpose
applicationWindow events, the window factory, and the audio generator factory.
worldEntities and the systems that follow them.
StandaloneA scope with its own private bus and no ticks, for servers and tests.

Channels and listeners

A channel publishes messages of one type; the scope's channel for a type registers its route on first use. A listener reads them in order.

RuleBehavior
Fan-outEvery listener sees every message published after it joined.
ReplayOn a ticking bus, a new listener starts at the current tick's first message, so it also sees messages sent earlier in the same tick. On a tickless bus, it sees only later messages.
OrderFirst in, first out within a route. Routes aren't ordered against each other.
VisibilityA message is readable once its publisher commits it; a reader never skips a slot that another thread is still writing.
Many at onceA publisher can reserve a run of slots; other publishers may interleave between runs but not within one.
FilteredA filtered listener skips messages that fail its predicate.
UnsubscribeDropping a listener releases what it held. A system that stops reading must drop its listener, or its storage is never returned.
BlockingNothing is dropped or overwritten. When the pool is full, a publisher waits for storage, and after one second logs the route and the slowest listener.

Factories and handles

A factory creates entities of one type and publishes a creation message with a stable handle.

RuleBehavior
HandleA 32-bit ID, never reused within a process.
CreateAllocates a handle and publishes the value under it. Creating with several representations publishes each under the same handle.
DerivePublishes a value under an existing handle: another representation, or a replacement that systems treat as an upsert.
Creation messageCarries the handle and the value.
Deletion messageCarries the handle and ends its lifecycle. After it, create a new value instead of deriving from the deleted handle.
Entity handleSeparate from a factory handle: a shared, reference-counted object compared by identity, used for long-lived services.

Retention

RuleValue
Storage64 MiB by default, set by messages.capacity, in chunks of 64 KiB.
Message sizeA message must fit one chunk with its stamp.
RoutesAt most 65,535 per bus.
TickEach tick begins by sweeping messages every listener has read and returning chunks nobody reads.
ObserverA passive observer records publication ranges and a catalog of every factory-created handle with its types, for the inspector. It holds at most 2,048 distinct types.

The world scope

At startup the runtime opens these routes on the world:

RouteOpened by
Action events and action declarationsThe input sink
Camera creationsThe renderer
Transformation updatesThe renderer's listener, and the inspector's watch
Deletions and action triggersThe inspector, for posting

A system subscribes by taking its listeners when it's constructed, so it sees only messages from then on plus the current tick's. Create a system before the entities it follows. Physics takes the transform route, the body, constraint, and ray query factories, and the deletion route; the scene graph takes the scene factories and deletions; animation takes the animator factory, the request and look target routes, and deletions, and posts to the pose and root motion routes; rendering managers and passes take transforms, poses, and deletions. A headless build keeps every route except poses, so servers run the same gameplay code with nothing listening.

Transforms

A transform is a world location, scale, and orientation.

RuleValue
FieldsPosition, scale, orientation. The identity is the default.
Serialized formposition and scale as three numbers, orientation as four in x, y, z, w order. Unknown fields, non-finite components, and invalid quaternions are rejected.
MatrixTranslation times rotation times scale: scale applies first.
InterpolationPosition and scale interpolate linearly, orientation along the shorter arc.
UpdateA transformation update is a creation message carrying a transform under the entity's handle, on the world's transform route. Creation and replacement travel on that one route.
HierarchyNone. A transform is always a world transform.
PosesA pose update carries an entity's global affine transforms, one per skeleton node, on the world's pose route, in headed builds only.

Names

A name is a non-empty string attached to an entity when it's created. The inspector filters entities by exact name. Names aren't unique.

Scenes

A scene groups entities for deletion only. A scene node attaches an entity under a scene or another member for the entity's lifetime, and membership never affects transforms. The scene graph keeps the tree.

Deletion

StepBehavior
DeletePublishes a deletion message for the handle, once, and forgets the handle in the observer.
CascadeOnce per step, before systems retire deleted entities, the scene graph links new scene nodes and, for every posted deletion, publishes a deletion for each nested member, children before parents. The root isn't published again; an unknown root publishes nothing.
PhysicsFlushing deletions removes the bodies and constraints of every deletion since the last flush.
RenderingManagers drop their mirrored state.

Rust API

On this page