sco_widgets_v1.update_nodes

Atomically replaces or inserts one subtree of an owned panel. nodes[0] is the root and every later node descends from it; node, stride and string rules as set_panel, with 1.0 or 1.1 node sizes. An existing root ID is replaced in place and keeps its parent; a new root ID becomes the last child of parent 0 or an existing ROW/COLUMN. IDs must not collide with nodes outside the replaced subtree; 256 nodes/panel and 4096 live nodes after the change. Failure preserves the tree.

Signature

sco_result (*)(sco_plugin *, const char *, const sco_widget_node *, uint32_t, uint32_t)

Service and availability

Service index

Property	Value
Symbol	`sco_widgets_v1.update_nodes`
Record ID	`sco-widgets-v1-update-nodes`
Service	sco.widgets
Table	sco_widgets_v1
Version macro	SCO_WIDGETS_VERSION_1_1
Packed table version	65537
Since / availability	`size >= 32`; 1.1
Complete member extent (x64 bytes)	32
Table size (x64 bytes)	48

Header source

Parameters and buffers

sco_result (*update_nodes)(sco_plugin* self, const char* panel_id, const sco_widget_node* nodes, uint32_t count, uint32_t node_stride);
Atomically replaces or inserts one subtree of an owned panel. nodes[0] is the root and every later node descends from it; node, stride and string rules as set_panel, with 1.0 or 1.1 node sizes. An existing root ID is replaced in place and keeps its parent; a new root ID becomes the last child of parent 0 or an existing ROW/COLUMN. IDs must not collide with nodes outside the replaced subtree; 256 nodes/panel and 4096 live nodes after the change. Failure preserves the tree.

Results and failures

OK; WRONG_THREAD off game thread; UNAVAILABLE stopped service/host; BAD_ARG malformed owner/ID/tree/size/stride/data or a moved root; NOT_FOUND absent owned panel; TOO_MANY limits or allocation failure. Failure atomic.

Absent capability

Check the table size covers the member and the pointer is non-NULL: a 1.0 table (24 bytes) has no 1.1 members. query_service answers UNAVAILABLE for 1.1 against a 1.0 host.

Ownership

Host deep-copies the subtree on success; the panel’s fn/ctx stay unchanged and borrowed. No allocation transfer.

Thread affinity

Game thread only; WRONG_THREAD elsewhere. Callbacks game thread under owner callout guard.

Callback context

Event, text and panel ID borrowed during callback only; callback ctx is plugin-owned.

Reentrancy

Callable from the panel’s own event callback; generation change drops remaining stale events, new tree renders next pass. Registry lock not held during plugin code.

Cleanup and cancellation

Success starts a new generation: remaining events of the current pass drop and the change renders next pass. Owner release and fault rules as set_panel. No separate cancel token.

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_widgets.h `(*update_nodes)`
cpp	direct	include/sco_widgets.h `(*update_nodes)`
csharp	unsupported	docs/contracts.md `C# and Lua sco.widgets 1.1 routes are unsupported.`
lua	unsupported	docs/contracts.md `C# and Lua sco.widgets 1.1 routes are unsupported.`

Examples

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

Tests

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