FluidSimCpp/docs/MACHINE_BUILDER.md

# 3D machine builder

Open **Machine Workshop** from the maximized main menu. Choose **New machine**, or
select a saved machine and choose **Edit** or **Play**. Pressing **B** in the
scenario browser opens a new design directly.

The builder supports general pneumatic circuits as well as engines. The two
example benches provide a four-stroke engine and a piston vacuum pump. The
parts picker uses cached 3D previews of the same meshes that appear in the world.

**Import engine layout** (I) transfers the existing 450 single, parallel twin,
flat six and V8 H-pipe layouts into new editable documents. The importer preserves
pipe routes and diameters, storage dimensions, bore/stroke, firing phases, cam
profiles, valve dynamics, shaft calibration, fuel calibration and ECU settings.
It inserts a visible carburetor or throttle into the final inlet segment and adds
the appropriate ECU with control wires. The metering body and stub replace part
of that inlet segment, preserving its total route length and gas volume.

## Build and configure

The workshop uses a dark editor layout with resizable, collapsible Library and
Inspector panels. Drag their dividers to resize; widths and collapse states are
saved locally. **Reset UI** restores the default panel layout. The **Library**
offers categories, search and part previews; **Objects** lists the current parts.
**Ctrl+F** focuses search. Long control names fit their available width and reveal
their full text on hover. Property labels sit above their editable values.

The inspector tabs are **Part**, **Links**, **Setup**, **Checks**, **Meters** and **Sense**.
The oscilloscope has a separate bottom dock; drag its upper edge to resize it.
The minimum window size is 1280x720, with the layout reviewed at 1920x1080 too.
Entering the workshop maximizes the Windows window; the application no longer
shrinks when moving between the workshop, home menu and engine scenarios.

1. Pick a part on the left and click the world to place it. Placement uses the
   horizontal plane set by **Machine → Place Y mm**. Hold Shift for repeated placement.
2. Select a placed part to open its properties. Right click a part for its context
   menu. Click the part name to rename it.
3. **G** selects Move. Drag a colored X, Y, or Z handle to translate in world axes,
   or drag a selected body to move in the screen plane.
   **R** selects Rotate; drag a colored ring to rotate about that world axis.
   **X** toggles snapping. Translation uses the configured grid; rotation snaps to
   15 degrees. Numeric position and rotation fields also allow precise changes.
4. Click a numeric property, type its value and press Enter. Escape cancels typing.
   The minus/plus buttons make incremental changes. Scroll over the inspector to
   reach additional properties.
5. Select a part to reveal its ports, then drag between ports or click a port
   followed by its target. **C** optionally shows all ports. Neutral markers are
   bidirectional gas ports; at least one end of a gas connection must be a pipe.
   The pipe endpoint snaps to the other part. Blue pins connect existing ECU
   assignment wires; ECU outputs are filled and inputs hollow. The **Links** tab
   configures or disconnects connections. Use the Move gizmo to move a small
   boundary symbol whose port occupies its center. **Escape** cancels a wire;
   **G** returns to Move. Route mode prioritizes editing pipe points.
   After choosing the first port, hover the target: a blue preview shows the
   snapped pipe route or control wire; a red preview explains why it cannot connect.
   Previewing does not change the design. Clicking an invalid target leaves the
   first port selected so you can choose another target.
6. **P** selects Route for a selected pipe. Use **Add path point**, select a point,
   then drag its X/Y/Z handles. The inspector edits the selected point's local
   coordinates. Disconnect an attached endpoint before moving it independently.
   Select a numbered point and edit **Point dia mm** to change its bore. Every
   point has its own diameter; adjacent values form a linear taper along that
   segment. This replaces the former inlet/outlet diameter fields.
   **Ctrl-click** near the selected pipe's centerline to insert a bend at that
   location, or right click a pipe and choose **Insert bend here**. The new point
   starts on the original route, preserving length and gas volume until moved.
   Length, the selected point's bore and volume are shown above the viewport while editing.

Alt+left drag or right drag on empty space orbits the view. Middle drag pans;
the wheel zooms; Home fits the design and **F** focuses the selected part or group.
Q selects without a transform tool.
Shift-click adds/removes parts from a selection. Shift-drag on empty space selects
a group; Ctrl+A selects the whole machine. Move and Rotate operate on that group.
Ctrl+C copies the selected parts, their internal air/control connections and
attached probes; Ctrl+V inserts a translated copy. Ctrl+D duplicates immediately.
Connections to parts outside the copied group are not copied. Delete removes the
selection. Ctrl+Z/Ctrl+Y undo/redo. The copied group remains available when loading
another machine during the same workshop session. Right-clicking a selected part
keeps the group selected and opens Copy, Paste, Duplicate and Save as assembly.

