Reading the kits' memory in place (structures) #

How an engine, a tool or a module in another language reads what the kits write in memory, without going through JSON: the fixed structures of the entity rows and of the poses, their generated accessors for each language, and the check that refuses a library that lays them out differently. Readable offline: gripforge docs structs, or the MCP tool gripforge_docs (topic structs).

What it is for #

A game runs its logic in the kit host (the logic modules on the web, the library libgfkits natively). Each frame an engine needs the entities, their transforms and some state. Asking for them as JSON copies and parses text every frame. The structures contract lets the engine read the same bytes the kit host wrote, in place:

• the rows of the entity table of the shared zone (ZoneEntityRow: id, flags, position, yaw, then the columns of the game);
• the interpolated poses of the entities being drawn (PresentPose);
• the headers of the zone, the inputs, the events, and the free-shape values kits exchange (FixedValue, FixedBlock…).

You need this guide if you write an engine adapter, a tool that reads the zone, or a kit module in a language other than Rust. A game that uses the catalogue never touches it.

A layout GripForge defines #

• Integers are little-endian; a field lies at the next multiple of its alignment (the C layout rules); an address inside a Fixed* structure is 64 bits wide whatever the address space.
• Nothing depends on a compiler or a language: any code that fills these bytes is a valid peer.
• Every structure has a number and a version (major.minor). A structure added, or a field added in reserved bytes, is a minor; a size, an offset or a meaning changed is a major.
• The reference of every structure, field by field with its offset, is docs/kit-structures.md (gripforge docs kit-structures). It is generated from one declaration file, and so is everything below.

There are two tables, both at contract 1.0:

Read the entity rows #

gfk_zone gives the table (rows, row_bytes, capacity, used, owner, epoch); row i starts at rows + row_bytes * i. The start of each row is a ZoneEntityRow (40 bytes):

The columns of the game schema follow (gfk_column gives the offset, size and type of one by name). epoch is the clock value of the last change of the world: if it did not move, no row changed, and you read nothing.

Valid until the next gfk_* call of the game (the zone may grow); the offsets are valid for the whole play.

Read the poses of what you draw #

gfk_present_poses(game, &n) returns the interpolated pose of each presented entity, one PresentPose per entity of the snapshot and in its order (same fields as the row start: id, flags, x, y, z, yaw). Nothing is copied. It is valid until the next gfk_present_frame of the game.

Start the presentation with the options that go with it (gfk_present_start, JSON):

gfk_copied(reset) counts the bytes copied between the library and the engine since the last reset (every answer written to the output, every JSON text handed in); reading in place is what keeps it low. gfk_physics_copied is the same count for the engine's physics callbacks.

The generated accessors #

Never edited by hand; regenerated from the declaration, and checked in the continuous integration.

The Unity and Unreal accessors need no setup beyond using the package: the host checks the library once when it loads.

The check at load #

The library answers its table with gfk_structs(&len): the magic GFST, the version of the engine table, then every structure with its size and the offset of every field as its compiler laid them out. An accessor refuses, with a message that names the reason, a library:

• without the table (... answers no structures table (magic GFST missing): it predates the engine structures, update it);
• of another major ("the package and the library do not lay the memory out the same way; update them together");
• of an earlier minor than the package needs;
• that lays a structure out differently from the declaration.

Update the package and the library together; never try to read a library the check refused.

Writing a module in another language #

A kit module that shares memory with the others must fill these bytes exactly. The rules to follow:

1. Take the layouts from docs/kit-structures.md (or the declaration it is generated from), never from your compiler.
2. Carry the table of the structures you use in a custom section gripforge.structs, so the loader can compare it.
3. Respect who owns each structure and how long it is valid: the page of each structure says whether the core or a kit writes it, and until when a pointer to it is valid.
4. Test your reading against the fixture of the contract: it holds every structure once, every field a value of its own, and each accessor must read the expected text line for line.

For writing a kit in Rust, see gripforge docs kit-third-party.

When it does not work #