The Playground joins parts by their holes, pins, sockets and faces. A part says where those are with three declarations. They build nothing you can see; they ride along with the geometry, so whatever translate() or rotate() moves a hole moves its declaration with it.

Holes and pins: feature()

A hole or a pin is one cylinder, given by its two ends and its diameter. The library's female() and male() call feature() with the sex already filled in:

include <redo_constants.scad>

difference() {
    cube([20, 10, 10]);
    translate([5, 5, 0]) hole(SCREW_HOLE_D);
    translate([15, 5, 0]) hole(SCREW_HOLE_D);
    female("hole_0", SCREW_HOLE_D, [5, 5, 0], [5, 5, 10], threaded = true);
    female("hole_1", SCREW_HOLE_D, [15, 5, 0], [15, 5, 10], threaded = true);
}
  • name is the feature's own name, unique in the part. It stays the same when the part's sizes change.
  • d is the diameter the geometry was cut at: the same value as the hole, not a rounded-off size.
  • from, to are its two ends. For a pin, from is where it leaves the body and to its free end. For a blind hole, from is its opening.
  • threaded is true when a screw threads into it: a hole at SCREW_HOLE_D is threaded, one at THRU_HOLE_D is not.
  • role is "mechanical" (the default) for holes Assembly joins face to face, or "electronic" for a pin, pad or socket Assembly plugs a pin or a cable into.
  • blind marks a hole that stops inside the part. seat says how deep a pin goes in.
  • key, flat, flats and slot describe a shape that is not round: a rail, a D-shaped shaft, a slot.
  • gear_teeth, gear_module, gear_face and gear_tooth go on the bore of a gear, so two gears placed together turn together.
  • thread_pitch and thread_starts describe a thread that is not the standard one for its size.

Declare the hole beside the cutter that makes it, even inside the difference(): a declaration is kept wherever it stands.

One feature per hole, not per opening. A hole running right through a part is one feature from face to face. Inside a loop, give each its own name, as str("hole_", i) does: two features with one name are one.

Sockets: port()

A port() is a socket a connector cable plugs into, such as a JST connector:

cube([10, 8, 6]);
port("power", "jst-ph", [5, 0, 3], [5, 6, 3], [1, 0, 0], [6, 4], ways = 2, pitch = 2);

It takes the connector's kind, the opening's mouth and bottom, the direction from pin 1 to the last (across), the opening's size, and for a connector with several pins how many (ways) and how far apart (pitch). pins names what each pin carries, so a cable plugged in is coloured to match. lead = true marks wires a part brings out itself, such as a battery's.

Flat faces: face()

A face() is a flat rectangle on the part's surface that another part's face can sit flush against: a board on a joist, a sheet against a stud.

cube([100, 50, 10]);
face("top", [50, 25, 10], [0, 0, 1], [1, 0, 0], [100, 50]);

It takes its centre at, the direction pointing out of the part (normal), the direction of its first side (across) and its two side lengths (size). Two faces joined can slide and turn against each other.

Seeing them

Turn on Settings → Developer → Show features and select a part to see its declarations drawn: aqua for a pin, purple for a hole.