box3dvehicleplugin

A car made of box3d rows from one description, driven by throttle, brake and steer.

#Putting it in a scene

List it after box3d and before render3d. The scene's sim lists the box3dvehicle kind from #plugins/box3dvehicle/box3dvehicle.sim.ts, and the scene has one box3dvehicle row for each car. The row holds the car's controls. On its first step the plugin spawns the car's parts as box3d rows: a chassis, a wheel for each corner, and a wheel joint from each wheel to the chassis. The row then holds their ids. The actor entry's pos and rot say where the car is made, and the plugin takes them off the row once it has. Name the plugin in world.box3d.mods.kinds, so box3d is handed the parts' entries and the scene's world.box3d lists none of them.

"world": {
  "box3d": { "subStepCount": 4, "static": [], "kinds": {}, "mods": { "ground": "terrain3d", "kinds": ["box3dvehicle"] } },
  "box3dvehicle": {
    "chassis": "chassis", "wheel": "wheel", "joint": "wheelJoint",
    "hit": { "speed": 3, "damage": 5 },
    "mods": { "gravity": "box3d", "land": "terrain3d", "bodies": "hitscan3d", "strike": "hitscan3d" },
    "vehicles": {
      "buggy": {
        "body": { "length": 3.6, "width": 1.8, "height": 0.7, "mass": 1100, "center": [0, -0.15, 0], "friction": 0.4,
                  "cabin": { "at": -0.2, "length": 1.8, "width": 1.5, "top": 1.2, "topWidth": 1.3, "height": 0.6 } },
        "bodies": {},
        "axles": [
          { "at": 1.2, "track": 1.6, "mount": 0.1,
            "wheel": { "radius": 0.4, "width": 0.3, "mass": 25, "friction": 1.2, "rollingResistance": 0.01 },
            "spring": { "stiffness": 40000, "length": 0.35, "travel": 0.3, "sag": 0.12 },
            "damper": { "bump": 2500, "rebound": 3500 },
            "bumpStop": { "length": 0.06, "stiffness": 80000 }, "antiRoll": 8000, "driven": false, "steered": true },
          { "at": -1.2, "driven": true, "steered": false, … }
        ],
        "engine": { "spinSpeed": 60, "spinTorque": 400, "brakeTorque": 900, "coastTorque": 30 },
        "steering": { "angle": 0.5, "hertz": 8, "dampingRatio": 1, "maxTorque": 3000 },
        "look": {
          "paint": { "body": 12597547, "cabin": 12597547, "trim": 2236962, "glass": 8956671, "light": 16774608, "tail": 13369344, "amber": 16750848,
                     "tyre": 1710618, "rim": 8421504, "chrome": 14540253, "seat": 3355443, "hook": 13369344, "spring": 13369344, "damper": 3355443, "arm": 5592405 },
          "segments": 24, "spokes": 6, "rim": 0.6, "coils": 6, "coilRadius": 0.05, "wire": 0.012, "arm": 0.025,
          "lock": 1.6,
          "points": {
            "seat": [-0.3, 0.45, -0.38],
            "gripL": { "at": [0.25, 0.75, -0.55], "part": "steer", "turn": [0, 0, 0, 1] }
          }
        }
      }
    }
  }
},
"prefabs": {
  "box3dvehicle": { "vehicle": "buggy", "throttle": 0, "brake": 0, "steer": 0 }
}

The rear axle in the example repeats the front axle's other keys. A car is driven by whatever writes its throttle, brake, steer and gear: a rule writing them onto the row, or a seat through the car's acts. A rule that makes a car in a step makes it with vehicle, which spawns the row with its parts made. What a car does while nobody drives it is up to the game.

The car's forward is its chassis's +x, up is +y, and left is −z. A car's wheels are listed axle after axle, the left wheel (−z) then the right (+z).

#Properties

Read from world.box3dvehicle. A child scene inherits it from the manager scene.

The fleet

Hitting bodies

