DataStoreBlobAdd

DataStoreResult DataStoreBlobAdd(HDataStoreContext store, HDataStoreBlob blob, DataStoreId group, HDataStoreBlobInstance* out_instance)

Retains the resource and copies fixed row bytes into shared mutable tables. Registrations of the same loaded resource share metadata, defaults and capacity. Strings and containers retain blob offsets. The caller keeps the immutable buffer alive until all references and registrations are released. Requires a store without active query reservations.

PARAMETERS

RETURNS

DataStoreBlobDestroy

void DataStoreBlobDestroy(HDataStoreBlob blob)

Resource pools retain a reference while any registrations remain. The last release frees the blob handle, never the caller's buffer. Does not remove any instance's rows. The caller may free the buffer after releasing this reference and removing all registrations.

PARAMETERS

DataStoreBlobLoad

DataStoreResult DataStoreBlobLoad(const void* buffer, uint32_t buffer_size, HDataStoreBlob* out_blob)

Validates all tables and borrows the supplied buffer without copying or modifying it. The input must be eight-byte aligned. Member offsets and row/struct sizes are validated for C-compatible alignment. The caller keeps the buffer unchanged and alive until the blob reference and all its registrations have been released. Loading does not register rows in a store.

PARAMETERS

RETURNS

DataStoreBlobRemove

DataStoreResult DataStoreBlobRemove(HDataStoreBlobInstance instance)

Removes its remaining rows, invalidates their IDs, frees its replacement payloads, and returns the registration slot for reuse. Shared capacity remains while other registrations use that resource; the last removal frees the pool and its blob reference. DataStoreGroupRemove also releases registrations owned by that group. Their handles must not be used afterward. The store releases all registrations when destroyed.

PARAMETERS

RETURNS

DataStoreBlobReset

DataStoreResult DataStoreBlobReset(HDataStoreBlobInstance instance)

Copies loaded values into this registration's remaining mutable rows and frees its replacement payload blocks. Does not restore removed rows or invalidate iterators. Borrowed replacement payloads expire. Other registrations are unaffected, even if they share a blob, type or group ID. The engine retains this handle when registering a game object's component tables; no datastore-wide group search is needed. Independently added rows are not included.

PARAMETERS

RETURNS

DataStoreCreate

HDataStoreContext DataStoreCreate(const DataStoreCreateParams* params)

The caller owns the store and releases it with DataStoreDestroy.

PARAMETERS

RETURNS

DataStoreDestroy

DataStoreResult DataStoreDestroy(HDataStoreContext store)

Frees the store, tables/rows and callback/event registrations. Finish callbacks and all access, end any schedule, then destroy queries. Borrowed blobs and callback contexts remain caller-owned; destruction does not invoke callbacks.

PARAMETERS

RETURNS

DataStoreEventAdd

DataStoreResult DataStoreEventAdd(HDataStoreContext store, const DataStoreEventDesc* desc)

Copies the descriptor and hashes between schedules. Events have no query or callback; the caller signals them explicitly with DataStoreSchedulerEvent.

PARAMETERS

RETURNS

DataStoreEventRemove

DataStoreResult DataStoreEventRemove(HDataStoreContext store, dmhash_t name)

Removes the named event between schedules. Dependent registrations retain their hashes.

PARAMETERS

RETURNS

DataStoreField

DataStoreQueryItem DataStoreField(const char* name, DataStoreValueType type, uint32_t access)

Hashes the name immediately; the returned descriptor does not retain the string.

PARAMETERS

RETURNS

DataStoreFieldGetBoolean

DataStoreResult DataStoreFieldGetBoolean(HDataStoreContext store, DataStoreId id, uint64_t field, uint8_t* out_value)

Uses the ID-read synchronization requirements of DataStoreFieldGetNumber.

PARAMETERS

RETURNS

DataStoreFieldGetBooleanBatch

DataStoreResult DataStoreFieldGetBooleanBatch(HDataStoreContext store, uint32_t count, const DataStoreId* ids, uint64_t field, uint8_t* out_values)

Reads IDs in input order without allocation. Stops at the first error; outputs may be partially written on failure; use them only after OK. Synchronize as for DataStoreFieldGetBoolean. Input/output arrays must not overlap and must contain count entries. Zero count accesses nothing.

PARAMETERS

RETURNS

DataStoreFieldGetFloat

DataStoreResult DataStoreFieldGetFloat(HDataStoreContext store, DataStoreId id, uint64_t field, float* out_value)

Uses the ID-read synchronization requirements of DataStoreFieldGetNumber.

PARAMETERS

RETURNS

DataStoreFieldGetFloatBatch

DataStoreResult DataStoreFieldGetFloatBatch(HDataStoreContext store, uint32_t count, const DataStoreId* ids, uint64_t field, float* out_values)

Reads IDs in input order without allocation. Stops at the first error; outputs may be partially written on failure; use them only after OK. Synchronize as for DataStoreFieldGetFloat. Input/output arrays must not overlap and must contain count entries. Zero count accesses nothing.

PARAMETERS

RETURNS

DataStoreFieldGetMatrix4

