#Gears and turning parts

Example: Gear Works (a gear from a model, a data-declared clockwork motor, a placement guide).

Gears are part of the game, in Movement: Gear Size 1 to Gear Size 8 (16 teeth a size), Hollow Gear Size 3 to 8 (teeth outside and in, its middle open), Rack Gear and Gear Shaft. The palette shows a Gear tile (every solid size, Size 1 at first) and a Hollow Gear tile (Size 3 at first), each remembering the size last placed; while placing, + and − change the size and H switches solid and hollow. A placed gear is resized with the scale tool (E): drag across its face for its size (it is replaced by that size on the same axis, keeping its settings, wires and mount, in one undo step; the mirror twin follows) or along its axis for its thickness. Players place one next to another and the placement guide shows where they mesh (grey: the teeth would not touch; green: they mesh). Everything that follows lets a mod add its own — and they mesh with the game's gears and with every other mod's.

For now the game's own gears are hidden from the block palette until a player types /gears in the developer console (/gears off hides them again). They are only hidden: creations with gears load and run, "base": "Gear 16" works, and a mod's gear blocks always appear.

Gears simulate on the Jolt physics engine (Settings → Physics → Physics Engine). On PhysX they are drawn but do not turn, and the game says so once. Nothing a mod does changes that; kinetics.available() tells a server script which it is.

#How gears behave

• One module, one grid. The game's gears have 25 mm teeth (module 0.025) and tooth counts that are multiples of 16, so every pitch radius is a whole number of 0.2 m cells: gears of any size mesh when their edges meet on the build grid, and each takes only the cells its teeth reach. Gears only mesh with gears of the same module.
• Gears never turn by themselves. The game's gears have no controls: a gear is bolted to the part it is built on and turns only when that part does — on a servo, a Bearing (wire the Engine into the Bearing, not the gear) or a wheel. On a part nothing turns, it holds still. Gears on different turning parts drive each other through their teeth; a gear on a rotor meshing one on that rotor's own base stops it, and its Jammed channel says so. RPM and Angle read the turn of its part. Gears in older saves set to Own axle keep turning freely on it. A gear with a mechanism of your own (below) defaults to its own axle, where your drive turns it.
• Loads are real. Gears on different parts push on each other through their teeth, and overloaded teeth jump. Gears on axles of their own meshed on one part form one train, which costs the physics what one gear costs — tens of thousands are fine.
• No speed limit. An axle turns at whatever speed its drive and ratios give — hundreds of thousands of rpm — without the physics breaking, and a fast one steers its part like a gyroscope.
• Worms lock. A worm drives its wheel, but the wheel cannot turn the worm back.

#A gear block

Add gear to a block definition:

{
  "id": "great-wheel",
  "name": "Great Wheel 96",
  "base": "Cube",
  "model": "/models/great-wheel.glb",
  "gear": { "kind": "spur", "size": 6 },
  "spin": { "meshes": ["Wheel"] }
}

With size (1–8: 96 teeth and 1.2 m of pitch radius at size 6) the gear gets exactly the game's geometry for that size: a box (2 × size + 1) cells square and one deep, faces on the cells its rim covers, only those cells occupied (a hollow gear's middle stays free for other blocks), stretching only along its axle, and the game's own teeth drawn when there is no model. "hollow": true adds teeth inside (size 3 and up). With size, leave out the keys it decides (teeth, module, axis, centre, hubs, faceWidth, and the block's size).

From gear the game also gives the block the Gear mechanism: no controls, bolted to its part (above), RPM, Angle and Jammed on wires; for a motor, servo or brake, give the block a mechanism of its own. A gear given teeth instead of a size gets the older shape — hub faces on a half-cell grid, a round footprint, a collider a little smaller than its teeth — and meshes, but off the grid; the mod's log then says "add gear.size for grid placement". Every key below can still be set explicitly.

A block based on one of the game's gears ("base": "Gear Size 3") is a gear already: give it a model and a name and you have a new-looking gear with the same teeth. A gear table then changes only what it names: new teeth that are a grid size (a multiple of 16) make it that size, anything else that reshapes it (another module, axis or box) makes it a plain, off-grid gear. The older names ("Gear 24" …) still work as bases.

Gear models are taken as they are — in metres, about their own origin — rather than fitted to a block and centred like other models, because the teeth must sit exactly on the pitch circle the physics rolls. Model the axle along +Z with tooth 0 centred on +X. modelUnits, fit and centre still override that.

#Block shape, faces and spinning parts

These work on any block, gear or not.

#A mechanism in data

mechanism gives a block its own settings panel, keys, wires and — on anything that turns — a shaft drive. The engine runs it natively every physics step, exactly like the game's own parts; there is no per-step script.

