Skip to content

Latest commit

 

History

History
101 lines (67 loc) · 9.08 KB

first-project.mdx

File metadata and controls

101 lines (67 loc) · 9.08 KB
title Your first project
description Taking a project from the editor's first launch to a game you can run, with creating, opening, and saving a project and a plain game export.
sidebar
order
1

A project is a folder: its content lives under Assets/, and the editor keeps its own data beside it (.Editor/ for project settings, .Cache/ and AssetDatabase.assetdb for derived data). This page takes a project from the editor's first launch to a game you can run. Build the editor first, as BUILD.md describes.

First launch

Started without a project, the editor shows the project picker. To open the last project you used instead, turn on Auto-load last project in Settings > User Settings > Startup; it is off by default. With it on, hold Shift while the editor starts to get the picker.

The picker's home screen has a New project card, an Open project card, and the list of recent projects. Behind the picker the editor holds an empty placeholder project, the default project. It cannot become one of your projects, so the picker stays open until you create or open one.

Platform Default project folder
macOS ~/Library/Application Support/GameEngine/Editor/DefaultProject
Windows %APPDATA%\GameEngine\Editor\DefaultProject
Linux $XDG_DATA_HOME/GameEngine/Editor/DefaultProject, or ~/.local/share/... when XDG_DATA_HOME is unset

The editor opens maximized on the primary monitor. To open it at a fixed size, for example for a recording or a screenshot series, pass --window <width>x<height>+<x>+<y>. The size is the window's client area and the position is its top-left corner, both in pixels (in points on macOS). The position is optional: without it, the operating system places the window. A position on a monitor to the left of or above the primary one is negative, as in +-1920+0. The editor does not start when the value is not in this form, and the log names the form.

Editor.exe --window 1920x1080+40+40

Create a project

:::steps

  1. In the picker, choose New project. The Templates tab lists the built-in templates.
  2. Pick a template. Blank starts with a camera, a sun, a sky at mid-morning, and a horizon haze (the default height fog) in Assets/Scenes/Main.scene. Basic 3D adds a ground plane and a few cubes to the same scene.
  3. Type a name under PROJECT NAME and choose a folder under LOCATION with Browse. The location must be an existing folder. The editor creates <location>/<name> and refuses a name that already exists there. Keep projects outside the engine checkout and its build/ folder.
  4. Choose Create project. The editor opens the new project on its startup scene (see Open a project).

:::

Open a project

  • From the picker: choose a project in the recent list, or choose Open project and then Browse to pick a folder. The editor opens the folder where it is. It does not copy it. The same view can also import a project from a .zip archive or a Git URL.
  • From a running editor: the Open Project Folder button in the top toolbar, or the Open Project command in the search (Cmd+K on macOS, Ctrl+K on Windows and Linux), shows the picker. The editor switches projects without restarting.
  • From the command line: pass --project <folder>. The editor skips the picker and opens that folder, creating it if it does not exist.

Opening a project from the picker, with --project, or the last project at startup opens the project's startup scene: the first scene in the build's scene list, else the scene named by project.startupScene in .Editor/ProjectSettings.json, else the scene you last opened in that project, else a new empty scene. Creating a project from a template or a community project sets project.startupScene to the scene its game.config names, or to its only scene. When the open scene has unsaved changes, the editor asks to save them before it switches projects; Cancel keeps the current project.

project.startupScene is one top-level key, and its value is the scene path relative to Assets/. The editor does not read a nested "project": { "startupScene": ... } object: it logs a warning that names the file and the key to use, then opens the scene you last opened in that project, else a new empty scene.

{
  "project.startupScene": "Scenes/Main.scene"
}
# macOS
build/macos-arm64-local/bin/Debug/Apps/Editor/Editor.app/Contents/MacOS/Editor --project ~/GameProjects/MyGame

# Windows
build\vs2026-x64-local\bin\DebugFast\Apps\Editor\Editor.exe --project C:\GameProjects\MyGame

# Linux
./build/linux-x64-local/bin/Debug/Apps/Editor/Editor --project ~/GameProjects/MyGame

Any folder can be opened as a project: the editor creates Assets/ if it is missing.

The C# project for your IDE

The editor creates GameEngine.Scripts.csproj at the project root, beside Assets/, when the project has none. Open that file in your IDE to edit the project's C# scripts: it compiles every .cs file under Assets/ against the engine. A new file the IDE creates at the project's top level lands at the project root, outside Assets/, where nothing compiles it, so create script files inside Assets/.

The file is yours: add NuGet packages to it as in any C# project (NuGet packages), and commit it. It imports GameEngine.Scripts.Engine.props and GameEngine.Scripts.Engine.targets, which hold the engine's settings and paths specific to your machine. The editor rewrites those two files each time it opens the project: do not edit them and do not commit them, and do not commit the obj/ folder the package restore writes beside them. When an import line is missing, the editor puts it back and the Log panel says so. A deleted GameEngine.Scripts.csproj is created again, without its packages. A generated copy of the file inside Assets/ is deleted when the project opens, and the Log panel says so.

Save a scene

Press Cmd+S on macOS or Ctrl+S on Windows and Linux, or use the Save Scene button in the top toolbar. A scene that has never been saved asks for a Scene name and a Folder, starting at the project's Assets/ folder. Scenes are .scene files. Cmd+Shift+S or Ctrl+Shift+S saves under a new name.

A line in a .scene file that names a field its component does not have, such as a misspelled or removed field, does not stop the scene from loading. The Log panel names the file and the line with one message, <Component> has no field named '<field>': delete the line or correct the spelling, and the editor asks before a save drops the line.

Export your game

The editor exports a game for the platform it runs on: the macOS editor builds macOS games, the Windows editor Windows games, and the Linux editor Linux games. Publishing to Steam is in Game builds and Steam publishing.

:::steps

  1. Open the Build panel with the Build button in the top toolbar (the game-controller icon), or Window > Build.
  2. Choose Settings in the panel. Under Global scene list, drop the scenes to ship from the asset browser onto the list. The first one opens when the game starts. With an empty list, the game ships the scene the project opens with. A project with no scene at all stops with No scene to build. Game name sets the name of the exported game. Without it the game takes the project folder's name.
  3. In the platform table, turn On your platform only: Mac, Windows or Linux. Windows is on by default. The panel builds one platform at a time, the first one turned on in the table's order.
  4. Choose Build. The Progress and Done columns follow the build. The button becomes Cancel while it runs.

:::

The game goes to Build Folder/<Platform> inside the project, for example Build Folder/Mac. Build path in the panel, or Build folder in the platform's settings, chooses another folder. An absolute path still gets the platform folder appended.

Platform Output Run it
macOS <Game name>.app, with the game's content inside the bundle Open the .app from Finder, or open "Build Folder/Mac/<Game name>.app"
Windows <Game name>.exe, game.config, and the game's content Run the .exe
Linux <Game name>, the engine's .so libraries, game.config, and the game's content Run ./<Game name> in Build Folder/Linux

A build replaces the previous output folder only when it has succeeded. Until then the previous output is kept. When the folder cannot be replaced, for example because the previous game is still running, the build stops with an error that names the folder. Game builds and Steam publishing explains how the output is replaced, and how to prepare, verify, and upload a release.