DataStoreResult DataStoreFieldGetMatrix4(HDataStoreContext store, DataStoreId id, uint64_t field, DataStoreMatrix4* out_value)

Uses the ID-read synchronization requirements of DataStoreFieldGetNumber.

PARAMETERS

RETURNS

DataStoreFieldGetMatrix4Batch

DataStoreResult DataStoreFieldGetMatrix4Batch(HDataStoreContext store, uint32_t count, const DataStoreId* ids, uint64_t field, DataStoreMatrix4* out_values)

Reads IDs in input order without allocation. Stops at the first error; outputs may be partially written on failure; use them only after OK. Synchronize as for DataStoreFieldGetMatrix4. Input/output arrays must not overlap and must contain count entries. Zero count accesses nothing.

PARAMETERS

RETURNS

DataStoreFieldGetNumber

DataStoreResult DataStoreFieldGetNumber(HDataStoreContext store, DataStoreId id, uint64_t field, double* out_value)

ID-based reads acquire no lock or query reservation. Prevent structural changes and conflicting writes with a matching query reservation or caller synchronization. Keep that protection while using borrowed strings or views.

PARAMETERS

RETURNS

DataStoreFieldGetNumberBatch

DataStoreResult DataStoreFieldGetNumberBatch(HDataStoreContext store, uint32_t count, const DataStoreId* ids, uint64_t field, double* out_values)

Reads IDs in input order without allocation. Stops at the first error; outputs may be partially written on failure; use them only after OK. Synchronize as for DataStoreFieldGetNumber. Input/output arrays must not overlap and must contain count entries. Zero count accesses nothing.

PARAMETERS

RETURNS

DataStoreFieldGetString

DataStoreResult DataStoreFieldGetString(HDataStoreContext store, DataStoreId id, uint64_t field, const char** out_value)

Uses the ID-read synchronization requirements of DataStoreFieldGetNumber.

PARAMETERS

RETURNS

DataStoreFieldGetStringBatch

DataStoreResult DataStoreFieldGetStringBatch(HDataStoreContext store, uint32_t count, const DataStoreId* ids, uint64_t field, const char** out_values)

Reads IDs in input order without allocation. Stops at the first error; outputs may be partially written on failure; use them only after OK. Synchronize as for DataStoreFieldGetString. Input/output arrays must not overlap and must contain count entries. Zero count accesses nothing. Returned strings are borrowed; finish using them before a store write or reset.

PARAMETERS

RETURNS

DataStoreFieldGetUInt32

DataStoreResult DataStoreFieldGetUInt32(HDataStoreContext store, DataStoreId id, uint64_t field, uint32_t* out_value)

Uses the ID-read synchronization requirements of DataStoreFieldGetNumber.

PARAMETERS

RETURNS

DataStoreFieldGetUInt32Batch

DataStoreResult DataStoreFieldGetUInt32Batch(HDataStoreContext store, uint32_t count, const DataStoreId* ids, uint64_t field, uint32_t* out_values)

Reads IDs in input order without allocation. Stops at the first error; outputs may be partially written on failure; use them only after OK. Synchronize as for DataStoreFieldGetUInt32. Input/output arrays must not overlap and must contain count entries. Zero count accesses nothing.

PARAMETERS

RETURNS

DataStoreFieldGetVector3

DataStoreResult DataStoreFieldGetVector3(HDataStoreContext store, DataStoreId id, uint64_t field, DataStoreVector3* out_value)

Uses the ID-read synchronization requirements of DataStoreFieldGetNumber.

PARAMETERS

RETURNS

DataStoreFieldGetVector3Batch

DataStoreResult DataStoreFieldGetVector3Batch(HDataStoreContext store, uint32_t count, const DataStoreId* ids, uint64_t field, DataStoreVector3* out_values)

Reads IDs in input order without allocation. Stops at the first error; outputs may be partially written on failure; use them only after OK. Synchronize as for DataStoreFieldGetVector3. Input/output arrays must not overlap and must contain count entries. Zero count accesses nothing.

PARAMETERS

RETURNS

DataStoreFieldGetVector4

DataStoreResult DataStoreFieldGetVector4(HDataStoreContext store, DataStoreId id, uint64_t field, DataStoreVector4* out_value)

Uses the ID-read synchronization requirements of DataStoreFieldGetNumber.

PARAMETERS

RETURNS

DataStoreFieldGetVector4Batch

DataStoreResult DataStoreFieldGetVector4Batch(HDataStoreContext store, uint32_t count, const DataStoreId* ids, uint64_t field, DataStoreVector4* out_values)

Reads IDs in input order without allocation. Stops at the first error; outputs may be partially written on failure; use them only after OK. Synchronize as for DataStoreFieldGetVector4. Input/output arrays must not overlap and must contain count entries. Zero count accesses nothing.

PARAMETERS

RETURNS

DataStoreFieldGetView

DataStoreResult DataStoreFieldGetView(HDataStoreContext store, DataStoreId id, uint64_t field, DataStoreValueView* out_view)

Uses the ID-read synchronization requirements of DataStoreFieldGetNumber.

PARAMETERS

