Skip to content

Authority & ownership new

Lattice supports two first-class authority models that coexist per-object (design 02 §17.2–§17.3):

  • Server / host-authoritative (the default) — the authority owns every object's state and clients converge to snapshots. Nothing in this section affects these objects.
  • Shared / distributed authority — a shared object's state authority can be held by a specific client, which simulates the object and broadcasts its [Networked] state while every other peer converges to it. Run a LATTICE_MODE_SHARED_HOST runner to act as the arbiter.

Authority is an ownership token (owner peer id, authority_tick). Conflicts resolve by last-writer-wins with a tick tiebreak (higher tick wins; equal ticks ⇒ lower owner id wins), which is deterministic and order-independent — eventual consistency. Transfer is mediated by the host so all peers agree on the new owner.

sequenceDiagram
  participant C1 as Client 1
  participant H as SHARED_HOST (arbiter)
  participant C2 as Client 2
  C1->>H: lattice_request_authority(obj)
  Note over H: mint token (tick > any in flight)
  H-->>C1: grant broadcast
  H-->>C2: grant broadcast
  Note over C1,C2: on_authority_changed fires on EVERY peer
  C1->>H: writes now win (C1 holds the token)

lattice_request_authority

LATTICE_API lattice_result lattice_request_authority(lattice_runner* r, lattice_netid id);

Request state authority over a shared object. Role: any peer in a shared-authority session. Sent reliably to the host arbiter, which mints a new token (tick strictly higher than anything in flight) and broadcasts the grant; once observed, on_authority_changed fires on every peer and the requester's writes win. Calling it on the SHARED_HOST itself grants locally + broadcasts.

Returns: LATTICE_OK if accepted/sent, LATTICE_ERR_UNKNOWN_OBJECT if id is unknown, or LATTICE_ERR_NOT_CONNECTED for a client with no session.

lattice_object_owner

LATTICE_API uint64_t lattice_object_owner(lattice_runner* r, lattice_netid id);

The peer id currently holding state authority over id. For a server-authoritative object this is its owner field; for a shared object it is the live token owner. Role: both. Returns: 0 if the object is unknown.

lattice_object_authority_tick

LATTICE_API uint32_t lattice_object_authority_tick(lattice_runner* r, lattice_netid id);

The current authority_tick (token claim counter) of id, for introspection/diagnostics. Role: both. Returns: 0 if the object is unknown or has never been written/transferred.

Reacting to transfers — on_authority_changed

void (*on_authority_changed)(void* user_data, lattice_netid id, uint64_t new_owner,
                             uint32_t authority_tick);

Fires on every peer (the granting host, the new owner, and every other peer) the tick it adopts the new ownership token, so game code can start/stop simulating the object locally. new_owner is the peer id that now holds authority; authority_tick is the token's claim counter at the grant. For a server/host-authoritative object this never fires (its authority never moves).

static void on_authority_changed(void* u, lattice_netid id, uint64_t new_owner, uint32_t tick) {
    int i_own_it_now = (new_owner == my_peer_id);
    /* enable local simulation of `id` iff i_own_it_now */
}