Counter

A small shared counter: state, a participant action, and a standard button.

What it demonstrates: State validation · participant actions · views.

Run this example

All learning examples appear in a compatible developer world. To export a standalone project, an operator with source access runs this from the Scape repository (choose a new destination under an existing directory):

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

In the exported project:

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

Follow connection and approval. The exported dev script invokes scape gizmo dev. The kit includes three private archives for the SDK, CLI and MCP server; keep them and the Yarn resolutions together. Third-party dependencies still need installation. See the CLI reference for commands; no public Scape registry install is available yet.

Try changing it

Add a decrement action. Keep the state a safe integer and reject unexpected payload fields.

Source

This code is included directly from the working example when the site builds.

src/definition.ts

/** Counter owns the shared count and controls; Scape supplies persistence and permissions. */
import { defineObject, exactKeys, ObjectActionError, record, requirePayload } from '@scape/sdk';

/** Start here: state, validation, two actions, and a declarative view. */
export const counter = defineObject<{ count: number }>({
  type: 'scape.counter',
  version: 1,
  emoji: '🔢',
  label: 'Counter',
  hint: 'count together',
  initial: () => ({ count: 0 }),
  valid: (state): state is { count: number } =>
    record(state) &&
    exactKeys(state, ['count']) &&
    Number.isSafeInteger(state.count) &&
    Number(state.count) >= 0 &&
    Number(state.count) <= 9999,
  actions: {
    increment: {
      permission: 'participant',
      run: (state, payload) => {
        requirePayload(payload, []);
        if (state.count === 9999)
          throw new ObjectActionError(409, 'Reset the counter before adding more');
        return { count: state.count + 1 };
      },
    },
    reset: {
      permission: 'editor',
      run: (_state, payload) => {
        requirePayload(payload, []);
        return { count: 0 };
      },
    },
  },
  view: (state, viewer) => ({
    title: `${state.count}`,
    description: 'Everyone can add one. The object editor can reset the count.',
    controls: [
      {
        id: 'increment',
        label: 'Add one',
        action: { name: 'increment', payload: {} },
        disabled: state.count === 9999,
      },
      ...(viewer.canEdit
        ? [
            {
              id: 'reset',
              label: 'Reset count',
              confirm: 'Clear the count?',
              action: { name: 'reset', payload: {} },
            },
          ]
        : []),
    ],
  }),
});

Download definition.ts

src/project.ts

/** Project entry: exports counter to Scape's SDK loader. */
import { defineProject } from '@scape/sdk';
import { counter } from './definition.js';

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

Download project.ts

Next steps

Test your changes · SDK reference · All examples

Counter ​

Run this example ​

Try changing it ​

Source ​

src/definition.ts ​

src/project.ts ​