JS Hexapod v0.8.0

Three.js 3D hexapod robot simulator with optional physical bot control via Socket.IO.

Quick Start

npm install
npm run dev      # http://localhost:3000
npm run build    # production build to dist/
npm run preview  # preview production build
npm run lint     # ESLint

Features

• 3D Preview — OrbitControls, grid, mesh/bone/points draw modes
• Gait Engine — tripod, ripple, quad, wave gaits with power/efficient/body_first/fast modes; systematic k-legs-lifted gait generation with balance validation and cyclic dedup
• Inverse Kinematics — gradient-descent PosCalculator, no trig-based joint computation
• Servo Speed Simulation — configurable servo rotation speed (units/sec), 60fps keyframe animation
• Physics Modes — None (instant tip teleport) / Servo Constraint (realistic servo speed simulation)
• Micro Steps — subdivide body movement into N keyframes for stable IK during large displacements
• Multi-leg Constraint Solver — PhysicsSolver coordinates all legs simultaneously during body movement
• Leg Editor — 2D canvas drag-to-adjust segment lengths and angles, per-leg DOF support, per-segment IK feedback
• Servo Control — 18-servo sliders with real-time command display and time chart
• Physical Bot — Socket.IO to localhost:8888, servo pulse command protocol (#0 P1500 #1 P1500 ... T500)
• Config Persistence — localStorage save/load, export/import JSON profiles, undo/redo
• Random Generator — one-click random bot parameters

Architecture

src/
  main.tsx                    # React entry point
  App.tsx                     # Shell: tabs, layout, HexapodProvider
  context/HexapodContext.tsx  # botRef, sceneRef, servo display, version bump
  components/
    SceneCanvas.tsx           # Three.js scene mount, builds Hexapod
    SceneControls.tsx         # 3 joysticks (Move/Body/Rot), XYZ/RxRyRz sliders, persists move_mode
    ControlPanel.tsx          # Draw type, gaits, action/step/physics, keyboard, send/sync
    AttributesPanel.tsx       # Profile (presets + body shape buttons), Adjust, Motions, Body Attrs
    ServoPanel.tsx            # 18 servo sliders + end-position inputs
    LegEditor.tsx             # 2D canvas joint editor with multi-leg editing
    StatusBar.tsx             # Status bar: gait, mode, physics, leg count
    StatusPanel.tsx           # Status history with play/apply
    CommandDisplay.tsx        # Current + last servo command
    TimeChart.tsx             # Command time interval chart
    Toolbar.tsx               # Undo/redo/save toolbar with keyboard shortcuts
    AttrSlider.tsx            # Reusable labeled range slider
    SliderColumn.tsx          # Reusable slider column (vertical/horizontal, spring-back)
  hexapod/
    hexapod.ts                # Hexapod class, config helpers
    hexapod_leg.ts            # HexapodLeg class
    gaits.ts                  # GaitController, gait actions
    gait_configs.ts           # Preset gait definitions (wave, ripple, tripod, quad)
    gait_generator.ts         # Runtime gait filtering and validation
    pos_calculator.ts         # Gradient-descent IK solver
    forward_kinematics.ts     # Pure forward kinematics (zero Three.js), for tests
    physics_solver.ts         # Multi-leg constraint solver
    servo_output.ts           # ServoOutput interface + DirectOutput/AnimatedOutput
    scene.ts                  # initScene — Three.js setup
    joystick2.ts              # Canvas-based 2D joystick
    leg_layout.ts             # Leg layout computation, joint positions
    presets.ts                # 15 preset configurations
    defaults.ts               # Constants, DEFAULT_HEXAPOD_OPTIONS
    utils.ts                  # DOM/vector/math/localStorage helpers
    appState.ts               # Mutable singleton state
    history.ts                # Undo/redo stack
    random.ts                 # Random options generator
  types/
    globals.d.ts              # Type declarations for legacy Three.js, Stats, Detector, THREEx
    hexapod.d.ts              # Core interfaces: HexapodOptions, HexapodLegOptions, LimbOptions
    css.d.ts                  # Module declaration for .css imports
stylesheets/
  application.css             # Original UI styles (imported by React app)

Design Rules

• No trig for joints — PosCalculator uses gradient descent, never sin/cos/atan2
• guide_pos is the unified reference frame for all gait tip/body movement
• Gait step factors: tips move by full step, body by step / leg_groups.length * 3
• Servo Constraint principle: animation reflects physical reality — servos rotate at constant speed independently, different arrival times are correct, never fake synchronization
• Keyframe animation: mesh keyframes for gait walking; body_mesh keyframes for body control; per-leg keyframes managed by AnimatedOutput strategy

See CLAUDE.md for full non-negotiable design rules. See CLAUDE_CN.md for Chinese version.

Three.js

Uses Three.js revision 72 (loaded as globals via <script>):

• THREE.Geometry (not BufferGeometry)
• Single-material mesh constructor
• .applyMatrix() (not .applyMatrix4())

Servo Command Format

#0 P1500 #1 P1500 #2 P1500 ... T500

Servo index, pulse width (500–2500), time interval in ms.

License

By Daniel Cheang @ 2015