Click **Assemblies** to save the selected group for reuse or insert a saved
assembly into the current design. Assemblies are stored in
`machines/assemblies/` as `*.assembly.toml` files and can be copied between
workspaces. Their internal connections, component settings, pipe profiles and
attached probes are preserved. On insertion, part and probe IDs are remapped and
the group is placed near the current selection (or the view center), selected and
focused for positioning. The destination machine's shaft and simulation settings
apply to the inserted components. Shaft gauges remain specific to each machine.

Escape cancels a placement/connection or clears selection; it never leaves the
workshop. Use **Menu** to return to the scenario menu, or close the application
window to exit.

In Move mode, grab an atmosphere symbol directly to select and drag it, or use
its X/Y/Z handles. Its attached pipe endpoint follows the move. Atmosphere
symbols remain selectable at the end of a wide pipe.

## Machine checks

Press **H** or click **Checks** to open the checks panel in Build or Test. Warnings
identify cylinders without a connected fuel source, ECUs without assigned parts,
and fixed throttles that are closed without an assigned ECU. Notes identify
sealed pipe/cylinder ports and remind you to crank a stopped free shaft.

Click a check to select and focus its part. Use the Part or Connections tabs to
configure it. Wheel or Previous/Next browses longer lists. Checks refresh after
edits, undo and redo; they do not change or prevent testing a design. A sealed
port can be intentional. Fuel checks establish wiring/plumbing reachability;
they do not guarantee flow through valves, correct calibration or combustion.
Unresolved sensor checks open the affected attachment in **Sense**.

Ideal junctions support multiple pipes on the same point. Connect free pipe ends
to the junction's center marker. Connecting a third pipe to an occupied
pipe-to-pipe join automatically replaces that join with a shared node. Switching
to stored-volume mode gives branches distinct ports on the visible box; switching
back to an ideal node brings them to its center.

## Physical dimensions

There is one design geometry shared by rendering, picking and simulation:

- **Pipes and reducers:** centerline segment lengths determine the simulated
  length. Each route point defines a diameter. Diameter varies linearly between
  adjacent points, allowing expansions, necks and reducers within one pipe. The
  finite-volume mesh integrates the exact frustum volumes across each cell,
  including cells that cross multiple profile segments. This preserves gas
  volume across mesh densities. Bends stay at their edited positions.
  Visual route points do not force extra simulation cells: the physics mesh follows
  total arclength at the selected cell density. A genuinely short pipe remains short
  and can require more CFL substeps.
  Sharp changes in area also constrain the timestep by the ratio between face
  area and the gas volume stored in a cell.
- **Chambers and storage junctions:** the visible internal box dimensions define
  capacity as X × Y × Z. Rotation changes the port locations and appearance,
  and preserves volume.
- **Cylinders and piston pumps:** bore, stroke and compression ratio define the
  gas cavity and clearance. The rendered piston and current simulated volume
  use the same displacement. Engine cylinders also expose valve diameters/counts,
  cam timing/lift, valve mass, spring, damping, preload, AFR and spark advance.
- **Throttle and check valve bodies:** throttles use their visible elliptical
  tube dimensions for gas storage; check valves use their box dimensions.
  Diameter and discharge coefficient define the restriction. Throttles
  can use the test pedal or a fixed opening. Check valves pass flow from their
  local -X inlet to +X outlet above the configured cracking pressure.
- **Ideal junctions:** characteristic and legacy modes have zero stored volume
  and are drawn as node symbols. The storage mode is drawn as a physical box.
- **Carburetor:** the elliptical throat stores gas according to its length and
  Y/Z diameters. The restriction diameter controls flow. Pilot/main/needle jets
  meter liquid fuel from the float bowl into that gas; the solver transports it
  through pipes into the cylinders. Jets, needle corrections, fuel density, bowl
  capacity/refill, fuel film and discharge settings are editable.
- **ECU:** a controller housing with no gas storage. Blue wires assign injection
  and ignition to cylinders, and throttle control to a throttle or carburetor.
  One ECU can control multiple parts. An unconnected ECU controls none.