RETURNS

DataStoreFieldSetBoolean

DataStoreResult DataStoreFieldSetBoolean(HDataStoreContext store, DataStoreId id, uint64_t field, uint8_t value)

Write a Boolean field

PARAMETERS

RETURNS

DataStoreFieldSetFloat

DataStoreResult DataStoreFieldSetFloat(HDataStoreContext store, DataStoreId id, uint64_t field, float value)

Write a Float field

PARAMETERS

RETURNS

DataStoreFieldSetMatrix4

DataStoreResult DataStoreFieldSetMatrix4(HDataStoreContext store, DataStoreId id, uint64_t field, const DataStoreMatrix4* value)

Write a Matrix4 field

PARAMETERS

RETURNS

DataStoreFieldSetNumber

DataStoreResult DataStoreFieldSetNumber(HDataStoreContext store, DataStoreId id, uint64_t field, double value)

Write a Number field

PARAMETERS

RETURNS

DataStoreFieldSetString

DataStoreResult DataStoreFieldSetString(HDataStoreContext store, DataStoreId id, uint64_t field, const char* value)

Copies the NUL-terminated string into owned storage; self-assignment is supported.

PARAMETERS

RETURNS

DataStoreFieldSetUInt32

DataStoreResult DataStoreFieldSetUInt32(HDataStoreContext store, DataStoreId id, uint64_t field, uint32_t value)

Write a UInt32 field

PARAMETERS

RETURNS

DataStoreFieldSetVector3

DataStoreResult DataStoreFieldSetVector3(HDataStoreContext store, DataStoreId id, uint64_t field, const DataStoreVector3* value)

Write a Vector3 field

PARAMETERS

RETURNS

DataStoreFieldSetVector4

DataStoreResult DataStoreFieldSetVector4(HDataStoreContext store, DataStoreId id, uint64_t field, const DataStoreVector4* value)

Write a Vector4 field

PARAMETERS

RETURNS

DataStoreFunctionAdd

DataStoreResult DataStoreFunctionAdd(HDataStoreContext store, const DataStoreSystemDesc* desc)

Copies the descriptor and hashes; registration does not invoke the callback.

PARAMETERS

RETURNS

DataStoreFunctionRemove

DataStoreResult DataStoreFunctionRemove(HDataStoreContext store, dmhash_t name)

Removes the named registration between schedules. The query and user context remain caller-owned. Dependent registrations retain their hashes.

PARAMETERS

RETURNS

DataStoreGroupRemove

DataStoreResult DataStoreGroupRemove(HDataStoreContext store, DataStoreId group)

Removes the group's rows across all tables, owned payloads and blob registrations, including empty registrations. Invalidates their row IDs and blob-instance handles and releases group bookkeeping. Other groups and their row IDs remain valid. Independent table registrations remain available for reuse. Does not scan unrelated rows. Requires a store without active query reservations; queue requests in caller-owned storage and apply them after jobs finish. Zero is not a removable group. Bookkeeping is created on first use and kept until group removal, including when rows are removed individually. Reusing the caller ID later recreates the group; existing query filters then match its new rows.

PARAMETERS

RETURNS

DataStoreIterGetType

uint64_t DataStoreIterGetType(const DataStoreIterator* iterator)

Get the current table type

PARAMETERS

RETURNS

DataStoreIterNext

bool DataStoreIterNext(DataStoreIterator* iterator)

Selects a nonempty contiguous batch. Invalidates child iterators, including when exhausted.

PARAMETERS

RETURNS

DataStoreIterRows

DataStoreRowIterator DataStoreIterRows(const DataStoreIterator* iterator)

Borrows the current batch; empty when no batch is selected.

PARAMETERS

RETURNS

DataStoreQueryCreate

DataStoreResult DataStoreQueryCreate(HDataStoreContext store, const DataStoreQueryDesc* desc, HDataStoreQuery* out_query)

Copies filters and tracks matching tables, including later registrations. Destroy the query before its store.

PARAMETERS

RETURNS

DataStoreQueryDestroy

DataStoreResult DataStoreQueryDestroy(HDataStoreQuery query)

Frees the query. Finish using its iterators first.

PARAMETERS

RETURNS

DataStoreQueryEnd

void DataStoreQueryEnd(HDataStoreQuery query)

Thread-safe release. The caller must join all jobs and finish using iterators and pointers first.

PARAMETERS

DataStoreQueryFindField

DataStoreFieldId DataStoreQueryFindField(HDataStoreQuery query, const DataStoreQueryItem* field)

Binds a requested full-name hash, kind and access to a handle valid until query destruction. The handle is neither a byte offset nor a query descriptor index. No lock or matching rows are required. Fixed-size kinds support typed pointers; DataStoreRowIterGetView also reads containers, strings and nulls. Table and row iteration order is unspecified. Pointer getters require this query's current row and matching typed handle, with its reservation active. No kind, bounds or lifetime checks occur. Writable pointers require DATASTORE_FIELD_MUTABLE during reservations. Borrowed pointers expire on row/batch advance, query end, or another mutating accessor/reset for the row/table. Never write through a read pointer.