{
  "id": "clockwork", "name": "Clockwork Motor", "base": "Gear 16",
  "mechanism": {
    "name": "Clockwork",
    "settings": [
      { "name": "Spring", "type": "choice", "options": ["Run", "Hold", "Coast"], "default": "Run" },
      { "name": "Speed", "type": "number", "default": 30, "min": 0, "max": 240, "unit": "rpm",
        "writable": true, "visibleWhen": { "Spring": "Run" } },
      { "name": "Torque", "type": "number", "default": 150, "min": 0, "max": 2000, "unit": "N·m" },
      { "name": "Wind", "type": "key", "default": "None" }
    ],
    "drive": { "modeSetting": "Spring", "modes": ["motor", "brake", "free"],
               "speed": "Speed", "speedUnit": "rpm", "torque": "Torque", "forward": "Wind" },
    "channels": [ { "name": "RPM", "source": "rpm" } ]
  }
}

Settings — up to 32, each { name, type, label?, hint?, section? }:

Any setting may add "writable": true (numbers and bools: a wire may set it while running) and "visibleWhen": { "Other": value or [values] } (shown only then; choices by option name). section is mode, controls, tuning or options.

drive (only on blocks that turn — a gear, or based on one):

A motor turns while commanded; a brake holds while commanded; a servo turns to its angle and holds it.

channels — values it reports on wires, each { name, source, unit?, hint? } where source is speed (in the drive's unit), rpm, angle (degrees, not wrapped), torque, command (-1…1 from keys and wires) or jammed. signal chooses what a wire carries when it names no channel (default rpm). Every number and bool setting is readable on wires as well.

The panel gets the rows a drive needs without declaring them: Toggle Mode and Require Seat when it has keys, Invert when engines may drive it, and Mount and Bearing Friction on a gear.

The mechanism's id is your.mod-id:<id> (default the block's id). Several blocks can share one: declare it on the first and write "mechanism": "clockwork" on the others.

#Placement guides

building.placement guides players placing a block type — what the game's gear guide does for gears. The function runs every frame of the drag (client scripts, building permission):

building.placement("clockwork", function(q)
  local s = q.suggested                          -- the game's own guide, for blocks it guides (gears)
  if not s or s.state ~= "valid" then return nil end
  return { position = s.position, rotation = s.rotation, state = "valid",
           label = s.label .. " · clockwork", settings = s.settings, attachTo = s.attachTo }
end)

q has position and rotation (where the editor would snap it), snapped, hit (position, normal, block), ray (origin, direction), scale, chosenRotation, creation and — for blocks the game guides — suggested (position, rotation, state, label, settings, attachTo).

Return a table to take over: position + rotation (world), state ("valid" green, "neutral" grey, "invalid" red, "default"), a short label by the cursor, settings the block is placed with, attachTo (a Block), and guides — circles { centre, normal, radius, state or color }, lines { from, to, … }, dots { position, radius, … }, up to 64 each. Without guides of your own the game's are kept. Return nil to keep the game's suggestion, false for no guidance. An error in the guide is logged and the block is left to the editor for a few seconds.

#The kinetics module

Gear blocks mesh by themselves wherever players put them. The kinetics module is for everything else: a custom block that turns on an axle, teeth on any block, gears meshed on command. Server scripts; making and driving needs the building.kinetics permission.

building.onPlaced("turntable", function(block)
  local shaft = kinetics.shaft(block, { axis = "+y", friction = 2 })     -- it turns about its own Y
  local ring = kinetics.gear(block, { shaft = shaft, teeth = 64, axis = "+y" })
  shaft:motor(6, 800)                                                      -- 6 rpm, at most 800 N·m
end)

kinetics.onTeethJumped(function(mesh, teeth) log.warn("teeth jumped on", mesh.a.block.name) end)

Shaft: angle, rpm, torque, jammed, simulated, block, mine; :motor(rpm, torque), :servo(degrees, rpm, torque), :brake(torque), :free(), :setFriction(n, damping), :setInertia(kg·m²), :add(block), :remove(block), :blocks(), :destroy(). Gear: kind, radius, teeth, shaft, block, :meshes(), :setShaft(shaft), :destroy(). GearMesh: a, b, engaged, force, slip, skips, :destroy().

A mod changes only what it made; the game's gears are changed through their blocks' settings. Everything a mod made is removed when it stops. Units: rpm and degrees in scripts, metres for radii, cells for positions on a block.

#Saves with mod blocks

A creation records which mods its blocks came from. Loading one shows which mods it was built with and whether each is active. If any is not, Load without mod blocks loads a copy with those blocks left out; the save file itself is never changed, so it loads whole again once the mods are back.