- **Pressure/atmosphere and end-cap symbols:** these represent boundary conditions
  and have no storage volume. A pressure boundary is an infinite reservoir with
  the configured pressure and temperature; an end cap reflects flow.

Moving, rotating or resizing a connected component updates the attached pipe
endpoints. Its pipes therefore change length when their routes change. There is
no pressure-driven visual expansion in this editor.

The flow equations remain one dimensional in pipes and lumped in chambers.
The 3D layout supplies physical sizes and junction directions; this is not a 3D
CFD mesh. Valve restrictions and zero-volume fittings use the existing boundary
models. Ideal pressure-actuated check valves have no moving reed mechanics.

## Test and return to editing

Press **Tab** or **Test** to compile the design and run it with audio and pressure
colors. Select a part to read its current pressure and volume. W/S or the pedal
bar changes throttle; hold V for starter torque on a free shaft. Space pauses
or resumes both physics and audio. Test offers **1x, 0.5x, 0.25x, 0.1x and 0.01x**
playback; Page Down halves the speed and Page Up doubles it (1% to 100%).
**Step 10 ms** advances a paused machine by exactly 0.01 simulated seconds.
The physics timestep and engine calibration stay the same at every playback speed;
audio pitch slows with playback. Buffered audio scales with speed to keep controls
responsive. The four existing pipe solvers and five audio
environments are selectable under **Machine** before starting a test.

New engine benches use a free shaft at zero initial RPM. Hold **Hold to start**
or V to crank. A cylinder only receives fuel from an explicitly assigned injection
ECU or from fuel physically delivered through a connected carburetor. There is no
implicit cylinder injector. A carburetor can run with mechanical ignition; an
optional ignition/idle ECU can control spark and opening.

For EFI, connect the ECU's blue output to each cylinder's blue input. Connect
that output to the throttle's blue input for idle/throttle control. ECU settings
include idle target/opening limits, PI gains, ignition-map points, cruise/power
AFR, throttle response, overrun cuts, rev limit, resume RPM and minimum cut time.
Fuel and spark cuts are independent. A cut lasts at least its configured time and
resumes only below the resume RPM. Carburetor ECUs use **Ignition / idle only**
so they do not add an invisible second fuel source.

The **Mech** category contains **Shaft / crankshaft**, **Flywheel**, **Drive motor**
and **Brake / load**. Connect their gold mechanical ports. Cylinders and piston
pumps also have a gold shaft port; each must attach to a named shaft before Test.
Moving a shaft changes its attachment lines without moving its cylinders or pipes.

Each shaft has independent angle, initial speed, base inertia and friction.
Flywheels add inertia once; the shaft inspector shows the connected total.
Motors can apply signed torque or impose an ideal target speed. The ideal speed
drive reports the work it supplies or absorbs, including speed changes. A brake
applies opposing torque and drag, dissipates work and cannot drive a stopped shaft
backward. Pure mechanical machines can run without any gas pipes.

Use **Setup** to choose the primary readout shaft, or pin it from a shaft's
inspector. Each ECU's controlled cylinders must share a shaft. Engine timing is
currently forward-only; standalone mechanical shafts support reverse rotation.
The legacy starter calibration remains on migrated shafts until explicit starter
parts are added. New shafts have no hidden starter torque by default.

The saved **Shaft, flywheel and brake bench** demonstrates acceleration, motor
power and absorbed load power. Its file is `machines/shaft-drive-bench.machine.toml`.

The overlay distinguishes **SPEED CONTROLLED**, **TORQUE DRIVEN**, **FREE SHAFT**, **FUEL OR SPARK CUT**,
**VALVE FLOAT**, and **NO FUEL SOURCE**. The model has no fixed 16,000 RPM cap.
With limiting disabled, controlled checks ran at 16,000, 20,000 and 24,000 RPM
without positivity repairs. The unloaded bench settled around 17,500 RPM as net
torque fell toward zero. This depends on geometry, valve dynamics, fuel/spark
calibration and losses; increasing a rev limit does not guarantee engine torque
at that speed.

Unconnected gas ports on pipes and cylinders are sealed; the status line reports
their count. Unused tank faces are simply walls. Unconnected mechanical attachments
receive a navigable check and prevent Test.
Invalid dimensions, duplicate connections and physically separated connected
ports are rejected. Numerical failures stop the test and report an error.

Press **Tab** again to stop playback and return to the same design and camera.
Starting another test initializes a fresh gas and mechanical state.

## Live tuning

