Skip to content

Realistic Vehicle Physics

Jump to bottom
AntonIT99 edited this page Oct 12, 2026 · 17 revisions

Realistic Vehicle Physics

Flan's Mod Ultimate 2.0 can drive vehicle behavior from real-world specifications instead of the legacy hand-tuned numbers. A content pack declares figures a reference book actually lists, such as mass in kilograms and top speed in km/h, and the mod derives acceleration, drag, lift and terminal speed from them. Mechas can independently use RealMaxSpeedKmh as their chassis movement speed without activating a ground or aircraft propulsion profile.

RealMassKg is also the mass source for the separate optional normalized-health system used by driveables and AA guns. Physical armour, projectile penetration, vehicle damage, and AA-gun mass-scaled health are documented on Vehicle Armour and Damage.

Everything on this page is optional. A content pack that declares none of the Real* keys behaves exactly as it did before this system existed. No legacy key changed its meaning, its unit, or its default.

Contents

Units and Conventions

The mod's physical convention, already assumed by the in-game speed readout, is:

1 block  = 1 metre
20 ticks = 1 second

Every real-world speed therefore converts to Minecraft units as:

blocksPerTick = kmh / 3.6 / 20 = kmh / 72

Ground vehicles and aircraft then apply the speed scale for their class, realisticPlaneSpeedScale or realisticGroundVehicleSpeedScale. Mechas instead apply their installed-engine and addon speed modifiers; they have no separate global realistic-speed scale.

All Real* values are stored exactly as authored, in the units their key name declares. Scaling happens only at the moment a speed is converted for use; the stored value never changes.

Parameter Reference

All keys are case-insensitive, like every other content-pack key. A key that is present without a value counts as not specified, not as zero. Each Real… key also accepts an unprefixed alias with the same unit suffix (for example, MassKg for RealMassKg). If both spellings are declared, the Real… spelling takes priority, even if its value is blank or invalid.

Common

Key Unit Optional Independent Contributes to Valid range Fallback when absent
RealMassKg / MassKg kilograms yes no ground profile, aircraft profile, optional driveable/AA-gun normalized health greater than 0, finite Legacy physics/health. The legacy Mass key is not used as a substitute.
RealMaxSpeedKmh / MaxSpeedKmh km/h yes yes for mechas ground profile, aircraft profile, independent mecha movement greater than 0, finite Legacy ground/aircraft speed, or mecha MoveSpeed.
RealEnginePowerKw / EnginePowerKw kilowatts yes no ground profile, aircraft profile greater than 0, finite Legacy propulsion. Unrelated to PartType.EnginePower.
RealEnginePowerHp / EnginePowerHp mechanical horsepower yes no ground profile, aircraft profile greater than 0, finite Same as RealEnginePowerKw.
RealEnginePowerPS / EnginePowerPS metric horsepower (Pferdestärke) yes no ground profile, aircraft profile greater than 0, finite Same as RealEnginePowerKw.
RealEngineThrustKn / EngineThrustKn kilonewtons yes no aircraft profile greater than 0, finite Shaft power is used instead, if declared.

RealEnginePowerKw and RealEngineThrustKn are alternatives, not a pair. Use power for piston and turboprop aircraft, combustion and electric ground vehicles, and propeller-driven ships; use thrust for jets. Declaring both is allowed but logs a note: aircraft use the thrust, everything else uses the power.

RealEnginePowerHp and RealEnginePowerPS are the same value in a different unit, for when a reference lists horsepower instead of kilowatts. Mechanical (imperial) horsepower and metric horsepower differ slightly — use whichever one your source actually quotes:

  • RealEnginePowerHp: mechanical/imperial horsepower, 1 hp = 0.745699872 kW.
  • RealEnginePowerPS: metric horsepower / Pferdestärke / cheval-vapeur, 1 PS = 0.73549875 kW. This is the unit German, French, and most other European reference material quotes engine power in, and it is not the same number as RealEnginePowerHp for the same engine.

Both are converted internally to kilowatts, so everywhere else in the system only ever sees RealEnginePowerKw; there is no need to convert by hand. If more than one is declared, priority follows the order they are listed above, matching the "later key wins" convention used by every other legacy alias in this mod: RealEnginePowerKw < RealEnginePowerHp < RealEnginePowerPS.

Aircraft

Key Unit Optional Independent Contributes to Valid range Fallback when absent
RealWingSpanM / WingSpanM metres yes no aircraft profile, induced drag greater than 0, finite Legacy roll response from RollLeftSpeed / RollRightSpeed, and drag without an induced term.
RealWingAreaM2 / WingAreaM2 square metres yes no aircraft profile greater than 0, finite Legacy lift. The legacy WingArea key is not used as a substitute.
RealClimbRateMs / ClimbRateMs metres per second yes no aircraft profile (calibration only) greater than 0, finite A permissive default excess-lift allowance.
RealAirBrakeAreaM2 / AirBrakeAreaM2 square metres yes yes deployed air-brake drag greater than 0, finite Derived from RealWingAreaM2 when absent.

RealClimbRateMs is deliberately not required for the aircraft profile. It is a calibration input, not a vertical velocity: the aircraft still climbs because thrust and lift exceed drag and weight, and the climb rate only caps how much excess lift may be converted into a sustained climb.

Rotorcraft

