Sushi Pigeon

How to use Sushi Pigeon

The same guide that ships with the app (Help → Learn has step-by-step tutorials). Stuck? See Support.

Why

AI can one-shot a Phaser or Three.js prototype, but getting from "sloppy demo" to "finished, commercial game" needs hands-on control: placing things precisely, tuning physics, fixing sprites, balancing sound, wiring up ads and leaderboards per platform. Sushi Pigeon is that control surface, and it speaks the same language as the AI: every click in the editor is a command, and the AI (Pige in the editor, or any LLM through MCP) uses the exact same commands. Nothing is a black box and everything can be undone.

What's in the box

AreaWhat
EditorHierarchy, scene view (2D and 3D with move/rotate/scale gizmos), inspector for every component, asset browser that updates as files change, console, play-in-editor, undo/redo, File/Edit/View/Help menus, light/dark themes
RuntimePhaser 4 for 2D + UI, Three.js for 3D, both at once in a single scene. Arcade physics (2D) and Rapier (3D). Scripts in TypeScript with a small, friendly API. Built-in behaviours (platformer, top-down, FPS, third-person, patrol, pickups…)
ErasMagnavox Odyssey, Pong, Atari 2600, Intellivision, LCD handhelds, NES, Master System, Game Boy, SNES, Mega Drive, PlayStation, N64, Saturn (and Modern). An era sets resolution, palette, sound chip and screen FX; the tools warn when you break its limits — optional, on by default, mix and match freely
Sprite toolPixel editor with era palettes, frames, animations, onion skin, mirror, import-any-image-as-era-pixel-art (quantise + dither)
Tilemap toolPaint tiles from any tileset, layers, collision layers
Music toolStep sequencer/piano roll with the era's real channel line-up (NES: 2 pulse + triangle + noise…), pulse/triangle/noise/wave/FM/TIA voices
SFX toolsfxr-style generator with presets (coin, jump, laser, explosion, power-up, hit, blip) and era bit-crush
ScriptsCode editor (CodeMirror) with the scripting API; attach scripts to entities with Inspector-editable props
PigeLocal Gemma 4 (downloaded on demand, runs offline) or Gemini / Ollama / any OpenAI-compatible API — edits the scene with commands, writes scripts, composes era-correct chiptunes, draws pixel sprites
Generative mediaFree on-device images (FLUX.2 klein / Z-Image via stable-diffusion.cpp, BiRefNet cut-outs), or fal.ai and kie.ai for images, music and sound effects, auto-converted to your era
MCP serversushi-pigeon-mcp lets Claude Code / Claude Desktop / Cursor drive the editor and project files safely
Pigeon PostOne SDK and one settings screen for Poki, CrazyGames, GameDistribution, Playgama, YouTube Playables, Facebook Instant, Newgrounds, itch.io, Twitch and TikTok Minis, plus real app builds for Google Play (Android APK/AAB with Play Games), the App Store (Xcode project with Game Center) and Windows/Steam (steamworks.js) — usable inside the engine or on its own in any web game