Properties are editable during Test unless marked **BUILD** and dimmed. Live changes
are validated and synchronized between physics batches, preserving gas state,
shaft state, simulation time, carburetor fuel film and controller history. Carb
jets, needle corrections, fuel settings, ECU calibration, fixed throttle opening,
check-valve cracking pressure, cylinder combustion settings, shaft losses,
motor torque/target speed and brake loads can be adjusted live. Live edits support undo/redo and saving,
and remain in the design when returning to Build.

Pipe routes/diameters, transforms, part dimensions, bore/stroke, cam profiles and
valve mechanics, connections, initial gas conditions, solver/mesh settings and
compiled boundary coefficients, initial shaft states and shaft/flywheel inertia
require Build. A live undo that would change one
of these properties is rejected without changing the running machine.

## Instruments and traces

Press **M** or **Meters**. Select a part, then choose **Pressure**, **Temp**, **Flow**,
**AFR**, **Lambda** or **Charge AFR**. **RPM**, **Torque** and **Power** target the
selected shaft or attached rotational part; without a compatible selection they
use the declared primary shaft. Up to eight channels can be attached.
Probes add no gas volume or restriction. Colored P1/P2 markers locate probes in
the world; clicking one in Select or Test opens its instrument settings.
Use **< Probe / Probe >** to choose the channel plotted on the scope.

Pipe taps use a fraction of arclength from Start to End, adjustable in the panel.
Measurements use the cell containing the tap, so spatial detail follows mesh
resolution. Lumped-part flow is net flow into the part; pipe flow is signed
Start-to-End. Pressure is absolute kPa, temperature K, flow g/s, torque Nm and
power kW. Motor gauges report drive torque/work, brakes report signed reaction
torque and positive absorbed power, and new shaft gauges report net acceleration
torque and kinetic power. Migrated legacy output gauges retain their running
averages of engine output after shaft friction, excluding bench drive and load;
the inspector identifies that measurement mode.

**Bulk AFR and lambda** track fuel origin as a conserved passive tracer, including
fuel already burned. Exhaust readings therefore travel with the gas through
pipes, chambers and shared junctions and mix according to transported mass.
Put a downpipe probe after a collector to read the combined exhaust there.
The exhaust starts as clean air, so downstream readings can remain very lean
until the original air has been purged by exhaust gas.
Lambda is bulk AFR divided by the probe's stoichiometric reference (default 14.7).
Changing the reference changes the displayed ratio, not the combustion chemistry.
**Charge AFR**, available on cylinders, reads current unburned fresh-air mass
divided by remaining unburned fuel mass. It becomes undefined after that fuel is
used. No fuel is shown as **--**, rather than an invented stoichiometric reading.
These are ideal model instruments; sensor heating, response delay and detailed
oxygen chemistry are not simulated.

The scope samples at 2,756.25 Hz in simulation time and retains the latest 32,768
samples (about 11.9 simulated seconds). Choose a 0.05, 0.2, 1 or 5 second display
window; the graph shows min/max/mean and preserves peaks when compressing samples
onto screen pixels. Frequencies above half the sampling rate cannot be resolved.
The scope stays open while switching to Part settings, allowing live carb/ECU
tuning while watching a trace. X closes the scope. Space freezes the machine for
inspection. The last capture remains available after returning to Build.

**Export captured CSV** writes simulation timestamps and labeled channel units to
`verification/measurements/`; undefined readings are empty cells. **Clear captured
trace** starts a new capture without resetting the machine. Adding/removing a
channel or changing a tap/reference clears the capture to keep its schema
consistent. Instruments can be configured during Test without reloading physics.

## Saving

Ctrl+S saves the design. A new design asks for a file name; Ctrl+Shift+S saves a
separate copy. Files use the versioned `*.machine.toml` format in `machines/`
relative to the working directory, or `FLUIDSIM_MACHINE_DIR` when set. Coordinates
and dimensional values are stored in SI units; inspector fields show their units.

Open/Saved files refreshes the library and provides separate Edit and Play
buttons. The scenario browser discovers saved machines each time it opens.
The document is validated before saving, and the written temporary file is read
back through the same loader before replacement. Unsaved changes prompt before
opening a different design, returning to the menu or closing the window.

Version 2 adds explicit fuel/control parts, control wires, imported port locations,
cam profiles and shaft losses. Version 1 files still load, but cylinders no longer
receive automatic fuel; add a connected carburetor or injection ECU to an older
engine design. The importer currently supports four-stroke layouts with uniform
ducts. Two-stroke crankcase/scavenge assemblies and profiled silencers are not yet
imported. Existing engine TOML files retain their separate schema.

