Gravity Lab — S.P.A.R.K. Chat Log

Every game, simulation, and animation shares one fundamental pattern: a loop that runs ~60 times per second, updating the world state and then drawing it. Drag & Drop Circles never introduced this loop — it redraws only in response to user events. Gravity Lab introduces requestAnimationFrame, which is that loop. Without this concept, students cannot build Asteroids, Snake, Flappy Bird, or any simulation. This is the single most important idea in graphics programming.

The choice of physics is deliberate. Velocity, gravity, and wall bounce introduce exactly three new mathematical ideas in the simplest possible order:

1. Velocity: position changes by adding (vx, vy) each frame — Euler integration.
2. Gravity: vy increases by a constant each frame — constant acceleration.
3. Wall bounce: reverse the relevant velocity component — reflection.

Circle-circle collision is the “boss level”: it requires vector decomposition, the concept of a collision normal, and the impulse equation. It is optional (students can toggle collisions off) but deeply satisfying when they turn it on and watch circles exchange momentum.

Both requestAnimationFrame (rAF) and setInterval can drive an animation loop, but they behave very differently:

setInterval(function () {
    update();
    draw();
}, 16);  // ~62fps, not synced

function animate() {
    update();
    draw();
    requestAnimationFrame(animate);
}
requestAnimationFrame(animate);

rAF is the industry standard for all browser animation. Students should learn it first and reach for setInterval only for non-visual timers (e.g., polling a server every 30 seconds).

The physics update uses Euler integration — the simplest possible method for advancing a simulation one time-step:

This is a first-order approximation: it assumes velocity is constant over the entire time step. For a 60fps simulation with small velocities, the error is imperceptible. More accurate methods (Verlet, Runge-Kutta) exist but add significant complexity for negligible visual improvement at this scale.

Key insight: order matters. Update velocity before position (symplectic Euler) for better energy conservation. If you update position first, the simulation leaks energy over time, and circles slowly gain speed from nothing.

In the drag-and-drop app, each circle had a random fixed colour. Gravity Lab maps the circle’s current speed to its hue each frame:

The result is a live heat map of kinetic energy. Students can immediately see: a circle speeding up after a collision flashes orange-red; a circle losing energy to the floor turns blue. This is not decoration — it is information, and it teaches students to connect a number (speed) to a visual (colour) in a way that is intuitive and memorable.

This technique appears in real visualisation tools (plasma displays, thermal cameras, satellite imagery). Teaching it here introduces data-driven colour mapping as a design pattern.

Drop Mode (click to spawn with zero velocity) shows gravity clearly but limits student agency. Fling Mode lets students aim and launch:

1. Press mouse button on empty canvas — record the anchor point.
2. While held, draw a rubber-band dashed line from anchor to cursor.
3. On release: vx = (anchor.x − release.x) × SCALE and similar for vy.
4. Spawn circle at anchor with those velocities.

The velocity is deliberately opposite to the drag direction (anchor → cursor gives pull-back direction, like a slingshot). This matches intuition: drag right to launch left. The yellow line makes the direction and magnitude visible before launch. The v = X px/frame label shows the numerical velocity. This turns an abstract number into a physical sensation students can develop intuition for.

Normal clear wipes the canvas completely before drawing. The trail effect replaces that wipe with a semi-transparent fill:

ctx.clearRect(0, 0, W, H);

ctx.fillStyle = 'rgba(8, 13, 28, 0.16)';
ctx.fillRect(0, 0, W, H);

Each frame, old circle drawings are dimmed by 16% but not erased. After ~6 frames they are nearly invisible. The result is a comet-tail motion trail. The alpha value (0.16) is a tuneable parameter — smaller = longer trails, larger = shorter. Students can change this one number and see the visual effect immediately. It is a perfect micro-experiment for a classroom exercise.

Circle-circle collision is the most mathematically demanding part of the app. The impulse method is used because it is derivable from first principles, correct, and short enough to fit on one screen.

Step 1 — Find the collision normal. When two circles overlap, the direction of the impact force is the line connecting their centres:

Step 2 — Separate overlapping circles. Because circles move in discrete steps, they can overlap between frames. Before fixing velocities, push them apart along the normal in proportion to their masses (heavier circle moves less):

Step 3 — Relative velocity along the normal. Only the component of relative velocity along the collision normal causes a collision response. The tangential component passes through unchanged (no friction):

Step 4 — Impulse magnitude. An impulse J changes momentum without changing time. For an elastic collision with restitution e:

Step 5 — Apply impulse. Velocity changes are proportional to the impulse divided by each circle’s mass:

This conserves linear momentum exactly and kinetic energy scaled by e². For e = 1 (perfectly elastic), total kinetic energy is preserved. Watch for the special case of equal masses: the circles exchange velocities, just like Newton’s cradle. This is testable. Drop two equal circles onto a stationary one; the stationary one moves at the same speed as the incoming one. Newton’s cradle in code.

A screenshot of the running simulation is an unusually effective hero image for an educational app. Unlike a decorative stock photo, it shows the student exactly what they will see when they open the app: coloured circles of varying sizes in mid-bounce, a dark canvas, some trailing ghost paths if they have ever turned on Trail mode. There is no gap between promise and delivery.

It also works as a grid icon in JS Apps for the same reason. The icon at 80×80px will be a compressed version of the simulation, which is still legible as “circles on a dark background” — distinguishable from every other icon on the page that uses a vector line-art style.

The CSS gradient overlay (dark-blue to dark-navy, 82% / 68% opacity) keeps the hero text legible on any device without the image needing to be pre-darkened. Reducing the overlay from the original pure-gradient values (88% / 72%) lets the background image contribute visibly instead of being mostly hidden. The 14% / 8% reduction is small but makes a meaningful difference on bright screens.

Gravity Lab appears in both the S.P.A.R.K. offcanvas and the Graphics offcanvas in Explore. This is correct because the app genuinely belongs in both categories:

• Graphics: The app generates visual content entirely on an HTML5 canvas using JavaScript. Every pixel is computed. No images are drawn, no SVG is used, no video is played back. This exactly matches the TNT Graphics category definition.
• S.P.A.R.K.: The app was designed using the S.P.A.R.K. methodology with a published chat log documenting every decision. The chat log doubles as a student teaching document with a comparison table, six decision boxes, math derivations, and a challenge section.

A CSS background shorthand can encode both the size and position of a background image in one declaration, separated by a /:

url('../gravityOutput.png') center / cover no-repeat

url('../gravityOutput.png') bottom / cover no-repeat

The position keyword bottom is shorthand for center bottom — it horizontally centres the image while vertically aligning its bottom edge with the element’s bottom edge. With cover sizing the browser scales the image until it fills the hero in both dimensions, then applies the position offset. The result: the image is always cropped from the top, never from the bottom.

For a physics simulation screenshot, this is the right choice. Circles accumulate near the floor when gravity is on, which is where the most visually interesting content sits — the multi-coloured pile-up of bouncing circles. center would show the middle of the image (mostly empty dark canvas), while bottom shows the action.