A helicopter has no wing, so RealWingSpanM and RealWingAreaM2 have nothing to describe and the aircraft profile would never activate for one. Rotor geometry supplies both instead, and unlike an invented wing it is a published figure for every real rotorcraft.

Key Unit Optional Independent Contributes to Valid range Fallback when absent
RealRotorDiameterM / RotorDiameterM metres yes no aircraft profile, span and disc area greater than 0, finite No derived lifting surface, so a wingless craft cannot complete the profile.
RealRotorCount / RotorCount rotors yes no derived disc area whole number, at least 1 A single main rotor.

The derivation is:

span = rotorDiameter
area = rotorCount * pi * (rotorDiameter / 2)^2

so the reference area is the swept rotor disc, which is the quantity a helicopter's published disc loading is calculated from. The physics model then treats disc loading exactly as it treats wing loading on a fixed-wing aircraft.

The span deliberately stays one rotor wide on a tandem or coaxial layout: two rotors sweep two discs but the craft is not twice as wide, and span feeds the roll-inertia heuristic rather than lift.

An authored RealWingSpanM or RealWingAreaM2 always wins over the derivation, which is what a compound helicopter with real wings needs. A craft that declares neither a wing nor a rotor still has no lifting surface and still cannot complete the aircraft profile.

For how helicopters use rotor geometry, power, mass, speed and climb rate in flight, including fallback rules for incomplete profiles, see Helicopter Flight. These rotorcraft rules also apply to VTOL hover mode; the fixed-wing lift and stall rules apply in plane mode.

Ground Vehicles

Key Unit Optional Independent Contributes to Valid range Fallback when absent
DriveType enum yes yes traction, launch grip, hill climbing RWD, FWD, AWD, TRACKED, MARINE Inferred from Tank and FourWheelDrive. MARINE is never inferred.
RealMaxReverseSpeedKmh / MaxReverseSpeedKmh km/h yes yes reverse terminal speed greater than 0, finite Legacy MaxNegativeThrottle behavior.
RealTurnRateDegPerSec / TurnRateDegPerSec hull degrees/second yes yes for tracks; rolling vehicles need RealMaxSpeedKmh full-input hull steering greater than 0, finite Existing steering formula and engine multiplier.

DriveType also accepts the spellings long-lived packs already use: 2WD, Rear, RearWheelDrive, Front, FrontWheelDrive, 4WD, AllWheelDrive, FourWheelDrive, Track, Tracks, Tank, ContinuousTrack, and for marine craft Ship, Boat, Naval, Screw, Propeller, Waterjet, Paddle. Hyphens, underscores and spaces are ignored.

MARINE leaves the launch ceiling unscaled, because a propeller is not traction limited the way a wheel is, and keeps the grade response neutral. It is never inferred: the Boat and FloatOnWater keywords are also carried by amphibious wheeled and tracked vehicles, so inferring a marine layout from them would silently change the traction of every amphibian. A hull that wants it declares it.

Hull Steering

RealTurnRateDegPerSec defines the sustained hull yaw rate at full steering input, not turret traverse or steering-wheel speed. For example:

RealTurnRateDegPerSec 12

This gives a tracked vehicle a sustained 180-degree turn in 15 seconds at 20 TPS. Starting with centred controls adds the existing steering buildup time. Convert a measured turn with angleDegrees / seconds; a full revolution uses 360 / seconds. Use level firm ground and record steering system, gear, load, surface, and whether the timing includes startup. This is a yaw-rate approximation, not a model of the difference between neutral and braked-track steering systems.

A valid value takes precedence over TurnLeftSpeed, TurnRightSpeed, the legacy throttle scaling and installed-engine EngineSpeed, independently of whether a complete propulsion profile is present. Tracks still require a running engine and intact steering; one surviving track retains half turning authority. Both tracks destroyed disables turning. Ordinary left/right input remains the same when reversing.

Rolling vehicles require a positive RealMaxSpeedKmh as the reference speed. Yaw scales with signed forward speed divided by the scaled reference speed, capped at the authored rate. They cannot pivot at rest and reverse steering direction when rolling backward; coasting with the engine off remains steerable. To convert a measured rate at speed v, multiply by RealMaxSpeedKmh / v. A centre-path radius R in metres gives degrees((RealMaxSpeedKmh / 3.6) / R); verify the reference point and diameter/radius convention before using a published turning circle. This approximation does not simulate high-speed grip limits or rollover.

The angular rate itself is not changed by the global speed scale. For rolling vehicles the reference speed follows the class scale. Missing, non-positive or non-finite rates retain existing steering. forceLegacyVehiclePhysics bypasses the override, and PushSpeedKmh crew-pushed vehicles retain their existing controls. Both spellings are case-insensitive; the Real spelling wins even when invalid.

Aircraft Ground Steering

PlaneType also reads RealTurnRateDegPerSec / TurnRateDegPerSec, but its reference is 10 km/h ground taxi speed, rather than maximum flight speed. The value is the aircraft's heading rate at sustained full steering input. It scales with signed forward rolling speed and caps at the authored rate; a parked aircraft with the override active clears residual yaw rather than pivoting.

