@adatechnology/game-vehicles-driving 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Fernandes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# @adatechnology/game-vehicles-driving
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Driving for vehicles, without three.js and without a game. The arcade driver is the car of the game, extracted: a pure step over a state, with every number an option.
+
+```ts
+import { createArcadeDriver, vehicleCorners } from '@adatechnology/game-vehicles-driving'
+
+const driver = createArcadeDriver({ maxForward: 20 })
+driver.place(0, 0, 0)
+const world = {
+  blocked: (x, z, yaw) => vehicleCorners(driver.spec, x, z, yaw).some(([a, b]) => isSolid(a, b)),
+  bodies: () => zombies.map((z) => (z.alive ? z : undefined)),
+}
+const { state, events } = driver.step({ throttle: 1, brake: 0, steer: 0, handbrake: false }, dt, world)
+// events: crash, noise (crash, engine, horn), run_over (kill, knock, push), horn
+```
+
+The driver never touches a game: the host applies damage, shakes the camera, kills the bodies and plays the sounds from the events. Tested against the game's own `carUpdate` cut from `jogo.js` (positions and events frame by frame).
+
+## Semi-simulation
+
+`createSemiSimDriver(spec)` is the driving the Frota document asks for: a single rigid body with a low centre of mass, a spring and damper on each wheel measured against the ground under it (`world.ground(x, z)`), longitudinal and lateral tyre forces apart inside a friction circle, an automatic gearbox with a simulated RPM, a handbrake that locks the rear wheels, surfaces (`dry_asphalt` 1.0, `wet_asphalt` 0.75 with aquaplaning above 90 km/h, `dirt` 0.65, `grass` 0.55, `mud` 0.4 that bogs a vehicle without four-wheel drive, `blood` 0.5) and damage that changes how it drives (`driver.condition`: a flat tyre pulls to its side, a damaged suspension rolls more, an engine under 30% fails at full throttle and can die uphill). Fuel use follows the RPM, the cargo and the engine (up to +40% when wrecked). `semiSpecFromStats` builds a spec from the design ratings; `impactEnergy`, `bodyDamage`, `vehicleDamageFromImpact` and `speedLoss` are the run-over formulas of section 08. There is no team code for it: the document's numbers are the tests, and no golden is claimed.

package/dist/index.d.ts

