Skip to content

Your first scene

This guide takes about ten minutes. It starts from an empty Project: on the Dashboard, click New Project, give a name under Its name, and click Make it.

Everything here can also be asked of the Agent. Doing it once by hand shows what the Agent works with.

The editor opens on level one, main.scene, which is empty. The camera, Main Camera, is in the shared scene, shared.scene, which Play loads once and keeps across levels. Keep it the only camera: a level needs none of its own, and with two the game does not decide which one shows. Both are in the Assets panel.

WhereWhat
LeftHierarchy: the entities of the scene, parents containing their children
CentreScene: the scene as authored. Game: the running game, during play. Code: the open scripts, there while one is open. Gamedoc: what the game is to be (The Gamedoc)
RightInspector: the components of the selected entity. Agent: what was asked of the Agent
BottomAssets: the files of the Project, in front the first time the editor opens and after Reset Layout. Console: messages. Scripts: its scripts. Timeline: the keys of an animation (Clips)
TopMenus and the path of the scene; Play, Pause and Step in the middle; tools and the Members who are here
  1. Click the + button in the toolbar (or Entity › Create › Empty Entity, or Shift+Mod+N). An entity named “Entity” appears in the hierarchy, selected, with its name ready to type over.
  2. Type Coin, press Enter. Escape keeps “Entity”; F2 renames it later.

An empty entity has a name and nothing else. What it is and does comes from its components.

Mod is Cmd on macOS and Ctrl elsewhere.

A new Project has no pictures yet, so bring one: any small PNG on your computer.

  1. Drag the file from your computer onto the editor, or, in the Assets panel, click + New and Import files…, and choose it.
  2. Select Coin. In the inspector, open Add component and choose Texture. A Sprite section appears as well: Texture requires Sprite, so the editor added both.
  3. Drag the picture from the Assets panel onto Source, under Texture.

The picture appears in the Scene view with its corner at the origin, where the two bright grid lines cross.

  1. Add component → Position. Move handles appear on the entity.
  2. Drag the red arrow to move along X, the green one along Y, or the square in the middle to move freely. Or type into X and Y in the inspector.
  3. Add component → Anchor makes the picture sit centred on its position instead of hanging from its corner.
  4. Add component → Tint, then pick a colour.

Which of two pictures is in front is their Position’s Z: the higher one; of equal Z it is usually the one made later, so give each its own Z where it matters. A child’s Z is added to its parent’s.

In the Scene view: the mouse wheel zooms, dragging with the middle button (or with Space held) pans, and F frames the selection. W, E, R switch between the move, rotate, and scale tools. The tools are in the Scene view’s top right corner: select, move, rotate and scale, then local axes and snap.

Every change is one undo step. Mod+Z takes back the last one, Shift+Mod+Z redoes it.

  1. Create a second entity and name it Coins.
  2. Drag Coin onto Coins in the hierarchy. It becomes a child of Coins and will move, turn, and scale with it. Drop on the top or bottom edge of a row instead to reorder without changing the parent.

The keyboard does the same: Alt+Up and Alt+Down reorder, Shift+Alt+Right moves an entity into the one above it, Shift+Alt+Left moves it out of its parent.

There is no save step. Every change is written to the Project as you make it, and reaches the other Members at once.

Press Play in the middle of the toolbar, or Mod+P.

The Game panel comes to the front and the game runs. The hierarchy and the inspector now show the running game, with live values.

  • Pause freezes the game. Step One Frame advances it by one frame. Resume lets it run again.
  • You can change values in the inspector while it runs, to try something out. These changes are not kept: the inspector says so, and they are gone when play stops.
  • Click the Game view to give the game the keyboard; Escape hands it back to the editor.

Press Stop. The Scene panel returns with the scene exactly as you left it, and your undo history is intact.

Nothing moves yet: the coin has a picture and a place, and no behaviour. That is what scripts are for.

A script is a TypeScript file that defines one component or one system. A component is data on an entity; a system is what runs every frame and works on the entities that have certain components. A script is part of the game as soon as it is saved.

  1. Open the Scripts panel, click New and choose Component. Type spin and press Enter. The script is made, and the page loads anew: a new component does that.
  2. Double-click spin.component.ts in the Scripts panel. The Code panel shows it: a component named Spin with one field, value.
  3. Select Coin, and Add component → Spin. Its Value field is in the inspector.

What turns the coin is a system that reads Spin: New › System in the Scripts panel makes one to fill in. The Code panel completes names as you type, shows a name’s type when you hover over it, and marks what TypeScript does not take. Mod+S there saves the script.

Numbers the whole game shares, such as how fast every coin turns, are Settings: New › Settings makes their script. Once the page has loaded again, File › Project Settings… shows them under This Project to change, and Open script opens the script where their fields are written.

What to write in a script is the Engine section’s subject: start with Concepts, then Systems and Queries. Or ask the Agent for it: “make the coin spin”.