sco_datacore_v1.add_record

Catalogue snapshot — development preview

SDK 2.3.0 · game pack 0.6.0 · source e616ed69d8f9f77b0f4827881c86d91e4a7d1689 Published release: sdk-v2.3.0 (immutable approved assets; this development preview is not an approved release). Source-backed inventory is not a runtime or in-game verification claim.

1.1: a new record of struct type named name (unique among records), its root copied from the record clone_record (a name or “guid:…”, required; a record of the same struct). guid: NULL or “” derives a stable one from the plugin id and name (the same at every launch); else “xxxxxxxx-…”, not zero. file_path: NULL or “” is libs/foundry/records/sco/<plugin id>/<name>.xml; else libs/foundry/records/… ending in .xml. out_record: an id like add_instance’s (the record’s root: “@<id>” as a record argument, SCO_DC_INSTANCE as a value); later operations may also name the record by name or GUID, and reference fields take it as SCO_DC_REF. SCO_BAD_ARG: a bad argument, or a name or GUID this patch already adds. The rest (struct has records, name and GUID new to the file, clone’s struct) is checked at the load. In the saved .toml it is a [[record]] operation. SCO_UNAVAILABLE on a 1.0 host. Implementation initializes out_record to 0 on failure.

Limitations / unestablished guarantees

• Internal allocation/failure guarantee unspecified.
• Recursive/concurrent same-patch reentrancy unspecified.
• Additional failures/output state unspecified unless described in the buffer contract.

Signature

sco_result (*)(uint64_t, const char *, const char *, const char *, const char *, const char *, uint64_t *)

Service and availability

Service index

Property	Value
Symbol	sco_datacore_v1.add_record
Record ID	sco-datacore-v1-add-record
Service	sco.datacore
Table	sco_datacore_v1
Version macro	SCO_DATACORE_VERSION_1_1
Packed table version	65537
Since / availability	size >= 64; 1.0 slot; works 1.1
Complete member extent (x64 bytes)	64
Table size (x64 bytes)	88

Header source

Parameters and buffers

sco_result (*add_record)(uint64_t patch, const char* type, const char* name, const char* guid, const char* clone_record, const char* file_path, uint64_t* out_record);
1.1: a new record of struct type named name (unique among records), its root copied from the record clone_record (a name or “guid:…”, required; a record of the same struct). guid: NULL or “” derives a stable one from the plugin id and name (the same at every launch); else “xxxxxxxx-…”, not zero. file_path: NULL or “” is libs/foundry/records/sco/<plugin id>/<name>.xml; else libs/foundry/records/… ending in .xml. out_record: an id like add_instance’s (the record’s root: “@<id>” as a record argument, SCO_DC_INSTANCE as a value); later operations may also name the record by name or GUID, and reference fields take it as SCO_DC_REF. SCO_BAD_ARG: a bad argument, or a name or GUID this patch already adds. The rest (struct has records, name and GUID new to the file, clone’s struct) is checked at the load. In the saved .toml it is a [[record]] operation. SCO_UNAVAILABLE on a 1.0 host. Implementation initializes out_record to 0 on failure.

Results and failures

Absent table: query_service NOT_FOUND; stopped operations: UNAVAILABLE. Unknown/released patch: NOT_FOUND; closed patch: BAD_ARG; operation cap: TOO_MANY. Additional failures/output state unspecified unless described in the buffer contract.

Absent capability

Absent table: query_service NOT_FOUND

Ownership

Strings/values copied; host owns patches and instances; IDs, not allocations, cross the ABI. Internal allocation/failure guarantee unspecified.

Thread affinity

Any thread; short locks, no wait for game load. Recursive/concurrent same-patch reentrancy unspecified.

Callback context

unspecified

Reentrancy

unspecified

Cleanup and cancellation

No in-flight cancellation; discard drops open/queued patch, not applied or saved effects. Unload forgets owned patches.

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/sco_datacore.h (*add_record)
cpp	typed-wrapper	include/scosdk/datacore.hpp const sco_result r = t_->add_record(id_, a.c_str(), b.c_str(), c.empty() ? nullptr : c.c_str(), d.c_str(),
csharp	typed-wrapper	sdk/csharp/Sco.Sdk/DataCore.cs r = t->add_record(Id, ty, n, g, c, p, &id);
lua	typed-wrapper	plugins/lua/sco_lua_game.c const sco_result r = dc->add_record(p->id, type, name, guid, clone, file, &id);

Examples

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

Tests

• tests/abi_datacore.c
• tests/test_datacore_service.cpp
• sdk/csharp/Sco.Sdk.Tests/FakeHost.cs
• tests/test_lua.cpp
• tools/test.sh
• sdk/csharp/Sco.Sdk.Tests/Layout.cs

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