gearbox-planets 

<script src="./point_src/gearbox-planets"></script>
parse

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:

// In HTML
<script src="point_src/gearbox.js"></script>
<script src="point_src/gearbox-planets.js"></script>

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

Creating a Planetary System

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

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

Control Methods

// 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

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
Meta Data
filepath_exists True
path gearbox-planets
filepath gearbox-planets.js
clean_files ()
  • ClassDeclaration
    class

    PlanetaryGearSystem

    extends None
    class comments:
     * Manages a planetary gear system with:
 * - Sun gear (center, typically the input/motor)
 * - Planet gears (orbit around sun while rotating)
 * - Ring gear (outer, internal gear that planets mesh with)
 * - Carrier (virtual mechanism that controls orbital motion)
    • constructor

      constructor

      (
      gearbox , options = {}
      )
      from PlanetaryGearSystem
      dict_keys(['kind', 'word', 'static', 'computed', 'is_symbol', 'value', 'type', 'comments', 'pos'])

      Configuration

    • method

      createPlanet

      (
      angle , radius
      )
      from PlanetaryGearSystem
      dict_keys(['kind', 'word', 'static', 'computed', 'is_symbol', 'value', 'type', 'comments', 'pos'])

      Create a single planet gear at the specified angle (in degrees)

    • method

      calculatePlanetPosition

      (
      angle
      )
      from PlanetaryGearSystem
      dict_keys(['kind', 'word', 'static', 'computed', 'is_symbol', 'value', 'type', 'comments', 'pos'])

      Calculate XY position for a planet at the given orbital angle * Angle is in degrees (polypoint convention)

    • method

      updateOrbitalPositions

      (
      )
      from PlanetaryGearSystem
      dict_keys(['kind', 'word', 'static', 'computed', 'is_symbol', 'value', 'type', 'comments', 'pos'])

      Update planet positions based on carrier rotation * This is called each frame by the gearbox * Working in DEGREES (polypoint convention)

    • method

      updateCarrierVelocity

      (
      )
      from PlanetaryGearSystem
      dict_keys(['kind', 'word', 'static', 'computed', 'is_symbol', 'value', 'type', 'comments', 'pos'])

      Calculate carrier rotation based on planet velocities * When planets rotate, they "walk" around the sun/ring, driving the carrier * * Working in DEGREES (not radians) since polypoint uses degrees

    • method

      setCarrierLocked

      (
      locked
      )
      from PlanetaryGearSystem
      dict_keys(['kind', 'word', 'static', 'computed', 'is_symbol', 'value', 'type', 'comments', 'pos'])

      Lock or unlock the carrier (prevents orbital motion)

    • method

      setRingLocked

      (
      locked
      )
      from PlanetaryGearSystem
      dict_keys(['kind', 'word', 'static', 'computed', 'is_symbol', 'value', 'type', 'comments', 'pos'])

      Lock or unlock the ring gear

    • method

      setSunMotor

      (
      velocity
      )
      from PlanetaryGearSystem
      dict_keys(['kind', 'word', 'static', 'computed', 'is_symbol', 'value', 'type', 'comments', 'pos'])

      Change the sun gear motor speed

    dict_keys(['kind', 'word', 'parentName', 'type', 'body', 'comments', 'pos'])