PARAMETERS

RETURNS

DataStoreQueryGetRowCount

uint32_t DataStoreQueryGetRowCount(HDataStoreQuery query)

Count reserved rows

PARAMETERS

RETURNS

DataStoreQueryIter

DataStoreIterator DataStoreQueryIter(HDataStoreQuery query)

Traverses all rows in an active query reservation. The scheduler keeps access reserved until every iterator and job finishes, including early exits.

PARAMETERS

RETURNS

DataStoreQueryIterRange

DataStoreIterator DataStoreQueryIterRange(HDataStoreQuery query, uint32_t first, uint32_t count)

Selects [first, first + count) within reserved rows, possibly across tables. Each job owns its cursor; ranges must be in bounds and disjoint when writing. Keep the reservation active until all iterators and borrowed pointers finish.

PARAMETERS

RETURNS

DataStoreQueryTryBegin

DataStoreResult DataStoreQueryTryBegin(HDataStoreQuery query)

Thread-safe, nonblocking reservation that keeps rows and bindings stable. Overlapping fields on the same table allow read/read access; writes conflict. Disjoint group filters permit concurrent writes to the same table. Aliased external views remain conservative. Without fields or whole-row flags, only row identities are read. DATASTORE_ROW_MUTABLE conflicts with any reader or writer of overlapping row values. Field filters still select matching tables. Field writes require DATASTORE_FIELD_MUTABLE, or DATASTORE_ROW_MUTABLE for native row access; string replacement and resets must happen outside reservations. Each query supports one active reservation, shared by its jobs. The caller schedules and synchronizes jobs, then calls DataStoreQueryEnd once, even for an empty query. The scheduler owns this scope for both serial and parallel iteration. Do not bypass reservations with unrelated ID-based access. Matching-table changes invalidate cached compatibility; row changes refresh ranges. First use of a query pair or changed ranges may allocate; later begins reuse storage.

PARAMETERS

RETURNS

DataStoreRowCreate

DataStoreResult DataStoreRowCreate(HDataStoreContext store, uint64_t type, DataStoreId group, uint32_t count, const void* rows, DataStoreId* out_ids)

Copies count complete rows using the registered C layout and row size. Assigns group to every row; groups can share a table. DataStoreGroupRemove removes owned rows. Stores current values only unless m_ResetPolicy is DATASTORE_RESET_RETAIN. Native rows have no component name; DataStoreRowGetComponentId returns zero. Supports fixed-size values, inline structs and DataStoreReference fields. Strings and dynamic containers are copied into table-owned storage, including nested payloads; all input memory can be released after the call. Dynamic struct fields share layout metadata and own separate child rows. Removal releases those rows for reuse; reset releases replacements and restores the original children. Removed rows' default slots and string/list payload chunks are reused. Empty payload blocks are released, keeping at most one small spare per arena. Booleans must be 0 or 1. Inputs, including padding, must be initialized, disjoint from store storage and valid through the call. On error no rows are published and output IDs remain unchanged. Nonempty batches require a store without active query reservations. An empty batch returns OK without accessing the store or arrays.

PARAMETERS

RETURNS

DataStoreRowCreateSoA

DataStoreResult DataStoreRowCreateSoA(HDataStoreContext store, uint64_t type, DataStoreId group, uint32_t count, uint32_t field_count, const DataStoreFieldArray* fields, DataStoreId* out_ids)

Supply every root field exactly once, in any order, with count values per array. Copies into the selected runtime storage and retains native reset rows only when m_ResetPolicy is DATASTORE_RESET_RETAIN. Types and element sizes come from the registered layout. Inline struct fields use arrays of complete structs, not separate arrays for their nested members. Inputs, including struct padding, must be initialized, disjoint from store storage and valid through the call. The table policy controls reset history. Group, locking and reference ownership rules match DataStoreRowCreate. On error no rows are published and output IDs remain unchanged.

PARAMETERS

RETURNS

DataStoreRowGetComponentId

uint64_t DataStoreRowGetComponentId(HDataStoreContext store, DataStoreId id)

Used by game object integration to associate a runtime row with its component. Uses the ID-read synchronization requirements of DataStoreFieldGetNumber.

PARAMETERS

RETURNS

DataStoreRowIterGetBoolean

const uint8_t* DataStoreRowIterGetBoolean(const DataStoreRowIterator* iterator, DataStoreFieldId field)

Uses the handle and pointer lifetime rules of DataStoreQueryFindField.

PARAMETERS

RETURNS

DataStoreRowIterGetBooleanMut

uint8_t* DataStoreRowIterGetBooleanMut(const DataStoreRowIterator* iterator, DataStoreFieldId field)

Uses the handle and pointer lifetime rules of DataStoreQueryFindField. Write only zero or one.

PARAMETERS

RETURNS

DataStoreRowIterGetData

const void* DataStoreRowIterGetData(const DataStoreRowIterator* iterator)

Requires a nonzero row stride. Cast only to the registered C layout, including its member offsets and size. Use DataStoreIterGetType to distinguish layouts in queries matching multiple types. Returns zero unless the query flags include DATASTORE_ROW_MUTABLE. Otherwise reads any field; permissions are cached in the iterator. Reference slots are internal handles, not native pointers; use container accessors for them. The pointer follows DataStoreIterator lifetime rules. No layout checks occur.

