FluidSimCpp/docs/ENGINE_CONFIG.md

# Engine definitions

Each `engines/*.toml` file defines one engine and its default vehicle/load
calibration. Files are loaded once when the program starts. Add a file, give it
a unique `id`, then restart to see it in the browser. Editing a definition does
not require recompiling the engine simulator.

Start by copying a similar engine, such as `single-450.toml`, `five.toml`,
`v8-h.toml` or `yz-racing.toml`. Existing definitions contain their effective
calibration values, including the previous carb and idle tunes.

```toml
schema_version = 1
id = "my-single"
name = "My four-stroke single"
category = "Singles / four-stroke"
description = "My calibration"
order = 100
cycle = "four_stroke"
```

`id`, `name`, `category`, `cycle` and `schema_version` are required. IDs use
lowercase letters, digits, `-` and `_`. `order` controls menu order; ties sort by
ID. Duplicate IDs, unknown keys, unsupported versions, incorrect types and
invalid physical values stop loading with a diagnostic identifying the file
and field. TOML syntax errors also report their location.

## File discovery and distribution

The first available directory is used:

1. `FLUIDSIM_ENGINE_DIR`, when set. A missing override directory is an error.
2. `engines/` under the working directory.
3. `engines/` beside the executable on Windows and Linux.
4. The source checkout's `engines/` directory as a development fallback.

Definitions are cached for the process lifetime. The selected directory is
loaded as one catalog; it is not merged with the bundled files. In a repository
working directory, source definitions take priority over build copies.

CMake synchronizes the definitions into the build output when building an
executable. Distribute that `engines/` directory with the executable. The TOML
parser is vendored, so loading definitions needs no network connection.

```powershell
$env:FLUIDSIM_ENGINE_DIR = "C:\MyEngines"
.\fluidsim_desktop.exe --example my-single
```

## Units and sections

File keys state dimensional units. `_mm` is millimetres, `_litres` is litres,
`_cc` is cubic centimetres, `_deg` is crank degrees, `_s` is seconds, `_nm` is
newton metres and `_kg_m2` is rotational inertia. The loader converts lengths
and volumes to SI units. Openings and mixture/taper multipliers are normalized
fractions, not percentages: `0.03` means 3%.

Four-stroke definitions use these sections:

| Section | Contents |
| --- | --- |
| `[engine]` | Cylinder count, layout, bank angle, phases, intake volumes, throttle, startup, load, and exhaust topology |
| `[cylinder]` | Bore/stroke/rod, compression, valve geometry and timing, combustion and heat transfer |
| `[crankshaft]` | Inertia and mechanical friction |
| `[ecu]` | Idle, actuator response, ignition curve, limiter and overrun thresholds |
| `[vehicle]` | Vehicle mass, gears, clutch, wheel geometry and road resistance |
| `[fuel]` | `system = "injection"` or `"carburetor"`, jet diameters and taper/film calibration |
| `[junctions]` | Fitting volume and H crossover selection |
| `[silencers]` | Connecting pipes, resonator and muffler profiles, when used |
| `[[pipes]]` | Ordered pipe groups for the selected exhaust topology |

`engine.phase_degrees` contains one phase per cylinder in cylinder index order,
within `[0,720)`. It records the actual crank offsets rather than a firing-order
label. `ecu.ignition_map` is an array of `[RPM, degrees BTDC]` pairs with strictly
increasing RPM. Negative advance means ignition after TDC.

For a carbureted four-stroke, use `ecu.idle_control = "fixed"` and set
`ecu.idle_base_opening`. Its limiter and overrun control cut ignition while the
carburetor continues supplying fuel. Jet diameters in `[fuel]` are effective
diameters after the previous displacement and jet multipliers have been applied.

Two-stroke definitions use `[two_stroke]`, `[ecu]` and `[vehicle]`.
`two_stroke.idle_slide_opening` sets the mechanical stop;
`idle_spark_gain` and `idle_minimum_advance_deg` set its idle spark trim.
Two-stroke jet multipliers retain their existing meaning.
`chamber_sections_mm` contains six `[length, inlet diameter, outlet diameter]`
sections: header, two diffusers, belly, baffle cone and stinger.

Required cylinder geometry must be explicit. Optional calibration fields use
the typed config defaults; a misspelled field is always an error. Existing files
include explicit values so their behavior does not depend on future defaults.

## Pipe groups and exhaust topologies

These definitions configure the existing topology builders. They do not yet
describe arbitrary graphs of cylinders and junctions. A group's `id` must be
unique; `count` repeats its dimensions across adjacent pipes.

```toml
[[pipes]]
id = "primaries"
count = 8
diameter_mm = 38.0
length_mm = 750.0
cells = 15
```

The order is significant because the topology builder connects the expanded
groups to fixed cylinder and junction ports:

| `engine.topology` | Pipe order after expansion |
| --- | --- |
| `collector` | Intake, N runners, N primaries, one tailpipe |
| `staged` | Intake, N runners, N primaries, outlet pipe(s), secondary pipe(s) |
| `american_v8` | Intake, 8 runners, 8 primaries, 4 secondaries, 2 bank collectors, 2 tailpipes, H crossover |

The staged inline triple has one secondary; other staged layouts have two.
Staged V engines have two independent outlets. The American topology requires
eight cylinders in a V layout; setting `junctions.h_pipe = false` closes both
ends of the unused crossover and leaves the banks independent.

A collector outlet can instead use `profile = "silenced"`. Its dimensions and
mesh then come from `[silencers]`, `[silencers.resonator]` and
`[silencers.muffler]`; omit the group's uniform pipe dimensions. The loader
checks expanded pipe counts and mesh limits before construction. Pipe positions
continue to use the shared scene routes for rendering and sound sources.