Version 3 stores `point_diameters_m`, one diameter in metres per `points_m` entry,
for each pipe. Version 1 and 2 pipes load with their former linear taper sampled
at each point's arclength, preserving the original shape and volume. Saving writes
version 3. Inserted points inherit the interpolated diameter; moving a point keeps
its assigned diameter. Undo/redo and duplicated assemblies retain the full profile.
Version 4 also saves instrument channels, tap positions and lambda references.
Versions 1 through 3 still load. Recorded samples are exported separately as CSV.

Version 5 saves connection ports and methods by stable names instead of enum
indices. Custom chamber ports retain paired coordinate/key lists. Versions 1
through 4 migrate on load, including legacy aliases of a shared ideal junction.
Saving writes version 5; existing files are not rewritten until explicitly saved.
Port descriptors now identify gas, rotational, translational, Boolean, Number
and legacy ECU-assignment domains. Only implemented parts appear in the picker;
declaring a domain does not create its future components.

Version 6 adds explicit shafts and mechanical configurations. Loading versions 1
through 5 creates a visible shaft and any required speed drive/load, preserves
cylinder phase offsets and retargets legacy shaft instruments. Saving writes
version 6 with named mechanical connections; no existing file is changed merely
by loading it. Copy/paste and assemblies retain internal mechanical attachments
and instrument targets; external attachments remain unresolved.

Version 7 adds sensor attachments with stable IDs and named kinds, host/reference
bindings, normalized pipe taps and crank offsets. Part/sensor ID counters survive
save/load so deleted identities are not reused. Versions 1 through 6 still load.
Version 8 also saves a separate typed logic graph with stable node/pin keys,
parameters, references and independent canvas positions. Saving writes version 8;
loading alone does not rewrite an existing file.

## Sensor attachments

Open `machines/sensor-bench.machine.toml` for a ready-to-run demonstration of all
six sensor assemblies, a filling tank, fixed valve and independently driven shaft.

Select a physical part and open **Sense**. Only supported sensor buttons are
enabled: pressure/MAP and gas temperature/IAT on gas storage, pipes and environment
boundaries; differential pressure on two such taps; signed total mass flow on a
pipe; crank speed/position on an explicit shaft; TPS on a throttle or carburetor.
Right-click a pipe and choose **Add sensor here...** to use the clicked arclength
location. Otherwise a new pipe sensor starts at 50%. Move its tap in Sense.

For differential pressure, add the positive tap first. Select the reference
physical part, return to Sense, switch to **Reference (-) tap** and choose
**Bind reference to selected part**. The output is positive pressure minus
reference pressure, in pascals. Absolute pressure outputs use pascals absolute;
temperature uses kelvin; total mass flow uses kg/s, positive from pipe Start to
End. A volume has no unique through-flow direction, so flow sensors require a pipe.

The ideal crank pickup supplies signed angular speed in rad/s, crank angle in
0..2pi radians and a Boolean synchronized output. The pickup's configurable
reference offset applies to its angle, while the runtime retains the shaft ID
and unwrapped crossings. Zero speed while stopped is valid. This is an ideal
pickup, without tooth acquisition or cam-phase inference. TPS reports mechanism
opening fraction, including the existing ECU throttle response, rather than
substituting pedal demand for a fixed opening.

Sensors sample once per simulation audio sample and display sample time and
validity during Test. Number outputs have filled green dots; Boolean outputs have
filled red dots. Attached sensors introduce no gas storage or flow resistance,
and do not use any of the eight recorded meter channels. Use their Logic
references to wire sensor-driven ECUs; the labeled legacy ECU retains its
compatibility behavior.

Click an S-numbered marker to inspect its sensor. Previous/Next browses all
attachments, including unresolved ones. To rebind, select a compatible physical
part, reopen Sense and choose **Bind host to selected part**. Deleting a host
keeps the sensor and its former host label; missing/incompatible bindings show
invalid outputs rather than ordinary zero readings. Copy/paste and assemblies
remap internal sensor hosts; omitted external references remain unresolved.
Creation, binding, pickup offsets and removal require Build and support undo/redo.

These sensors measure gas temperature and total mass flow. Fresh-air MAF, cam
phase, lambda and material/head temperature sensors follow their own roadmap
stages and physical models.

## Logic editor and runtime