PARAMETERS

RETURNS

DataStoreRowIterGetDataMut

void* DataStoreRowIterGetDataMut(const DataStoreRowIterator* iterator)

Uses the layout and lifetime rules of DataStoreRowIterGetData. Returns zero unless the query flags include DATASTORE_ROW_MUTABLE, which reserves reads and writes of the entire row. Never overwrite reference slots or whole rows containing references. Boolean writes must be zero or one. The access flag is cached in the iterator; this getter does not access the query or store.

PARAMETERS

RETURNS

DataStoreRowIterGetFloat

const float* DataStoreRowIterGetFloat(const DataStoreRowIterator* iterator, DataStoreFieldId field)

Uses the handle and pointer lifetime rules of DataStoreQueryFindField.

PARAMETERS

RETURNS

DataStoreRowIterGetFloatMut

float* DataStoreRowIterGetFloatMut(const DataStoreRowIterator* iterator, DataStoreFieldId field)

Uses the handle and pointer lifetime rules of DataStoreQueryFindField.

PARAMETERS

RETURNS

DataStoreRowIterGetGroupId

DataStoreId DataStoreRowIterGetGroupId(const DataStoreRowIterator* iterator)

Get the current row group

PARAMETERS

RETURNS

DataStoreRowIterGetId

DataStoreId DataStoreRowIterGetId(const DataStoreRowIterator* iterator)

Get the current row ID

PARAMETERS

RETURNS

DataStoreRowIterGetMatrix4

const DataStoreMatrix4* DataStoreRowIterGetMatrix4(const DataStoreRowIterator* iterator, DataStoreFieldId field)

Uses the handle and pointer lifetime rules of DataStoreQueryFindField.

PARAMETERS

RETURNS

DataStoreRowIterGetMatrix4Mut

DataStoreMatrix4* DataStoreRowIterGetMatrix4Mut(const DataStoreRowIterator* iterator, DataStoreFieldId field)

Uses the handle and pointer lifetime rules of DataStoreQueryFindField.

PARAMETERS

RETURNS

DataStoreRowIterGetNumber

const double* DataStoreRowIterGetNumber(const DataStoreRowIterator* iterator, DataStoreFieldId field)

Uses the handle and pointer lifetime rules of DataStoreQueryFindField.

PARAMETERS

RETURNS

DataStoreRowIterGetNumberMut

double* DataStoreRowIterGetNumberMut(const DataStoreRowIterator* iterator, DataStoreFieldId field)

Uses the handle and pointer lifetime rules of DataStoreQueryFindField.

PARAMETERS

RETURNS

DataStoreRowIterGetUInt32

const uint32_t* DataStoreRowIterGetUInt32(const DataStoreRowIterator* iterator, DataStoreFieldId field)

Uses the handle and pointer lifetime rules of DataStoreQueryFindField.

PARAMETERS

RETURNS

DataStoreRowIterGetUInt32Mut

uint32_t* DataStoreRowIterGetUInt32Mut(const DataStoreRowIterator* iterator, DataStoreFieldId field)

Uses the handle and pointer lifetime rules of DataStoreQueryFindField.

PARAMETERS

RETURNS

DataStoreRowIterGetVector3

const DataStoreVector3* DataStoreRowIterGetVector3(const DataStoreRowIterator* iterator, DataStoreFieldId field)

Uses the handle and pointer lifetime rules of DataStoreQueryFindField.

PARAMETERS

RETURNS

DataStoreRowIterGetVector3Mut

DataStoreVector3* DataStoreRowIterGetVector3Mut(const DataStoreRowIterator* iterator, DataStoreFieldId field)

Uses the handle and pointer lifetime rules of DataStoreQueryFindField.

PARAMETERS

RETURNS

DataStoreRowIterGetVector4

const DataStoreVector4* DataStoreRowIterGetVector4(const DataStoreRowIterator* iterator, DataStoreFieldId field)

Uses the handle and pointer lifetime rules of DataStoreQueryFindField.

PARAMETERS

RETURNS

DataStoreRowIterGetVector4Mut

DataStoreVector4* DataStoreRowIterGetVector4Mut(const DataStoreRowIterator* iterator, DataStoreFieldId field)

Uses the handle and pointer lifetime rules of DataStoreQueryFindField.

PARAMETERS

RETURNS

DataStoreRowIterGetView

void DataStoreRowIterGetView(const DataStoreRowIterator* iterator, DataStoreFieldId field, DataStoreValueView* out_view)

Uses the same valid-row and matching-handle contract as typed pointer getters. Containers and strings require read-only access. No name lookup or allocation.

PARAMETERS

DataStoreRowIterNext

bool DataStoreRowIterNext(DataStoreRowIterator* iterator)

Invalidates borrowed field pointers; clears the current row when exhausted.

PARAMETERS

RETURNS

DataStoreRowRemove

DataStoreResult DataStoreRowRemove(HDataStoreContext store, DataStoreId id)

