Product scope and problem statement
A robotics simulation project usually combines assets, scenes, control, recording, debugging interfaces, and remote services. If each part owns a physics backend directly, hidden environment dependencies, duplicate lifecycle logic, and irreproducible runs appear quickly.
FastSim separates those concerns into three stable planes:
| Plane | Responsibility | Primary artifact |
|---|---|---|
| Compilation | Read the Run, resolve registries, validate resources and plugins | Immutable ExecutionPlan and Run Lock |
| Runtime | Lifecycle, scoped services, control arbitration, output finalization | An Application with explicit state and generation |
| Simulation | Scene, state, control, and backend capabilities | UniRoboSim Provider, Session, and World |
FastSim does not replace Isaac Lab, MuJoCo, or PyBullet, and it does not reimplement physics or rendering. Core does not own pick, place, task trees, planning algorithms, model inference, or teleoperation device protocols. Plugins own those capabilities and enter the runtime through the same controlled services.
That boundary keeps Core small and stable while Rule-based, Model, Teleop, Agent, Record, Replay, Debug, TUI, and Server packages evolve independently.
Audience and documentation structure
- Simulation application authors organize projects with Runs and component URIs, then validate, lock, and launch them with the CLI.
- Platform and plugin developers use the Python API, Plugin SPI, scoped services, and generated references.
New readers should continue with Platform architecture and Design principles. Use Installation and first run when ready to execute a project, or go directly to Configuration and the Python SDK for exact interfaces.
This site separates explanations, task-oriented guides, exact references, and runnable examples. The number of source READMEs does not determine the primary documentation hierarchy.
Inspectable application model
FastSim's out-of-the-box engineering capability is the composition of Core and the official plugin repository. Core owns compilation, lifecycle, public services, authority, Operations, and controlled output publication. Plugins provide Mission, Model, Teleop, Record, Replay, Server, TUI, MCP, visualization, and interactive-debug workflows. UniRoboSim Providers implement the real physics world.
The boundary is deliberate: domain semantics stay in plugins, runtime authority stays in Core, and backend-specific mechanics stay in Providers. A Mission plugin may understand “grasp the cup,” but it reads Scene/Frame/Geometry and submits portable control through the Application rather than taking ownership of the simulator.
FastSim records operational facts that ad-hoc scripts often leave implicit: the selected component release and physical resources, configuration provenance, service grants, reset invalidation, Provider capabilities, and output commit state.
Compilation turns editable declarations into a typed immutable Plan. Runtime snapshots carry run, generation, revision, and tick identity. Control is admitted through targets and authority. Outputs pass staging, validation, and atomic publication. These are the foundations of reproducibility; a seed alone is not enough.
- Authors declare a Run and reuse versioned components through a Project and Registries.
- The compiler validates, resolves resources, selects variants, binds plugins, and calculates grants.
- The immutable ExecutionPlan becomes the only construction input to the Application.
- The owner loop prepares the Provider, stable services, and selected plugin instances.
- Callers query committed values and submit controlled work with explicit Operation identity.
- Stop and close converge plugins, subscriptions, Operations, and outputs before releasing the Provider.
Feature ownership
Put a fact in Core when every application must share its identity, lifecycle, authority, or reproducibility boundary. Put task language, model inference, device mapping, recording policy, or interface presentation in a plugin. Put engine startup, native objects, physics stepping, and engine-specific capabilities in a Provider. Put expensive inspection and format conversion after sealed outputs in offline tools.
After this page, Platform architecture explains the layers and data flows. Application authors can then start with Run, Plan, and Lock; plugin developers should follow with Plugins and capabilities.