Your First Project

A Lumina project is separate from the engine source. Each project is a small C++ module that links against the engine build shared by every project, and loads at runtime. You do not copy template files by hand. The editor scaffolds the project, fills in its name and identifiers, and generates its project files for you: a Visual Studio solution on Windows, a compile_commands.json on Linux.

The project browser

When the editor starts without a project, it opens the Open Project browser. This is what you see the first time you run the engine from Installation. From here you can create a new project, reopen a recent one, or browse for an existing .lproject file.

Create a project

1. Click “Create New Project”

   This opens the New Project dialog.

2. Pick the template and name the project

   The only template is Blank Project (C++), an empty C++ module with C# scripting wired up.

   Enter a project name. It becomes your module name and a C++ identifier, so it must start with a letter or underscore and contain only letters, digits, underscores, or hyphens (64 characters max). For example, MyGame.

3. Choose a location

   Set the folder the project will be created in, then click Create Project.

   The editor copies the Blank template into <Location>/<Name>, fills in the project name, a new GUID, and your engine path, then runs LuminaBuildTool to generate the project files. On Windows that is <Name>.sln; on Linux it is a compile_commands.json in the project root. Watch the editor’s output log for progress.

4. Open it

   On Windows, when the Project Created dialog reports the solution is ready, click Open Solution. The engine editor closes and <Name>.sln opens in Visual Studio.

   On Linux there is no solution to open. Open the project folder in your editor of choice, which will pick up the generated compile_commands.json for completion, and build from a terminal as below.

Build and run your project

Windows

1. Press F5 in your project’s solution

   The configuration defaults to Development Editor, on the x64 platform.

   Note

   The first build of a project also builds the matching engine libraries if they are missing. That is a one-time cost handled automatically by a prebuild step; later builds reuse the cached libraries.

2. The editor launches with your project loaded

   F5 compiles your game module into a DLL and starts the editor with your project open. Breakpoints in your game module hit as soon as it loads.

From now on, F5 in your project’s solution is your full build-and-run loop. The engine’s own Lumina.sln is only needed to work on the engine itself.

Tip

Rider users: the template ships .run/Launch Editor.run.xml and .run/Launch Editor (Debug).run.xml. Pick one from the configuration dropdown next to the Run button.

Linux

Run these from anywhere; -Project is what ties them to your project.

1. Build

   "$LUMINA_DIR/LuminaBuild.sh" Build MyGame -TargetType=Editor -Project=/path/to/MyGame

   Note

   The first build of a project also builds the matching engine libraries if they are missing. That is a one-time cost: the engine target is declared as a requirement of every game target, and its output lives in the engine tree and is shared by every project.

   This compiles your game module into Binaries/Linux64/libMyGame-Development.so inside your project.

2. Run

   "$LUMINA_DIR/LuminaBuild.sh" Run MyGame -TargetType=Editor -Project=/path/to/MyGame

   A game target builds a library rather than an executable, so Run does what F5 does on Windows: it launches the engine editor with --Project already pointed at your project. That is declared by the target rules, so both routes launch the same thing.

From now on, those two commands are your full build-and-run loop. The engine’s own targets are only needed to work on the engine itself.

Tip

To debug, run the editor under gdb with the same arguments the target rules use: gdb --args "$LUMINA_DIR/Binaries/Linux64/Lumina-Development" --Project=/path/to/MyGame/MyGame.lproject. Breakpoints in your game module resolve once it loads.

Project layout

MyGame/
├── MyGame.lproject          Project descriptor (name, GUID, version, plugins)
├── GenerateProject.bat      Regenerate the .sln after adding or removing modules or plugins
├── GenerateProject.sh       The same on Linux, writing compile_commands.json instead
├── .run/                    Rider run configurations
├── Config/
│   └── GameSettings.json    Per-project settings (startup maps and project settings)
├── Source/                  Your C++ module
│   ├── MyGame.Build.cs      Module rules (dependencies, defines, include paths)
│   ├── MyGame.Target.cs     Target rules (launch module, project to open)
│   └── MyGameModule.cpp/.h
├── Plugins/                 Project-local plugins
└── Game/
    ├── Content/             Assets, mounted as /Game/Content in the editor
    └── Scripts/             C# scripts (.cs) + the project's script .csproj

A generated Intermediates/Reflection/ folder appears after the first build. It holds generated reflection code and should not be edited.

MyGame.Build.cs is where you add engine or third-party dependencies. See Build System for what those rules files can express.

The editor

When the editor opens with your project, you will see these main panels.

• Scene Outliner lists every entity in the active world.
• Viewport is the 3D view of the world.
• Details shows the components on the selected entity. Every field is generated from the reflection system.
• Content Browser shows your project’s assets from Game/Content/. Toggle it with Ctrl+Space.
• Output Log shows engine and script logging. Toggle it with Ctrl+J.

Viewport controls

Action	Control
Fly the camera	Hold right mouse, then WASD
Adjust fly speed	Mouse wheel while flying
Frame the selection	F
Select an entity	Click it in the viewport or outliner
Add / range select	Ctrl-click / Shift-click
Move / rotate / scale gizmo	W / E / R (Spacebar cycles)
Toggle world / local space	X
Undo / redo	Ctrl+Z / Ctrl+Y

Use the toolbar’s Play or Simulate buttons to run the world. Simulate runs physics and scripts in place; Play duplicates the world and switches to it. Stop returns to the editor world.

Iterating

Change	What to do
Edit a .cpp or .h	Windows: press F5. Linux: re-run LuminaBuild.sh Build, then Run. Either rebuilds the game module and relaunches the editor.
Add a new .cpp or .h	The same. Sources under your module are discovered at build time, so nothing needs regenerating to compile them. Run GenerateProject.bat / GenerateProject.sh when you want your editor’s file list or completion to catch up.
Edit a C# script	Save the file. Scripts recompile and hot-reload in the running editor.
Import an asset	Drop the file into Game/Content/. It appears in the Content Browser.

Note

Prefer the command line? You can also scaffold a project by copying Templates/Blank/ yourself and running its GenerateProject.bat or GenerateProject.sh. The editor’s Create New Project does exactly this, so it is the recommended path. Every generated project ships both scripts, so a project created on one platform still works on the other.

---

You have a project building and the editor running. Continue to the Manual to learn about entities, components, and scripting.