Floor fan

A configurable direction and switch compose into a reusable pushing tile.

What it demonstrates: Select fields · automatic saving · directional push.

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-fan --template fan

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

Change its initial direction, then switch it off and on. Return null to stop pushing; the host still owns movement.

Source

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

src/definition.ts

/** A switchable floor fan: state selects a push; Scape handles each player's movement. */
import {
  defineObject,
  exactKeys,
  record,
  requirePayload,
  ObjectActionError,
  type GizmoPush,
} from '@scape/sdk';

const directions = ['right', 'down', 'left', 'up'] as const;
export interface FanState {
  on: boolean;
  direction: GizmoPush['direction'];
}
export const fan = defineObject<FanState>({
  type: 'example.fan',
  version: 1,
  emoji: '🪭',
  label: 'Floor fan',
  hint: 'step onto the fan to get pushed; choose its direction in Configure',
  initial: () => ({ on: true, direction: 'right' }),
  valid: (state): state is FanState =>
    record(state) &&
    exactKeys(state, ['on', 'direction']) &&
    typeof state.on === 'boolean' &&
    directions.some((direction) => direction === state.direction),
  walkable: true,
  // No step callback is needed. Returning null stops pushing without changing walkability.
  // Opposing input stays allowed, unlike the conveyor's one-way surface.
  push: (state) => (state.on ? { direction: state.direction } : null),
  actions: {
    toggle: {
      permission: 'participant',
      run: (state, payload) => {
        requirePayload(payload, []);
        return { ...state, on: !state.on };
      },
    },
    direction: {
      permission: 'editor',
      run: (state, payload) => {
        requirePayload(payload, ['direction']);
        if (!directions.some((direction) => direction === payload.direction))
          throw new ObjectActionError(400, 'Choose a direction.');
        return { ...state, direction: payload.direction as FanState['direction'] };
      },
    },
  },
  view: (state, viewer) => ({
    title: 'Floor fan',
    description: '',
    fields: [
      {
        id: 'direction',
        label: 'Direction',
        kind: 'select',
        value: state.direction,
        options: directions.map((value) => ({
          value,
          label: value[0].toUpperCase() + value.slice(1),
        })),
      },
    ],
    controls: [
      {
        id: 'toggle',
        icon: 'toggle',
        label: state.on ? 'Turn off' : 'Turn on',
        pressed: state.on,
        action: { name: 'toggle', payload: {} },
      },
      {
        id: 'direction',
        label: 'Set direction',
        trigger: 'change',
        fields: ['direction'],
        disabled: !viewer.canEdit,
        action: { name: 'direction', payload: {} },
      },
    ],
  }),
});
export default fan;

Download definition.ts

src/project.ts

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

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

Download project.ts

Next steps

Test your changes · SDK reference · All examples