The override applies only with deployed gear, authored wheel positions and actual ground support. Engine-off coasting remains steerable, reverse taxi reverses the turn direction, and a destroyed steering part prevents controlled turning. Airborne rudder, bank, helicopter hover yaw and their legacy control modifiers retain their existing behavior. forceLegacyPlanePhysics bypasses the override. It is independent of a complete real-world propulsion/flight profile and is not multiplied by global aircraft speed scales or engine part speed.

Research taxi turn geometry, not a flight-turn-time statistic. A measured centre-path radius gives degrees((10 / 3.6) / radiusMetres) per second. A timed turn at a known ground speed converts as measuredRate * 10 / measuredSpeedKmh. Airport-planning nose, wingtip and outside-tire turning radii are different paths and need a documented conversion before use as an aircraft-centre radius.

The built-in category turn-rate inventory includes disclosed estimates where measurements are unavailable. Values of 0 for fixed mounts and non-taxiing craft mean no override, not immobilization. See the repository's docs/reports/driveable-turn-rate-research.md and CSV manifests for provenance. The plane-filed Admiral Hipper entry retains its vehicle counterpart's marine rate for compatibility, but this ground-only plane override does not control it afloat.

Marine

Key Unit Optional Independent Contributes to Valid range Fallback when absent
RealDraftM / DraftM metres yes yes flotation height greater than 0, finite Legacy constant Buoyancy lift.

RealDraftM only takes effect on a hull that actually floats, meaning FloatOnWater true or the Boat keyword.

Unlike the ground and aircraft profiles, the marine profile is not gated on the definition's category. It activates whenever the hull floats and all of the following are present and valid, whether the definition is a VehicleType or a PlaneType:

  • RealMassKg, or a displacement alias;
  • RealMaxSpeedKmh, or RealMaxSpeedKn;
  • one engine power key;
  • RealDraftM.

What makes a hull a hull is that it floats, not which folder the pack filed it under. So a ship authored under definitions/planes — as the bundled Manus ships pack does for the Prinz Eugen, with Mode Plane and Boat True — is still fully simulated: it gets marine propulsion, normalized health, armour and draft. It cannot complete the aircraft profile, which would demand a wing span and area, and being outside the GROUND category it never completes the ground one either. Neither matters, because the marine branch is the one a hull is meant to take.

A hull carrying only displacement and draft completes nothing and silently stays on the legacy MaxThrottle curve. Author the whole set or none of it, and confirm the result with /vehiclephysics.

Naval sources state displacement in tons and speed in knots, so four unit aliases exist. They are not separate quantities: each converts into the common key it duplicates and overrides it when both are present.

Key Unit Converts into Factor
RealDisplacementT / DisplacementT metric tonnes RealMassKg 1000
RealDisplacementLongTons / DisplacementLongTons imperial long tons RealMassKg 1016.0469088
RealMaxSpeedKn / MaxSpeedKn knots RealMaxSpeedKmh 1.852
RealMaxReverseSpeedKn / MaxReverseSpeedKn knots RealMaxReverseSpeedKmh 1.852

Priority within the mass group is RealMassKg < RealDisplacementT < RealDisplacementLongTons, matching how the engine power aliases already resolve. Long tons and metric tonnes differ by 1.6%, which is why they are separate keys rather than one "tons" key.

Keys That Are Deliberately Absent

There are no new keys for length, width, beam, wheelbase or track width. Those are derived from geometry the definition already declares:

Derived value Derived from
Length SetupPart core box depth
Width / beam SetupPart core box width
Height SetupPart core box height
Wheelbase Fore-aft spread of the declared WheelPosition lines
Track width Lateral spread of the declared WheelPosition lines

This is already accurate: the shipped S-100 Schnellboot's core box yields 35.1 m by 5.3 m against a real 34.9 m by 5.1 m.

Keys You Must Not Reuse

These legacy keys keep their legacy meaning and are never read as real-world values. Using them will not activate anything.

Legacy key Legacy meaning Real-world equivalent
Mass Unscaled legacy multiplier; several shipped packs set it to 1.0 RealMassKg
MaxSpeed / MaximumSpeed Blocks per tick RealMaxSpeedKmh
WingArea Dimensionless legacy lift multiplier RealWingAreaM2
MaxThrust Dimensionless legacy thrust value RealEngineThrustKn
EnginePower Gameplay value on engine PartType items RealEnginePowerKw
Width / Height Model pixels on MechaType derived from collision geometry

Activation Rules

Two categories of parameter behave differently.

Coupled Parameters: All Or Nothing

A propulsion profile activates only when every member of its required set is present and valid. A partial set changes nothing: the vehicle stays entirely on legacy propulsion rather than running half of each model.

Ground propulsion profile requires all of:

RealMassKg
RealEnginePowerKw
RealMaxSpeedKmh

Aircraft profile requires all of:

RealMassKg
RealMaxSpeedKmh
RealWingSpanM
RealWingAreaM2
RealEnginePowerKw  OR  RealEngineThrustKn

Each profile is also gated by category: ground keys on an aircraft, or aircraft keys on a ground vehicle, activate nothing.

Independent Parameters: Each On Its Own

DriveType, RealMaxReverseSpeedKmh and RealDraftM take effect individually.

Hill climbing has no separate authored parameter. A complete ground profile derives a forgiving uphill response from RealEnginePowerKw / RealMassKg and DriveType. Gentle slopes retain full propulsion, steeper slopes progressively reduce it, and even extreme block terrain retains a 20% crawl floor. Legacy vehicles retain their existing behavior.

