Command Line¶

The editor accepts a few launch options, so that scripts and training setups can open a project and scene directly, start the gRPC server without clicking through the editor, and choose the ports of the built-in MCP server. This page lists those options, how the editor checks them, and the exit codes it returns.

In short

Pass a project file, then --scene to open straight into a scene and --server to start the gRPC server once the scene has loaded. --mcp chooses the MCP server's ports. An unknown or repeated option stops the editor before it opens, with exit code 2. There is no headless mode. On Windows, redirect the editor's output to a file to read --help, --version or an error message.

Usage¶

LuckyEngine [options] [project.hproj]

Run the editor from a terminal: on Windows, LuckyEngine.exe in the folder you installed or extracted Lucky Engine to; on Linux, the AppImage, for example ./LuckyEngine-2026.3-Linux-x64.AppImage. In the generic examples on this page, LuckyEngine stands for either.

Options start with --, or with a single -. Give a value after a space or an equals sign: --scene Main and --scene=Main are the same.
Pass at most one project file. Options and the project file can come in any order.
Everything after a lone -- is read as a path, which is how to pass a path that starts with -.

The usage line that --help prints also mentions luckyengine:// links. Your browser uses these to return you to the editor when you sign in. You don't pass them yourself.

macOS

This page covers the Windows and Linux editor. Launching the experimental macOS app bundle with options isn't covered.

Options¶

Option	Description
`project.hproj`	The project to open. A relative path is resolved against the working directory. The file must exist. Without a project, the editor opens the project you used last, or the bundled Welcome project.
`-C DIR`	The editor's working directory. A relative project path is resolved against it. The folder must exist.
`--scene NAME_OR_PATH`	The scene to open instead of the project's start scene. The editor also skips the Welcome screen and opens straight into the editor. See Choosing the scene.
`--server`	Starts the gRPC server once the project and its startup scene have loaded. See Starting the gRPC server.
`--mcp PORT`	The TCP port of the editor's MCP server, from 1 to 65535. The default is 19330. The editor also skips the Welcome screen.
`--mcp-http PORT`	The HTTP port of the MCP server. Needs `--mcp`, and must differ from it. The default is the `--mcp` port plus one, or 19331 when neither option is given.
`--help`, `-h`	Prints the usage line and the option list, then exits.
`--version`	Prints the editor's version and build details as one JSON object, then exits.

--help and --version don't open the editor window and don't need a graphics device. They can't be combined with a project file or with other options. The list that --help prints includes a few options for specialised tooling that this page doesn't cover.

The MCP server runs whenever the editor is open, on this computer only. To connect an AI assistant to it, see AI Assistants (MCP).

Choosing the scene¶

--scene looks for the scene in the project that opens:

A scene whose path, relative to the project's Assets folder, or whose file name matches exactly: Scenes/Main.hscene or Main.hscene.
Otherwise, a scene whose name matches, ignoring case, with or without the extension: main or MAIN.hscene.

Give the scenes you open this way unique file names: if two scenes in different folders have the same file name, --scene can open either of them, even when you pass the path. If nothing matches, the editor logs an error and opens the project's start scene.

Starting the gRPC server¶

--server starts the gRPC server as soon as the project and its startup scene have loaded, on address 127.0.0.1 and port 50051, the defaults of the gRPC Server panel. Like the panel's Start Server button, it also turns on the External Action Gate for the loaded scene.

--server doesn't press Play. Your client enters Play mode over gRPC, or you press Play in the editor. It doesn't skip the Welcome screen either, so add --scene to land in the viewport.

There are no options for the gRPC address or port. To run the server elsewhere, change Address and Port in the gRPC Server panel and start it from there. The gRPC API page covers the server, the action gate and the clients.

Examples¶

Open a project and scene¶

Replace the folders with your own.

LinuxWindows (PowerShell)

cd ~/LuckyEngine        # the folder you extracted the AppImage to
./LuckyEngine-2026.3-Linux-x64.AppImage ~/Robots/MyRobot/MyRobot.hproj --scene Main