`machines/logic-compressor-bench.machine.toml` demonstrates an automatic air
supply: tank pressure feeds below-threshold hysteresis (120/150 kPa absolute),
an AND gate combines demand with a master switch, and a command node owns the
compressor motor's enable field. A numeric control supplies angular speed. The
saved defaults run the demonstration from Test. Choose **Logic** or **Split**
in the workspace toolbar to inspect its graph beside the physical machine.

The Logic library offers node categories, search and an Objects list. Pick a node,
then click the canvas to place it. Drag node headers to arrange the graph; Shift
and a selection rectangle select groups. Middle drag pans, wheel zooms about the
pointer, Home fits the active view, and F focuses its selection. Switching views
keeps the camera, canvas navigation, selection and running simulation. In Split,
click the desired pane to choose its navigation/inspector context.

Drag between compatible pins, or click a pin and then its target. Inputs are
hollow rings; outputs are filled circles. Boolean is red and Number green. One
output can fan out. Starting from a connected input rewires it atomically;
rejection leaves the original connection intact. Right-click a pin to disconnect
its wires. Escape cancels a pending connection. The library filters compatible
node kinds while a pin is pending, and a newly placed numeric node adopts that
pin's quantity/reference. Other numeric schemas are configured in the inspector.

Select a node to edit its name, parameters, quantity and pressure reference.
Numbers use the units shown on their fields/pins (SI internally). Enter applies
a text edit; Escape cancels it. Invalid text remains editable. Hover pins for
type, direction, units, validity, supported ranges and required/default metadata.
Combinational-cycle candidates highlight their cycle nodes and report the path.
H opens diagnostics; clicking a signal warning reveals the affected node.

Create sensors in 3D **Sense**, then choose **Show Logic** to reveal their reference.
The **Command** button on supported physical parts creates/reveals a command
reference. Its inspector chooses a command function and compatible physical
target. Selecting a sensor/command node selects that physical host; **Focus in
3D** opens Split and focuses the host. Reference nodes do not add gas storage or
duplicate a physical sensor/actuator.

During Test, node topology, schemas, bindings, control ranges and initial memory
require Build. Safe constants, thresholds and canvas layout remain editable.
Click switch controls, hold momentary buttons, drag sliders, or type into numeric
controls on their nodes. Paused control changes queue for the next physics sample;
their control widgets identify queued values while pin values stay frozen. Momentary
buttons release on focus loss, leaving Logic, or stopping Test. Manual Test inputs
do not silently overwrite their configured initial states. Readouts show compact
UI-sampled trends; recorded meter channels and CSV export remain separate.

Ctrl+C/V copies nodes and internal wires; Ctrl+D duplicates, Delete removes, and
Ctrl+Z/Y undo/redo. Same-document sensor copies reference the same sensor entity.
Copies pasted into another document detach external sensor references and keep
their labels. Pasted command nodes require an explicit new target so they cannot
take over an existing actuator field accidentally. Copying physical assemblies
remaps their internal sensors, command targets and connected control harnesses.

The graph runtime supports typed controls, Boolean gates, comparisons, arithmetic,
mapping, selectors, sensors, commands, displays and explicit one-tick delays.
Each audio sample evaluates the graph before physics and holds commands during
fluid substeps. Unknown types/ports, incompatible quantities, multiple drivers
and combinational cycles are rejected. Required unconnected inputs block Test.
Missing measurements and math faults carry invalid status; motor/valve commands
apply their declared inactive fallback rather than retaining a previous command.

The graph is saved in `[logic]` tables, including independent canvas positions.
Physical inspector controls identify signal-owned fields; existing manual or ECU
controls cannot simultaneously own them. Existing engine ECUs retain their
labeled legacy compatibility model; new sensor-driven presets use explicit
measurements as described below.

## Sensor-driven ignition and Alpha-N EFI

Open `sensor-ignition-bench.machine.toml` or `sensor-alpha-n-bench.machine.toml`
from saved machines for a working 3000 RPM test bench. The first uses a physical
carburetor; the second transports fuel from an attached intake injector. Both
have crank-to-ECU wiring visible in **Logic**. Press Test to run, then inspect
inputs and physical parts in Logic/3D or Split.

Select an ECU and cycle its preset between **Legacy ideal**, **Crank ignition**
and **Alpha-N EFI**. Sensor presets assign only cylinders through blue links;
choose **Show ECU connector in Logic** and connect crank speed and angle from
one physical pickup. Alpha-N also requires a throttle-position sensor. No driver
demand wire is needed for a manually adjusted throttle. The cylinder's **Pickup
TDC deg** is its calibrated TDC in the sensor's wrapped crank coordinates; for a
pickup offset of zero, a cylinder physical phase of 90 degrees has TDC at 270.
Crank-only ignition is wasted spark, without hidden cam/cycle synchronization.

For EFI, select an intake chamber and choose **Attach fuel injector**, then
choose its Alpha-N fuel ECU. Scroll its properties to set injector capacity,
initial fuel mass, fuel temperature, finite/ideal rail supply and cylinder-dose
count. A common-plenum injector can deliver several cylinder doses; their total
must match the ECU's assigned cylinders. The ECU's **Fuel RPM**, **Fuel TPS** and
**Fuel cell** fields edit the calibrated table (RPM rows, TPS columns, displayed
mg per cylinder per four-stroke cycle). This is an open-loop calibration, not a
measurement of trapped air mass.

Required input faults, stale or mixed pickups, and pickup/engine shaft mismatch
cut new spark events and EFI delivery. Constants and arithmetic cannot substitute
for physical crank timing. Previously ignited fuel finishes its physical burn.
The ECU inspector reports sensor faults and rev limiting; injector hosts report
flow and remaining fuel. Ignition maps and RPM limits allow live tuning. Fuel
maps, injector setup, strategy and pickup calibration require Build.

Fuel delivery currently uses a declared regulated rail and continuous/batch-average
vaporized fuel addition into the gas volume. There is no liquid rail-pressure
sensor or sequential pulse-width/evaporation model yet. Format 9 saves the new
bindings and calibrations; older machines continue loading without being rewritten.

## Speed-density EFI

Open `sensor-speed-density-bench.machine.toml` for the minimal MAP/IAT engine
example. Select **Speed-density EFI** in the ECU preset cycle and choose **Show
ECU connector in Logic**. Connect crank speed/position, an absolute-pressure MAP
pickup in the intake manifold and a gas-temperature IAT pickup at the intake.
TPS is not required for this basic preset. Missing or invalid measurements cut
fuel and new ignition events; the controller does not read hidden cylinder charge.

In the ECU properties, **SD displacement cc** is the calibrated swept volume per
cylinder. **SD target AFR**, air gas constant and the VE table determine the
open-loop estimate `MAP * displacement * VE / (R_air * IAT)`. **SD VE RPM** gives
the rows and **SD VE MAP kPa** the columns; **SD VE cell %** edits row-major table
values. Values outside the table axes use its edge calibration. These settings
require Build; the ignition map and rev limiter still permit live tuning.

Injector attachments can target Alpha-N or speed-density ECUs. Their explicit
capacity and finite/ideal rail supply continue to limit actual delivered fuel.
The dry ideal-gas estimate does not measure fresh-air fraction under intake-gas
dilution and currently has no warm-up, acceleration or lambda corrections. Format
10 saves this strategy and its calibration while preserving loading of versions
1..9.

## Architecture and further work

The proposed expansion is documented in the
[machine systems roadmap](MECHANICAL_BUILDER_PLAN.md): typed ports and logic,
explicit shafts, pneumatic parts, sensor attachments and sensor-driven ECU
presets, with one integrated delivery order. See the linked implementation
progress for completed parts and the remaining planned features.

`MachineDocument` stores parts with stable IDs, local geometry and explicit port
connections. `MachineSimulation` compiles that document into the existing
`Pipe1D`, `Volume0D`, `FourStrokeCylinder`, `BoundarySystem`, `Solver` and
`MechanicalSystem` components.
Shaft, ECU, cam, combustion and fuel-metering updates run once per audio sample,
as in the original engine scenarios. Gas transport and pressure-operated check
valves retain CFL substeps. Compiled part/gate lists avoid repeated graph scans.
The editor consumes snapshots while testing and owns its document separately.
Pipe meshes are cached until their local route or diameters change; transforms
and pressure colors reuse the mesh. Part icons share a cached texture atlas.

The editor includes fifteen part types, gas and mechanical example circuits, four preset imports,
save/load, group transforms, pipe routing, shared nodes, undo/redo, selection
copy/paste, reusable assemblies, and Build/Test. Remaining workshop work is
focused on port-picking and control-wire visibility in dense assemblies, clearer
group-edit feedback, property help, and adjustable port placement. New machine
types, gears and clutches remain on the component roadmap; explicit shafts are implemented.

