Technical documentation
LunCoSim Documentation¶
An open-source workbench for authoring, simulating, and operating space missions with USD, Modelica, and Rhai.
Abstract. LunCoSim combines a composed OpenUSD scene, continuous Modelica models, and discrete Rhai mission policy into one running simulation. This document describes the project model, the authoring workflow, the runtime contracts that connect the three formats, and the evidence required before a result is trusted. It is written for engineers, mission designers, educators, and tool integrators who need to understand both what to author and why the runtime behaves as it does.
Contents
- General — purpose, installation, first run, perspectives, Twins, and the format boundaries.
- Tutorials — guided lessons from a first drive to a validated, shareable Twin.
- USD — scene composition, physics, typed ports, programs, materials, and asset addressing.
- Modelica — continuous behavior, cosimulation, the Lunica workbench, libraries, and experiments.
- Rhai — scenario lifecycle, task trees, commands, events, tests, and reusable policy patterns.
- Shaders — WESL material parameters, texture layers, USD material binding, terrain rendering, and quality budgets.
- SysML v2 — requirement sources, system structure, typed analysis, and verification with scene tests.
- UI & Settings — global and project settings, HUD surfaces, theming, and runtime-authored UI.
- Reference — command line, controls, manifests, file formats, HTTP API, mission control, validation, and troubleshooting.
About this document¶
This guide documents the behavior of the shipped application and the contracts an author can rely on. Where a capability is partial, experimental, or limited to one platform, the limitation is stated in the relevant section rather than implied by silence.
The documentation follows the same ownership rule as the software:
- USD owns scene structure, geometry, materials, physics schemas, and typed connections.
- Modelica owns continuous equations and state.
- Rhai owns events, commands, mission sequencing, and authored verdicts.
- TOML owns project and asset configuration.
- The runtime owns projection, scheduling, physics integration, and rendering.
A reader who remembers only one rule should remember this one: do not
reimplement a fact in a second layer. A wheel position belongs in USD, a motor
curve in Modelica, a waypoint mission in Rhai, and a download declaration in
Assets.toml.
Conventions¶
| Convention | Meaning |
|---|---|
| Bold | A user-interface label, a perspective name, or a term defined in the glossary. |
Monospace |
A file name, command, attribute, property, or literal value. |
> |
A menu path, for example File → Open Twin…. |
| Note boxes | A constraint, a platform limitation, or a warning about a common mistake. |
| Code blocks | Authored source or a command to run. Shell blocks use a POSIX shell unless marked otherwise. |
| Version numbers | LunCoSim is under active development; command and schema details can change between releases. |
Paths in this document use forward slashes. On Windows, substitute the
platform separator where the application accepts a native path. Logical asset
addresses such as lunco:// and twin:// always use forward slashes.
How to use this document¶
A new user should read Installation, run First mission, and then read How it fits together. An author who already knows the workbench can go directly to the format chapter for the layer being edited. An integrator should start with Integrate your stack and the HTTP API. An instructor should read the Tutorials overview and the lesson descriptions before using the classroom track. A requirements author should start with SysML v2.
Current status¶
LunCoSim is under active development. Model coverage, platform support, and tool maturity vary. A successful build, a clean parse, or a green scene test is evidence about a specific claim; none of them is a general accuracy certificate. The Validation chapter explains how to separate preflight, runtime behavior, requirement coverage, and physical accuracy.
Release builds and notes are published on the GitHub releases page. Community links are in the site footer.