Repo Map

Repo map — layout, binaries, and when to use them

A Rust/Bevy Cargo workspace: 60+ library crates + a handful of app binaries, plus assets, docs, specs, and skills. This skill is the fast orientation; the two authoritative, always-current indexes are:

• docs/apps/README.md — every runnable binary, full CLI flags, launch lines.
• docs/crates-index.md — every library crate, grouped by domain, with responsibilities.

When those disagree with anything here, they win.

When a capability is hard to find

This map routes to owners; it is not an exhaustive capability list. Before calling a feature missing, use capability-discovery: search the relevant skills and docs, then crates/, assets/, registrations/callers, maintained dependencies, and the live API/runtime. Search alternate vocabulary and standard USD schema/property names before adding a new command, field, tool, or crate. Report the exact searched scope and distinguish “not found” from “not verified” or “externally blocked”.

Top-level layout

Binaries — which one do I run?

Pick by task, not by habit:

Launch the installed production executable, or explicitly select a checkout build when source validation is the goal. Workspace default-members make a bare cargo run ambiguous — always pass a target:

# GitHub/release install on PATH (or override with an absolute installed path).
export LUNCOSIM_BIN="${LUNCOSIM_BIN:-luncosim}"
export LUNCOSIM_SERVER_BIN="${LUNCOSIM_SERVER_BIN:-luncosim-server}"
export LUNICA_BIN="${LUNICA_BIN:-lunica}"
"$LUNCOSIM_BIN"
"$LUNCOSIM_BIN" --api 4101
"$LUNCOSIM_SERVER_BIN" --api 4101

# Source checkout alternative: build, then override the variables before use.
# cargo build -p lunco-luncosim --bin luncosim -j 4
# export LUNCOSIM_BIN=target/debug/luncosim
# cargo build -p lunco-luncosim-server --bin luncosim-server -j 4
# export LUNCOSIM_SERVER_BIN=target/debug/luncosim-server

"$LUNICA_BIN" --api 4101

# Source checkout alternative for the Modelica workbench:
# cargo build -p lunco-modelica-ui --bin lunica -j 4
# export LUNICA_BIN=target/debug/lunica

Utility / dev bins: modelica_run (lunco-modelica-execution, headless Modelica CLI → CSV), modelica_library_indexer (lunco-modelica-assets, rebuild the Modelica-library search index — re-run after a source-library change), lunica_worker (lunco-modelica-execution, wasm compile worker, bundled not run), build_modelica_library_assets (lunco-modelica-assets), net_smoke (lunco-luncosim, production transport smoke test). Authored luncosim behavior tests run through luncosim test plus their Rhai scenarios. Details: docs/apps/README.md.

Talking to a running app (agents)

The windowed apps that embed the API bridge (luncosim, lunica, and anything with LunCoApiPlugin) honor:

• --api [PORT] — enable the HTTP automation API. Default port 4101. This is mandatory for luncosim visual/runtime validation; use an explicit free port. (lunco_api_contracts::DEFAULT_API_PORT); the MCP config points here via LUNCO_API_PORT. Without --api, no network surface.

• --no-ui — headless (skip winit/egui, run the shared sim loop).

• --scene <path> — (luncosim) load a USD scene on boot; path is relative to the assets/ root (do not prefix with assets/).

Use production luncosim for scene-test and visual evidence. Use luncosim-server (or luncosim --no-ui) for numeric/headless evidence only; headless runs cannot prove screenshots, rendering, or visual acceptance. Keep the binary, revision, readiness state, and evidence type explicit in reports; these evidence paths are complementary, not interchangeable.

Drive it: POST /api/commands with {"type":"ExecuteCommand","command":"<Name>","params":{...}}; discover the live command set with DiscoverSchema (it's introspected, never hard-coded). Full recipe in the run-modelica / test-via-api skills.