# SDK reference

Find the exact methods, events, defaults and limits for the JavaScript SDK. Start with [a browser game](web-games.md) or [your own Node server](quickstart.md), then use these pages while you build.

| Module | What it does |
| --- | --- |
| [relay-host](sdk-relay-host.md) | Create a room, accept phones and send private views through the hosted rendezvous service. |
| [client](sdk-client.md) | Connect a custom phone UI or an authenticated engine client with `Session`. |
| [node-host](sdk-node-host.md) | Accept phones directly on a Node HTTP(S) server and serve the browser controller. |
| [node-peer](sdk-node-peer.md) | Supply a native WebRTC implementation to a Node relay host. |
| [surface](sdk-surface.md) | Build, normalize and lay out custom controllers, with older-app fallbacks. |
| [keyboards](sdk-keyboards.md) | Select language layouts and edit text without a system keyboard. |
| [controls](sdk-controls.md) | Read positional buttons, axes, movement and physical gamepads. |
| [feedback](sdk-feedback.md) | Validate cues, haptic patterns, rumble, sound catalogs and WAV files. |
| [protocol](sdk-protocol.md) | Validate JSON frames, join links, app versions and controller input. |
| [wire](sdk-wire.md) | Encode compact input and pings; pace updates and release stale input. |
| [connection](sdk-connection.md) | Choose permitted routes through registered transports and codecs. |
| [actions](sdk-actions.md) | 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](https://controller.plus/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](quickstart.md) 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](troubleshooting.md#troubleshooting-for-developers) for connection failures, missing events, old apps and input that stops or stays held.