Skip to content

Presentation

The decision: does anything observe the world on a different cadence, thread, or process than the simulation tick? If yes, publish versioned DeltaFrames; if no, omit the render bridge — it is optional, and nothing else depends on it.

Branches

Branch Pick when
Headless servers, batch experiments, tests: no observer exists, so skip DeltaCollector entirely
DeltaFrame consumer any renderer, UI, or network mirror: the consumer owns shadow state, applies immutable versioned frames, and resynchronizes on gaps

Consumers never rescan the world: frame records carry either individual changed tiles or box-granular dirty bounds, and the consumer re-reads the named tiles — or repaints the recorded box — from the authoritative world (or receives values over its own channel). Frame versions make missed frames detectable and recovery explicit rather than silent.

What it looks like

tess::collect_tile_deltas(deltas, world, kTerrainDirty);
const auto frame = deltas.publish();

The frame borrows the collector's storage; it does not own it. Its spans stay valid until the next publish() or reserve() on that collector — apply the frame, or copy what you need out of it, before publishing again. Its header is a value and outlives all of that, which is why version and gap checks are safe to keep.

A DeltaCollector is also not copyable, and a moved-from one behaves as if cleared: its next frame is truncated so your consumer resyncs rather than silently accepting an empty one. Reuse it by assigning a fresh collector, or by clear() and a baseline.

That matters most for the branch this page recommends. "Different cadence, thread, or process" describes the consumer, not the frame: a DeltaCollector is externally synchronized like every other tess scratch, so what crosses a thread or socket is applied shadow state or a copy of the records — never the DeltaFrame itself, whose spans point into memory the simulation thread is about to refill. Holding a frame across a publish reads records that are being overwritten, and because that storage stays live and owned throughout, no sanitizer will flag it.

Learn and specify

  • Teach: getting-started §8, rung 8; examples/render_delta_consumer.cc rebuilds a shadow grid from frames alone, and examples/colony_2d.cc shows the bridge inside a full schedule loop.
  • Specify: simulation note — collection, publication, versioning, resync.