Each step, every body the bodies mod hands that the chassis's box reaches, while the chassis moves at hit.speed m/s or faster, is struck through the strike mod, once a step, on its part nearest the box. The box is the body's length, height and width, without the cabin. A capsule is met as itself, and a cylinder as the segment up its middle with its radius round it. The chassis must be moving toward the body, unless the body stands inside the box, in which case it is struck whichever way the chassis moves. The body's row's hit act is handed { damage, by, part, point, dir, what: "body", speed }: damage is hit.damage times the chassis's speed in m/s, by the chassis's id, point where on the body the box met it, dir the unit way the chassis moves, and speed its speed. hitscan3d's bodies leaves out a body lying off, so a body that goes off once it is struck, as one lying dead, is not struck again.

A vehicle

One entry of .vehicles. The body, the wheels, the joints and the drawing are all made from it. Lengths are metres, masses kilograms, angles radians.

body

axles

A list with one entry for each axle. Each makes two wheels.

engine

A petrol or electric car's row carries gear: −1 is reverse, 0 neutral, and for petrol 1 and up are the gears. For an electric car, and for a petrol car with automatic, any forward gear is drive. Each step the plugin writes rpm and torque on the row. On such a car a throttle below 0 is the brake pedal. On a direct-drive car it drives the wheels backwards.

look

Colours are numbers, 0xRRGGBB.

With look.model, the model's own nodes place the lamps by the start of their names. Every node named beam… throws a beam of lights.beam, a spot light aimed along the node's +x, and its dip is the node's own turn. Every mesh named, or under a node named, tail…, reverse… or amber… takes the car's tail, reverse or amber lens material. A look with model and no lights has no lamps. Every node named steer… that is not under another is a steering wheel, which turns with the steering about its own x: its +x runs down the column into the dash, +y up its face and +z to the right.

look.lights

Every light is made with the car and kept, at no intensity while off, so switching one never changes how many lights a frame draws. None casts a shadow. The lights can be found in the render3d scene by name: box3dvehicle.beam for each headlight's spot light, box3dvehicle.brake and box3dvehicle.reverse for the two point lights, box3dvehicle.tail and box3dvehicle.backup for the drawn lenses of the tail and reverse lights,, box3dvehicle.model for a model's group on the chassis, and box3dvehicle.steer for the drawn steering wheel.

look.open

An open jeep, every panel rounded, built to the body's box round its cabin. All lengths are metres.

#Methods

Driving

Closed acts on the car's row. A seat reaches a car only through a player row that holds it, which passes them on. Each takes only a finite number and keeps it to its range.

pedal( v )

Sets the one pedal of an arcade car, −1 to 1, kept on the row as pedal. A car that picks its own forward gear brakes with it held back while it rolls forward. Once it goes slower than its vehicle's pedal.stop along its heading, it is put in reverse and the same pedal drives it backwards. Pushed forward, the pedal brakes the car while it rolls backwards, and below stop puts it back in drive. Any other car takes the pedal as its throttle.

throttle( v )

Sets the throttle itself, −1 to 1, and lets go of the pedal.

steer( v )

Sets the steering, −1 to 1. Positive turns left.

brake( v )

Sets the brake, 0 to 1.

shift( by )

Moves the gear by 1 or −1. A manual petrol car goes from reverse up to its top gear. An electric car, or an automatic, goes between reverse, neutral and drive. A direct-drive car has no gear.

The row

Fields of the box3dvehicle row.

Rules

From #plugins/box3dvehicle/box3dvehicle.sim.ts.

vehicle( w, name, pos, rot ) : Row

Spawns a car of the fleet's vehicle name at pos turned rot, with its parts made and its joints driven, and returns its row. The row is spawned whole, as a row spawned in a step is sent before any hook of it runs.

scrap( w, car )

Ends a car and every part of it: its joints, its wheels, its chassis and its row.

design( world, car ) : Vehicle

The vehicle a car row is, the one of the scene's fleet that its vehicle names.

ride( vehicle, g ) : Ride[]

What each axle is on this car, standing still under gravity g in m/s². Each entry is { load, carried, hz, bump, rebound, clearance }: each wheel's load in newtons, the mass it carries in kg, how often the chassis bounces on the springs there in hertz, how near the dampers come to stopping that bounce without passing the rest point when pushed in and pulled out (1 stops it exactly), and the gap under the body in metres.

loads( vehicle, g ) : number[]

Each wheel's share of the chassis's weight in newtons, standing still on flat ground: the shares that hold the chassis up and level about its centre of mass.

