Manual
Manual
Your first project
Make a game from a template in the Hub, open it in the editor and press Play. This page also explains what each folder of a project holds.
Create a project
- In the Hub, click Projects, then New Project.
- Under Editor version, pick the editor to make the game with. If you have none yet, see Install an engine version.
- Pick a template from the cards. Search templates finds one by name, kind or keyword.
- Type a Project name.
- Under Location, pick the folder your project's folder is made in. It starts as
source/abyssin your home folder, and the line under it shows the full path. - Pick Version control: None, or Git, which makes a Git repository whose first commit is the template's files. Git uses the
giton your computer and the name and email it is set to. - Click Create Project.
The Hub copies the template into a folder named after your game, adds it to Projects, and opens it in the editor you picked. The template's own name, StarterGame, becomes your game's name in file names and text, in each form it takes: for Space Race, Space Race, SpaceRace, space-race and space_race.
The templates
Every editor carries two templates of its own:
| Template | What it starts with |
|---|---|
| 3D Game | A scene, Main, with a Main Camera and a Directional Light. Its packages are Physics 2D and Physics 3D. |
| 2D Game | A scene, Main, with a Main Camera that is a 2D camera, for sprites. It opens in the Scene panel's 2D view. Its package is Physics 2D. |
After these come the templates on abyssengine.net that work with the editor you picked. A free one you do not own yet is added to your My Assets as the game is made, which needs you signed in (Sign In to Get). One for sale shows its price, and its button opens its page on the website. The Hub keeps each template it downloads, so the next game made from it downloads nothing.
What is in a project folder
A project is a folder with one C# project file in it. For a game called SpaceRace:
| Path | What it holds |
|---|---|
SpaceRace.csproj | The game's C# project. It names the engine version: <Project Sdk="AbyssEngine.Sdk/0.4.0" />. |
SpaceRace.slnx | A solution listing the game's project and each package's, for your code editor. Each build writes it. |
assets/ | Everything the game ships that is not code: scenes, prefabs, models, images, sounds, materials. Beside each file is a .abyss sidecar holding its identity and import settings. |
scripts/ | The game's C# code. |
shaders/ | The game's own shaders, if it has any. |
settings/ | The project's settings as JSON files, such as project.json (the engine version that last opened it), build.json (the scenes in the build), player.json and packages.json (the packages the game uses). |
packages/ | The packages installed in the game, a folder each. |
rust/ | The game's own Rust code, if you add any. |
web/ | Scripts and files for the page a web build plays on, if any. |
cache/ | What the editor imported, and what it remembers for you, such as where the Scene view was looking. |
builds/ | What a build writes, a folder per platform. |
bin/, obj/ | .NET's build output. |
Keep assets/, scripts/, shaders/, settings/ and your own packages in version control, sidecars included. The rest is made again when needed, and is already left out: the template's .gitignore covers bin/, obj/ and the Cargo.toml and Cargo.lock a build writes, and the editor gives cache/ and builds/ a .gitignore of their own. It also writes packages/.gitignore to leave out the engine's own packages, which every build puts back from settings/packages.json; any other package, or one you changed, stays in.
See Assets, identities and addresses for how the editor tracks each file.
Open the project in the editor
New Project opens your game for you. After that, open it from Projects in the Hub: click Open on its row. The three-dot button on the row has Open With (another installed version), Show in File Manager and Remove from List. Add lists a game folder that is already on your computer.
As the editor starts, it builds the game's scripts, putting back the packages settings/packages.json lists, and opens the first scene of the build: Main, for a template. After that, it opens on the scene that was open when you closed it, with the Scene view where you left it.
If the project was last opened by another engine version, the editor asks whether to open it in this one or quit. Opened, the project names this editor's version from then on, as it does after Open With in the Hub.
Press Play
- Click Play at the top of the editor, or press Ctrl+P.
- The game runs in the Game panel, the tab beside Scene, seen through the cameras in its scene: the template's Main Camera.
- Press Ctrl+P again, or click the button again, to stop.
While the game plays, paused included, the editor is tinted dark orange. Changes you make then do not last: stopping puts the scene back as it was before you pressed Play. Each Play starts your game's C# afresh, as a built game starts.
Add something to the scene
- Choose Entity ▸ 3D Object ▸ Cube. In the 2D template, choose Entity ▸ 2D Object ▸ Square. It is made at the origin, which the template's camera looks at, and appears in the Hierarchy, picked.
- Press W for the Move tool and drag the arrows in the Scene panel to move it, or type a Position in the Inspector.
- Press Ctrl+S to save the scene.
- Press Ctrl+P. The Game panel shows what you made.
Ctrl+Z takes back each change you make, one at a time, and Ctrl+Y puts it back. See The editor's windows for what each panel does.
Edit the code
Your game's C# is in scripts/. A template has one file, Program.cs:
namespace SpaceRace;
public static class Program{ [STAThread] public static int Main(string[] args) => AbyssGame.Run(args);}The engine's source generator writes AbyssGame into every game. The editor and a built game start your game themselves, so this Main is only what dotnet run uses to play it from its folders.
To work on code:
- Open
SpaceRace.slnxin your code editor, or double-click a script in the editor's Project panel. A script opens in the program your system opens.csfiles with. - Save your change and come back to the editor. It builds and loads your scripts again, with the scene as it was. File ▸ Refresh (Ctrl+R) does the same at once.
- Messages from your code, and errors from building it, appear in the Logs panel. Scripts that do not build leave the last ones that did loaded.
You can also build from a terminal: once an editor has run on the computer, dotnet build and dotnet run work in the game's folder, as the editor makes its engine packages available to .NET.
Next steps
- Entities, components and systems: the data model your game is made of.
- C# in a game: writing components, systems and plugins.
- Scenes and prefabs: saving, loading and reusing parts of a game.
- Rust in a game: adding Rust beside the engine.
- Build and run your game: making something players can run.