UseRealisticVehicleHealth true is also independent from the propulsion profiles. Driveables need a valid RealMassKg and positive authored hitbox-health weights; AA guns need only a valid RealMassKg and receive one derived health pool. It does not activate real-world movement and is documented on Vehicle Armour and Damage.

Crew-pushed guns

PushSpeedKmh gives a ground VehicleType a walking-speed movement mode for wheeled emplacements. A positive value sets its full-throttle forward speed in km/h, independent of engine power, fuel, and the realistic speed scale. It takes precedence over both a complete real-world propulsion profile and legacy MaxThrottle. MaxNegativeThrottle still gates reversing; steering uses TurnLeftSpeed and TurnRightSpeed. The built-in anti-tank-gun category sets these controls and a 4 km/h push speed for PaK 40 and similar guns.

Resulting Modes

Mode Meaning
Legacy No usable real-world data. Behavior is unchanged from before this system.
Legacy + real-world overrides The coupled profile is incomplete, but at least one independent parameter is active.
Real-world derived The coupled profile is complete and owns propulsion.

Precedence and Fallbacks

Fallbacks are applied per value, not globally:

explicit real-world parameter
    > value derived from existing geometry or config
    > legacy parameter
    > legacy default

For overlapping systems, the order is:

complete real-world profile
    > legacy experimental flags (NewFlightControl, UseRealisticAcceleration)
    > legacy physics

The legacy experimental flags are not removed and still work on definitions that use them. They are simply outranked when a complete profile is present.

What the Real-World Profile Replaces

When the ground profile is active it takes over these behaviors completely, so none of them can double-apply:

Replaced Replaced by
Fixed 0.01 throttle acceleration Throttle becomes the driver's demand; the power model owns acceleration
UseRealisticAcceleration with legacy Mass RealEnginePowerKw over RealMassKg
MaxThrottle-derived target speed RealMaxSpeedKmh
Legacy 0.26 / 0.32 tracked and wheeled speed factors RealMaxSpeedKmh

When the aircraft profile is active it replaces the legacy Lift, MaxThrust, Mass, MaxSpeed and NewFlightControl flight model, and it replaces the legacy speed-dependent control curve with one normalized against the aircraft's own terminal speed.

Retained Gameplay Modifiers

These legacy fields keep working under the real-world profile, because they express authoring intent the source data cannot:

Retained Why
TurnLeftSpeed / TurnRightSpeed Aircraft handling trim; vehicle steering fallback when no valid RealTurnRateDegPerSec override applies
LookUpSpeed / LookDownSpeed / RollLeftSpeed / RollRightSpeed Aircraft control feel
MaxNegativeThrottle as a gate 0 still means the vehicle cannot reverse at all
EmptyDrag Extra drag on an unoccupied airframe
FoldWingForLand wing drag Not expressible in real-world data
WheelSpringStrength, WheelRadius Suspension feel
FallDamageFactor, CollisionDamage* Balance
Drag Still drives legacy drag; the derived model calibrates its own

Reverse behavior deserves a specific note. RealMaxReverseSpeedKmh caps reverse speed rather than scaling it, so MaxNegativeThrottle is never applied twice. A vehicle with MaxNegativeThrottle 0 has deliberately disabled reverse, and no real-world value can re-enable it.

Speed Scales

File: config/flansmodultimate-common.toml

["Vehicle Physics Settings"]
    forceLegacyPlanePhysics = false
    forceLegacyVehiclePhysics = false
    realisticPlaneSpeedScale = 1.0
    realisticGroundVehicleSpeedScale = 1.0
    realisticAircraftReferenceSpeedScale = 0.25
    realisticAircraftThrottleResponse = 3.0
    maxPlaneSpeedKmh = 10000.0
    maxVehicleSpeedKmh = 10000.0
Setting Expected value Default Range
forceLegacyPlanePhysics boolean false true / false
forceLegacyVehiclePhysics boolean false true / false
realisticPlaneSpeedScale decimal 1.0 0.1 to 1.0
realisticGroundVehicleSpeedScale decimal 1.0 0.1 to 1.0
realisticAircraftReferenceSpeedScale decimal 0.25 0.05 to 1.0
realisticAircraftThrottleResponse decimal 3.0 1.0 to 5.0
maxPlaneSpeedKmh decimal 10000.0 1.0 to 100000.0
maxVehicleSpeedKmh decimal 10000.0 1.0 to 100000.0

Aircraft and ground vehicles carry their own independent scale, so the two classes can be tuned against each other. The scale is selected by the definition's category, so a marine craft authored as a VehicleType follows realisticGroundVehicleSpeedScale, while a hull authored under definitions/planes is in the aircraft category and follows realisticPlaneSpeedScale and forceLegacyPlanePhysics instead — even though its propulsion comes from the marine profile. Mechas have no real-world profile of their own and are never scaled.

Effective conversion:

effectiveBlocksPerTick = (realMaxSpeedKmh / 72) * classSpeedScale
Value Meaning
1.0 100% real-world speed
0.75 75%
0.5 50%
0.25 25%

Only speeds are scaled. Mass, engine power, thrust, wing span, wing area, slope and draft are never scaled. Vehicles that declare no real-world parameters are unaffected at any setting.

