Callbacks, enums & result codes

lattice_callbacks

All callbacks fire synchronously inside lattice_runner_tick() on the caller's thread. No exception may propagate out of a callback into the core. Install the table with lattice_runner_set_callbacks before start. Any function pointer left NULL simply isn't called.

typedef struct {
    void* user_data;
    void (*on_connected)    (void* user_data);
    void (*on_disconnected) (void* user_data, int reason);
    void (*on_spawned)      (void* user_data, lattice_netid id, lattice_type_id type, uint64_t owner);
    void (*on_despawned)    (void* user_data, lattice_netid id);
    void (*on_state_updated)(void* user_data, lattice_netid id);
    void (*on_rpc)          (void* user_data, lattice_netid id, uint16_t rpc_id,
                             const uint8_t* payload, uint32_t len);
    void (*on_event)        (void* user_data, uint16_t event_id, lattice_netid netid,
                             uint64_t sender, const uint8_t* payload, uint32_t len);
    void (*on_authority_changed)(void* user_data, lattice_netid id, uint64_t new_owner,
                                 uint32_t authority_tick);
    void (*on_log)          (void* user_data, lattice_log_level level, const char* msg);
    void (*on_violation)    (void* user_data, uint64_t conn, lattice_ac_violation violation,
                             uint32_t severity, int64_t detail);
    void (*on_http_result)  (void* user_data, uint64_t handle, int ok, int status,
                             const uint8_t* body, uint32_t body_len);
    void (*on_store_result) (void* user_data, uint64_t handle, int op, int ok, int found,
                             int from_cache, const uint8_t* value, uint32_t value_len);
} lattice_callbacks;

Callback	Fires when	Documented on
on_connected	a session is established	Runner
on_disconnected	the session drops (reason is a code)	Runner
on_spawned	an object appears (id, type, owner)	Types & objects
on_despawned	an object is removed	Types & objects
on_state_updated	an object's replicated state converged	Types & objects
on_rpc	an RPC arrives	RPC
on_event new	a custom event arrives	Events
on_authority_changed new	a shared object's authority moves	Authority
on_log	the core emits a log line	below
on_violation new	anti-cheat rejects a submission	Anti-cheat
on_http_result new	a mediated fetch completes	Jobs & fetch
on_store_result new	a store op completes	Store

---

Enums

lattice_game_mode

typedef enum {
    LATTICE_MODE_SERVER      = 0, /* dedicated server: authority, typically headless    */
    LATTICE_MODE_HOST        = 1, /* server that is also a local participant            */
    LATTICE_MODE_CLIENT      = 2,
    LATTICE_MODE_SHARED_HOST = 3  /* shared/distributed authority                        */
} lattice_game_mode;

lattice_connection_state

typedef enum {
    LATTICE_CONN_DISCONNECTED  = 0,
    LATTICE_CONN_CONNECTING,
    LATTICE_CONN_CONNECTED,
    LATTICE_CONN_DISCONNECTING
} lattice_connection_state;

lattice_field_kind

typedef enum {
    LATTICE_FIELD_BOOL = 0,
    LATTICE_FIELD_INT32,
    LATTICE_FIELD_INT64,
    LATTICE_FIELD_FLOAT,
    LATTICE_FIELD_DOUBLE,
    LATTICE_FIELD_RANGED_INT,
    LATTICE_FIELD_COMPRESSED_FLOAT,
    LATTICE_FIELD_VECTOR2,
    LATTICE_FIELD_VECTOR3,
    LATTICE_FIELD_VECTOR4,
    LATTICE_FIELD_QUATERNION,
    LATTICE_FIELD_STRING,
    LATTICE_FIELD_BYTES,
    LATTICE_FIELD_STRUCT
} lattice_field_kind;

lattice_log_level

typedef enum {
    LATTICE_LOG_TRACE = 0,
    LATTICE_LOG_DEBUG,
    LATTICE_LOG_INFO,
    LATTICE_LOG_WARN,
    LATTICE_LOG_ERROR
} lattice_log_level;

static void on_log(void* u, lattice_log_level lvl, const char* msg) {
    if (lvl >= LATTICE_LOG_WARN) fprintf(stderr, "[lattice] %s\n", msg);
}

The routing enums lattice_rpc_target and lattice_event_target, the lattice_ac_violation categories, and the lattice_http_* / lattice_store_* enums are documented on their own pages.

---

lattice_result

typedef enum {
    LATTICE_OK = 0,
    LATTICE_ERR_INVALID_ARG,
    LATTICE_ERR_NOT_AUTHORITY,
    LATTICE_ERR_NO_SESSION,
    LATTICE_ERR_UNKNOWN_TYPE,
    LATTICE_ERR_UNKNOWN_OBJECT,
    LATTICE_ERR_SCHEMA_MISMATCH,
    LATTICE_ERR_BUFFER_TOO_SMALL,
    LATTICE_ERR_NOT_CONNECTED,
    LATTICE_ERR_INTERNAL
} lattice_result;

Code	Meaning
LATTICE_OK	Success.
LATTICE_ERR_INVALID_ARG	A NULL handle or out-of-range argument.
LATTICE_ERR_NOT_AUTHORITY	An authority-only op (e.g. spawn) called on a client.
LATTICE_ERR_NO_SESSION	No active session for the operation.
LATTICE_ERR_UNKNOWN_TYPE	The lattice_type_id is not registered.
LATTICE_ERR_UNKNOWN_OBJECT	The lattice_netid is not known.
LATTICE_ERR_SCHEMA_MISMATCH	A type's content hash differs across peers.
LATTICE_ERR_BUFFER_TOO_SMALL	An output buffer was too small.
LATTICE_ERR_NOT_CONNECTED	A client op issued with no session.
LATTICE_ERR_INTERNAL	An internal error.

Render any code with lattice_result_str(code) (Serialization → Misc helper).

POD value types

typedef struct { float x, y; }       lattice_vec2;
typedef struct { float x, y, z; }    lattice_vec3;
typedef struct { float x, y, z, w; } lattice_vec4;
typedef struct { float x, y, z, w; } lattice_quat;
typedef uint64_t lattice_netid;   /* NetworkObject id; 0 == invalid */
typedef uint32_t lattice_type_id; /* registered type id; 0 == invalid */