sc_inventory_v1.snapshot

Catalogue snapshot — development preview

SDK 2.4.0 · game pack 0.8.0 · source d16f013c629797275e40124184b261da54cce0ef Published release: sdk-v2.4.0-rc.1 (release candidate 1, attested assets; the final signed release follows; this development preview is not an approved release). Source-backed inventory is not a runtime or in-game verification claim.

Copy the local player’s current item-port snapshot into out (caller sets out->size; out->count is capacity in, ports filled out, max 128). The ports are the whole attached tree, depth first: each port, then the ports of the container attached to it, empty ports included. Read-only: per valid port, the attached item’s item type id (field item_class_id, an ordinal of the game’s item-type enumeration) and its session-scoped entity id (joins game.entities); generation advances on port-set change. With out->size >= sizeof(sc_inventory_snapshot) (1.1) it also sets flags (TRUNCATED: ports beyond the cap exist; LIMITED: the walk’s own limits cut the tree) and total_seen; a 1.0 caller passing the 1.0 size never sees them. Values are the client’s view of server state at snapshot time; nothing can be written through this ABI.

Limitations / unestablished guarantees

• Local player ports only in 1.0 (ships/mounts are follow-ups).
• Per-class item names are not established; the 192-category vocabulary is build-scoped to 4.10.197.2878.
• No stack counts (layout unattested).
• Snapshot semantics: 128 ports max; the walk covers the whole attached tree depth first (at most 8 levels below the player’s container, 256 containers, 4096 ports counted); flags and total_seen say what was cut; generation is computed by comparing successive snapshots (the game has no change counter); per-frame streams are out of contract.
• Nesting is not reported: ports come in walk order without a parent or depth.

Signature

sco_result (*)(sco_plugin *, sc_inventory_snapshot *)

Service and availability

Service index

Property	Value
Symbol	sc_inventory_v1.snapshot
Record ID	sc-inventory-v1-snapshot
Service	game.inventory
Table	sc_inventory_v1
Version macro	SC_INVENTORY_SERVICE_VERSION_1_1
Packed table version	65537
Since / availability	size >= 16; 1.0; flags and total_seen 1.1
Complete member extent (x64 bytes)	16
Table size (x64 bytes)	16

Header source

Parameters and buffers

sco_result (*snapshot)(sco_plugin* self, sc_inventory_snapshot* out);
Copy the local player’s current item-port snapshot into out (caller sets out->size; out->count is capacity in, ports filled out, max 128). The ports are the whole attached tree, depth first: each port, then the ports of the container attached to it, empty ports included. Read-only: per valid port, the attached item’s item type id (field item_class_id, an ordinal of the game’s item-type enumeration) and its session-scoped entity id (joins game.entities); generation advances on port-set change. With out->size >= sizeof(sc_inventory_snapshot) (1.1) it also sets flags (TRUNCATED: ports beyond the cap exist; LIMITED: the walk’s own limits cut the tree) and total_seen; a 1.0 caller passing the 1.0 size never sees them. Values are the client’s view of server state at snapshot time; nothing can be written through this ABI.

Results and failures

OK snapshot copied, UNAVAILABLE service off, no backend bound, out null, out->size below the 1.0 snapshot size, no local player, no item-port container on the player, or the adapter’s guards failed; BAD_ARG invalid self.

Absent capability

game.inventory.read defaults OFF (a product switch, and every inventory.* signature row must be OK); off, unbound or unready, the service publishes UNAVAILABLE. Adapter grounded on F-4.10.197.2878-011..-016; synthetic evidence only, not run in game.

Ownership

Provider fills caller-owned storage; a plain copy crosses. No allocation, no engine pointer transfer, nothing retained from out.

Thread affinity

Game thread only.

Callback context

No plugin callback.

Reentrancy

Snapshot read; the adapter reads the container’s port vector in place and calls only per-port accessors, each checked against its signature row first.

Cleanup and cancellation

StopGameInventory withdraws the service; read-only, no engine state to restore.

Language mappings

Status labels are copied verbatim from the catalogue: direct is native access; typed-wrapper is wrapper-backed; restricted is a subset/adaptation; unsupported means no supported route is established. No status implies universal safety.

Language	Catalogue status	Source evidence / wrapper tokens
c	direct	include/sc_inventory.h (*snapshot)
cpp	direct	include/sc_inventory.h (*snapshot)
csharp	typed-wrapper	sdk/csharp/Sco.Sdk/Game/Inventory.cs _table->snapshot(_plugin.SelfPtr, &value)
lua	typed-wrapper	plugins/lua/sco_lua_game.c inventory->snapshot(self, &snapshot)

Examples

None identified in the catalogue; this is not proof none can exist.

Tests

• tests/abi_game_inventory.c
• sdk/csharp/Sco.Sdk.Tests/GameFakeHost.cs
• tests/game_contracts/lua_cases.inc
• tools/test_sdk_catalogue.py

Find by task

read inventory; read player inventory; inspect attached item ports

This is a search phrase for the existing contract, not an additional API alias.

ABI pins prove layout, not semantic behavior or a live game session.