3D worlds (sky, post-processing, terrain, scatter, characters)

  • Add things: GameObject → 3D has sub-menus — Shapes (cube, sphere, cylinder, cone, capsule, torus, plane, ramp, icosphere), World (noise terrain, water, forest / pines / grass / rocks scatter), Lights (point, spot, directional, hemisphere, area), Characters (first/third-person, click-to-move, chasing enemy — all on Rapier's kinematic character controller), Physics (hinged door, swinging ball, motor wheel), Cameras (orbit, cinematic path + path points) and Models. The same menu has Sky and Post-processing look presets.
  • Look: click empty space so nothing is selected — the Inspector shows Sky & lighting (sky presets, sun, sky lighting, tone mapping/exposure, shadow quality/softness/distance, fog) and Post-processing (bloom, GTAO, depth of field, vignette, colour grade + LUT, chromatic aberration, outline by tag, FXAA/SMAA). The Scene view shows it live.
  • Materials: a Mesh's Inspector has a material editor with a live swatch (standard / physical / toon / unlit / lambert, textures, normal maps, glow, transparency). Save as material… makes a shared .material.json (also Assets → New 3D material); editing it updates every mesh that uses it.
  • GLB models: the Inspector previews the model, lists its clips and sets loop / speed / blend. Scripts: this.entity.animator.play('Run', { fade: 0.3 }); events: Play 3D animation clip.
  • Scatter: select a Scatter entity and press S (or Paint in the Inspector) — drag on the ground to paint instances, Shift-drag erases; Generate fills the area on the terrain. Instances are GPU-instanced and hidden by chunk beyond the draw distance.
  • Scripts: this.scene.raycast(from, dir), this.scene.pick(x, y), this.scene.findPath(from, to), camera.shake() (2D and 3D); built-ins orbit-camera, camera-path, nav-agent, click-to-move. Events: Ray hits, Can see, Walk to (pathfinding), Turn to face.

3D Model studio (how to use)

  • Make one: Assets → New 3D model (or GameObject → 3D → Make a 3D model, or right-click in Assets) and pick a template: empty voxels, a voxel character (body, head, arms, legs as separate parts), a crate, or a low-poly cube / tree / barrel. It opens in the Model tab.
  • Voxels: tools Add, Remove, Paint, Box (Shift carves), Fill, Extrude and Pick (keys 1–7, Ctrl+click picks a colour); Mirror X/Y/Z copies every edit. Middle-drag / Alt+drag orbits, wheel zooms, F frames. Parts (left panel) are separate pieces you can attach to each other.
  • Low-poly: Add part → cube, plane, cylinder, cone, sphere, wedge, pyramid. Object moves/turns/scales parts (W/E/R), Face and Vertex select (Shift adds) and move with the gizmo; Extrude, Inset, Colour, Delete. Shading flat or smooth.
  • Texture: Colour → Texture bakes face colours into an auto-unwrapped texture; the Texture tool paints pixels right on the model. Edit in Sprite editor moves it into a pixel sprite; any sprite/image or .material.json can be swapped in.
  • Era budget: the right panel counts triangles, vertices and texture size against the era (PS1 ~400 triangles, 128 px textures; N64; Saturn), warns when over, and Reduce to … simplifies it. Era look previews the wobbly PS1 / N64 look; Bend the era limits hides the warnings.
  • Animate: + Clip adds Idle, Walk, Spin, Bounce, Wave or an empty clip; scrub the timeline and move parts (or press Key) to set keys. Clips go into the exported .glb, so this.entity.animator.play('Walk') and Play 3D animation clip use them.
  • Use it: drag the .model.json into the Scene view, press Place in scene, or Swap model… on a Model component. The game loads the .glb exported next to it on every change. Not included: boolean (CSG) operations and bones.

Behaviours (how to use)

Select an entity and press Add behaviour in the Inspector: behaviours are grouped like Construct 3 (Movement, General, Attributes, Logic) with a search box — type “bullet”, “health” or “path” and press Enter. Each behaviour shows its props (with dropdowns and entity/tag pickers), the events it fires, the values you can read and the methods you can call. Ready-made examples are in GameObject → 2D → Gameplay (Bullet, Moving platform, Spawner, Turret, Ladder, Checkpoint, NPC with dialogue, Path, Path follower). Drag a Path’s points in the Scene view (click a ＋ to add one, right-click a dot to remove it). In event sheets use the Behaviours group (“On death”, “Damage”, “Call behaviour method”…), in expressions Player.health.hp, and in scripts this.entity.behaviour('health').damage(1). They work with Arcade physics bodies and without them (then entities tagged solid block movement).

Genre kits: enemy AI, racing, platformers, shooters (how to use)

  • Start from a template: the New project dialog has genre filters — Kart racer (top-down), 3D arcade racer, Metroidvania, Shmup and Maze chase are small but playable.
  • Drop in pieces: GameObject → 2D (or 3D) → Gameplay → AI enemies, Racing, Platformer, Arcade & shooter, Maze chase. The same pieces are in the Scene view's right-click Add here menu.
  • Enemy AI: add the State machine behaviour (Inspector → Add behaviour → AI), pick a ready-made brain, or press Edit state machine… to draw your own: drag states, right-click for more, pick each state's action and add transitions (first match wins). Pige and MCP use ai.setBrain.
  • Races: a Race manager + karts with Racer + numbered Race checkpoints (0 = finish line) + a Racing line path for the AI. race.checkpointsFromPath lays the gates along the line. UI labels show {lap}/{laps}, {position}, {raceTime}, {raceMessage}.
  • Platformers: the Platformer behaviour now has double jump, wall jump, dash and ledge grab props; add Crumbling platform, Spring, Conveyor, Stompable enemies and Camera rooms for Metroidvania screen slides.
  • Shooters/arcade: Wave spawner ("5 Enemy ship v; 8 Enemy ship circle"), Bullet emitter patterns, Power-ups, Lives & high scores (local table), the asteroids ship and rocks. Bullets and waves keep to the era's sprites-on-screen limit unless bendEra is on.

Free AI images on this PC

Settings → Media generation → On this PC: download FLUX.2 klein 4B (5.6 GB, fast) or Z-Image Turbo (+4.4 GB, more detail; recommended with a 10 GB+ graphics card) and, optionally, the BiRefNet background remover (0.1 GB). Then Assets → Generate game art with AI → Character sprite / Item / Tileable texture / Background (or Generate with AI → Service: On this PC). You get the full picture plus an era pixel version (a .sprite.json for sprites and items, a palette-snapped PNG for tiles and backgrounds). Edit picture → On this PC edits or varies a picture you have. No key, no credits, nothing leaves the PC; Pige uses it too when no fal.ai / kie.ai key is saved. The first picture takes 1–2 minutes while the graphics card warms up; after that about 15 s each on an RTX 4070 Ti SUPER. Research, licences and timings: docs/LOCAL-IMAGEGEN.md.

Bitmap fonts

Text and UI labels can use crisp pixel fonts. Three original era fonts ship with the editor — NES 8×8, C64 8×8 and LCD 5×7 (ASCII + Latin-1) — and retro eras give new text their font automatically. Pick one in the Inspector's Font list (with a live sample), or make your own with Assets → New font (bitmap)…: the Font tool shows a grid of characters (ASCII, Latin-1, Latin Extended, Greek, Cyrillic, kana or your own), click one to draw it with the pixel tools, set baseline / line height / spacing / kerning / outline / shadow, and watch the live preview. Import from an image sheet (pick the grid and character order) or from a TTF/OTF (rendered at a pixel size and thresholded). Missing glyphs used in this project lists, per language, the characters your text and translations need that the font lacks; the Console warns about them too. Text has alignment, wrap width, colour tint, a typewriter speed (events Type text / Finish typing / Is typing) and in 3D (a camera-facing sprite). Drop a .font.json on the Scene view to make text with it, or on text to switch its font.

Audio

GameObject → Audio (or right-click → Add here → Audio) adds a Sound (2D: pans left/right and fades with distance; 3D: positional HRTF sound with rolloff, cone and Doppler), Music (a playlist with crossfades and shuffle), an Ambience zone (loops while the listener is inside), a Reverb / echo zone and an Audio listener (the camera by default — set it to the player). Drag a sound from Assets onto the scene to make a Sound, or onto an entity to give its behaviour a sound (Pickup, Platformer jump/land, Hurt, Goal, Shooter, or builtin:play-sound). The Inspector previews and auditions sounds (Audition = hear it panned from the view centre); the Scene view draws min/max ranges and zone bounds. View → Audio mixer (or the Mixer tab) has a fader, meter, mute and solo per bus (master, music, sfx, ambience, voice, ui and your own), effects per bus (filters, reverb, echo, distortion, bit-crusher), music ducking and era sound. Events have an Audio group; scripts use this.audio.play('jump', { at: this.entity }), this.sound.play() and this.game.music.crossfade(…). Sounds can be files, .sfx.json or synth presets (preset:coin) that fit the era.

Scene view controls

Pick Blender, Unity or Maya mouse navigation in Settings → Editor (or the mouse button at the top of the Scene view). Every style also accepts the gestures the others share, so muscle memory works:

Blender (default)UnityMaya
Orbit (3D)Middle-dragAlt+left-dragAlt+left-drag
PanShift+middle-dragMiddle-dragAlt+middle-drag
ZoomWheel · Ctrl+middle-dragWheel · Alt+right-dragWheel · Alt+right-drag
Fly (3D)Hold right mouse + WASD, Q/E down/up, Shift faster, wheel sets speedsamesame

Space+drag or the Hand tool (Q) pans; F frames the selection, Home frames everything; numpad 1/3/7 look from the front/right/top (Ctrl for the opposite side), 5 toggles orthographic, 0 looks through the scene's camera, and the axis widget in the corner does the same with a click. Left-drag on empty space box-selects in 2D and 3D; a right-click that doesn't drag opens the context menu.

2D physics: Arcade or Matter

Game settings → 2D physics engine picks Arcade (the default: fast, bodies never rotate — great for platformers) or Matter (rigid bodies that tumble, stack and roll, like Construct's Physics behaviour). A scene can override it in its settings. Under Matter:

  • GameObject → 2D → Physics adds a physics box, ball, polygon rock, a character, a rope, a seesaw or a ragdoll; New game → Physics playground has all of them (drag things with the mouse while playing).
  • A body's density, mass, friction, bounce, fixed rotation, bullet and collision groups are in the Inspector.
  • Add component → Joints (2D physics) (or right-click two selected bodies → Join A to B) adds rods, springs, hinges with motors and limits, welds and mouse drag; the Scene view draws them.
  • Scripts use this.entity.physics.applyForce / applyImpulse / applyTorque / angularVelocity / contacts…; event sheets have a Physics group. The Game view's Physics debug button outlines bodies, joints and contacts.

Arrange, rulers, 2D lights and effects

  • Arrange (top menu, Scene view right-click, Hierarchy right-click, and the Arrange toolbar that is always in the 2D Scene view): align left/centre/right/top/middle/bottom (Alt+A/H/D/W/V/S), distribute (Alt+Shift+H/V), line up with each other, the screen or the scene, match width/height/size, bring forward/to front (Ctrl+] / Ctrl+Shift+]), send backward/to back (Ctrl+[ / Ctrl+Shift+[), flip (Shift+H/V), snap to grid (Shift+S), lock (Ctrl+L), group/ungroup (Ctrl+G / Ctrl+Shift+G). Disabled buttons say what to select.
  • Select menu: same type, same object (Coin, Coin 2… or prefab), same layer, same tag, invert (Ctrl+I), children, parent.
  • Rulers and guides: drag out of a ruler to make a guide, drag it back to delete; dragged things snap to guides. Grid size, show grid (Ctrl+'), snap (Ctrl+Shift+'), rulers (Shift+R) and guides (Ctrl+;) are in the Scene view toolbar.
  • 2D objects (GameObject → 2D → Shapes / Backgrounds / Lights / Logic / Media, and UI): polygon, star, tiled and parallax backgrounds, 9-slice sprites (drag the margin lines in the Inspector), video, trigger zones, spawn points, Camera 2D (two active = split screen), masks, torches/lamps/flickering lights; UI checkbox, toggle, slider, text input, progress bar.
  • 2D lighting: Scene settings → Lighting 2d (ambient colour, darkness overlay); each layer has a Lit switch; the Scene view Lights button previews it. Effects (Add component → Effects): tint, blend mode and a stack of glow, outline, drop shadow, blur, pixelate and colour filters you can reorder and toggle.

Music and sound effects

Songs (Assets → New song, or New song from a template: battle, overworld, boss, title jingle, game over, victory). A song is made of sections (A, B, C…) laid out on the Song timeline at the top: click a slot to edit it, drag to reorder, right-click to repeat, make unique, or "loop the song back to here" (an intro that plays once). Edit a section in the Piano roll (click to draw, drag to lengthen, Ctrl/Shift+drag or the Select tool for a box, Alt+drag copies, double-click deletes, velocity lane below) or the Tracker (Tab switches; type notes, arrows move). Right-click notes, the grid, the ruler, track headers and sections for everything. Keys: Space plays the section, Shift+Space the song; Ctrl+C/X/V/D, Delete, Ctrl+A; ↑/↓ transpose (Shift = octave), ←/→ nudge; Ctrl+Q quantize, Ctrl+H humanize; Ctrl+R record, Ctrl+M metronome. The computer keyboard is a piano (Z–M and Q–U rows, − / = octave): with Record on it records live while playing, or step-enters at the cursor. Shift+drag the ruler for a loop region. Each track has mute/solo/volume/pan and an instrument (presets, pulse duty, wave-table drawing, noise mode, ADSR, vibrato, arpeggio, slide/glide, or a drum kit lane). Export WAV (song, looped, one section, or stems). Pige can compose a section, continue it, or write a variation.

Sound effects: pick a kind in the Library (16 kinds; the ⟳ button mutates the last one of that kind), tune grouped sfxr parameters (right-click a group to copy/paste/reset/randomize), stack up to 3 generators, use Pitch/Length for the whole sound, star sounds in the History, compare with A/B, and add variants (the game picks one at random each play) or "Make 5 variant assets". Era limits apply unless you turn on "Bend era limits". Drag a sound or song from Assets into the Scene view (or press Add to scene) for a Sound or Music object (SP-71).

Era screens and device frames (how to use)

Picking an era now shows the game the way that hardware did: a curved CRT with scanlines, phosphor mask and composite colour bleed for the TV consoles (with the right pixel aspect, e.g. NES 8:7), a ZX Spectrum's border and attribute clash, a Game Boy's pea-green dot-matrix LCD with ghosting, a dark unlit GBA screen, or a Game & Watch-style segment LCD over a printed background.

  • File → Screen & device frame… (also Game settings, and the Screen button in the 2D Scene view) has every setting with a tooltip: screen type, era colours, pixel aspect, scanlines, composite blur, mask, curvature, glow, border, attribute clash, LCD grid/ghosting/shadow, unlit screen, printed background, grain, and era defaults.
  • Device frame: draw a handheld (wide G&W-style, Tiger-style, tabletop, grey brick, wide colour) or a CRT TV round the game, with your title and colours. Its buttons are clickable and touchable (they press left, right, jump, action, pause), so exported games work on phones. The Scene view's Frame button shows it while you design.
  • LCD games: start from the LCD handheld game template, or GameObject → 2D → *LCD segment character / falling object / score / MISS counter*. A segment character has fixed poses (Inspector → Add pose here at each spot); the unlit poses stay as faint ghosts. Light one from events with Light LCD segment (a pose number or next / previous / first / last); the entity's segment variable always holds the lit pose, so events and scripts can check where it is.

Sound chips and the Amiga / PS2 / Xbox eras (how to use)

Eras now include the Amiga (OCS/ECS and AGA), PlayStation 2 and original Xbox, and every song plays on its era's sound chip: the Master System's SN76489 (10-bit periods, 2 dB volume steps, white/periodic noise — plus the YM2413 FM unit), the Mega Drive's YM2612 (6 four-operator FM voices, the DAC on FM 6, PSG on top), the SNES SPC700 (BRR samples, gaussian softness, echo with an 8-tap filter, pitch modulation), Amiga Paula (4 × 8-bit, hard L-R-R-L, LED filter), the PS1 SPU (ADPCM + reverb presets), PS2 SPU2 and Xbox DirectSound.

  • Song tool → Sound chip: pick the chip, see which hardware voice each track gets, set the echo / reverb / LED filter, or switch on Bend the era limits to play anything. Templates list your era's own song first (Mega Drive FM battle, Amiga MOD-style tune, SNES orchestral overworld, SMS PSG adventure, PS1 ambient hall, 6th-gen action).
  • FM editor: give a track the fm wave, then Make it 4-operator FM (or load a patch: slap bass, brass, lead, e-piano, orchestra hit, drums, the 15 OPLL instruments). Pick an algorithm from the diagrams and edit each operator (MUL, DT, TL, AR, D1R, SL, D2R, RR, KS) in the table; the little graphs show each operator's envelope.
  • Samples: the sample wave plays a built-in instrument (strings, piano, choir, slap bass, orchestra hit…, all made from maths) or any WAV in your project, with root note, rate and loop.
  • ProTracker .MOD: Assets → Import ProTracker MOD as a song… (or double-click a .mod), and Song tool → Export → ProTracker module.
  • SFX tool → chip presets: PSG coins, FM zaps, Paula 8-bit blasts, SNES chimes, PS1 whooshes.
  • Screens: the Amiga sits on a home-computer monitor (sharp RGB), the PS2 and Xbox on a 2000s TV (the PS2 with interlace shimmer), the Mega Drive's composite blur blends dithered stripes. PS2 3D adds bloom, motion trails and depth haze; Xbox 3D turns textures into bump maps with glossy per-pixel light (Game settings → Display → Fx).
  • Controls: Game settings → Era controller sets the buttons of a Mega Drive 3/6-button pad, SMS pad, SNES pad, DualShock, Xbox Duke / Controller S or an Amiga joystick (command input.useController).
  • New fonts: Workbench 8×8 (Amiga), Arcade Bold 8×8 (Sega) and Quest 8×12 (16-bit RPG text); new template: Amiga shoot-’em-up.

Input, players, save data and settings (how to use)

  • View → Input & controls (also Game settings → Open Input & controls) opens a tab with:
    • Actions: rows are actions, columns are keyboard / gamepad / touch, with each binding drawn as its button (pick Xbox, PlayStation, Switch, 8BitDo or generic glyphs). + adds a key or button from a list or Press a key…; Feel sets analog (0–1) or button, deadzone, hold, double tap and input buffering. Presets: platformer, twin-stick, racing, fighting (with ↓↘→ combos), menus. The Era controller card shows what the era's pad had (NES = d-pad, A, B, Select, Start), flags the rest, Fit to era trims it, Bend the era limits allows anything.
    • Players: 1–8 local players, each with a device (any, a keyboard half, a gamepad, touch); Split the keyboard; Press a button to join turns on a lobby. Live tester lights up connected controllers and the actions per player.
    • Touch layout: drag the on-screen d-pad, stick and buttons on a phone-shaped screen. Combos & sticks: motions and 2D vectors.
  • Text and UI labels can say Press {button:jump}: players see Ⓐ, ✕, Ⓑ, Space or the touch label for their own device (GameObject → UI → Button prompt). Scripts: this.input.player(2).pressed('jump'), vector('move'), value('accelerate'), combo('fireball'), rumble(0.6, 0.2); events: Input group (player pressed, held for, double-tapped, combo performed, player joined, rumble, listen for a new binding…).
  • Save data: tick the save box next to a global or scene variable (Inspector), or Save position / Stays destroyed on an entity. this.game.save('1') / Save the game / a Save point (GameObject → 2D) writes a slot; project.save sets slots, autosave (scene change / interval), version + migrations, scrambling, and the platform's cloud save. The Game view's Save data button shows every slot and the player's settings, live or stored: inspect, edit, load, delete, clear.
  • game.settings is the player's options, remembered for them: settings.setVolume('music', 0.5), language, fullscreen, effects (CRT/LCD look), shake, controls.rebind('jump'); an Options screen only needs get/set (AGENTS.md lists the keys).

RPG kit (how to use)

  • New game → Top-down RPG gives a working town (talk to the Elder with X, buy from Mags, fight slimes with Z in the cellar, open the chest, touch the boss for a turn-based battle) — or Turn-based battle for just a battle screen.
  • View → Database edits items, characters, enemies, skills, quests, shops, loot tables and dialogues (saved as data/*.json). Click a row for its form; Generate… adds era-sized rows (in a NES game: 8-letter names, small numbers); Ask Pige fills it (“make 10 potions and swords for a NES RPG”).
  • Dialogues → Open (or View → Dialogue graph) shows a conversation as nodes: drag from a node's right edge to link, right-click to add nodes, Preview to try it. Conditions like quest.slimes = "active" or inventory.key >= 1; actions give items, start quests, open shops, change scenes.
  • GameObject → 2D → RPG has the hero, NPCs, shopkeepers, chests, item pickups, database enemies, a boss, party followers, companions, quest zones and the battle controller; the Inspector picks database rows for their props.
  • While playing: Q quest log, I bag. Event sheets have an RPG group (has item, quest is…, give item, start conversation, open shop, start battle…); scripts use this.game.rpg (AGENTS.md → RPG kit).

Multiplayer (how to use)

Games can be played by 2–16 people on different screens with Flock (packages/flock, standalone like Pigeon Post).

  • Try it: File → New → Multiplayer arena (2–4 players), then Play → Play with 2 windows. The Game view hosts, a second window joins as player 2; walk with the arrows/WASD in each window and collect gems. Net stats (Game view bar) shows ping and bytes/s.
  • Make your own: Game settings → Multiplayer (max players, updates per second, host decides or each owner decides, transport). Select an entity → Add component → Multiplayer → Networked: pick its owner (Host, Each player = one copy per player who joins, or Player 1…8) and what's synced (x, y, rotation, vars.score…). GameObject → 2D → Multiplayer has ready-made networked players, UI → Multiplayer has the Host / Join buttons and code box (or Add lobby UI in Game settings).
  • Rules once: put scoring and spawning under the event condition Is the host (Multiplayer group), or if (this.game.net.isHost) in a script. Other events: On player joined/left, On network message, Host / Join / Leave, Send network message. Scripts: this.game.net.
  • On the LAN: start Play → Preview on phone; phones and PCs that open that address can type the host's code and join the editor's games. Exported web games use the relay at the address they're served from (or Game settings → Relay address). WebRTC works peer-to-peer with copy/paste codes and no server; online matchmaking (Supabase Realtime) comes with the online backend (docs/ONLINE.md → Multiplayer).
  • Know the limits: one host, no host migration; the host (or each owner) is trusted — there is no anti-cheat. Old eras cap the players at what their hardware could plug in (NES Four Score = 4…) unless you tick Bend the era limits.

Game UI kit (how to use)

  • Ready-made screens: GameObject → UI → Screens adds a main menu, pause menu (Esc / P / Start), options (volume, music, sound, fullscreen, language, controls — saved), game over (opens when lives hit 0), level complete with stars (opens on the level-complete event), HUD, dialogue box, shop and inventory (I key). They work as soon as you press Play.
  • Widgets and layout: GameObject → UI → Widgets (dropdown, menu list, tabs, dialog, tooltip, hearts, inventory slot, ring bar, minimap, toast) and → Layout (row, column, grid, scroll view). Put widgets inside a container in the Hierarchy and its Layout (gap, padding, align, fit) places them.
  • States: select a widget → Inspector → UI widget → States. Pick normal / hover / pressed / disabled / selected / focused or add a custom one (locked, new…), set its colours, text, frame, scale, offset, opacity and sound, and click the eye to preview it in the Scene view. Switch states while playing with the “Set UI state” event action or game.ui.setState(widget, 'locked', true).
  • Themes: Game settings → UI theme (or a widget's Theme, which its children inherit): NES box, SNES RPG window, Game Boy, Modern flat, PS1 menu, or Assets → New UI theme for an editable .uitheme.json. Colours snap to the era palette unless the theme sets bendEra.
  • Buttons do things with click events: open:Options, close, resume, next, menu, quit, restart, toast:Saved!, set:music=0.5, buy:potion=10, scene:Level 2 — and every click is also a custom event for event sheets and scripts. Bind sliders/checkboxes/dropdowns to settings.music, settings.sfx, settings.master, settings.fullscreen, settings.language (scripts: game.settings).
  • Keyboard and gamepad: arrows / WASD / D-pad move the focus, Tab cycles, Enter / Space / A confirms, Esc / B goes back. The focused widget shows the theme's focus (an outline, glow or a ▶ cursor).
  • Why not a DOM UI library? In-game UI is drawn by Phaser on the game canvas, like everything else: it scales with the pixel-perfect screen, goes through the era CRT/LCD pipeline, uses the era's bitmap fonts and palette, and exports unchanged to web portals, desktop and mobile. HTML overlays would sit on top of the CRT effect, blur pixel fonts and behave differently per platform.

Sushi Pigeon AI (how to use)

Settings → Pige’s AI starts with the Sushi Pigeon AI card: Claude, hosted by Sushi Pigeon — no key, nothing to download. It comes with paid plans: Bento (the Nigiri brain — quick, Claude Haiku 5.5) and Omakase (every brain: Nigiri, Sashimi — sharpest everyday, Claude Sonnet 5.5, the default — and Toro — premium, Claude Opus 5.5). Kappa (free) keeps the built-in Gemma or your own Claude / Gemini / OpenRouter key. On a paid plan it is picked automatically until you choose another AI; pick a brain on the card and the bar shows about how many requests are left this month. It isn't live yet — until Sushi Pigeon accounts exist the card says “Coming with Sushi Pigeon accounts” (dev preview: SP_HOSTED_DEMO=pro|plus|resting). Plans, brains and names are one table in src/shared/hostedai.ts; the server side is worker/ and supabase/ (see docs/ONLINE.md).

Sprite studio (how to use)

Open any .sprite.json (Assets → New pixel sprite, or double-click one). It works like Aseprite / Pyxel Edit:

  • Tools (left, with keys): Pencil B, Eraser E, Shade D (lighten along the palette ramp, right button darkens), Line L, Rect R, Ellipse O, Fill G, Select M, Lasso Q, Wand W, Move V, Pick I. Brush options: pixel-perfect strokes, symmetry X/Y, filled shapes, contiguous fill and dither patterns. Press ? for every shortcut.
  • Timeline (bottom): layers × frames. Eye / lock per layer, opacity slider, merge down; per-frame durations in ms; Shift+click frame numbers then New tag to make an animation; set its direction (forward / reverse / ping-pong). Right-click layers, frames, cels, tags and swatches for everything else (copy a cel to another frame, rename, delete…).
  • Selections: drag inside to move, Alt-drag a copy; the selection bar flips, turns, rotates (RotSprite) and scales (nearest neighbour). Ctrl+C / Ctrl+V copy between frames and between sprites. Ctrl+right-click opens the canvas menu.
  • Onion skin (⚙ for frames before/after and their tints) and the floating Preview window (real speed, zoom, mirror, 3×3 tile view).
  • Effects (right): outline (inner/outer, on its own layer), drop shadow, hue shift inside the era palette, colour variants saved as new sprites ("red enemy"), RotSprite rotation, replace colour.
  • Era limits (right, live): colours, size and palette for the project's era; Enforce era stops you going past them, Fit to era repairs a sprite (snap colours, merge to the limit, crop).
  • Import / export: Assets → Import Aseprite file (.ase/.aseprite with layers, frames, tags, durations); PNG strips (Make & import, or right-click an image → Make an animated sprite from this strip). Export a sheet PNG + JSON, an animated GIF or an .aseprite file next to the sprite.
  • Preview in game puts the sprite, playing the chosen animation, on the selected entity in the Scene view.
  • Pige and MCP can do the same through sprite.effect, sprite.variant, sprite.tag, sprite.layer and sprite.frameDuration.

Plan, Storyboard and World map (how to use)

Plan the game next to building it. Everything lives in the project as plan/*.json, so it syncs and travels with the game, and every change is undoable.

  • Plan menu → Plan opens the game design doc: Characters (portrait, bio, stats, linked sprites and prefabs), Story (acts and beats — paste an outline and press Add beats), Levels (goal, scene, status), Ideas (sticky notes; double-click the board), Tasks (To do / Doing / Done kanban) and Notes (markdown; [[Name]] links to a character, level or scene). Chips everywhere jump to what they link to.
  • Plan → Storyboard: panels with a quick sketch (in the era's palette unless you bend the era limits), a picture or a live view of the linked scene, plus caption, dialogue, shot, duration, characters and story beat. Play animatic plays it as a slideshow; PNG strip and Print / PDF export it.
  • Plan → World map: every scene is a card with a live thumbnail. Drag the ● on a card onto another card to link them — a door, two-way door, portal, level exit or random portal (weighted targets). That adds a real door entity (behaviour Door / scene exit) to one scene and an arrival spawn point to the other, so the game works straight away; doors, goals, buttons and "Go to scene" events you add in a scene show up on the map too. Regions colour areas, Room grid lays it out like a Metroidvania map, Auto-arrange sorts it from the start scene, and scenes nothing leads to are marked Can't reach. Double-click a card to open its scene. GameObject → Door / exit to scene does the same from the Scene view.
  • Welcome → Start with a plan seeds a pitch page, a three-act story, the first level, starter tasks and a panel.
  • Pige reads the plan and can add to it ("make 3 characters for my RPG", "turn this outline into story beats", "link the cave to the castle with a door") through the plan.* and worldmap.* commands (also over MCP).

Tool names (how to use)

The headline tools carry a Japanese flavour name next to their plain name: Sumi (Sprite studio, “ink”), Origami (3D Model studio), Taiko (Song), Suzu (Sound effects), Shodō (Font), Hanabi (Particles), Karakuri (Event sheets), Chizu (World map), Emaki (Storyboard), Kanban (Planner), Kura (RPG Database), Noren (UI kit / UI theme), Dashi (Audio mixer) and Koma (Timeline). Menus and search still use the plain names; the Japanese name shows in the tab, the menu hint and empty states. Hover it to read what it means. All names live in one table, src/renderer/src/toolnames.ts.

RPG progress in saves (how to use)

With the RPG kit on (View → Database), the bag, gold, equipment, party, quests and story flags are saved with every save slot and autosave automatically — no need to tick the rpg global as Saved. Saves made before 0.8 (RPG state among the globals) still load. While playing, the Inspector shows object values such as rpg as a one-line summary (gold 60 · inv {1} · party [2]…); click it to read the whole thing as JSON.

Pige's prompt budget (how it works)

Pige knows every editor command and behaviour by name (a compact index), but only sees the full argument shapes for the ones your request needs — picked from its words and from smart search. When it needs more it asks the editor (look commands audio) in the same turn. This keeps the prompt around 20K characters, so the built-in Gemma answers faster and hosted requests cost less. Sizes are checked by test/pigebudget.test.ts; results are in docs/PIGE-EVAL.md.

Store builds: installer, signing, Steam leaderboards, Mac/Linux, store listing (how to use)

  • Windows installer: Publish → Windows desktop → App: Make an installer (on by default). Build for Windows makes the portable ZIP and export/<Game>-Setup-<version>.exe (installs per user, Start-menu + optional desktop shortcut, uninstaller). Smallest installer uses LZMA: ~30% smaller, a few minutes to build.
  • Code signing: Build → Code signing: a .pfx file, a certificate in Windows / on a USB token (thumbprint), or Azure Trusted Signing. Needs signtool (Windows SDK). Settings stay in the editor's settings, never in the game folder; What do I need to buy? explains the options.
  • Steam leaderboards: this.platform.leaderboards.submit('best', score) keeps the best score on Steam; await this.platform.leaderboards.entries('best', { range: 'around' }) downloads rows (global, around, friends). Save slots' cloud copy goes to Steam Cloud.
  • macOS / Linux: Make macOS / Linux project writes export/desktop-src; on a Mac run npm install && npm run mac (set APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID to notarise), on Linux npm run linux.
  • Store listing: Publish → Google Play / App Store / Steam / itch.io → Store listing: write the pitch and privacy policy, Take screenshot from Game view a few times, then Export listing pictures → export/store-listing/<store>/ with every size plus a README checklist (age rating questionnaire, privacy, forms).

Lean exports and the size budget (how to use)

Go to Publish, pick a web platform and press Export (or Check size on the Size budget card). An export ships only the runtime parts your game uses. A 2D game leaves out Three.js, Rapier, the RPG and genre kits, multiplayer and the script compiler, and 3D and its physics load only when a 3D scene starts. The export also crushes PNGs, turns WAVs into Ogg Opus and leaves out assets that nothing uses.

The card shows:

  • total, initial, gzip and brotli sizes
  • a pass/fail line for each limit of YouTube Playables, Poki, CrazyGames, Facebook Instant Games and itch.io
  • which runtime parts are included, and why (hover a part)
  • the biggest files, with tips

Its switches are Crush PNGs, WAV → Ogg, Drop unused assets and Full runtime. They're saved as publish.lean.

For 3D games, the biggest single saving is turning off Scene → 3D physics when nothing needs rigid bodies, because Rapier is 4.3 MB. See docs/EXPORT-SIZE.md for details and measurements, and run node scripts/export-size.mjs to measure the templates again.

Learn: tutorials and help (how to use)

  • Help → Learn (or the Learn with Pige card on the Welcome screen) lists ten step-by-step tutorials of 5–10 minutes: your first platformer (through to a web export), sprites and animation, event sheets, chiptunes, sound effects and the mixer, a 3D level, an RPG town, menus with the UI kit, two-player co-op and publishing to Poki/itch/Android.
  • Each tutorial runs on a fresh practice project made from its template, so your own games are never touched. Pick a different era in the hub if you like.
  • Pige explains each step and a spotlight points at the real button. The step ticks itself off when you do it (Pige watches the project, not your mouse), then moves on. Show me does the step for you with the same commands as everything else, so Ctrl+Z undoes it. Back and Skip are always there, and your place is saved: Continue picks up where you left off.
  • A ? on the active tool tab, each dock tab and each Inspector component opens a short help card: what it is, common tasks, a Read more with the matching README section, and a button for its tutorial. Help → Help for this tab does the same.
  • Find anything (Ctrl+K) finds help topics and tutorials as well as the things in your project.
  • Tutorials and help cards are plain JSON in learn/ — see docs/LEARN.md to add your own.

Motion and the Hustle Pigeon example (how to use)

  • Play the example: Welcome screen (or Help → Learn) → Examples → Hustle Pigeon → Open. You get your own copy in the projects folder; press Play. It's a 3–10 cup shell game (SNES): watch the pea, pick the cup with the mouse/tap or arrows + Z; lifelines on keys 1–4.
  • Motion in scripts — moves you decide while the game runs (deals, shuffles, swaps, UI slides): 
    await this.motion.to(cup, { x: 120, y: 80 }, { duration: 0.3, ease: 'quadInOut', arc: 16 }) // arc bends the path; hop jumps
await this.motion.sequence().to(a, { y: 40 }, 0.2).with(b, { y: 40 }, 0.2).wait(0.1).call(() => this.audio.play('ding')).play()
this.motion.timeScale = 0.5 // slow motion for every move
    this.scene.pick(pointer.x, pointer.y, { tag: 'cup' }) finds what's under the pointer in 2D too; entity.depth changes draw order.
  • Motion in event sheets (group Motion): Move along arc, Swap places, Set motion speed, condition Is moving. The example's title screen shuffles its cups this way.
  • How it was built: node scripts/examples/hustle-pigeon/build.mjs (after npm run build:mcp) drives the MCP server — sprites, songs, SFX, particles, scenes, UI screens and events — and writes examples/hustle-pigeon.

Grid puzzles, level packs and the Mirror Pigeons example (how to use)

  • GameObject → 2D → Gameplay → Grid puzzle: Grid pusher (player), Mirror twin, Pushable crate, Goal spot. Every Grid pusher and Pushable in a scene share one turn system: arrows take a turn, Z / Backspace undoes (hold to keep going), R restarts (undoable), the move counter is {moves}. Walls are solid tiles or “solid” entities; goals are tiles with the tile property goal: true or “goal” entities. A pusher’s Mirror (x, y, xy) makes it a reflection twin; a blocked pusher stays put while the others move.
  • Game settings → Level pack: the level scenes in order, par per level (Solve works out the fewest moves with the game’s own rules), unlock rule and the 2-star rule. Import Sokoban levels (XSB) pastes standard Sokoban text (# wall, @ pigeon, $ crate, . goal, plus & twin and ~ water) and makes one scene per level from a tileset.
  • UI → Screens → Level select lists the pack with stars and locks; the Level complete (stars) screen shows the stars; progress (best moves, stars) is saved to the “progress” save slot. UI → Widgets → Puzzle HUD shows level, moves/par and an Undo button. Events: Puzzle → On puzzle solved, Undo move, Restart puzzle, Next level…; scripts: this.game.levels.
  • Mirror Pigeons (Help → Learn → Examples, or New project → Examples): Sokoban with a reflection — Coo pushes seed crates while Ooc, the pigeon across the stream, does every move backwards. 14 levels in four worlds (no twin, left/right mirror, up/down mirror, both). Rebuild it with node node_modules/vite-node/vite-node.mjs -c vitest.config.ts scripts/examples/mirror-pigeons/build.ts.

Survival kit, physics materials and the Ricochet Rush example (how to use)

  • Play it: Welcome screen (or Help → Learn) → Examples → Ricochet Rush → Open. Arrows/WASD fly Pip; one touch from a ball ends the run, Space retries, R restarts, Esc pauses. Survive 25 s to unlock the next arena; best times are kept on the device.
  • Physics materials: Inspector → Physics body (2D) → Material (or physics.setMaterial {ids, material}) sets bounce, friction, grip, air friction, density and gravity scale in one go: default, super ball (perfectly elastic), rubber, basketball, steel, stone, wood, ice, clay, balloon.
  • Behaviours (Add behaviour, AGENTS.md): Keep moving (balls that never stop: launch, keep speed in a range, optional homing), Auto-scroll camera (the view scrolls by itself; its trailing edge kills or pushes the player and under Matter the edges become moving walls that bounce hazards — give hazards their own body group), Spawn schedule (0s Red ball every 3.5s; 30s Blue ball every 12s x2 max 5, gaps shrink every level, warning marker + puff), Graze (near-miss score with combos), Survival timer (stopwatch, best time per scene, unlock a key after N seconds) and Records (menus show bests and lock buttons: Arena 2 button needs arena2 : SURVIVE 25s IN ARENA 1).
  • GameObject menu: 2D → Physics → Bouncing ball (never stops); 2D → Logic → Auto-scroll camera, Spawn schedule; UI → Survival timer (HUD).
  • Particles on a sprite/shape entity now play as a trail that follows it, and hidden (inactive) template entities no longer get physics bodies.
  • How it was built: node node_modules/vite-node/vite-node.mjs -c vitest.config.ts scripts/examples/ricochet-rush/build.ts (after npm run build) drives the MCP server and writes examples/ricochet-rush.

Dungeon crawler kit and the Crypt of Wings example (how to use)

  • Play the example: Welcome screen (or Help → Learn) → Examples → Crypt of Wings → Open, then Play. A Wizardry-style crawler for the Amiga: arrows step and turn, Q/E sidestep, X opens doors, M shows the big map, C makes camp, I opens the bag.
  • Start your own: New project → Dungeon crawler (first person), or GameObject → 3D → Gameplay → Dungeon crawler → Dungeon and First-person party (grid crawler); GameObject → UI → Widgets → Automap and Party HUD.
  • Paint the map: select the Dungeon. The Inspector has a palette (wall, floor, safe floor, start, door, locked door, secret wall, stairs, trap, chest, fountain, message, boss, exit): click or drag on the grid. Right-click a cell for its details — chest item/gold/loot, the key a locked door needs, where stairs go, a sign's text, a boss's enemies, a standing picture. It warns about stairs to nowhere, missing keys and the era's triangle budget.
  • Looks follow the era: 8-bit eras draw Wizardry wireframe lines; later eras use flat colours or your wall/floor/door textures (tick Bend era for textures on 8-bit machines).
  • Random battles: the Dungeon's Encounters (rat*2 | 2: bat, bat | skeleton) and Encounter steps (8–15) start the RPG kit's turn-based battle; a Battle scene with a grid crawler set to backdrop shows the corridor you were standing in. The party comes back to the same cell; cell, facing, explored map, doors and chests are saved with every save slot.
  • Events and scripts: the grid crawler fires step, turn, bump, door, locked, unlocked, stairs, trap, chest, fountain, sign, encounter, boss and exit (event sheets: On behaviour event); scripts call forward(), turnLeft(), teleport(x, y, 'N'). Pige and MCP use dungeon.paint, dungeon.setMap, dungeon.setCell, dungeon.resize.
  • How the example was built: node scripts/build-examples.mjs crypt-of-wings runs scripts/examples/crypt-of-wings.ts, which makes every scene, database row and dialogue with COMMANDS, draws the textures and monsters as .sprite.json, takes its songs from the Song tool's templates (on the Amiga's Paula chip) and its sounds from the SFX tool, checks every map cell is reachable, and writes examples/crypt-of-wings.

Grid runner kit and the Night Runner example (how to use)

  • Play the example: New project → Examples → Night Runner (C64). Arrows run and climb, Z/X dig left/right, R gives up a life, N on the title turns on night mode.
  • Make a grid game: paint a tilemap, then in the Tile palette right-click a tile and pick its Kind (grid games): Brick (solid, diggable), Stone, Ladder, Bar, Trapdoor. Pige/MCP: tilemap.setTileKind, and tilemap.paintRows paints a whole level from ASCII rows.
  • Add the pieces: GameObject → 2D → Gameplay → Grid runner (player, guard, gold, guard respawn point, torch). The player has Grid runner; guards add Grid chaser (BFS chase, holes, carrying gold) and Visible in light.
  • Night: turn on the scene's darkness (Scene → 2D lighting → Darkness) or use the event action Set darkness (night); give the player a Light 2D child as a lantern. Things with Visible in light only show inside a light, or flicker into view when heard.
  • Events (group "Tiles & night"): Show / hide tile layer (an exit ladder appearing), Set tile, Dig tile (refills), Is trapped, Is in light, Darkness is on, Tile kind at cell. Rebuild the example with npm run example:night-runner.