cd C:\LuckyEngine       # the folder you installed Lucky Engine to
.\LuckyEngine.exe D:\Robots\MyRobot\MyRobot.hproj --scene Main

The same launch with -C, so that the project path is relative:

LuckyEngine -C ~/Robots/MyRobot MyRobot.hproj --scene Main

Launch for training over gRPC¶

Open the project on its training scene and start the gRPC server, ready for a client:

LinuxWindows (PowerShell)

./LuckyEngine-2026.3-Linux-x64.AppImage -C ~/Robots/MyRobot MyRobot.hproj --scene Training --server

.\LuckyEngine.exe -C D:\Robots\MyRobot MyRobot.hproj --scene Training --server

The editor opens on the Training scene and starts the server on 127.0.0.1:50051. Connect your client, enter Play mode from it, and step the simulation as described in gRPC API.

Run more than one editor¶

Each editor runs its own MCP server. When you run several editors at once, give each additional editor its own --mcp port, so that an AI assistant reaches the editor you mean:

LuckyEngine -C ~/Robots/SecondRobot SecondRobot.hproj --mcp 19340

This editor's MCP server listens on TCP port 19340 and HTTP port 19341. If both editors also need a gRPC server, start the second one from its gRPC Server panel with a different Port.

Reading output and exit codes¶

--help and --version write to standard output. Errors are written to standard error.

LinuxWindows (PowerShell)

Output appears in the terminal. The shell variable $? holds the exit code:

./LuckyEngine-2026.3-Linux-x64.AppImage --version
./LuckyEngine-2026.3-Linux-x64.AppImage --scene Main MyRobot.hproj; echo "Exit code: $?"

On Windows, LuckyEngine.exe is a desktop application. It doesn't print to the console you start it from, and the shell doesn't wait for it to exit. To read its output and exit code, start it with Start-Process, wait for it, and redirect its output to files:

$p = Start-Process -FilePath .\LuckyEngine.exe -ArgumentList '--version' `
        -Wait -PassThru `
        -RedirectStandardOutput version.json -RedirectStandardError errors.txt
$p.ExitCode
Get-Content version.json

If the editor doesn't open when you launch it with options, run the same command this way, with your options in -ArgumentList. The reason is in errors.txt.

Errors¶

The editor checks the whole command line before it starts. It stops, without opening its window, when:

an option is unknown or repeated, an option is missing its value, or an option that takes no value is given one (--server=1);
more than one project file is given;
the project file or the -C folder doesn't exist;
an --mcp or --mcp-http port is outside 1 to 65535, the two ports are equal, or --mcp-http is given without --mcp;
--help or --version is combined with a project file or other options.

It writes one line of JSON to standard error. The status field is failed, exit_code repeats the exit code, diagnostic_code names the problem (for example invalid_arguments or missing_project), and message explains it.

Upgrading from 2026.2

Earlier versions ignored options they didn't recognise, and accepted --headless without acting on it. 2026.3 rejects unknown options with exit code 2 and --headless with exit code 3, so remove them from your launch scripts. The editor executable is also renamed: on Windows, launch LuckyEngine.exe instead of LuckyEditor.exe.

Exit codes¶

Code	Meaning
`0`	Success: `--help` or `--version` finished, or the editor was closed normally.
`2`	The command line is invalid. See Errors.
`3`	The requested mode isn't supported: `--headless` or `--unattended`.
`4`	The editor failed while starting up.
`5`	The editor stopped because of an error while running, for example after losing the graphics device.
`6`	The editor couldn't write its output.

No headless mode¶

The editor always opens its window and needs a GPU that meets the requirements. --headless and --unattended are rejected with exit code 3, and no editor starts.

Where to go next¶

gRPC API covers driving a running simulation from Python or any other language.
AI Assistants (MCP) covers connecting an AI assistant to the editor.
Get Started covers installing the editor and its requirements.