Every speed a class owns follows its scale together — top speed, reverse speed, climb rate, the derived reference airspeed and the wheel look-ahead — so a slowed aircraft still takes off and stalls at sensible fractions of its own reduced top speed instead of becoming unflyable.

The settings are server-authoritative and are synchronized to clients along with the rest of the common config, so item tooltips on a multiplayer server show the server's effective values rather than the client's local file.

Global Legacy Overrides

forceLegacyPlanePhysics and forceLegacyVehiclePhysics take precedence over all other movement settings for their respective classes. When enabled, the runtime ignores the selected class's Real* movement profile, independent speed scale and hard speed cap, and restores the legacy movement clamp, wheel look-ahead and flotation behaviour. The vehicle switch also bypasses real-world drive type, reverse speed, hull turn rate, slope, draft and cornering loss; the plane switch bypasses derived fixed-wing propulsion, lift, control authority, manoeuvre drag and stall behaviour. Damage and health features are outside movement physics and are not disabled.

For fixed-wing aircraft using the ordinary legacy fallback, propulsion and powered motion correction decrease with the fraction of intact propellers. Losing every propeller stops propulsion; an aircraft with intact wings can continue gliding while it has airspeed. NewFlightControl already accounts for propeller damage in its acceleration path.

Enforced Speed Ceilings

maxPlaneSpeedKmh and maxVehicleSpeedKmh are a different mechanism from the scales. A scale changes what a driveable's top speed is; a ceiling refuses to let anything travel faster than a fixed figure, whichever path produced its velocity. They therefore apply to every plane and vehicle — legacy driveables, helicopters, VTOL and six-DOF craft included — not only to types running a real-world profile.

The ceiling scales the whole velocity vector, so the direction of travel is preserved rather than being clipped per axis, and it is completely inert while a driveable is slower than the ceiling. The defaults are high enough that they never engage; lower one to rein in a pack that authors absurd speeds.

They are unrelated to the internal movement clamp, which is an integration safety bound against runaway velocity and is not configurable.

The aircraft reference-speed scale is applied to the physical wing-loading result before the existing 45%-of-top-speed playability cap:

physicalReferenceSpeed = sqrt(2 * (mass / wingArea) * g / (airDensity * 1.4))
effectiveReferenceSpeed = min(
    physicalReferenceSpeed * realisticAircraftReferenceSpeedScale,
    effectiveTopSpeed * 0.45)

At the default 0.25, an aircraft with a physical reference speed of 138 km/h supports its weight at 35 km/h. This one effective reference speed drives lift, stall-like behaviour, stall recovery, and wheel release during takeoff. Derived aircraft therefore do not also apply the legacy TakeoffSpeed threshold. Set the value to 1.0 for the unscaled physical result. Legacy aircraft, helicopters, VTOL, and six-DOF craft are unaffected. A derived plane's item tooltip shows the resulting value as Minimum Flight Speed, in km/h.

Aircraft Throttle Response

realisticAircraftThrottleResponse is the exponent n applied to the throttle lever before it scales derived fixed-wing thrust:

thrust = (propellerEfficiency * power / airspeed) * throttle^n

It exists because a throttle lever and a speed readout do not have a linear relationship in reality, and some servers would rather they did.

At 1.0 the lever meters engine power, exactly as a real throttle does: half throttle is half of the rated output. Since level-flight drag power rises with the cube of airspeed, thrust balances drag at

speed = topSpeed * cbrt(throttle^n)

so half power still gives about 79% of top speed. This is why a real fighter cruises fast on a modest power setting and needs full emergency power only for the last few percent of its top speed.

Raising n trades that realism for a tidier HUD. At 3.0 the exponent cancels the cube root and the lever becomes linear in speed — but the engine is then producing only an eighth of its rated power at half throttle, which is not physical.

For a Bf 109 G-10 (3280 kg, 1800 PS, 685 km/h):

Throttle n = 1.0 (power-linear) n = 2.0 n = 3.0 (default, speed-linear)
10% 318 km/h (46%) 149 km/h (22%) 69 km/h (10%)
25% 432 km/h (63%) 272 km/h (40%) 171 km/h (25%)
50% 544 km/h (79%) 432 km/h (63%) 343 km/h (50%)
75% 622 km/h (91%) 568 km/h (83%) 514 km/h (75%)
100% 685 km/h (100%) 685 km/h (100%) 685 km/h (100%)

Top speed at full throttle is identical in every case; only the shape of the lever in between changes. Values below 1.0 reach high speed sooner still. Legacy aircraft, helicopters, VTOL, and six-DOF craft are unaffected.

The figures above assume level flight against the full drag model. The drag curve has a genuine minimum-power speed, so a low throttle setting is held honestly rather than optimistically; see How aircraft drag works.

The Throttle Lever

Holding the throttle key moves the lever progressively faster the longer it is held: the authored per-tick step is multiplied from half at the moment of the press up to a maximum reached after 30 ticks. A tap is therefore a fine nudge, while a long hold sweeps the whole range in a few seconds instead of tens of them. Every tick applies its own fractional step, so the lever never moves in visible jumps.

Driveable Keys Base step Full sweep
Aircraft Space / Left Ctrl 0.2% per tick ~3.9 s
Ground vehicles Q / E 1% per tick ~2.0 s

