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: 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. 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 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 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.