Getting started

TPG games are focused web apps connected by a runtime contract. The platform owns the room, identity, and lifecycle; your game owns what players see and what their choices mean.

Before you begin

You need Node.js 24, npm, and a browser. The public @tpgames/* packages install from npm without a token or access to the TPG repository. Your game can live in its own repository.

Create a project with the starter:

npm create @tpgames/game@latest -- my-party-game \
  --game-id my-party-game \
  --title "My Party Game"
cd my-party-game
npm install
npm run dev

If you already have @tpgames/sdk-dev-kit installed, tpgames init my-party-game creates the same starter. Both paths require a new target path.

The starter gives you:

• a manifest that declares the game and its surfaces
• a host display for the shared screen
• a controller surface sized for phones
• local runtime helpers and a bundle command
• AGENTS.md and a self-contained TP Games development skill for compatible coding agents

The main packages are @tpgames/game-kit for the game runtime, @tpgames/sdk-dev-kit for local authoring and packaging, and @tpgames/core-manifest for strict manifest validation. The starter installs and pins the compatible versions for you.

Understand the three visible roles

Most games begin with a host display and controller. Spectators are optional, but keeping the role distinct makes future choices explicit.

The fourth role, logic, is never a presentation surface. It represents the authority that accepts intents and commits canonical state.

Build one complete loop

Resist the urge to start with menus and art. Prove one loop all the way through:

1. Render a prompt on the host display.
2. Render one choice on the controller.
3. Send that choice as an intent.
4. Let the authority update shared state.
5. Render the result on both surfaces.

That loop exercises the contract you will depend on for every future mechanic.

Run the local checks

Keep the starter commands green as you work:

npm run typecheck
npm run test
npm run bundle

The bundle step should produce the manifest and every declared surface. A missing controller asset is a packaging error even when the host page looked correct in local development.

Test with real phones before uploading

Install cloudflared, then start a real TPG room backed by your local Vite source:

npm run dev:devices

The command starts a temporary Cloudflare Quick Tunnel and opens the host room. Scan the room QR with as many phones as your game needs. In a headless environment, add -- --no-open to print the host link instead. No registry upload, game API key, or bundle build is required.

If you already run a tunnel, pass its HTTPS origin instead:

npm run dev:devices -- --port 5173 --public-url https://your-tunnel.example.com

Keep the tunnel's origin port and --port identical. A Quick Tunnel exposes your local Vite server and source modules publicly. Treat the generated host link as private because it contains the temporary development-manifest descriptor; share only the room QR or controller invite. Keep .env files, credentials, and private assets outside Vite's served root, and stop the command and tunnel when testing is finished.

Choose your next step

• Read the room and authority model before adding shared state.
• Browse the examples hub for framework-specific structure.
• Check the capability matrix before requesting camera, microphone, gamepad, fullscreen, or pointer lock.
• Follow publishing a game once a local bundle is ready.