Aircraft ramp further, to eight times the base step, because their authored step is very fine; ground vehicles reach four times theirs. The ramp restarts whenever the lever is released or reversed, and, on a ground vehicle, whenever the lever passes through zero, so the change from drive to reverse is never made at sweep speed. Holding both keys at once holds the lever still.

The ground-vehicle lever travels on its own fine step rather than the momentary W / S pedal rate, so every setting in the range is reachable. This applies to all driveables, including those on legacy physics.

Holding Space immediately suppresses propulsion and pivot steering and overrides the W/S pedals and Q/E throttle keys in both realistic and legacy physics. The throttle lever still returns to neutral progressively, using the same accelerating step as holding its decrease-toward-zero key, stopping at neutral, while wheel-braking deceleration is applied as a physical speed limit instead of the former one-tick velocity cut.

Engine Parts

RealEnginePowerKw is the vehicle's reference powerplant, and the installed engine part remains a gameplay multiplier on top of it:

usable power = RealEnginePowerKw * PartType.EngineSpeed

EngineSpeed is a dimensionless gameplay value that defaults to 1.0, so a standard engine gives exactly the real-world figure and a better engine gives proportionally more. Engine upgrades therefore keep working.

PartType.EnginePower is deliberately not consulted by the real-world path. It is an arbitrary gameplay number, not kilowatts, and reinterpreting it as such would mix two unit systems.

Derived Values

Computed once when the content pack is loaded, not per tick:

Value Derived from
Power-to-weight (kW/kg) RealEnginePowerKw / RealMassKg
Thrust-to-weight RealEngineThrustKn and RealMassKg
Wing loading (kg/m²) RealMassKg / RealWingAreaM2
Roll inertia factor RealWingSpanM and RealMassKg
Drive type DriveType, or Tank / FourWheelDrive
Length, width, height Core collision box
Wheelbase, track width Wheel positions

Computed per tick from those, using the current speed scale:

Value Notes
Effective top speed blocks per tick
Effective reverse speed blocks per tick
Available acceleration Falls with speed, reaching zero exactly at top speed
Reference airspeed Stall-like speed from wing loading, scaled, then clamped for playability
Lift fraction Rises with the square of airspeed
Control authority Normalized against the aircraft's own top speed, then scaled per axis
Aerodynamic drag Parasitic plus induced, calibrated to balance thrust at top speed

How Ground Acceleration Works

Power-to-weight is an input, not the answer. Treating kW/kg directly as an acceleration would make it independent of speed, so the vehicle would either snap to its top speed or never reach it. Instead:

F_traction(v) = P / max(v, v_launch)     capped by a traction limit
F_resist(v)   = k * v²   with k chosen so the two balance at the top speed
a(v)          = (F_traction - F_resist) / m

Because the two forces balance exactly at RealMaxSpeedKmh by construction, the vehicle approaches its top speed smoothly and can never overshoot it. Gear ratios, engine RPM and tyre models are deliberately not simulated; a single acceleration ceiling stands in for the grip and gearing limits instead.

Steering also consumes forward speed. The current yaw rate and speed imply a lateral cornering acceleration; a bounded share is paid as longitudinal tyre or track scrub. A gentle bend therefore has a small cost, while holding full steer at speed prevents a vehicle from cornering forever at its straight-line maximum.

How Aircraft Drag Works

An aircraft pays two kinds of drag, and both are needed. Parasitic drag rises with the square of airspeed; induced drag — what the wing pays for making lift — falls with it, and dominates at cruise:

D(v) = k_parasitic * v²  +  k_induced / v²
k_induced   = 2 * W² / (rho * pi * span² * e)      with e = 0.75
k_parasitic chosen so D(topSpeed) equals available thrust

Calibrating the parasitic term against thrust at top speed keeps RealMaxSpeedKmh authoritative exactly as it is for ground vehicles, while the induced term supplies the drag the aircraft actually feels everywhere below it. Total drag is therefore a bucket curve with its minimum around a third of top speed, which is where a real airframe's maximum-endurance speed sits.

RealWingSpanM is what makes this work; an aircraft that declares no span falls back to the parasitic term alone.

Two guards keep it well behaved. The induced term may claim at most half the thrust budget at top speed, so a heavy short-span airframe still has a sane top speed, and below 12% of top speed it is held flat and faded out rather than diverging toward standstill.

A closed throttle additionally guarantees a minimum deceleration, standing in for the drag of an idled or windmilling propeller disc, which the authored data cannot express. It is gated on the lever rather than on thrust, because low thrust at low speed is ordinary cruise, not coasting.

Ground Handling

While an aircraft is on its wheels it tracks its nose in the horizontal plane only, and the vertical axis is left entirely to gravity, lift and the suspension. The undercarriage adds rolling resistance, and wheel braking on top of it once the throttle is closed, so a landing roll actually comes to a stop. Below walking pace with the throttle shut the aircraft is parked outright.

On a low-throttle landing roll, pitch and roll ease back toward the aircraft's authored resting pose. This removes any remaining bank gradually while leaving full-power takeoff rotation unaffected.

Stall Behaviour

Below 90% of the reference airspeed a nose-high aircraft lowers its own nose, scaled by both how slow it is and how steeply it is pointed up. The correction is a bias, not a takeover: the pilot keeps full authority, it never raises the nose, and it never pushes past level. It stands in for the angle of attack the derived model does not carry, and it makes hanging on the propeller until the aircraft mushes into the ground impossible.