Uses swap removal; other live IDs remain valid. The removed ID becomes stale. Requires a store without active query reservations. To remove during traversal, collect DataStoreIds in a caller-owned reusable buffer and apply removals after all query reservations finish. Reclaims the retained default slot and owned dynamic child rows. String/list payload chunks are recycled; empty blocks are freed, retaining one small spare per arena. Borrowed blob payloads remain unchanged.

PARAMETERS

RETURNS

DataStoreRowReset

DataStoreResult DataStoreRowReset(HDataStoreContext store, DataStoreId id)

Restores all fields, including nested values, to their loaded or added defaults. Other rows are unaffected, including other components with the same group or type. Does not allocate, change IDs or query membership, or invalidate iterators. Mutable row storage stays in place. Owned replacement payloads are released for reuse; borrowed views and strings must no longer be used. Returns LOCKED during query reservations. Tables registered with DATASTORE_RESET_NONE do not retain history and cannot reset.

PARAMETERS

RETURNS

DataStoreSchedulerBegin

DataStoreResult DataStoreSchedulerBegin(HDataStoreContext store, HJobContext jobs)

Starts one invocation of all registered functions and events. Resolves dependencies after registration changes and clears function completion and event signals from the previous invocation. Reserves each ready function's query and submits its jobs. Borrowed job context must outlive this invocation. Zero-worker contexts execute work during DataStoreSchedulerUpdate. Pair success with DataStoreSchedulerEnd; no threads are created or destroyed here.

PARAMETERS

RETURNS

DataStoreSchedulerEnd

DataStoreResult DataStoreSchedulerEnd(HDataStoreContext store)

Ends the invocation, discarding unsignaled events and functions waiting on them. Returns BUSY while jobs await completion or ready functions await query access; keep pumping DataStoreSchedulerUpdate before retrying. A failed end retains reservations and dependencies. Registration changes are allowed after success. The next begin starts fresh.

PARAMETERS

RETURNS

DataStoreSchedulerEvent

DataStoreResult DataStoreSchedulerEvent(HDataStoreContext store, dmhash_t name)

Signals an engine milestone, such as the start of an update stage, once its own prerequisites are satisfied. The scheduler immediately submits every ready function, subject to remaining dependencies and query access checks. This call does not wait for jobs. BUSY leaves the event pending: pump DataStoreSchedulerUpdate and retry before entering an engine stage that requires those prerequisites. Signal each event once per invocation; DataStoreSchedulerBegin clears previous signals. Events do not reserve data or protect engine accesses outside registered queries.

PARAMETERS

RETURNS

DataStoreSchedulerSync

DataStoreResult DataStoreSchedulerSync(HDataStoreContext store)

Pumps jobs until running functions and ready functions finish, including their dependents. Functions waiting on unsignaled events remain pending. Keeps the schedule active so later events can use earlier completions without rerunning work. Query reservations are released as functions finish; this does not lock the store. Call on the scheduler's main thread, outside jobs and completion callbacks.

PARAMETERS

RETURNS

DataStoreSchedulerUpdate

DataStoreResult DataStoreSchedulerUpdate(HDataStoreContext store)

Pumps the borrowed job context's completion callbacks on the main thread. In a zero-worker context, also executes at most one queued job. This may service other users of the same job context. Do not call recursively from a job or completion callback. The last job of each function releases query access and submits newly ready functions. Also retries functions blocked by external query reservations. Read/read and disjoint writes may overlap; conflicting accesses wait. Use m_DependsOn when order matters. The same query handle cannot have two active reservations. Unsignaled events do not keep this call BUSY unless a pending function depends on them.

PARAMETERS

RETURNS

DataStoreTableAdd

DataStoreResult DataStoreTableAdd(HDataStoreContext store, const DataStoreTableDesc* desc)

Copies tags and field metadata. Fields have fixed kinds and non-overlapping byte offsets. Duplicate type hashes and full-name field hashes (including inline members) are rejected. Successful registration updates live queries. Requires a store without active query reservations.

PARAMETERS

RETURNS

DataStoreTableAddView

DataStoreResult DataStoreTableAddView(HDataStoreContext store, const DataStoreTableDesc* desc, void* values, uint32_t value_count, uint32_t row_count, const uint32_t* indices, DataStoreId* out_ids)

Creates a runtime table over caller-owned AoS values without copying them. Layouts contain scalar/vector/matrix fields; struct and reference fields are unsupported. Indices select source rows and are copied; NULL selects rows in order. Optional out_ids receives row identities. Keep values alive, aligned and stationary until DataStoreTableRemove or store destruction. The caller synchronizes external access with query reservations. Shared reads are allowed; writable jobs must select distinct source rows, including within one query. Views with overlapping source rows conflict on overlapping writable fields. View rows cannot be created, removed or reset individually, or serialized. Unregistering frees metadata and identities, never the borrowed values.

PARAMETERS

RETURNS

DataStoreTableRemove

DataStoreResult DataStoreTableRemove(HDataStoreContext store, uint64_t type)

