Machines

Package @ferret/physics-mechanisms, capability machine.

What it is for#

Use it wherever something turns something else: a car's gearbox and differential, a crane winch with a brake, a windmill driving a millstone, a paddle wheel that sweeps crates off a belt, a turbine feeding a generator. The capability does not make torque by itself. Engines come from combustion, generators and motors from electric. Machines is what connects them to loads, and what decides how fast everything ends up turning.

How to think about it#

A machine is a small network. The nodes are shafts: each one spins at one speed and has inertia, so it takes time to speed up. The links are couplings that force a relation between two speeds: a gear pair makes them proportional, a clutch makes them equal while it grips, a brake pins one to zero.

Torque is added by drivers: a motor, an engine, a turbine, or a load, which is just a negative driver. Every step the network works out the speed each shaft must have so that all couplings are satisfied at once. This is exact even for stiff ratios, so a 1:100 reduction does not wobble.

Nothing is free. Each gear mesh passes on only part of the torque (its efficiency); the rest turns into heat, and the network keeps the account. Work done by drivers equals what the loads took, plus losses, plus what the shafts store as spin. A page of numbers that does not add up is a sign something is wrong with the setup.

Choosing a coupling#

Clutches and brakes take a command between 0 and 1: the pedal or lever position. A brake starts released and a clutch starts engaged, which is the usual surprise when "nothing moves".

Using it#

import { Drivetrain } from '@ferret/physics-mechanisms';

const train = new Drivetrain();
const motorShaft = train.shaft({ name: 'in', J: 0.1 });
const wheel = train.shaft({ name: 'out', J: 0.5, b: 0.5 });   // J: inertia, b: drag that grows with speed
train.speed('motor', motorShaft, () => 10);                     // 10 rad/s
train.gear('mesh', motorShaft, wheel, 20, 40, { efficiency: 0.95 });
train.step(1 / 240);

A reduction of 20 teeth to 40 turns the wheel at half the motor's speed, in the other direction, with about twice the torque less the losses.

In a game you hand the drive train to the capability, so it advances with the world:

import { machines } from '@ferret/physics-mechanisms';

const host = world.addService(new PhysicsHost({ capabilities: [machines(train)] }));
host.enable('machine');

Connecting to the scene#

• A mesh that turns. Give the shaft a node name and axis: the scene node of that name rotates with the shaft. Wheels, fans, gauges.
• A paddle, a turntable, a crane jib (bind). The shaft turns a kinematic body around a pivot. What the world does back to the body, such as a crate in the way, comes back as a load on the shaft, so a paddle slows when it pushes something and the motor stalls when it jams.
• A free wheel (couple). The shaft turns a dynamic body held on its axis, through a viscous coupling. The body keeps its momentum, and the shaft slips against a load it cannot move.

What drives and what loads#

• A motor, engine or load is a drive(shaft, fn) where fn(omega, angle, time) returns a torque. A load is a negative number.
• Wind and water turbines are drivers: windTurbine takes the radius and a wind speed, waterTurbine takes flow and head. Both obey the physical limits: no wind turbine can pull more than 59 % of the wind's power (Betz), and a water turbine delivers efficiency × density × gravity × flow × head.
• Pumps, fans and compressors are loads (pumpLoad): the shaft pays flow times pressure rise divided by efficiency.
• propeller gives thrust and a torque load from speed.
• A piston engine from combustion plugs in as drive(crank, (w, th) => engine.torque(w, th)). Give the crank a flywheel inertia (J of 0.1 to 0.2) so the speed does not jerk with every stroke.

Things that break#

A gear with a limit, or a shaft with a diameter and shear strength, breaks when the torque passes it. A broken part simply stops transmitting, and the event machine:break { element, torque } says which. lewisForce gives the bending limit of a tooth from its material, module and width; toothContactPressure and STEEL_FLANK do the same for surface wear.

Backlash leaves a gap between teeth where nothing is transmitted; closing it at speed loses the energy of the knock.

A motor with a driver that sits below stall.speed for stall.time seconds raises machine:stall. A clutch starting or stopping slipping raises machine:slip; the heat of the slip is in the coupling's loss, and slipHeats in links turns it into heat in a housing.

Parameters#

Commands#

machine.info, machine.set { element, command }, machine.state (speeds, torques, energy), machine.step { dt, substeps? }.

machine.set also takes an object for an element with a model ({ element: "gearbox", command: { gear: 3 } }) and names a control that is not a coupling (throttle, brake); machine.state adds models and controls. A manual gearbox is described in gearbox.

Cost#

Each substep solves a dense system the size of the number of couplings. Dozens of machines are cheap. Hundreds of couplings in one drive train get expensive; keep independent machines in separate Drivetrains.

When it does not behave#

Worked scenarios with numbers (gearbox, planetary set, differential, clutch, breaking gear, turbines) are in the tests: tests/unit/examples/physics-mechanisms.test.ts.

Speed sources and housings#

train.speedSource(name, shaft, { speed, ramp }) makes a shaft of infinite inertia that sets its own speed (a water-wheel axle, a motor on a governor). Gears, belts and clutches behind it still carry real torques, so a gear can strip and a clutch can slip while the source keeps turning. src.setSpeed(w, ramp) goes to a new speed along a linear ramp; src.torque and src.power read what it delivers.

A shaft can name a housing (an object with torque(vector, dt)): whatever changes the shaft's angular momentum (a motor, a load through a gear, friction) puts the opposite torque on the housing, once per step, as the mean of that step along the shaft's axis. The capability that owns the housing body turns it into kernel.applyTorque. A shaft without a housing is fixed to the world. The shaft's speed is relative to the housing; the housing's own turning does not feed back into it.

Reference#

machines, Drivetrain, Shaft, Coupling, windTurbine, waterTurbine, gasPower, pumpLoad, propeller, lewisForce.