Skip to content
sco-core SDK

sco_api.invoke

From the game thread: runs now, calls done (if set) once before returning, and returns the same result. From another thread: copies name and args, queues the call and returns SCO_OK; done then runs exactly once, on the game thread. Any other return (SCO_BAD_ARG, or SCO_TOO_MANY when the queue is full or memory runs out) means nothing was queued and done is never called. A call still queued when the plugin unloads is dropped without calling done.

Signature

Section titled “Signature”
sco_result (*)(sco_plugin *, const char *, const sco_arg *, uint32_t, sco_invoke_done, void *)

Service and availability

Section titled “Service and availability”

Service index

Property Value
Symbol sco_api.invoke
Record ID sco-api-invoke
Service sco_api
Table sco_api
Version macro SCO_API_MAJOR/SCO_API_MINOR
Packed table version 65537
Since / availability size >= 80; 1.0
Complete member extent (x64 bytes) 80
Table size (x64 bytes) 128

Header source

Parameters and buffers

Section titled “Parameters and buffers”

sco_result (*invoke)(sco_plugin* self, const char* name, const sco_arg* args, uint32_t nargs, sco_invoke_done done, void* ctx);
From the game thread: runs now, calls done (if set) once before returning, and returns the same result. From another thread: copies name and args, queues the call and returns SCO_OK; done then runs exactly once, on the game thread. Any other return (SCO_BAD_ARG, or SCO_TOO_MANY when the queue is full or memory runs out) means nothing was queued and done is never called. A call still queued when the plugin unloads is dropped without calling done.

Results and failures

Section titled “Results and failures”

Game thread: command result incl NOT_FOUND, BAD_ARG, UNAVAILABLE capability, CRASHED guarded fault, or provider result. Other thread: OK queued, BAD_ARG/TOO_MANY nothing queued. Initial validation can return before done.

Absent capability

Section titled “Absent capability”

unspecified

Ownership

Section titled “Ownership”

On game thread, arguments borrowed during call. Else name/arguments/string values copied into host queue allocations; done/ctx borrowed. reply borrowed during done only.

Thread affinity

Section titled “Thread affinity”

Any thread; on game thread command/done run synchronously; elsewhere queued and done runs on game thread. Recursive invoke depth/limit unspecified.

Callback context

Section titled “Callback context”

on game thread command/done run synchronously; elsewhere queued and done runs on game thread.

Reentrancy

Section titled “Reentrancy”

unspecified

Cleanup and cancellation

Section titled “Cleanup and cancellation”

Queued call dropped on calling owner release without done; non-OK enqueue return means done never runs. No invocation-specific cancellation.

Language mappings

Section titled “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_api.h
(*invoke)
cpp typed-wrapper include/scosdk/plugin.hpp
if (!reply) return api_->invoke(self_, name, args, nargs, nullptr, nullptr);
csharp typed-wrapper sdk/csharp/Sco.Sdk/Plugin.cs
r = a->invoke(_self, n, block.Args, block.Count, &DoneTrampoline, (void*)id);
lua restricted plugins/lua/sco_lua.c
const sco_result r = s->api->invoke(s->self, name, nargs ? args : NULL, (uint32_t)nargs, DoneCb, &d);
sdk/docs/lua.md
Runs any command, sc-offline’s or a plugin’s, now.

Examples

Section titled “Examples”

Tests

Section titled “Tests”

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