Projects and templates

Every NEO game is a project: a folder with a neo.toml project file at its root. The Studio always has one project open, and every new project starts as a copy of a template. This page covers what's in a project, how to make and switch projects, and where the Studio keeps them.

What's in a project#

A project made from the GASP template looks like this:

my_game/
├── neo.toml          the project file: plugins, their settings, the [script] manifest, [project]
├── scene.json        what you added and moved in the Studio (written once you edit the scene)
├── README.md
├── assets/           the project's own content: imports land here (scripts go in assets/scripts/)
├── media/icon.png    the game's icon
└── crates/
    ├── my_game_game/     the game itself (Rust)
    └── my_game_editor/   the editor with the game built in

neo.toml#

neo.toml is the project file. It has three kinds of section:

A new project also gets a [project] section recording where it came from:

[project]
name = "my_game"
title = "My Game"
template = "gasp"
assets = "assets"          # the project's own content
shared_assets = "<path>"   # the template's content, relative to the project

The game compiles neo.toml in and reads it as is. The Studio edits it in place and keeps your comments: the Plugins panel, for example, writes [plugins] and [plugin.<id>] for you. You can also open and edit it in Source mode.

scene.json#

scene.json sits next to neo.toml and records what you did in Scene mode: the objects you added with + Add and the moves you made to the game's own objects. The same file is used by the browser Studio, the desktop Studio and the game itself, wherever it runs. See Scene and objects.

Content#

A project has its own assets/ folder and reads the template's content under it, by reference rather than as a copy. When the game asks for a file, it gets the project's copy if there is one, otherwise the template's. So a file you put at the same path in your own assets/ replaces the template's file, and everything else comes from the template. Imports from the Assets panel go into your project's assets/.

The templates#

Project ▾ ▸ New Project… shows the templates the Studio offers, each as a card with its name and description. GASP, the NEO engine's GASP template, is selected by default and marked "default".

A project made from the GASP template is a small, complete game built on the engine's gameplay kit:

• a third-person character with movement, sprinting, crouching, jumping and traversal (vault, mantle, hurdle), physical animation and ragdolls;
• a traversal course to play it on, with other characters to meet;
• the orbit camera and keyboard, mouse and gamepad controls (click to capture the mouse, Esc to release it, Backspace to reset);
• footsteps and ambient sound, and a sun.

The character, input, camera and audio aren't copied into the project: they come from engine crates, so a project picks up engine fixes. See Gameplay kit and Samples and templates.

Make a new project#

1. Open Project ▾ and choose New Project… (it says "from a template").

2. Fill in the New Project dialog:

   Field	What it does
   Name	The project's name. A live hint shows the folder and crates it will create, or why the name doesn't work.
   Title	Optional. The name people see. Left empty, it's made from the name.
   Location (in the workspace)	The folder the project goes in. Default projects.
   Template	The template to copy. GASP is selected by default.

3. Choose Create. The dialog then shows "title is ready", the folder and crates it made, and how many files it copied.

4. Choose Switch to it to open the project, or Done to stay where you are. The new project is in the Project ▾ menu either way.

Name rules#

A project name:

• uses lowercase letters, digits and _ only, and starts with a lowercase letter (my_game);
• has at most 32 characters, and no trailing or double _;
• isn't reserved: neo, bevy, any name starting with neo_ or bevy_, xtask, editor, engine, plugins, test, tests and target are refused;
• isn't already used by another project in the workspace.

The name becomes the project's folder, its crate names (my_game_game, my_game_editor) and the game's command namespace, and the default title is made from it.

Switch projects#

Project ▾ lists your workspace under "Projects in this workspace". The open one is checked and marked "open"; the others say "switch". Pick one to open it.

In the browser Studio, switching saves everything, then reloads the page on the new project, because each project runs its own game. On the desktop, switching builds the other project's editor, starts it and closes the current one. The command editor.project.switch {name} does the same.

Where your projects are saved#

In the browser, every file save writes to the project store and the page persists it to IndexedDB. A save still on its way when the page goes away (a reload right after a save) is kept and finished on the next load, and a project switch waits until every write is stored.

Commands#

Next steps#

• Scene and objects
• Source mode
• Plugins and neo.toml
• Samples and templates