Lift uses airspeed projected along the aircraft's nose rather than total world velocity, so falling vertically does not restore lift merely because total speed is increasing. Aerodynamic direction alignment can still redirect and damp the descent without treating it as lift, while regaining forward airflow restores the wing progressively. There is no separate downward stall force: sink comes from gravity exceeding the reduced lift below reference speed.

Control Authority

Control authority is normalized against the aircraft's own top speed rather than the legacy fixed breakpoints, which assumed a two-blocks-per-tick top speed and dropped authority to zero above three — the reason fast aircraft used to become uncontrollable. For more arcade-friendly reduced-throttle flight, all three axes build quickly from zero at a standstill, reach full authority at one tenth of top speed, and keep it through the low-speed range. They taper at high speed as the surfaces load up without ever reaching zero.

The three axes are scaled separately, because a real aircraft rolls fastest, pitches more slowly, and yaws slowest of all on the smallest surface. At full deflection and full authority a fighter with default handling modifiers rolls at about 100 degrees per second. Fixed-wing rudder yaw uses 80% of its former rate in both the derived and legacy flight models; helicopter yaw is unchanged. The authored RollLeftSpeed, LookUpSpeed, TurnLeftSpeed and their counterparts are retained unchanged as trims on top, and the slew rate is scaled by the roll inertia factor derived from RealWingSpanM and RealMassKg, so a heavy long-winged aircraft responds more slowly than a light one.

With keyboard and mouse roll input neutral, an airborne aircraft receives a very slow restoring roll moment toward horizontal. It scales with usable forward airflow for fixed wings or rotor authority for helicopters, yields immediately to the pilot, and is disabled for a fixed-wing aircraft missing either wing. Complete real-world profiles also scale the rate with the existing span-and-mass roll response; aircraft without those characteristics use a conservative default. Common config enableAircraftRollSelfLeveling disables the restoring moment globally when set to false.

Changing attitude also costs airspeed. The derived model applies additional drag from the aircraft's actual angular rates, weighted most heavily for yaw (fuselage sideslip), then pitch, then roll. The loss rises with airspeed and persists while angular momentum is still carrying the aircraft through the manoeuvre.

Mouse pitch and roll are normalized into the same stick range as the keyboard axes and pass through the same flap response. This fixes the former 20-degree direct mouse deflection versus roughly 9-degree steady key deflection. Keyboard pitch/roll remains active in mouse-control mode, so the two inputs can reinforce, cancel, or override each other without either receiving a larger authority.

Item Tooltips

Hold Shift over a driveable item. The tooltip shows the physics the vehicle is actually using, read from the same resolver the simulation uses, so the two cannot disagree.

The tooltip only shows authored real-world source values and the independently usable overrides. It deliberately does not show derived or Minecraft-effective values — converted speeds, ratios such as power-to-weight or wing loading, reference airspeed, or geometry derived from the collision box and wheel positions. Those stay fully available through /vehiclephysics, which reads the same resolved physics; the tooltip is meant to stay short.

When configured, the same tooltip also shows nominal hull/turret/part armour, authored plate slopes, normalized-health status, derived total HP, and per-part HP allocation. Effective armour is intentionally omitted because it depends on the incoming projectile direction.

A vehicle on the real-world profile:

Physics: Real-world derived
Mass (kg): 2890
Engine Power (kW): 993
Max Speed (km/h): 635
Wing Span (m): 11.23
Wing Area (m²): 22.48
Climb Rate (m/s): 17
  Control Trim (yaw / pitch / roll): 1 / 1 / 1

A vehicle on legacy physics:

Physics: Legacy
Max Throttle: 0.45
Max Reverse Throttle: 0.25
Drag: 1
Acceleration Model: Legacy fixed
Drive Type: Rear wheel drive (inferred)

A vehicle with independent overrides only:

Physics: Legacy + real-world overrides
Max Throttle: 1
Drag: 1
Acceleration Model: Legacy fixed
Drive Type: Tracked
Max Slope (°): 35

When the speed scale is not 1.0, an extra line makes it explicit:

Speeds scaled to 0.5x by the server config

Debugging

/vehiclephysics

Permission: Operator; executor: Player

Prints the full physics resolution for the driveable the player is riding, or the driveable item held in either hand. This is where every derived and Minecraft-effective value lives — effective speed, power-to-weight, wing loading, reference airspeed, derived geometry, and so on — none of which appear in the tooltip. It also answers the question the tooltip cannot: why is this vehicle on legacy physics.

The report contains:

  • Active mode, category and effective speed scale
  • Every authored Real* value, in its authored units
  • Whether each profile is complete, and which keys are missing if not
  • All resolved values, or the legacy source that is driving propulsion instead
  • Drive type, and whether it was explicit or inferred
  • Reverse, slope and draft overrides, or the legacy values in force
  • The movement safety clamp and wheel probe distance
  • Derived geometry
  • Authored armour and normalized-health allocation

Example:

/vehiclephysics

Malformed Real* values are also reported as content-pack errors in the log when the pack loads, naming the key and the offending value. A malformed optional value never aborts loading; it is dropped and the affected subsystem falls back.

Worked Examples

A Jeep on the full ground profile

