Client SDK

The NetStack client connects to a project over WebSocket, keeps a local mirror of synchronized state and lets you call Functions.

Install

Download the bundle and add it to your project, or load it directly in a browser:

<script type="module">
  import { NetStackClient } from "https://getnetstack.com/sdk/netstack-client.js";
</script>

For bundlers, save netstack-client.js into your source tree and import it from there. It is a single dependency-free ES module, about 4 KB.

Godot developers should use the Godot addon instead.

new NetStackClient(options)

Option	Type	Description
url	string	Your project's WebSocket address, such as wss://yourgame.netstack.network.
roomId	string	The room to join.
playerId	string	The ID this player joins as.
webSocketImpl	WebSocket constructor	Optional. Needed on Node versions without a global WebSocket.
callTimeoutMs	number	Optional. How long call() waits for an answer. Default 10000.

Methods

connect()

Opens the connection, joins the room and resolves with a snapshot of the room: its properties and the players in it. Rejects with a NetStackRemoteError if the server refuses the join, for example JOIN_REJECTED when a plan limit is reached or PROJECT_SUSPENDED.

call(functionName, args?)

Calls a Function and resolves with its return value. Rejects with a NetStackRemoteError carrying the error code and message if the Function threw a NetStackError or failed. It also rejects with DISCONNECTED if the connection drops, or CALL_TIMEOUT if no answer arrives in time.

try {
  const result = await client.call("buyItem", { itemId: "sword" });
} catch (error) {
  if (error.code === "NOT_ENOUGH_GOLD") showMessage(error.message);
}

on(event, listener)

Subscribes to an event and returns a function that unsubscribes.

getRoomProperties()

Returns the current room properties.

getPlayerProperties(playerId?)

Returns the properties you are allowed to see for a player. Defaults to your own player.

getPlayerIds()

Returns the IDs of the players currently in the room.

leave() and disconnect()

leave() leaves the room. disconnect() closes the connection.

Events

Event	Payload
joined	The room snapshot.
left	None.
disconnected	None.
event	{ name, data } for events broadcast by Functions.
propertyChange	{ scope, playerId?, key, value }
propertyDelete	{ scope, playerId?, key }
error	{ code, message }

Other languages

There is no engine-specific SDK required. Any client that can open a WebSocket or UDP socket and exchange JSON works. See the wire protocol.