Joints#

A joint holds an object to another object, or to the world, and lets it move in one particular way: a door turns on its hinge, a drawer slides on its rail, a lamp swings on its chain.

A door that swings open up to 100 degrees

local self = require("self")local vec = require("vec") -- The hinge runs up the door's left edge (half its width from the centre).self:set_joint{ type = "hinge", anchor = vec(-0.5, 0, 0), min = 0, max = 100 }

Push that door and it swings round its edge, and stops at 100 degrees.

Six kinds#

`type`	Moves like	Uses
`"hinge"`	turns about one axis	a door, a wheel, a lever, a gate
`"slider"`	slides along one axis	a drawer, a piston, a lift on a rail
`"ball"`	swings any way about one point	a pendulum, a lamp on a chain
`"weld"`	does not move at all	two bodies glued into one
`"rope"`	anything, but never further than `length`	a rope, a leash
`"spring"`	pulled back towards `length`	a spring, a bungee, a bouncy platform

The options#

Vectors are in the object's own frame, so they turn with it. Angles are in degrees, distances in metres.

Option	What it sets	Default
`type`	One of the six kinds above.	required
`to`	The other object: from `objects`, or its id.	the world
`anchor`	Where the joint is, from the object's centre.	the centre
`axis`	The axis a hinge turns about, or a slider slides along.	up, `vec(0, 1, 0)`
`min`, `max`	How far it may turn or slide.	no limit
`motor`	`{ speed = … }` to keep moving, or `{ target = … }` to go somewhere and stay.	none
`force`	The motor's strength ceiling.	unlimited
`length`	A rope's longest reach, or a spring's rest length.	1
`stiffness`, `damping`	How hard a spring pulls back, and how fast it stops bouncing.	50, 5

set_joint also makes the object dynamic: a joint only means something on an object the physics moves.

Where zero is#

The pose the object is in when you call set_joint is the joint's zero. min, max and a motor's target all count from there. A door made closed with min = 0, max = 100 opens up to 100 degrees from closed, and stays that way however often the world is edited afterwards.

A positive angle turns the object counter-clockwise about its axis, seen from the tip of the axis.

Motors#

A motor makes a hinge or a slider move on its own.

A windmill

local self = require("self")local vec = require("vec") -- The blades turn about the axis that points out of the mill.self:set_joint{ type = "hinge", axis = vec(0, 0, 1), motor = { speed = 45 } }

speed is in degrees per second for a hinge and metres per second for a slider. target drives it to an angle or a position and holds it there, which is how an automatic door works:

A door that opens when touched

local self = require("self")local vec = require("vec") self:set_joint{ type = "hinge", anchor = vec(-0.5, 0, 0), min = 0, max = 90,                motor = { target = 0 } }local open = falseself:on_touch(function()    open = not open    self:set_motor{ target = open and 90 or 0 }end)

self:set_motor changes only the motor; the joint and its zero stay as they were. self:set_motor(nil) turns the motor off.

Two objects together#

to names the other body. Both must be dynamic for the pair to move together. Otherwise the joint holds the object to where the other one stands.

A lamp hanging from a beam on a 2 m chain

local self = require("self")local objects = require("objects")local vec = require("vec") local found = objects:named("Beam")-- The chain is tied to the top of the lamp.self:set_joint{ type = "rope", to = found and found[1], anchor = vec(0, 0.3, 0), length = 2 }

A rope is tied at anchor on this object and at the spot that anchor is in when the joint is made, so the lamp drops until the chain is tight.

Reading and removing#

Verb	What it does
`self:joint()`	The joint this object has, in the same shape `set_joint` takes, or `nil`.
`self:clear_joint()`	Removes the joint. The object stays dynamic.

Every verb answers true, or nil, reason when the call itself is wrong: an unknown type, min above max, or a motor with both a speed and a target. None of them raises an error.

How it works#

A joint is stored as properties of the object, like dynamic and mass. It is saved with the world, it replicates like any other property, and the region's physics and every player's prediction build exactly the same joint from it.