Installation

There are two installation paths, and which one is yours depends on whether you are using NameFrame or developing it. If you received a release bundle, use the bundle. The source checkout below it is for contributors.

Commercial Preview bundle#

This is the path for evaluators and customers. The bundle is immutable and self-contained: the installer verifies it before it changes anything on the machine, and installs Python dependencies from the wheels inside it rather than from the network.

Unpacked, a bundle contains:

NameFrame/
├── bundle_manifest.json         every file with its size and SHA-256
├── install_windows.ps1          the installer
├── payload/python/              the built wheel and an offline wheelhouse
├── payload/unreal/NameFrameCapture/   the Unreal plugin
├── sample/                      the Golden Pilot project
├── compatibility/               the verified engine and Python tiers
├── GOLDEN_PILOT_WORKFLOW.md
└── EXTERNAL_PILOT_EVIDENCE.md

Requirements for the current bundle:

• Windows
• The Python version recorded in bundle_manifest.json; the product minimum is 3.11, and 3.11 and 3.12 are the versions CI verifies
• Unreal Engine 5.8 for the current verified tier, if you are installing the plugin

Look before you install. A dry run reports every action without touching the machine:

.\install_windows.ps1 -DryRun `
  -UnrealProject C:\Projects\Pilot\Pilot.uproject `
  -InstallPlugin

Then run it for real:

.\install_windows.ps1 `
  -UnrealProject C:\Projects\Pilot\Pilot.uproject `
  -InstallPlugin

Other lifecycle switches: -Repair reinstalls from the same bundle, -UninstallPlugin and -UninstallPython reverse the install, -SkipSmoke skips the post-install check, and -LogPath writes a transcript you can attach to a support request.

Developer source checkout#

Use this only when developing NameFrame itself. Requires Python 3.11 or newer; it pulls in numpy, opencv-python and pyyaml, all permissively licensed.

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

On macOS or Linux, activate with source .venv/bin/activate instead.

Check it worked:

nameframe --help

Optional: MCP support

Only needed if an AI assistant will be talking to NameFrame.

python -m pip install -e ".[mcp]"

Verify the install in 30 seconds#

This generates a small procedural dump, labels it, reports it, exports a dataset and scores it, with no Unreal involved:

nameframe generate --demo --samples 8 --seed 7 --output _demo/check --dataset-task box --dataset-format yolo,coco --fail-under 80

Open _demo/check/report/index.html and _demo/check/validation/validation.html. If both exist and the score is a number, your install is fine.

Unreal plugin#

The capture plugin is NameFrameCapture, under unreal/Plugins/NameFrameCapture/. It has a Runtime module (capture, zones, spawning) and an Editor module (the Studio panel).

1. Copy the plugin into your project

   Copy the whole NameFrameCapture folder into <YourProject>/Plugins/. Create the Plugins folder if it isn't there yet.

2. Enable the dependencies

   The plugin declares Niagara as a required plugin. For command-line and headless control you also need the engine's Remote Control API plugin enabled in the project.

3. Rebuild

   Right-click the .uproject, choose Generate Visual Studio project files, then build. Or just open the project and let Unreal compile the plugin when it offers to.

4. Open the Studio panel

   In the Unreal editor: Tools → NameFrame Studio. The console command NameFrame.Studio.Open does the same thing.

The commercial-preview compatibility manifest supports and verifies Unreal Engine 5.8. The installer reads this manifest and warns for any other engine version. You can pass an explicit local override for an experiment, but that does not change the product's supported tier. Native proof is tied to the exact plugin-source digest, so diagnostics can flag stale evidence instead of silently expanding the compatibility claim.

Scripted install from a source checkout

The equivalent of the bundle installer, but for a repository clone. It handles the venv, the package and the plugin copy in one go. Dry-run first to see what it will do:

.\scripts\install_windows.ps1 -DryRun -UnrealProject D:\Projects\MyProject\MyProject.uproject -InstallPlugin

Drop -DryRun to actually apply it. -Repair reinstalls, and -UninstallPlugin removes the plugin again.

Note the difference from the bundle: this one takes -RepoRoot and installs whatever the working tree currently contains. The bundle installer takes -BundleRoot and installs a verified, hashed payload. They are not interchangeable.

Remote Control (only for CLI capture)#

Commands like capture-unreal, scene-unreal and live-smoke talk to an already-open Unreal editor over HTTP. The default endpoint is:

http://127.0.0.1:30010

Override it per command with --remote-url, or globally with the NAMEFRAME_UE_REMOTE_URL environment variable.

Where things live#