@@ -0,0 +1,405 @@
+/** What the player (or an AI) asks of the vehicle in one step. */
+interface DriveInput {
+    /** 0..1, accelerates (and brakes hard against a reverse move). */
+    throttle: number;
+    /** 0..1, brakes hard against a forward move, reverses from a stop. Throttle and brake together cancel. */
+    brake: number;
+    /** -1..1, positive steers to the left (the game's A key), as the yaw grows counter-clockwise seen from above. */
+    steer: number;
+    handbrake: boolean;
+    /** The horn this step. */
+    horn?: boolean;
+}
+/** The position and motion of the vehicle. Yaw 0 points to +x; the forward vector is `(cos yaw, -sin yaw)` on (x, z). */
+interface DriverState {
+    x: number;
+    z: number;
+    yaw: number;
+    /** Signed speed along the forward vector, m/s. */
+    v: number;
+    /** Current steering angle, radians (smoothed toward the input). */
+    steer: number;
+    /** Seconds until the engine noise is next emitted. */
+    noiseTimer: number;
+}
+/** A body the vehicle can run over. */
+interface DrivingBody {
+    x: number;
+    z: number;
+}
+/** What the vehicle drives through. All hooks are optional except `blocked`. */
+interface DrivingWorld {
+    /** True when a vehicle at (x, z) with this yaw overlaps something solid. `vehicleCorners` lists the points the game tests. */
+    blocked(x: number, z: number, yaw: number): boolean;
+    /** The bodies that can be run over right now, indexed as the host indexes them; a dead or absent one is `undefined`. */
+    bodies?(): ReadonlyArray<DrivingBody | undefined>;
+}
+type DrivingEvent = 
+/** A hard hit (above `crash.minSpeed`): the host damages the vehicle by `damage`, shakes the camera, hurts the driver when `hurtDriver` is above 0. */
+{
+    type: 'crash';
+    speed: number;
+    damage: number;
+    shake: number;
+    hurtDriver: number;
+}
+/** A noise the horde can hear. */
+ | {
+    type: 'noise';
+    radius: number;
+    x: number;
+    z: number;
+    source: 'crash' | 'engine' | 'horn';
+}
+/** A body hit above `runOver.killSpeed`: dies, limbs come off; the vehicle takes `vehicleDamage`. */
+ | {
+    type: 'run_over';
+    outcome: 'kill';
+    index: number;
+    speed: number;
+    vehicleDamage: number;
+}
+/** A body hit between `knockSpeed` and `killSpeed`: it loses `damage`, is stunned and thrown with (`vx`, `vz`); the vehicle slows by `slow`. */
+ | {
+    type: 'run_over';
+    outcome: 'knock';
+    index: number;
+    speed: number;
+    damage: number;
+    stunSeconds: number;
+    vx: number;
+    vz: number;
+    slow: number;
+}
+/** A body hit below `knockSpeed`: the horde holds the vehicle (it slows) and the body is pushed aside by (`dx`, `dz`). */
+ | {
+    type: 'run_over';
+    outcome: 'push';
+    index: number;
+    speed: number;
+    dx: number;
+    dz: number;
+} | {
+    type: 'horn';
+};
+interface StepResult {
+    state: DriverState;
+    events: DrivingEvent[];
+}
+/** A driver turns inputs into motion. */
+interface Driver {
+    readonly state: DriverState;
+    step(input: DriveInput, dt: number, world: DrivingWorld): StepResult;
+    /** Puts the vehicle somewhere, standing still. */
+    place(x: number, z: number, yaw: number): void;
+}
+
+interface RunOverRules {
+    /** Above this speed (m/s) a body is knocked down. */
+    knockSpeed: number;
+    /** Above this speed a body is killed. */
+    killSpeed: number;
+    /** Knock damage is `speed² * knockDamage`. */
+    knockDamage: number;
+    /** Seconds a knocked body is stunned. */
+    stunSeconds: number;
+    /** Fraction of the vehicle speed given to a knocked body. */
+    throwFactor: number;
+    /** Sideways speed added to a knocked body. */
+    sideKick: number;
+    /** The vehicle keeps this fraction of its speed after knocking a body. */
+    knockSlow: number;
+    /** Damage the vehicle takes for each body killed. */
+    killVehicleDamage: number;
+    /** Below `knockSpeed` the vehicle slows by `exp(-holdDrag * dt)` for each body in the way. */
+    holdDrag: number;
+    /** Metres added around the vehicle's footprint when testing a body. */
+    margin: number;
+}
+interface CrashRules {
+    /** Below this speed an impact is only a bump (no event, but the vehicle still bounces). */
+    minSpeed: number;
+    /** Above this speed the impact damages the vehicle by `speed * damage`. */
+    damageSpeed: number;
+    damage: number;
+    /** Camera shake is `speed / shakeDivisor`. */
+    shakeDivisor: number;
+    /** Above this speed the driver is hurt by `speed * hurtFactor`. */
+    hurtSpeed: number;
+    hurtFactor: number;
+    /** The speed after an impact is `v * bounce`. */
+    bounce: number;
+    noiseRadius: number;
+}
+/** The numbers of the game's drivable car (G 70188-70290). Every one is an option. */
+interface ArcadeSpec {
+    length: number;
+    width: number;
+    accel: number;
+    /** Deceleration when accelerating against a reverse move, or braking against a forward move. */
+    brakeAgainstMotion: number;
+    reverseAccel: number;
+    /** Coasting drag: `v *= exp(-drag * dt)`. */
+    drag: number;
+    handbrakeDrag: number;
+    maxForward: number;
+    maxReverse: number;
+    /** Largest steering angle, radians. */
+    steerMax: number;
+    /** The steering angle follows its target by `min(1, steerResponse * dt)`. */
+    steerResponse: number;
+    /** Distance used in `yaw += steer * v / wheelbase * dt`. */
+    wheelbase: number;
+    engineNoiseInterval: number;
+    engineNoiseBase: number;
+    engineNoiseSpeedFactor: number;
+    hornNoiseRadius: number;
+    crash: CrashRules;
+    runOver: RunOverRules;
+}
+declare const defaultArcadeSpec: ArcadeSpec;
+type ArcadeOptions = Partial<Omit<ArcadeSpec, 'crash' | 'runOver'>> & {
+    crash?: Partial<CrashRules>;
+    runOver?: Partial<RunOverRules>;
+};
+/** The eight points the game tests for a wall: the four corners, the middle of the front and rear, and the middle of both sides. */
+declare function vehicleCorners(spec: Pick<ArcadeSpec, 'length' | 'width'>, x: number, z: number, yaw: number): Array<[number, number]>;
+/**
+ * The arcade driver: the game's car, extracted. A pure step function over `DriverState`: no three.js, no game. Port of `carUpdate`
+ * (jogo.js 70233-70290) with the same order of operations, so a scripted run gives the same positions and events.
+ */
+declare function createArcadeDriver(options?: ArcadeOptions): Driver & {
+    readonly spec: ArcadeSpec;
+};
+
+type RunOverOutcome = 'push' | 'knock' | 'kill';
+/** What a vehicle moving at `speed` (m/s) does to a body it touches: pushes it (and is held), knocks it down, or kills it. */
+declare function runOver(speed: number, rules?: Partial<RunOverRules>): RunOverOutcome;
+
+/** A kind of ground the tyres run on. */
+interface Surface {
+    id: string;
+    /** Multiplier of the tyre grip (dry asphalt = 1). */
+    grip: number;
+    /** Above this speed (km/h) the tyres float: grip drops linearly to `grip * aquaplaningFactor` over `aquaplaningBand` km/h. */
+    aquaplaningKmh?: number;
+    aquaplaningFactor?: number;
+    aquaplaningBand?: number;
+    /** A vehicle without four-wheel drive sinks: its rolling resistance becomes the spec's `bogResistance`. */
+    bogs?: boolean;
+}
+/** The table of the Frota document, section 03 (Surfaces). Every number is a default a game can replace. */
+declare const defaultSurfaces: readonly Surface[];
+interface SurfaceOptions {
+    packs?: ReadonlyArray<{
+        surfaces?: readonly Surface[];
+    }>;
+    patch?: Readonly<Record<string, Partial<Surface>>>;
+    remove?: readonly string[];
+}
+interface SurfaceRegistry {
+    get(id: string): Surface;
+    readonly surfaces: readonly Surface[];
+}
+/** The registry of surfaces: the document's table, plus packs, patches and removals by id. An unknown id falls back to dry asphalt. */
+declare function createSurfaces(options?: SurfaceOptions): SurfaceRegistry;
+/** Grip of a surface at a speed, with aquaplaning. */
+declare function surfaceGrip(surface: Surface, speedMetresPerSecond: number): number;
+
+interface FuelModel {
+    /** Litres per second at idle. */
+    idleRate: number;
+    /** Extra litres per second at full throttle and redline. */
+    fullRate: number;
+    /** Extra consumption per unit of cargo mass over the vehicle's own mass (0.5 = +50% when the load equals the vehicle). */
+    loadFactor: number;
+    /** Extra consumption of a wrecked engine (0.4 = up to +40% at zero health). */
+    damagedEngineExtra: number;
+}
+declare const defaultFuelModel: FuelModel;
+/**
+ * Litres per second: it depends on the RPM, the throttle, the weight of the cargo and the state of the engine
+ * (Frota document, section 04: "a damaged engine spends up to 40% more").
+ */
+declare function fuelRate(model: FuelModel, rpmFraction: number, throttle: number, loadRatio: number, engineHealth: number): number;
+
+interface SemiWheel {
+    /** Metres ahead of the centre of mass (negative behind). */
+    x: number;
+    /** Metres to the right of the centre line. */
+    z: number;
+    steer?: boolean;
+    drive?: boolean;
+    /** The handbrake locks it. */
+    handbrake?: boolean;
+}
+interface SemiSimSpec {
+    /** Kilograms. */
+    mass: number;
+    /** Yaw moment of inertia, kg·m². Default `mass * (wheelbase² + track²) / 12`. */
+    yawInertia?: number;
+    /** Height of the centre of mass above the ground, metres. Lower = less roll and pitch. */
+    centreHeight: number;
+    wheels: readonly SemiWheel[];
+    wheelRadius: number;
+    fourWheelDrive: boolean;
+    /** Air drag: `0.5 * 1.2 * Cd * A`, in kg/m. */
+    drag: number;
+    /** Rolling resistance coefficient on hard ground. */
+    rolling: number;
+    /** Rolling resistance of a vehicle that sinks on a `bogs` surface without four-wheel drive, while it is trying to move. */
+    bogResistance: number;
+    maxSteer: number;
+    /** Total brake force, newtons, split by the wheel loads. */
+    brakeForce: number;
+    engine: {
+        idleRpm: number;
+        peakRpm: number;
+        redlineRpm: number;
+        peakTorque: number;
+    };
+    /** Gear ratios, first to last. */
+    gears: readonly number[];
+    reverseRatio: number;
+    finalDrive: number;
+    /** Share of the engine torque that reaches the ground. */
+    efficiency: number;
+    /** Upshift above this fraction of the redline; downshift under `downshiftRpm` fraction. */
+    upshiftFraction: number;
+    downshiftFraction: number;
+    suspension: {
+        restLength: number;
+        spring: number;
+        damper: number;
+    };
+    tyre: {
+        /** Peak friction coefficient on dry asphalt. */
+        friction: number;
+        /** Lateral force per radian of slip, as a multiple of the wheel load, before saturating. */
+        corneringStiffness: number;
+    };
+    tank: {
+        capacity: number;
+    } & Partial<FuelModel>;
+}
+/** What is wrong with the vehicle, each from 0 (gone) to 1 (new). The host fills it from `kit.zoneOverall` or from a destructible. */
+interface VehicleCondition {
+    /** Health of each wheel in the order of `spec.wheels`. Under 0.2 the tyre is flat. */
+    tyres?: readonly number[];
+    engine?: number;
+    suspension?: number;
+}
+interface SemiInput extends DriveInput {
+    /** Forces a gear (1-based, 0 = neutral, -1 = reverse). Absent = automatic. */
+    gear?: number;
+}
+interface SemiGround {
+    /** Height of the ground under the point, metres. Default 0. */
+    height?: number;
+    /** Id of the surface. Default `dry_asphalt`. */
+    surface?: string;
+}
+interface SemiWorld {
+    ground?(x: number, z: number): SemiGround;
+}
+interface SemiState {
+    x: number;
+    z: number;
+    yaw: number;
+    /** Body-frame speeds: forward and to the right, m/s. */
+    u: number;
+    w: number;
+    /** Yaw rate, rad/s, positive turning left. */
+    yawRate: number;
+    /** Ride height of the centre, pitch (nose up) and roll (right side down). */
+    height: number;
+    heightRate: number;
+    pitch: number;
+    pitchRate: number;
+    roll: number;
+    rollRate: number;
+    rpm: number;
+    /** Gear in use: 0 neutral, -1 reverse. */
+    gear: number;
+    engineOn: boolean;
+    /** Stuck: a 2WD vehicle on a bogging surface. */
+    bogged: boolean;
+    fuel: number;
+    /** Load on each wheel, newtons. */
+    loads: number[];
+    /** Slip of each wheel (1 = sliding). */
+    slip: number[];
+    steerAngle: number;
+}
+type SemiEvent = {
+    type: 'stall';
+} | {
+    type: 'bogged';
+} | {
+    type: 'aquaplaning';
+    wheel: number;
+} | {
+    type: 'shift';
+    gear: number;
+} | {
+    type: 'out_of_fuel';
+};
+
+/** A mid-size passenger car, so a game can start from numbers that drive like a car. Every field can be replaced. */
+declare const defaultSemiSpec: SemiSimSpec;
+interface SemiSimOptions {
+    surfaces?: SurfaceRegistry;
+}
+interface SemiDriver extends Omit<Driver, 'step' | 'state'> {
+    readonly spec: SemiSimSpec;
+    readonly state: SemiState;
+    condition: VehicleCondition;
+    /** Sets the load carried, kilograms; the mass, the wheel loads and the fuel use follow. */
+    setCargo(kg: number): void;
+    /** A surface that overrides the ground under the wheels for `seconds` (blood after a run-over). */
+    contaminate(surfaceId: string, seconds: number): void;
+    /** Fills the tank (litres). */
+    refuel(litres: number): void;
+    step(input: SemiInput, dt: number, world?: SemiWorld): {
+        state: SemiState;
+        events: SemiEvent[];
+    };
+}
+/**
+ * The semi-simulation driver (Frota document, section 03): a single rigid body with a low centre of mass, a spring and damper on each wheel
+ * measured against the ground under it, separate longitudinal and lateral tyre forces inside a friction circle, an automatic gearbox with a
+ * simulated RPM, a handbrake that locks the rear wheels, surfaces with their grip, and damage that changes how it drives. No team code exists
+ * for it: the numbers are the document's and the tests check them.
+ */
+declare function createSemiSimDriver(specification?: Partial<SemiSimSpec>, options?: SemiSimOptions): SemiDriver;
+
+/** Kinetic energy of a vehicle against a body: `0.5 * mass * speed²` (joules, with kg and m/s). Frota document, section 08. */
+declare const impactEnergy: (vehicleMass: number, relativeSpeed: number) => number;
+/** Damage to the body that was hit: `energy * bumperMultiplier * zoneFactor`. The zone factors (head, torso, legs) belong to the game. */
+declare const bodyDamage: (energy: number, bumperMultiplier: number, zoneFactor: number) => number;
+/** Damage to the vehicle: `energy * 0.04 * (1 - frontArmor)`, with the armour from 0 to 1. */
+declare const vehicleDamageFromImpact: (energy: number, frontArmor: number, factor?: number) => number;
+/** Speed the vehicle loses: `bodyMass / (vehicleMass + bodyMass) * speed`. */
+declare const speedLoss: (bodyMass: number, vehicleMass: number, speed: number) => number;
+
+/** The design ratings of a vehicle (the shape of `fleetStats` in `game-vehicles-fleet`; any object with these fields works). */
+interface DesignStats {
+    /** 0-10. */
+    acceleration: number;
+    /** 0-10. */
+    handling: number;
+    maxSpeedKmh: number;
+}
+interface BodyDimensions {
+    mass: number;
+    wheelbase: number;
+    track: number;
+    fourWheelDrive?: boolean;
+}
+/**
+ * A semi-simulation spec for a two-axle vehicle from its design ratings: the grip follows the handling, the torque follows the acceleration,
+ * and the air drag is set so that the top gear tops out at the design top speed.
+ */
+declare function semiSpecFromStats(stats: DesignStats, body: BodyDimensions, base?: Partial<SemiSimSpec>): SemiSimSpec;
+
+export { type ArcadeOptions, type ArcadeSpec, type BodyDimensions, type CrashRules, type DesignStats, type DriveInput, type Driver, type DriverState, type DrivingBody, type DrivingEvent, type DrivingWorld, type FuelModel, type RunOverOutcome, type RunOverRules, type SemiDriver, type SemiEvent, type SemiGround, type SemiInput, type SemiSimOptions, type SemiSimSpec, type SemiState, type SemiWheel, type SemiWorld, type StepResult, type Surface, type SurfaceOptions, type SurfaceRegistry, type VehicleCondition, bodyDamage, createArcadeDriver, createSemiSimDriver, createSurfaces, defaultArcadeSpec, defaultFuelModel, defaultSemiSpec, defaultSurfaces, fuelRate, impactEnergy, runOver, semiSpecFromStats, speedLoss, surfaceGrip, vehicleCorners, vehicleDamageFromImpact };