Command-Line Interface#

The lychsim command-line tool manages Unreal projects, launches them in the background, and inspects running instances – so you don’t have to drive subprocess.Popen by hand. Run lychsim --help to list every subcommand, or lychsim <command> --help for per-command flags.

The subcommands are grouped by workflow:

Lifecycle#

lychsim run#

Launch a registered UE binary or .uproject in the background and print its ip:port once UnrealCV is listening.

lychsim run                          # arrow-key picker over registered envs
lychsim run MyProject                # launch a registered env by name
lychsim run MyProject --port 7777    # pin the UnrealCV port
lychsim run MyProject --offscreen    # render off-screen (-RenderOffScreen)
lychsim run MyProject --map MyLevel  # open a specific level
lychsim run MyProject --extra-arg=-vulkan --extra-arg=-windowed

Multiple instances can run side-by-side; lychsim auto-bumps each new instance’s port so they don’t fight over unrealcv.ini.

lychsim ps#

Show running LychSim instances. Stale entries (pid dead or exe mismatch) are reaped before listing.

lychsim ps
lychsim ps --json     # machine-readable

lychsim logs#

Print or follow a launched instance’s redirected UE log.

lychsim logs <handle>            # last 50 lines
lychsim logs <handle> -n 200     # last 200 lines
lychsim logs <handle> --all      # entire log
lychsim logs <handle> -f         # follow (tail -f)

The <handle> is the value shown in the HANDLE column of lychsim ps.

lychsim stop#

Terminate a running instance by handle, or all of them with confirmation.

lychsim stop <handle>
lychsim stop all              # prompts y/N
lychsim stop all -y           # skip the prompt
lychsim stop all --dry-run    # show what would be killed
lychsim stop <handle> --grace 10  # SIGTERM, then SIGKILL after 10s

Data Capture#

lychsim capture#

Snapshot a running scene’s visuals and annotations to disk. The simulation is paused (so physics and animations don’t drift between requests), the standard outputs are captured, then the simulation is resumed – even on error.

lychsim capture ./snapshot
lychsim capture ./snapshot --host 127.0.0.1 --port 7777
lychsim capture ./snapshot --cam-id 1
lychsim capture ./snapshot --width 1920 --height 1080 --warmup 100
lychsim capture ./snapshot --no-pause   # if the scene is already static

Output layout:

output_dir/
    lit.png
    seg.png
    depth.npy
    normal.png
    object_annots.json
    camera_annots.json

The camera annotations JSON is augmented with an fxfycxcy intrinsics field derived from the FOV and film size.

Note

Connecting via the wrapper resizes camera 0’s film size to --width x --height (default 1920 x 1080). If you are capturing camera 0, that matches the flag. If you are capturing a different camera and care about camera 0’s resolution, leave the defaults alone or pick values matching the running instance.

Registries#

LychSim keeps two configuration registries under $LYCHSIM_HOME:

  • env – registered projects and shipped binaries (a .uproject, an .exe/.sh, or a directory containing either).

  • engine – UE installs (e.g. 5.4, custom-build).

lychsim env#

Manage registered UE projects and binaries.

lychsim env                                      # list registered envs (default)
lychsim env list --json
lychsim env add /path/to/MyProject.uproject      # auto-named from the path
lychsim env add /path/to/Demo --name demo        # custom name
lychsim env remove <name> [<name> ...]

lychsim engine#

Manage UE engine installs. Auto-discovery covers the common installation locations on each platform; use add for custom builds.

lychsim engine                          # list discovered + registered engines
lychsim engine add 5.4 /path/to/UE_5.4
lychsim engine remove <name> [<name> ...]

Diagnostics#

lychsim doctor#

Run sanity checks across the install: registered env paths, engine discovery, GPU presence, default port availability, LychSim plugin enablement.

lychsim doctor
lychsim doctor --verbose    # include passing checks
lychsim doctor --json       # machine-readable

A non-zero exit code indicates one or more failed checks.