Deep Dive: Building "Gravity Paint" - A Tactile Physics Instrument with React, Matter.js, and p5.js

Physics-based browser games are nothing new, but creating something that feels truly organic, interactive, and sensorily satisfying remains a rewarding engineering challenge. In this technical blog post, we look under the hood of Gravity Paint – a gravity-aware sandbox puzzle where players paint rigid rope cables to funnel a stream of colorful glass, steel, and bubble marbles into an target collection bucket.

We’ll dissect how to seamlessly combine the state-management of React 19, the performant rigid-body simulations of Matter.js, the smooth visual canvas loops of p5.js, and an in-house Web Audio API synthesizer.

The Three-Headed Architecture: React, P5, & Matter.js

When creating complex interactive canvases, the biggest design issue developers face is Architectural Coordination.

React is superb at managing structured data, layout trees, level progression, and sidebars. However, React's virtual-DOM rendering is completely unsuited for high-frequency (60fps) physics steps.
Matter.js runs an analytical engine representing worlds, vectors, collisions, shapes, forces, and constraint joints.
p5.js (instance-mode) handles graphic pipelines, drawing pixels, mouse inputs, clear frames, and UI animations.

Using these together requires a meticulous boundary of concerns:

+------------------------------------------+
|                 REACT UI                 |
| (Campaign Progress, Sound Settings, HUD) |
+--------------------+---------------------+
                     |
         Dispatches Window Event
                     |
                     v
+--------------------+---------------------+
|              P5.js INSTANCE              |
|  (Renders pixel world, manages inputs)   |
+--------------------+---------------------+
                     |
             Updates Coordinates
                     |
                     v
+--------------------+---------------------+
|             MATTER.JS WORLD              |
|  (Evaluates collisions, forces, joints)  |
+------------------------------------------+

To prevent memory leaks and coordinate clean slate shifts (like when a level resets or chains are cleared), we wrap the entire canvas setup inside a single React useEffect() ref hook container. Communication across the react wrapper and inner loop coordinates cleanly through custom Window events (CustomEvent), which avoids messy React re-renders interfering with the physics cycle.

The Physics of Paintable Ropes (Chains)

How do we build paintable rope constraints that drape, sag, and sag under weight?

In Matter.js, there is no built-in "rope" body. Instead, a rope is represented as a composite sequence of circular bodies linked sequentially via distance constraints.

1. Tracking Drag Inputs

When a player clicks and drags on the canvas, we record coordinate arrays inside p5:

p.mouseDragged = () => {
  const lastPt = tempPoints[tempPoints.length - 1];
  const distToPrev = p.dist(p.mouseX, p.mouseY, lastPt.x, lastPt.y);

  // Add a new link point only if the mouse has moved far enough (dense brush optimization)
  if (distToPrev > 16) {
    tempPoints.push({ x: p.mouseX, y: p.mouseY });
  }
};

2. Spawning Composite Structures

On mouse release, we convert these floating coordinates into interconnected Matter.js bodies:

const segmentCount = tempPoints.length;
const links: Matter.Body[] = [];
const constraints: Matter.Constraint[] = [];

// Create the link circles
for (let i = 0; i < segmentCount; i++) {
  const pt = tempPoints[i];
  const link = Matter.Bodies.circle(pt.x, pt.y, 4, {
    density: 0.005, // Dictates sag behavior
    friction: 0.08,
    restitution: 0.4,
    collisionFilter: { group: Matter.Body.nextGroup(true) } // Disable self-collisions within the rope
  });
  links.push(link);
  Matter.World.add(world, link);
}

// Interconnect the circles via spring constraints
for (let i = 0; i < segmentCount - 1; i++) {
  const con = Matter.Constraint.create({
    bodyA: links[i],
    bodyB: links[i + 1],
    stiffness: 0.85, 
    length: p.dist(tempPoints[i].x, tempPoints[i].y, tempPoints[i+1].x, tempPoints[i+1].y),
    render: { visible: false }
  });
  constraints.push(con);
  Matter.World.add(world, con);
}

The Gravity Snapping Algorithm

If a rope is left unanchored, gravity causes it to plunge into the abyss. To make it a puzzle, we introduce Golden Anchors. These are coordinate locks.

During mouse-down (drag start) and mouse-up (drag end), we check for proximity to preset anchors using traditional Euclidean space calculations:

const findClosestAnchor = (x: number, y: number, radiusThreshold: number = 32) => {
  let closest: { x: number; y: number } | null = null;
  let minDist = radiusThreshold;

  currentLevel.anchors.forEach(anc => {
    const d = p.dist(x, y, anc.x, anc.y);
    if (d < minDist) {
      minDist = d;
      closest = anc;
    }
  });
  return closest;
};

If a snap coordinate is found within range:

We align the starting/ending rope link precisely to the Golden Anchor Center.
We create an absolute anchor constraint linking the segment directly to the static Matter world coordinate (represented by a static body).

// Pin rope end firmly to Golden Anchor
const staticAnchorBody = Matter.Bodies.circle(snappedAnchor.x, snappedAnchor.y, 1, { isStatic: true });
Matter.World.add(world, staticAnchorBody);

const anchorConstraint = Matter.Constraint.create({
  bodyA: TargetRopeEndBody,
  bodyB: staticAnchorBody,
  stiffness: 0.95,
  length: 0
});
Matter.World.add(world, anchorConstraint);

This creates the gorgeous suspension bridge effect where ropes sway and sag under the impact of rushing marbles!

Creative Sandbox UX: "Clear Chains" Feature

During playtesting, we observed that players wanting to fine-tune their designs became frustrated with full system resets. Resetting cleared their current level collection score and restarted level progress.

To fix this, we implemented Iterative Design Clearing.

We introduced a Clear Chains feature. It targets and clears only the user-painted Matter composite chains, leaving the physics progress of flowing particles, level timers, and collection tally scores completely intact:

// Define clear logic cleanly within Matter physics scope
const handleClearChainsEvent = () => {
  if (!world) return;

  // Recursively dismount current chains from Matter.World
  chains.forEach(c => {
    if (c) {
      if (c.links) c.links.forEach(l => l && Matter.World.remove(world, l));
      if (c.constraints) c.constraints.forEach(con => con && Matter.World.remove(world, con));
    }
  });
  chains = []; // Clear local tracker list
  setChainsCount(0); // Sync React state counter
};

Mitigating React Closure Pitfalls in High-Hz Canvas Loops

One of the trickiest bugs solved in this runtime was the Sloppy Run State Capture Freeze.

The Symptom:

When a player dropped more than 5 marbles, a "Sloppy Run! Game Over" card appeared on the screen, prompting a retry. Even though the overlay was active, the marble faucet spigot continued spawning balls, and the fallen ball counter kept increasing, rendering the UI state incorrect.

The Root Cause:

Inside P5's high-frequency p.draw loop (running at 60fps), referencing the React state value showSloppyMessage returns a closure value captured at P5 initialization time. The canvas loop was checking a stale state, meaning it didn't know the game over modal was shown!

The Solution:

We implemented Synchronized Mutable Refs to act as hot-wiring bridges between React and the P5 paint routine:

// 1. Declare state and tracking Ref
const [showSloppyMessage, setShowSloppyMessage] = useState<boolean>(false);
const showSloppyMessageRef = useRef(showSloppyMessage);

// 2. Hot-swap state into hot-ref on state changes securely
useEffect(() => { 
  showSloppyMessageRef.current = showSloppyMessage; 
}, [showSloppyMessage]);

// 3. Inside p5 loop drawer, evaluate strictly from raw Ref:
if (faucetActiveRef.current && activeState === "playing" && !showSloppyMessageRef.current) {
  if (p.frameCount % streamSpeedRef.current === 0) {
    spawnMarble(); // Faucet spawning stops instantly!
  }
}

By querying the Hot-Ref inside p.draw(), the physics loop reacts instantaneously to state changes without experiencing closure lags or forcing canvas re-mounts.

Sound Synthesis: Interactive Web Audio API

To provide sensory satisfaction, Gravity Paint bypasses bulky .mp3 assets in favor of dynamic Web Audio Synthesizers. Whenever a marble collides or drops, we initiate synthetic tone triggers:

export class Synthesizer {
  private ctx: AudioContext | null = null;

  playPing(index: number) {
    if (!this.ctx) this.ctx = new (window.AudioContext || (window as any).webkitAudioContext)();

    const osc = this.ctx.createOscillator();
    const gain = this.ctx.createGain();

    // Choose dynamic pentatonic scaling for musical feedback
    const baseFreq = 220;
    const pentatonicScales = [1, 1.125, 1.25, 1.5, 1.667, 2, 2.25, 2.5, 3];
    const multiplier = pentatonicScales[index % pentatonicScales.length];

    osc.frequency.setValueAtTime(baseFreq * multiplier, this.ctx.currentTime);
    osc.type = 'triangle'; // Smooth, woody marimba timbre

    gain.gain.setValueAtTime(0.2, this.ctx.currentTime);
    gain.gain.exponentialRampToValueAtTime(0.001, this.ctx.currentTime + 0.45);

    osc.connect(gain);
    gain.connect(this.ctx.destination);

    osc.start();
    osc.stop(this.ctx.currentTime + 0.5);
  }
}

This creates a generative visual-instrument experience out of a simple canvas sandbox!

Combining rigid-body physics engines like Matter.js with p5.js layouts inside highly reactive frameworks like React 19 can be challenging. By: