Build your first Gizmo

Use Node.js 22 or newer, Yarn, an exported Scape development kit, and an account on a host that supports developer worlds. Packages are not yet available from a public registry; see availability.

Obtain a project

If you have a kit, extract it into your project directory and continue below. If you operate from Scape source, create one from the repository:

yarn sdk:starter /path/to/my-gizmo

The destination must not exist, and its parent directory must exist. The export contains a blank project and three local archives: the SDK, unified Scape CLI and MCP server. Keep the archives and the manifest's Yarn resolutions together; third-party dependencies still need installation. It does not copy the Scape game or any account credentials.

For a worked example, add a template:

yarn sdk:starter /path/to/my-lamp --template lamp

Install and build

Inside the exported directory:

yarn install
yarn build

The starter contains src/definition.ts and src/project.ts. A project default-exports its definitions:

import { defineProject } from '@scape/sdk';
import object from './definition.js';

export default defineProject({ objects: [object] });

The kit's scape.entry points to src/project.ts. You can add more definitions later; the host accepts up to 16 per project.

Connect to your world

yarn dev --origin https://your-scape-host

Use the compatible HTTPS host supplied by your operator. The CLI opens no inbound server and needs no browser-to-laptop connection or tunnel.

Open the printed link, sign in, compare the displayed code with your terminal, and choose Connect this project in the developer sidebar. A code expires in five minutes. Approval grants a two-hour, world-scoped development session.

The kit's dev script runs scape gizmo dev; you can also call yarn scape gizmo dev --origin https://your-scape-host directly. This pairs the Gizmo project, not an agent.

The sidebar shows the accepted local revision and available Gizmos. Choose your Gizmo and place it. Save a source file to send an updated build.

Make a change

Change the label or view description in the blank definition and save. The CLI compiles and uploads the project. The host validates the full update before activating it. If it fails, the previous accepted build stays active and the sidebar shows the error.

Try the Counter to add a first action. Use your own namespace and a unique emoji for a new definition. The scape. namespace and built-in interactive emojis are reserved; bundled examples may retain their existing identities on compatible hosts.

Finish a session

Stop the command or disconnect in the sidebar. The last accepted code and world state remain. Reconnect to continue editing. This is a development session, not a publication flow.

Next, learn projects, state and actions, or test an example.