Planetary Gears Extension

An optional extension for the GearBox that adds support for planetary gear systems.

Features

• Sun Gear: Central motor gear that drives the system
• Planet Gears: Orbit around the sun while rotating on their own axes
• Ring Gear: Outer internal gear that planets mesh with
• Carrier: Virtual mechanism that controls orbital motion

Usage

Loading

Include gearbox-planets.js after loading gearbox.js:

```javascript // In HTML

// Or in theatre file: files: ... ../point_src/gearbox.js ../point_src/gearbox-planets.js ```

Creating a Planetary System

```javascript let gearbox = new GearBox();

let planetary = gearbox.createPlanetarySystem({ sunXY: { x: 400, y: 300 }, // Center position sunRadius: 60, // Sun gear size planetRadius: 25, // Planet gear size ringRadius: 150, // Ring gear size (optional, auto-calculated) planetCount: 3, // Number of planet gears (3-5 recommended) sunMotor: 1 // Motor speed in degrees per frame }); ```

Accessing Components

javascript planetary.sun // The sun gear (Point) planetary.planets // Array of planet gears [Point, Point, ...] planetary.ring // The ring gear (Point)

Control Methods

```javascript // Change sun motor speed planetary.setSunMotor(2.0)

// Lock/unlock the carrier (prevents orbital motion) planetary.setCarrierLocked(true)

// Lock/unlock the ring gear planetary.setRingLocked(true)

// Make the ring gear rotate planetary.ring.motor = 1 ```

Properties

javascript planetary.carrierAngle // Current orbital angle (degrees) planetary.carrierVelocity // Current orbital velocity (degrees/frame) planetary.orbitRadius // Distance from sun to planet centers

How It Works

1. The sun gear rotates (motor-driven)
2. Sun meshes with planet gears → planets rotate
3. Planets mesh with ring gear → more rotation force
4. Planet rotation creates tangential velocity
5. Tangential velocity drives the carrier to orbit
6. Carrier updates planet XY positions each frame

The system automatically integrates with the GearBox touch detection and gear meshing logic.

Examples

See theatre/gearbox-planetary.js for a complete working example.

Notes

• All angles are in degrees (polypoint convention), not radians
• Motor speeds are in degrees per frame
• Ring radius is auto-calculated if not provided to ensure proper meshing
• Planets can be dragged but will fight with their orbital motion
• Sun and ring gears can be freely dragged