Removes an independently registered table and all its rows. Their IDs become stale, even if the type is registered again. Updates live queries. Requires a store without active query reservations.

PARAMETERS

RETURNS

DataStoreTag

DataStoreQueryItem DataStoreTag(const char* name)

Hashes the name immediately; the returned item does not retain the string.

PARAMETERS

RETURNS

DataStoreViewGetBoolean

DataStoreResult DataStoreViewGetBoolean(const DataStoreValueView* view, uint8_t* out_value)

Copies the value without conversion. Errors leave the output unchanged.

PARAMETERS

RETURNS

DataStoreViewGetCount

DataStoreResult DataStoreViewGetCount(const DataStoreValueView* view, uint32_t* out_count)

Count container entries

PARAMETERS

RETURNS

DataStoreViewGetElement

DataStoreResult DataStoreViewGetElement(const DataStoreValueView* view, uint32_t index, DataStoreValueView* out_view)

Read a list element

PARAMETERS

RETURNS

DataStoreViewGetField

DataStoreResult DataStoreViewGetField(const DataStoreValueView* view, uint64_t field, DataStoreValueView* out_view)

Uses a local member hash; repeat for further nesting. No member enumeration.

PARAMETERS

RETURNS

DataStoreViewGetFloat

DataStoreResult DataStoreViewGetFloat(const DataStoreValueView* view, float* out_value)

Copies the value without conversion. Errors leave the output unchanged.

PARAMETERS

RETURNS

DataStoreViewGetMatrix4

DataStoreResult DataStoreViewGetMatrix4(const DataStoreValueView* view, DataStoreMatrix4* out_value)

Copies the value without conversion. Errors leave the output unchanged.

PARAMETERS

RETURNS

DataStoreViewGetNumber

DataStoreResult DataStoreViewGetNumber(const DataStoreValueView* view, double* out_value)

Copies the value without conversion. Errors leave the output unchanged.

PARAMETERS

RETURNS

DataStoreViewGetString

DataStoreResult DataStoreViewGetString(const DataStoreValueView* view, const char** out_value)

Borrows the NUL-terminated string until the view expires. Errors leave the output unchanged.

PARAMETERS

RETURNS

DataStoreViewGetType

DataStoreValueType DataStoreViewGetType(const DataStoreValueView* view)

Read a view's kind

PARAMETERS

RETURNS

DataStoreViewGetUInt32

DataStoreResult DataStoreViewGetUInt32(const DataStoreValueView* view, uint32_t* out_value)

Copies the value without conversion. Errors leave the output unchanged.

PARAMETERS

RETURNS

DataStoreViewGetVector3

DataStoreResult DataStoreViewGetVector3(const DataStoreValueView* view, DataStoreVector3* out_value)

Copies the value without conversion. Errors leave the output unchanged.

PARAMETERS

RETURNS

DataStoreViewGetVector4

DataStoreResult DataStoreViewGetVector4(const DataStoreValueView* view, DataStoreVector4* out_value)

Copies the value without conversion. Errors leave the output unchanged.

PARAMETERS

RETURNS

DataStoreViewIter

DataStoreViewIterator DataStoreViewIter(const DataStoreValueView* view)

Visits list elements in order or immediate struct values in storage order. Struct order is unspecified. Empty containers and non-container views yield no values. No allocation; count is resolved once.

PARAMETERS

RETURNS

DataStoreViewIterNext

bool DataStoreViewIterNext(DataStoreViewIterator* iterator, DataStoreValueView* out_view)

Returned views use the existing typed view getters. Nested containers can have their own iterators. Exhaustion leaves the output unchanged.

PARAMETERS

RETURNS

DataStoreCreateParams

TYPE

Zero selects the default for each size. Pages are allocated lazily and shared by table value chunks. These are allocator sizes, independent of OS pages.

MEMBERS

DataStoreEventDesc

TYPE

An externally signaled milestone in the same dependency graph as query callbacks. Hashes are copied. Dependencies may name functions or events registered later; DataStoreSchedulerBegin rejects missing prerequisites and cycles.

MEMBERS

DataStoreFieldArray

TYPE

One input column for DataStoreRowCreateSoA. The registered layout determines the element type and size; an inline struct uses complete native struct elements. STRING, dynamic STRUCT and LIST columns use DataStoreReference elements.

MEMBERS

DataStoreFieldDesc

TYPE

Offsets follow C alignment. Inline members and their parents require single-segment names for full-name hashing. Registration copies the compiled metadata.

MEMBERS

DataStoreIterator

TYPE

Stack cursor; iterators and fixed-size field access allocate nothing. Keep the query/store alive and its query reservation active. Do not copy active iterators. Parents must stay at the same address; stepping one invalidates its children, including when exhausted. Lifetimes are not checked. Batch and row order are unspecified.

DataStoreListInput

TYPE

With m_Types NULL, m_Type describes a contiguous native array. Numeric elements use their native API types; STRING, STRUCT and LIST elements use DataStoreReference. With m_Types set, m_Values is a const void* array of payload pointers: addresses of native scalar/vector/matrix values, string bytes, DataStoreStructInput or DataStoreListInput. NULL-kind elements need no payload. m_Type is ignored. Both arrays contain m_Count entries. Inputs are borrowed through creation; values are copied, including nested payloads. Input rules match DataStoreStructInput.

