Connect bodies with a joint

quick start Beginner ⏱ 5 min vgai 0.1.0

Prerequisites: Installed vgai and run the editor

What you'll learn

• Declare a joint between two bodies in a scene (entity `joints` field)
• Use a revolute joint to make a pendulum
• Understand anchors and the rotation axis

What you'll build: A pendulum — a dynamic arm swinging from a fixed pivot via a revolute joint.

Walkthrough — Connect bodies with a joint · generated by site/media/lessons/learn-joints.lesson.ts (5 steps)

A joint constrains how two rigid bodies move relative to each other. You declare joints in the scene on an entity’s joints field — no code. Here a revolute joint (a hinge) pins a dynamic Arm to a fixed Pivot; gravity does the rest, and the arm swings like a pendulum.

Follow along in the live web editor

▶ Open the joints scene — every step below (including Play) runs right in your browser, no install required.

Steps

1. Open the scene. The scene is already open — if you followed the link above, the joints scene is loaded and rendering (in the local dev editor: VGAI_PROJECT=examples/learn-joints npm run dev): a small fixed pivot and a long dynamic arm held out horizontally from it.

   

   A fixed Pivot and a dynamic Arm, joined by a revolute joint.

2. Enter play — gravity swings the arm. Released from horizontal, the arm falls and rotates about the joint’s axis.

   

   Released — the arm swings about the revolute joint.

3. The arm swings through its arc, pinned to the pivot. The joint keeps the arm’s end fixed at the pivot while letting it rotate about axis: [0,0,1].

   

   The revolute joint = a hinge: the arm rotates about one axis.

4. The joint holds the arm to the pivot as it keeps swinging. It’s a pendulum — it oscillates (slowly damping) entirely from the constraint plus gravity.

   

   A pendulum: constraint + gravity, no per-frame code.

5. Stop play mode. Press Stop (or Escape).

// learn-joints.vscn.json — the Arm entity declares the joint
"joints": [
  { "type": "revolute", "target": "pivot",
    "anchor": [-1.5, 0, 0], "targetAnchor": [0, 0, 0], "axis": [0, 0, 1] }
]

Anchors & axis

anchor is the joint point in this body’s local space; targetAnchor is the point in the target body’s space — the joint keeps those two points coincident. axis is the hinge’s rotation axis. Other types: fixed, prismatic (slider), spherical, spring.

Recap

New functionality

• Declared a revolute joint between two bodies in a scene
• Watched a dynamic arm swing from a fixed pivot

New concepts & skills

• Joints are declared on an entity's `joints` field — no code
• anchor/targetAnchor pin two local points together; axis is the hinge axis
• revolute = hinge; also fixed / prismatic / spherical / spring

Next lesson → Manual: joints

On Your Own!

Extend what you built:

• Add limits {min,max} to the revolute joint and watch the swing clamp
• Chain a second arm to the first for a double pendulum
• Swap the type to prismatic for a sliding constraint

See also

• Joints (manual) · Rigid bodies