Core API functions of the Patika library for managing the context and simulation loop.

API Reference

Core API functions of the Patika library for managing the context and simulation loop.

PatikaAPI Public API Core API functions of the Patika library for managing the context and simulation loop.

Functions

patika_createfn

PatikaHandle patika_create(const PatikaConfig* config)

Create a Patika simulation context.

PatikaConfig with fixed capacities and queue sizes. A valid PatikaHandle on success, or NULL on allocation failure. Yes. Typically called during initialization before other threads start. The returned handle owns double-buffered snapshots and all internal pools.

Name	Type	Description
`config`	`const PatikaConfig *`	Non-null pointer to @ref PatikaConfig with fixed capacities and queue sizes.

Returns: A valid

patika_destroyfn

void patika_destroy(PatikaHandle handle)

Destroy a Patika simulation context and free all resources.

No. Ensure no other thread is calling patika_tick or producers after this call.

Name	Type	Description
`handle`	`PatikaHandle`	Context to destroy; ignored if NULL. @threadsafe No. Ensure no other thread is calling @ref patika_tick or producers after this call.

patika_load_mapfn

PatikaError patika_load_map(PatikaHandle handle, const uint8_t* map_states, uint32_t width, uint32_t height)

Load map cell states into the internal grid.

map_states Pointer to width*height bytes representing cell states. width Map width in cells; must equal PatikaConfig::grid_width . height Map height in cells; must equal PatikaConfig::grid_height . PATIKA_OK on success, PATIKA_ERR_NULL_HANDLE if handle is NULL. The function assumes the buffer covers the entire grid. Supplying mismatched dimensions leads to undefined behavior. Call from the simulation thread or when paused.

Name	Type	Description
`handle`	`PatikaHandle`	Simulation handle.
`map_states`	`const uint8_t *`	Pointer to width*height bytes representing cell states.
`width`	`uint32_t`	Map width in cells; must equal @ref `PatikaConfig::grid_width` .
`height`	`uint32_t`	Map height in cells; must equal @ref `PatikaConfig::grid_height` .

Returns: @ref PATIKA_OK on success,

patika_submit_commandfn

PatikaError patika_submit_command(PatikaHandle handle, const PatikaCommand* cmd)

Submit a single command to the MPSC command queue.

cmd Command payload; the memory is copied into the queue. PATIKA_OK if enqueued, PATIKA_ERR_QUEUE_FULL if the queue is full, or PATIKA_ERR_NULL_HANDLE if handle is NULL. Yes. Multiple producers may call concurrently.

Name	Type	Description
`handle`	`PatikaHandle`	Simulation handle.
`cmd`	`const PatikaCommand *`	Command payload; the memory is copied into the queue.

Returns: @ref PATIKA_OK if enqueued,

patika_submit_commandsfn

PatikaError patika_submit_commands(PatikaHandle handle, const PatikaCommand* cmds, uint32_t count)

Submit multiple commands to the MPSC command queue.

cmds Array of PatikaCommand . count Number of elements in cmds . PATIKA_OK if all commands were enqueued, otherwise PATIKA_ERR_QUEUE_FULL on the first failed enqueue, or PATIKA_ERR_NULL_HANDLE if handle is NULL. Yes. Multiple producers may call concurrently.

Name	Type	Description
`handle`	`PatikaHandle`	Simulation handle.
`cmds`	`const PatikaCommand *`	Array of @ref PatikaCommand .
`count`	`uint32_t`	Number of elements in @p cmds .

Returns: @ref PATIKA_OK if all commands were enqueued, otherwise

patika_tickfn

void patika_tick(PatikaHandle handle)

Advance the simulation by one tick.

No. Exactly one consumer thread must call this function. Consumes queued commands, computes next steps for active agents, updates the snapshot buffer, and increments statistics.

Name	Type	Description
`handle`	`PatikaHandle`	Simulation handle. @threadsafe No. Exactly one consumer thread must call this function. @details Consumes queued commands, computes next steps for active agents, updates the snapshot buffer, and increments statistics.

patika_poll_eventsfn

uint32_t patika_poll_events(PatikaHandle handle, PatikaEvent* out_events, uint32_t max_events)

Drain events from the SPSC event queue.

out_events Output array to write into. max_events Capacity of out_events . Number of events written to out_events . Yes, but only one consumer thread may call this function.

Name	Type	Description
`handle`	`PatikaHandle`	Simulation handle.
`out_events`	`PatikaEvent *`	Output array to write into.
`max_events`	`uint32_t`	Capacity of @p out_events .

Returns: Number of events written to

patika_get_snapshotfn

const PatikaSnapshot* patika_get_snapshot(PatikaHandle handle)

Get the latest immutable snapshot.

Pointer to the current PatikaSnapshot , or NULL if handle is NULL. Yes. The returned pointer stays valid until the next patika_tick flips buffers. Copy data if you need it beyond the next tick.

Name	Type	Description
`handle`	`PatikaHandle`	Simulation handle.

Returns: Pointer to the current

patika_get_statsfn

PatikaStats patika_get_stats(PatikaHandle handle)

Retrieve cumulative statistics.

A by-value PatikaStats copy. If handle is NULL, returns zeroed stats. Yes. Statistics are updated during patika_tick .

Name	Type	Description
`handle`	`PatikaHandle`	Simulation handle.

Returns: A by-value

patika_add_agent_syncfn

PatikaError patika_add_agent_sync(PatikaHandle handle, int32_t start_q, int32_t start_r, uint8_t faction, uint8_t side, BarrackID parent_barrack, AgentID* out_id)

Convenience helper to enqueue an

CMD_ADD_AGENT command. handle Simulation handle. start_q Start cell q. start_r Start cell r. faction Faction identifier. side Team/side identifier. parent_barrack Owning barrack or invalid ID. out_id Optional pointer that will be written with the new AgentID when the command is processed during patika_tick . The pointer must remain valid until after the next tick. PATIKA_OK if the command was enqueued, error code otherwise. Yes. Multiple producers may call concurrently. This is not a synchronous allocation; the agent becomes active when the simulation thread processes the queue.

Name	Type	Description
`handle`	`PatikaHandle`	Simulation handle.
`start_q`	`int32_t`	Start cell q.
`start_r`	`int32_t`	Start cell r.
`faction`	`uint8_t`	Faction identifier.
`side`	`uint8_t`	Team/side identifier.
`parent_barrack`	`BarrackID`	Owning barrack or invalid ID.
`out_id`	`AgentID *`	Optional pointer that will be written with the new AgentID when the command is processed during @ref patika_tick . The pointer must remain valid until after the next tick.

Returns: @ref PATIKA_OK if the command was enqueued, error code otherwise.