MEMBERS

DataStoreMatrix4

TYPE

Matrix4 value

MEMBERS

DataStoreQueryDesc

TYPE

Requires all tags and fields in one table, and matches any listed group. Empty filters impose no restriction. Bind requested fields with DataStoreQueryFindField. Zero-initialize. Items end at the first DATASTORE_QUERY_ITEM_NONE or the array capacity. Filters are copied during creation; group IDs use an explicit count because zero is valid.

MEMBERS

DataStoreQueryItem

TYPE

Construct with DataStoreTag or DataStoreField, or initialize the kind and hash directly. Field names may include inline members, such as "light.color"; dynamic members cannot bind.

MEMBERS

DataStoreReference

TYPE

Use for STRING, dynamic STRUCT and LIST fields in native rows or field arrays, including nested members. Select the union member matching the declared kind. Payloads and descriptors are borrowed through creation and copied into the table. References must be non-NULL. This is an input descriptor, not a stored pointer view; read strings through the typed API. Reference slots occupy eight bytes on all supported hosts and follow the registered C alignment rules.

MEMBERS

DataStoreRowIterator

TYPE

Traverses the current batch. DataStoreIterator lifetime rules apply. Fixed-size writes preserve sibling fields and defaults. Reset outside reservations.

DataStoreStructDesc

TYPE

Reusable metadata, copied by registration. Members must not overlap. Layouts must be acyclic. Inline structs and dynamic containers share a 64-level nesting limit.

MEMBERS

DataStoreStructInput

TYPE

Describes one native struct, with per-input member names and kinds. The table field uses STRUCT without an inline layout. Members may contain DataStoreReference values, including further containers. Inputs must be acyclic, no deeper than 64 container levels including enclosing inline structs; names within each struct must be unique.

MEMBERS

DataStoreSystemDesc

TYPE

Hashes are copied during registration. The query must belong to the supplied store. Keep the query and context alive until unregistration or store teardown. At teardown, finish callbacks, end the schedule and destroy queries before the store. Dependencies name complete updates and may refer to updates registered later. DataStoreSchedulerBegin resolves hashes to indices and rejects cycles. Use dmHashString64 during setup; reverse hashes are available for diagnostics. Prerequisites may name functions or events. Every prerequisite must be registered; the engine registers DATASTORE_EVENT_GAMEOBJECT_PRE_UPDATE and DATASTORE_EVENT_GAMEOBJECT_POST_UPDATE in its own store.

MEMBERS

DataStoreTableDesc

TYPE

Tags and metadata are copied. Tags and total metadata entries, including nested members, are each limited to 65,535. Full-name hashes must be unique across the entire layout, including inline members. Rows share this fixed layout.

MEMBERS

DataStoreValueView

TYPE

Created by the view accessors. Copyable; owns no storage. Finish using views and borrowed strings before a store mutation, row/batch advance or query end. Synchronize ID-based reads externally; query views use the current reservation. The private representation is not a serialized/native row layout.

DataStoreVector3

TYPE

Vector3 value

MEMBERS

DataStoreVector4

TYPE

Vector4 value

MEMBERS

DataStoreViewIterator

TYPE

Borrows its parent view, which must remain unchanged and outlive iteration. Has the same borrowed-data lifetime and synchronization requirements as DataStoreValueView.

DATASTORE_CONTEXT_NAME

Registry name for the engine-owned HDataStoreContext, available from extension app initialization through app finalization. Borrow the store; do not destroy it. Finish jobs and release your queries and tables before finalization ends. Enable creation with engine.datastore = 1; the default is 0 (disabled). Context lookup returns NULL while disabled.

DATASTORE_EVENT_GAMEOBJECT_POST_UPDATE

Registered in the engine's DATASTORE_CONTEXT_NAME store when engine.datastore is enabled. Signaled after dmGameObject::Update, including late updates, and before rendering. The engine waits for ready functions and their dependents, then ends the frame's schedule. Post-update functions can depend on functions from DATASTORE_EVENT_GAMEOBJECT_PRE_UPDATE. This precedes game-object PostUpdate deletion processing and does not refresh world transforms after callback writes. Callbacks run on workers; do not access game objects or Lua there. Standalone stores must register and signal their own events.

DATASTORE_EVENT_GAMEOBJECT_PRE_UPDATE

Registered in the engine's DATASTORE_CONTEXT_NAME store when engine.datastore is enabled. After input dispatch and before game-object updates, the engine starts the frame's schedule and signals this event. It waits for submitted functions and their dependents before updating components. The same schedule remains active through DATASTORE_EVENT_GAMEOBJECT_POST_UPDATE. Callbacks run on a dedicated engine job context; do not access game objects or Lua from workers. This does not refresh world transforms. Standalone stores must register and signal their own events.

DATASTORE_QUERY_MAX_ITEMS

Maximum items in a query descriptor

DATASTORE_SYSTEM_MAX_DEPENDENCIES

Maximum function or event dependencies