sco_ui_v1.bind_hotkey

Binds chord to the command name (“<x>.<y>”; any plugin’s or a host feature’s) with nargs arguments (args may be NULL with 0), which are copied, strings included. When the product sees the chord it invokes the command through the command registry, as invoke would, with this plugin as the caller; the command needn’t exist yet. SCO_BAD_ARG: a bad chord or command name, a bad argument, or the chord taken: bound already (by anyone, this plugin included) or reserved by the product; last_error names the owner. SCO_TOO_MANY: the host’s hotkey table is full.

Signature

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

Service and availability

Service index

Property	Value
Symbol	`sco_ui_v1.bind_hotkey`
Record ID	`sco-ui-v1-bind-hotkey`
Service	sco.ui
Table	sco_ui_v1
Version macro	SCO_UI_VERSION_1_0
Packed table version	65536
Since / availability	`size >= 56`; 1.0
Complete member extent (x64 bytes)	56
Table size (x64 bytes)	80

Header source

Parameters and buffers

sco_result (*bind_hotkey)(sco_plugin* self, const char* chord, const char* command, const sco_arg* args, uint32_t nargs);
Binds chord to the command name (“<x>.<y>”; any plugin’s or a host feature’s) with nargs arguments (args may be NULL with 0), which are copied, strings included. When the product sees the chord it invokes the command through the command registry, as invoke would, with this plugin as the caller; the command needn’t exist yet. SCO_BAD_ARG: a bad chord or command name, a bad argument, or the chord taken: bound already (by anyone, this plugin included) or reserved by the product; last_error names the owner. SCO_TOO_MANY: the host’s hotkey table is full.

Results and failures

Absent table: query_service NOT_FOUND; stopped self-taking methods: UNAVAILABLE; invalid/released self: BAD_ARG; allocation exceptions: TOO_MANY. Additional failures/output state unspecified unless described in the buffer contract.

Absent capability

Absent table: query_service NOT_FOUND

Ownership

Strings/arguments copied; draw/ctx borrowed until unregister/unload. Host owns registry; no allocation transfer.

Thread affinity

Any thread; draw callbacks game thread. Other recursive reentrancy unspecified.

Callback context

draw callbacks game thread.

Reentrancy

unspecified

Cleanup and cancellation

unbind_hotkey/ordinary unload/non-retained crash cleanup ends binding; cancellation of an already-issued command unspecified. Retained-provider faults skip owner resource-release hooks and require restart; backing resources remain retained, not safe for cached calls. Guarded draws stop, but snapshots and chord reservations remain.

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_ui.h `(*bind_hotkey)`
cpp	typed-wrapper	include/scosdk/ui.hpp `return t_->bind_hotkey(self_, chord, command, args.size() ? args.begin() : nullptr, static_cast<uint32_t>(args.size()));`
csharp	typed-wrapper	sdk/csharp/Sco.Sdk/Ui.cs `return _t->bind_hotkey(Self, c, n, block.Args, block.Count);`
lua	typed-wrapper	plugins/lua/sco_lua.c `const sco_result r = ui->bind_hotkey(s->self, chord, name, nargs ? args : NULL, (uint32_t)nargs);`

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.