RealMassKg 1113
RealEnginePowerKw 44
RealMaxSpeedKmh 105
DriveType AWD
RealMaxReverseSpeedKmh 12

MaxNegativeThrottle must still be greater than 0 for the reverse cap to apply.

A Spitfire on the full aircraft profile

RealMassKg 2890
RealMaxSpeedKmh 635
RealEnginePowerKw 993
RealWingSpanM 11.23
RealWingAreaM2 22.48
RealClimbRateMs 17.0

A jet, using thrust instead of power

RealMassKg 12700
RealMaxSpeedKmh 2120
RealEngineThrustKn 79.6
RealWingSpanM 9.96
RealWingAreaM2 30.0

At scale 1.0 this aircraft reaches 29.4 blocks per tick, which is why the movement safety clamp is raised for profiled vehicles. Consider a speed scale below 1.0 for jets on a normal server.

A boat with a real draft

Boat
FloatOnWater True
Buoyancy 0.08
RealDraftM 1.5

Without RealDraftM flotation checks the configured wheel anchors, including FloatOffset on vehicles. Floating planes receive Buoyancy for each submerged anchor, including ships authored as planes and using marine propulsion. With RealDraftM and an authored core box, the hull settles so the lowest corner of that box sits 1.5 m below the waterline, accounting for model scale and pose. The compact entity collision box is not a keel. Packs without a core box keep their wheel-based flotation even when a category supplies a historical draft.

EpicShip naval damage

EpicShip true (including the legacy spelling epicShip) enables naval damage rules on both vehicle-based and plane-based ships. It is off by default and requires Boat or FloatOnWater true. Ordinary ships retain wheel-based flotation, or draft-based flotation when they have a usable core box.

Boat
EpicShip true
Buoyancy 0.05

Declare damageable compartments with the normal SetupPart definitions:

  • buoyancy: its remaining health fraction reduces upward lift and caps forward and reverse throttle. With less than 10% health, sinking starts and propulsion stops once the origin is more than one block below the surface.
  • bow, stern, midsection: destroying any defined compartment causes sinking.
  • left and right: destroying a side causes sinking and listing toward that side. port and starboard are supported when the corresponding legacy side is not defined.

Undefined and zero-maximum-health compartments count as healthy. An older pack does not need to define every compartment, and existing part-health saves and server damage snapshots remain the source of truth.

The Labjac deep-water recovery formula is 0.3 × (1.1 × buoyancy fraction − 0.5). Partial buoyancy loss can therefore cause downward movement when deeply submerged. Destroyed hull compartments use a slow deep sinking target of −0.009 blocks per tick; near the waterline a doomed hull targets −0.5 blocks per tick. The modern response approaches those velocities smoothly and overrides healthy draft lift. Listing rates and limits preserve the fork's radians after conversion to degrees: roll grows by about 0.0286° per tick up to 85.94°, and pitch by about 0.0143° per tick up to 34.38°. Repairs allow the ship to level again.

Weapons, including passenger guns, require water at offsets (6, −4, 6), (−6, −4, −6), and (0, −6, 0) from the origin. These samples must be loaded; the check never loads chunks. Outside such a deep body of water, throttle is capped at ±0.3 and weapons are disabled. The buoyancy health cap also applies.

A critically damaged sinking ship is destroyed by the server once its origin is more than 15 blocks below the measured local water surface. This uses the normal configured destruction effects and passenger release. Shallow-water wrecks can remain on the bottom. Depth is measured locally, rather than against Labjac's global sea-level constant, and no repeated depth explosions are emitted.

Adding real data to a pack you do not control

Use the Category System to inject Real* keys into third-party definitions without editing their .txt files. Category properties are merged into the definition before parsing, so they behave exactly as if the pack had declared them.

Official Modern Warfare MIM-23 carrier

The tracked MIM-23 launcher uses an M727 HAWK carrier propulsion profile in both its source definition and the built-in vehicle category: 12,900 kg combat mass, 202 hp, and a 64 km/h road maximum. These figures come from the M727 specialist reference, which cites the vehicle's Army technical manuals. The unarmoured hull remains unarmoured. The 16 km/h reverse limit and 10 mm protection for each track are gameplay estimates, not verified historical specifications. Forward/reverse throttle and track steering are enabled; the existing model and weapon mounting are retained.

Limitations

These are known and deliberate for the current implementation.

  • Only fixed-wing aircraft use the new flight model. Helicopter, VTOL and six-degree-of-freedom craft keep their legacy behavior even with a complete profile, because their control models are not expressible in the same data.
  • Steering is an angular-rate approximation. RealTurnRateDegPerSec can override legacy steering and engine multipliers. Without it, existing steering remains. Derived wheelbase and track width do not yet drive a steering geometry model.
  • Mecha are always legacy. They share the driveable type hierarchy but have no real-world profile.
  • No gearbox. Gear ratios, engine RPM and clutch behavior are not simulated.
  • Collision response is still massless. RealMassKg does not yet affect how a vehicle pushes entities or how impacts resolve.
  • Very high speeds are untested in play. Client interpolation, chunk loading ahead of the vehicle, and collision resolution above roughly 8 blocks per tick have not been verified in a running game. Reduce realisticPlaneSpeedScale, or set maxPlaneSpeedKmh, if fast aircraft behave poorly on your server.

Clone this wiki locally