SDK reference
Find the exact methods, events, defaults and limits for the JavaScript SDK. Start with a browser game or your own Node server, then use these pages while you build.
| Module | What it does |
|---|---|
| relay-host | Create a room, accept phones and send private views through the hosted rendezvous service. |
| client | Connect a custom phone UI or an authenticated engine client with Session. |
| node-host | Accept phones directly on a Node HTTP(S) server and serve the browser controller. |
| node-peer | Supply a native WebRTC implementation to a Node relay host. |
| surface | Build, normalize and lay out custom controllers, with older-app fallbacks. |
| keyboards | Select language layouts and edit text without a system keyboard. |
| controls | Read positional buttons, axes, movement and physical gamepads. |
| feedback | Validate cues, haptic patterns, rumble, sound catalogs and WAV files. |
| protocol | Validate JSON frames, join links, app versions and controller input. |
| wire | Encode compact input and pings; pace updates and release stale input. |
| connection | Choose permitted routes through registered transports and codecs. |
| actions | Map controllers to players and named game actions. |
Imports and installation
The package name is @controller-plus/sdk. Install the SDK archive linked from Downloads; the package is not published to the npm registry. The archive version and installed app version are separate numbers.
The root import exports controls, protocol, client, actions, connection and feedback. Subpath imports exist for controls, protocol, actions, connection, relay-host, node-host, node-peer, surface, keyboards and games. There are no package subpaths named client, feedback or wire. Use the root for the first two. wire.mjs is a browser/source module.
Browser source modules live at https://controller.plus/sdk/src/<module>.mjs. A server using serveControllerAssets serves the same modules under its own /sdk/src/. Node adapters live in the package's adapters directory and require Node 22 or newer. Do not load them in a browser.
Examples
Each JavaScript example is a separate ES module. Save it as an .mjs file after installing the SDK. Network examples export their room or host so your application can display the invite and close it when done. HTML examples are complete pages. Use HTTPS for internet play. Follow the quickstart for a phone-reachable local address.
The reference describes runtime behavior. Some TypeScript declarations lag behind it, including surface support, peer options and newer Session events. A missing declaration does not imply a missing runtime method; see the signatures on each page. The examples use JavaScript.
Common contracts
Unless a page says otherwise, JavaScript string limits count UTF-16 code units (length/slice), message byte limits count UTF-8 bytes, and keyboard entry limits count graphemes where supported.
Input is a full state: axes[4], buttons[16], and optional motion. Right and down are positive. Names are display text; use the server-assigned playerId as identity. Private views go to one phone. Public state goes to the room. Validate every player event against the game's current phase and ownership rules.
Session.on() and RelayRoom.on() return an unsubscribe function. ControllerHost uses Node's EventEmitter, where on() returns the host and off(event, callback) removes a listener. A successful send is not an acknowledgement that a phone displayed or played it.
See Troubleshooting for developers for connection failures, missing events, old apps and input that stops or stays held.