RTX Remix Toolkit Contributor Guide#

Internal reference for contributors to RTX Remix Toolkit. Covers build setup, architecture, implementation patterns, code quality standards, and development tools.

Quick Start#

Prerequisites#

Windows 10 or 11
Git
GPU with RTX support
~50 GB free disk space

For full hardware and software requirements, see Technical Requirements.

Get the Source Code#

git clone https://github.com/NVIDIAGameWorks/toolkit-remix.git
cd toolkit-remix

Build the Project#

.\build.bat

The first build downloads all dependencies (Kit SDK, Python 3.10, tools) automatically via packman. Subsequent builds are incremental. See Tech Stack Overview for how the build pipeline works.

Run the App#

.\_build\windows-x86_64\release\lightspeed.app.trex_dev.bat

Developer mode — includes verbose logging and extension hot-reload. See Repo Tools → Run for all launch options and flags.

Format Your Code#

.\format_code.bat

Auto-formats all Python files with ruff (style + import sorting) and C++ files with clang-format. Run before every commit to avoid formatting-only diffs in review. See Repo Tools → Root Scripts for all available scripts.

Lint Your Code#

.\lint_code.bat all

Runs ruff checks with auto-fix. Catches common errors, unused imports, and style violations that formatting alone doesn’t cover. Both format and lint can be automated with pre-commit hooks — see Repo Tools → Root Scripts.

Run Tests#

.\_build\windows-x86_64\release\tests-<extension.name>.bat -n default

Runs user-written tests for a single extension. See Running Tests for filtering, coverage, and troubleshooting.

Build the Documentation#

.\build_docs.bat

Builds the Sphinx documentation locally. Output lands in _build/docs/. Useful for previewing doc changes before submitting. See Repo Tools → Root Scripts for all available scripts.

Submit a Pull Request#

Before opening a PR, check every item in the Review Checklist: branch naming ( dev/<user>/<feature>), version bumps for modified extensions, changelog entries, and ≥75% test coverage on new code.

External Contributors#

Fork this repository, create a development branch, and submit a Pull Request against main. An automated bot will prompt you to sign the Contributor License Agreement via your PR’s comment page.

Table of Contents#

Getting Started#

Page	Description
Tech Stack Overview	How repoman, packman, Kit SDK, premake, and Python fit together. The build pipeline from `build.bat` to a running app.
Git Workflow	Branch naming, commit format, and merge request process.
Running Tests	Test commands, filtering with `-f`, troubleshooting (registry sync, timeouts), and coverage reports.
Review Checklist	Pre-submission checklist: action undoability, USD context compatibility, dependency management, docstrings, version bumping, and changelog updates.
Learning Resources	Kit SDK, USD, and Omniverse documentation and video tutorials.

Architecture & Design#

Page	Description
Code Architecture	USD contexts, extension lifecycle, design principles, event subscriptions, and system-level patterns (Commands, Factory/Plugin, Settings, Job Queue, Pip Archive).
Extension Guide	Extension naming, dependency direction, namespaces, directory layout, `extension.toml` reference, `premake5.lua` boilerplate, Python stubs, and `docs/README.md` structure.

Code Quality Standards#

Page	Description
Code Style	Python 3.10, max 120 chars, black + isort + ruff, naming conventions, no lazy imports, `__all__`, license headers, and Google-style docstrings.
Engineering Standards	Fix root causes, never paper over. Anti-patterns table and smell tests for broken async, swallowed exceptions, and design problems.
Testing Standards	75% coverage requirement, plan-before-code, unit vs E2E, Arrange/Act/Assert, test naming, and anti-patterns.

Implementation Patterns#

Page	Description
Building UI Components	`omni.ui` layout guidelines: alignment, spacing, dimensions, and Remix stylesheet conventions.
Implementing Commands	Undoable user actions with `omni.kit.commands.Command`: `do()`/`undo()`, grouping, dispatch, and testing.
Implementing Service Endpoints	REST endpoints with `ServiceBase` and `omni.flux.service.factory`: routing, registration, and testing.
Implementing Stage Manager Plugins	The Stage Manager plugin system: 8 plugin types, schema config, and Flux/Lightspeed layering.
Implementing Ingestion Pipeline Plugins	Validation framework: 4 plugin types, execution flow, DataFlow, and mass validation.
Adding Pip Package Dependencies	Third-party packages via `omni.flux.pip_archive`: OSRB requirement, `pip_flux.toml`, and post-merge steps.

Development Tools#

Page	Description
Repo Tools	All root-level scripts: build, run, format, lint, build docs, pre-commit hooks, repo subcommands, and CLI launchers.
VSCode / Cursor Setup	Workspace setup, recommended extensions, tasks, debug config, and agent commands.
PyCharm Setup	Python path, run profiles, scope config, and external tools for format/lint.
Debugging	Attaching debuggers to Kit: debugpy (VSCode) and PyCharm Professional. The `break` flag trick for tests.
Profiling	Performance profiling with Tracy: app-start and on-demand (`F5`).