### Next session

Continue the active component goal: explicit shafts, flywheels, drives, brakes
and six basic sensor assemblies are implemented and verified. The typed logic
runtime, persistence, physical commands and basic Logic/split editor are integrated
with thirteen focused suites passing at the editor milestone. Sensor-driven
ignition/Alpha-N presets, grouped ECU inputs, pickup calibration and explicit
injector attachments are now integrated, saved and tested with actual combustion
in two new benches. Speed-density EFI now adds a third working bench with actual
MAP/IAT inputs, calibrated VE/displacement, saved bindings and workshop controls.
Fifteen focused suites pass. Continue stage 4 with physical
needle/shutoff/regulator/relief valves and pressure-switch control; see the next
physical component slice in the progress file. Keep advanced graph UX/operator panels on the UI
backlog. See [component progress](COMPONENT_IMPLEMENTATION.md). Preserve the
existing uncommitted working tree and user-edited machine files.

### Historical session notes

The user asked to stop polishing and launch the current build on 2026-10-30.
The updated desktop executable was built and launched with
`machines/single-450-imported.machine.toml`. Changes are saved locally and remain
uncommitted. Preserve the existing working tree.

Continue with small usability refinements, particularly port picking and control
wire visibility in dense assemblies, group-edit feedback, and property help.
The 2026-10-31 usability pass added validated connection previews, click-position
bend insertion, focus selection and navigable machine checks. It also corrected
the OpenGL/SFML state handoff so controls remain visible after raw 3D rendering.
If the reported 16,000 RPM stop persists, reproduce it with the user's exact
machine/settings: controlled tests passed through 24,000 RPM and the free bench
settled around 17,500 RPM, so a universal 16,000 RPM cap was not reproduced.
Legacy version 1 engine files need an explicit carburetor or injection ECU now.

Workshop performance was fixed on 2026-10-30. Arclength meshing, sample-rate
control updates, compiled gate lists and cached rendering reduced flat6 simulation
cost from 104.4 to 8.8 us/sample at 3,000 RPM and 35% pedal. It now uses 98 cells
and approximately one CFL substep/sample, matching the native layout's mesh.
The importer positions its metering body to allow a longer outlet stub while
preserving the inlet endpoints, total route length and gas volume. Untouched stock
imports were refreshed; custom saved designs retain their authored geometry.
Flat6 and V8 audio-driven playback kept real time with no measured underruns.
See the [performance report](../verification/performance/2026-10-30/workshop-report.md)
for timings, validation and reproducible commands. Further work can focus on the
usability items above and closer calibration parity with native engine scenarios;
the workshop still represents its metering hardware as explicit editable parts.

## Checks

`fluidsim_machine_tests` covers centerline/profile volumes, rotated tanks,
connection snapping, malformed graphs, file round trips, closed/open throttle
behavior, shared nodes, group transforms, explicit fuel sources, ECU cut duration,
carburetor-only combustion, preset imports, vacuum pumping and an EFI bench.
`fluidsim_machine_builder_tests` checks projection and picking, world rotations,
mouse-driven translation, Shift selection, assembly duplication/deletion, undo
and Build/Test transitions. Assembly checks cover connected subset copies,
air/control endpoint remapping, geometry and probe persistence, cross-document
paste, library saving/browsing/insertion, and insertion undo/redo. Escape and
explicit Menu/window exit paths are checked separately.
Its `--preview <directory>` option writes editor screenshots for layout review.
It also checks pipe-cache invalidation, transform/pressure cache reuse, deleted
parts and the icon atlas. Physics checks cover route-knot-independent meshing,
real short-pipe CFL limits and pump sample-rate refinement.
Additional checks cover non-mutating connection previews, incompatible air/control
pins, occupied ports and collapsed pipes; shared fuel-source diagnosis; perspective
bend insertion with undo/redo; and check-to-part navigation. Preview mode also
verifies rendered UI pixels after both scene and icon rendering.
Instrument checks cover probe persistence, exhaust AFR/lambda after combustion,
conserved fuel-origin transport through solvers and junctions, pause/step/slow
playback, live tuning without a reload, locked geometry, live undo/redo and CSV
channel units. The [instrument verification report](../verification/performance/2026-10-31/workshop-instruments.md)
records the playback checks with eight channels active.
`fluidsim_machine_tests --rpm-sweep` checks high RPM and a 30-second free-running
acceleration trace with the ECU rev limiter disabled.