Instances

A server is a runtime host; an instance is one live script running on it. A single server can run many instances — a lobby that spawns per-level game shards, for example — and instances can message each other. These builtins are server-side unless noted.

Advanced surface

Most mods never need this page — a single client/server script is complete on its own. Reach here when you're building an orchestrator that manages multiple script instances.

Spawning instances

spawn(script_label: string, instance_id: string, handoff: u8[], persistent: bool): bool

Creates a new instance of a library script under the given ID. Returns true on success, false if the ID is already in use. handoff is delivered to the new instance; persistent controls whether it survives with no clients.

find_instance(script_label: string): string   // ID of a live instance, or "" if none
list_instances(): string[]                     // all live instance IDs (excl. this one)
list_scripts(): string[]                        // labels the server is configured to host
player_count(script_label: string): i32         // connected clients across all instances of a label

player_count walks the spawn tree transitively, so an orchestrator with no direct clients still sees the players held by the shards it spawned — useful for load-balancing ("send this player to the least-full level-1 shard").

uuid(): string   // a fresh 32-char lowercase-hex unguessable ID

uuid mints IDs for spawn. It's server-only because "knowledge is access control" (below) means a private room must use an unguessable ID the script generates itself.

Inter-instance messaging

tell(url: string, data: u8[])      // fire-and-forget bytes to the instance at url
my_url(): string                   // this instance's own routable URL
instance_url(id: string): string   // build the URL for a same-server instance ID

event receive_from(from_url: string, data: u8[])   // another instance sent bytes

tell queues delivery and returns immediately; the recipient's event receive_from fires asynchronously with the sender's my_url() as from_url, so it can reply. There is no synchronous ask — Munos has no callback/continuation model and a blocking same-server call would deadlock. Request/response is a script-level idiom: include a correlation tag, store local state keyed by it, and match it in event receive_from.

server {
    event receive_from(from_url: string, data: u8[]) {
        // handle a message from a sibling instance; reply with tell(from_url, …)
    }
}

Knowledge is access control

Any instance can tell any other if it has the URL. Instance IDs are unguessable UUIDs, and URLs propagate only via spawn handoffs and the from_url of an incoming receive_from. An orchestrator that keeps its children's URLs private isolates them; one that hands them around enables sibling-to-sibling messaging.

tell is server-only — client scripts speak to their server with send, not to other instances.

Shard configuration

shard_config(): string    // the config string the admin passed this instance
list_shards(): string[]   // URLs of currently-registered shards

shard_config() is an opaque, script-defined string an instance can branch on to decide its role:

const ROLE = shard_config()

server {
    if ROLE == "role=lobby" {
        // lobby logic
    } else {
        // gameplay logic
    }
}

string_from_bytes (see Networking) is handy here for turning a handoff payload into a string to pass to tell.