standing( vehicle ) : number

How high the chassis origin stands over flat ground at rest, in metres: a wheel's radius plus the spring's length less its sag, less the mount's height, taking the highest of the axles.

pull( w ) : number | undefined

How hard the scene's gravity pulls in m/s²: the length of what its gravity mod hands back, or undefined when it names none.

automatic( vehicle ) : boolean

Whether a car picks its own forward gear, so its driver only chooses reverse, neutral or drive: an electric car, or a petrol car with automatic.

pedals( vehicle, car ) : { brake, reverse }

How hard a car's row brakes, 0 to 1, and whether it drives backwards. The brake is its brake, or its throttle below 0 where that is the brake pedal. It drives backwards in reverse gear, or with the throttle below 0 for a direct-drive car.

torqueAt( curve, rpm ) : number

A petrol engine's torque at full throttle at rpm, in N·m: the curve's points joined by straight lines, its ends held past them.

pointOf( vehicle, name ) : { at, part?, turn? } | undefined

The look's point name, a bare [x, y, z] given as { at }, or undefined for a name the look has not.

On the page

Through plugins.box3dvehicle.

point( id, name ) : THREE.Object3D | undefined

The empty of the look's point name on the car whose box3dvehicle row is id, as it is drawn this frame. Its world matrix is this frame's once the plugin's afterTick has placed the car. Undefined while the car is not drawn, for a name its look has not, and, for a point on a model's steering wheel, until the model has come.

#Mods

Name them in world.box3dvehicle.mods.

• box3d
  gravity: gravity(w) hands back the gravity the car's parts fall by, a vector. Its length is the g that every spring's preload and every figure of the ride is worked out in. A car's parts fall by box3d's gravity and nothing else, so a scene must name a gravity: a car in a scene that names none fails on its first step.
• terrain3d
  land: land(plugins) is the page's ground, an object whose height(x, z) is the ground there. Dust and tracks need it, and with none no wheel is on the ground and none is thrown or laid. It must be listed before this plugin, and a scene with dust or tracks that lists it after, or not at all, fails.
• hitscan3d
  bodies and strike, for Hitting bodies. bodies(w) hands back the bodies a car can hit, each { id, kind, pos, shapes }, its shapes capsules and upright cylinders: every body a shot can hit now. strike(w, row, struck) hurts one, calling its row's hit act, as a rule's, with what struck it.

Two more are named in the same place, and any plugin that hands them back may be named. grip(w, x, z) hands back how well the ground at [x, z] grips, a multiplier: each step every wheel's friction is set so that its contact grips as the wheel's friction times the grip under it. With none, every wheel grips at its wheel.friction everywhere. drag(w, x, z) hands back the ground's rolling resistance at [x, z], in newtons per newton of load: each step every wheel on the ground is pushed against the way it goes by that times what its corner's spring pushes it down with, never by more than takes its share of the car to a stop that step. With none, the ground holds no wheel back.

box3dvehicle gives three mods.

• box3d
  kinds: the chassis, wheel and joint kinds, made from each car's vehicle. The chassis is the body's box and its cabin's hull, with the body's friction. Each wheel is a ball of its axle's wheel.radius with contact events on, so its row says what it touches, and with its mass and inertia set outright. Each joint is a wheel joint from the chassis to the wheel's inner face.
• scatter3d
  hollows: name it in world.scatter3d.mods as { hollows: ["box3dvehicle"] }. hollows(plugins) gives each car's body, from the bottom of its box to the top of its cabin, and each of its wheels as a box, so scatter3d draws no grass, bush or branch inside a car.
• interact
  point and object: name them in world.interact.mods as { point: "box3dvehicle", object: "box3dvehicle" }, so a body getting in, driving or getting out is placed at, and reaches for, the look's points. point(w, car, name) is { at, yaw }, the point's world place this step: at is the chassis row's pos plus the point's at turned by the chassis row's rot, a point on the steering wheel taken with the wheel straight, and yaw is the radians the chassis's +z faces about world up, facing (sin yaw, cos yaw). Before the car's first step, the chassis is where the row says it will be made. It is undefined for a name the look has not. object(plugins, car, name) is the page's point(car, name).

#In the guide