DEV Community: DevNash

Make a canvas fish swim: force, not animation

DevNash — Mon, 17 Aug 2026 11:52:18 +0000

Our fish slid sideways. Not badly — you had to watch for a second before it bothered you — but once you saw it you could not unsee it: the body was doing a swimming motion while the whole animal was being carried along a track, like a plank on a conveyor. This is what we had to change to fix it, and the three fixes we tried first that did nothing.

Throughout, sideslip means one thing: the angle between where the fish is going and where its body is pointing.

The model that slides

The usual way to draw a swimming fish is three independent steps:

// 1. steer: turn the heading toward where we want to go
fish.angularVelocity += (torque - drag) * dt;
fish.angle += fish.angularVelocity * dt;

// 2. move: push the body along that heading
fish.x += Math.cos(fish.angle) * speed * dt;
fish.y += Math.sin(fish.angle) * speed * dt;

// 3. decorate: run a wave down the spine so it looks alive
for (let i = 1; i < spine.length; i++) {
  const tailward = i / (spine.length - 1);
  const wave = Math.sin(fish.swimPhase - tailward * 4.8) * amp;
  const angle = fish.spineAngles[i - 1] + wave;
  spine[i].x = spine[i - 1].x - Math.cos(angle) * segmentLength;
  spine[i].y = spine[i - 1].y - Math.sin(angle) * segmentLength;
}

Read step 3 against steps 1 and 2. The wave runs after the position has already been decided. The shape of the body and the track it travels are computed independently and never meet. That disconnect is the whole defect, and everything below follows from it.

Three patches that improved a number and changed nothing

Weld the momentum to the visible body axis. Take the body's actual axis, and rotate the velocity vector toward it every frame:

const bodyAxis = fish.spineAngles[0];
const speed = Math.hypot(fish.velocityX, fish.velocityY);
if (speed > 0.5) {
  const course = Math.atan2(fish.velocityY, fish.velocityX);
  const rot = angleDifference(bodyAxis, course) * Math.min(1, dt * 10);
  fish.velocityX = speed * Math.cos(course + rot);
  fish.velocityY = speed * Math.sin(course + rot);
}

The angle between the centre-of-mass velocity and the body axis drops to almost nothing, and the fish still visibly slides. In steady state that measurement cannot say anything else — the patch makes the centre of mass travel along its axis by construction. But nobody watches the centre of mass. What you watch is the body: eight spine points, each still free to translate however the wave feels like translating it. Instrumenting the one point that cannot express the defect is how you stay confidently wrong while the picture never changes.

Move the pivot forward, so turns rotate about the head instead of the middle. Add a rotation-carry factor, so stored joint angles rotate with the heading and the tail stops lagging. Both are real improvements to real numbers. Neither changed the picture.

The instrument that settled it

We stopped measuring scalars and started stamping the entire spine onto the canvas every third of a second, leaving the stamps behind:

// throwaway instrument in a standalone tuning page, not in the game
function captureSpineSnapshot(sampleTime) {
  spineSnapshots.push({
    t: sampleTime,
    spine: fish.spine.map((p) => ({ x: p.x, y: p.y })),
  });
  if (spineSnapshots.length > 90) spineSnapshots.shift();
}

A swimming fish threads those outlines through each other: each part of the body passes near where the part ahead of it has been, so the stamps interleave into one corridor. A sliding fish leaves a ladder of parallel lines — the unmistakable picture of a shape being carried sideways. Unlike a scalar readout, that image cannot be argued with, and it kills a false "verified fixed" in about a second.

Force, not pose

We rewrote it under one rule: behaviour may only set muscle terms. It may never write position or heading.

There are three muscle terms — beat frequency, wave amplitude and a curvature bias for steering — plus a goal heading. Everything else is a consequence.

First the body has a shape. Segment depths give each piece its area against the water, and the mass sits forward, not in the geometric middle:

const DEPTH_PROFILE = [0.14, 0.22, 0.27, 0.28, 0.23, 0.14, 0.08, 0.18];
const MASS_PROFILE = (() => {
  const weights = [0.16, 0.20, 0.20, 0.16, 0.12, 0.08, 0.05, 0.03];
  const total = weights.reduce((a, b) => a + b, 0);
  return weights.map((value) => value / total);
})();
const SWIM = {
  cruiseHz: 1.5, dashHz: 4.6, waveLength: 1.0, tailAmp: 0.13,
  normalDrag: 26, dragRatio: 52, bendGain: 1.0,
};

The depth profile peaks about a third of the way back — that deep forward body is what resists yaw, and flattening it makes the fish wag. The last entry is the caudal fin, not body depth.

The muscle terms produce a shape, in the fish's own frame:

function bodyShape(fish, phase) {
  const body = bodyOf(fish);
  const lambda = SWIM.waveLength * body.length;
  const scale = SWIM.tailAmp * fish.waveGain;
  const points = [{ x: 0, y: 0 }];
  let bend = 0;
  for (let i = 0; i < body.segments.length; i += 1) {
    const s0 = body.arc[i] / body.length;
    const s1 = body.arc[i + 1] / body.length;
    const y0 = waveAmpAt(s0) * scale * Math.sin(phase - 2 * Math.PI * body.arc[i] / lambda);
    const y1 = waveAmpAt(s1) * scale * Math.sin(phase - 2 * Math.PI * body.arc[i + 1] / lambda);
    // steering is curvature accumulated joint by joint, so the body forms an
    // arc — not a rigid rotation of the whole fish
    bend += fish.bendBias * SWIM.bendGain * 0.34 * body.bendWeight[i];
    const angle = Math.atan2((y1 - y0) * body.length, body.segments[i]) + bend;
    points.push({
      x: points[i].x + Math.cos(angle) * body.segments[i],
      y: points[i].y + Math.sin(angle) * body.segments[i],
    });
  }
  ...
}

Then every segment meets the water. Its velocity is the rigid-body motion plus the muscle deformation, split into a component across the segment and one along it:

// cosine/sine rotate body frame -> world; q is the segment midpoint and dq its
// deformation velocity; r is that midpoint relative to the centre of mass.
const ux = fish.velocityX - fish.angularVelocity * ry + (cosine * dqx - sine * dqy);
const uy = fish.velocityY + fish.angularVelocity * rx + (sine * dqx + cosine * dqy);

const un = clamp(ux * nx + uy * ny, -400, 400);   // across the segment
const ut = clamp(ux * tx + uy * ty, -400, 400);   // along it

// resistance across the body is dragRatio times what it is along it: this is
// both where the thrust comes from and why the fish cannot move sideways
const kn = SWIM.normalDrag * body.areaWeight[i] / body.length;
const kt = kn / SWIM.dragRatio;
const fn = -kn * un * Math.abs(un);
const ft = -kt * ut * Math.abs(ut);

forceX += fn * nx + ft * tx;
forceY += fn * ny + ft * ty;
torque += rx * (fn * ny + ft * ty) - ry * (fn * nx + ft * tx);

Sum over segments, integrate, done. Mass is 1 by choice — only ratios matter here — so force is acceleration:

fish.velocityX += forceX * dt;
fish.velocityY += forceY * dt;
fish.angularVelocity += torque / bodyInertia(shape) * dt;
fish.x += fish.velocityX * dt;
fish.y += fish.velocityY * dt;
fish.angle += fish.angularVelocity * dt;

Sideslip is now impossible to author, because nothing authors motion at all. The lateral resistance is dragRatio times the forward resistance, so any sideways velocity dies almost as fast as it appears. The fish does not slide because the water will not let it — not because we constrained it.

Two honest notes. This is resistive-force theory: drag per segment, no added-mass term. A real fish gets a large part of its thrust from accelerating the water it pushes, and we do not model that at all, which is probably why the anisotropy has to be as high as 52 to look right. And dragRatio is not a measured property of anything — it is the knob that sets cruising speed, and we set it by watching koi cross the pond.

Run it on a fixed small step, not a whole frame:

const steps = Math.max(1, Math.ceil(dt / 0.004));
const stepDt = dt / steps;
for (let i = 0; i < steps; i += 1) stepSwimPhysics(fish, stepDt);

Quadratic drag plus a frame-rate dip is an explosion. Ask how we know.

Two ways we got it wrong

Counting the recoil twice. Published amplitude envelopes for swimming fish are measured in world coordinates — they describe how much each point of a real fish ends up moving, which already includes the body's recoil against its own tail. Feeding that curve in as the muscle command looks obviously right:

// wrong: this is the motion, not the command that produces it
function ampAt(x) { return 0.05 - 0.13 * x + 0.28 * x * x; }

The physics then adds recoil a second time and the fish waddles forward, head swinging. The command has to be quieter at the front than the resulting motion is, because the head's sway is a consequence, not an instruction:

// right: near zero at the head, growing tailward; the head's real sway
// appears on its own, as recoil
const waveAmpAt = (x) => Math.pow(Math.max(0, x), 1.9);

Using the wrong reference point. The shape has to be recentred each step, and we first recentred it on the geometric centroid of the spine. That puts a spurious rigid-body translation into what is supposed to be pure deformation, the drag is quadratic so it does not cancel, and it feeds yaw recoil. On a treadmill test — fish held in place, water flowing past, watching whether it holds station — it swims cleanly for several seconds and then wags in place while its speed collapses. The centroid has to be mass-weighted:

let cx = 0;
let cy = 0;
for (let i = 0; i < points.length; i += 1) {
  cx += points[i].x * MASS_PROFILE[i];
  cy += points[i].y * MASS_PROFILE[i];
}
return points.map((point) => ({ x: point.x - cx, y: point.y - cy }));

Check the sign of your plant

With the body working, the fish still would not turn toward anything. It cruised with the body permanently bent, held what amounted to full rudder, and pinned itself against the walls. We tried proportional gain, damping, a dead zone, ±180° tie-breaking, a commitment threshold. Some helped a little. Some made it worse in ways nothing explained.

Then we ran the plant open-loop: freeze the behaviour layer, hold a fixed bend, and read the yaw rate off the console. It takes two lines. A positive bend command yawed the fish negative — and the controller was feeding a positive command for a positive error. The steering loop had been positive feedback the whole time, and every parameter tuned above it was the gain of a runaway loop.

The sign was the bug. Fixing it also let us delete the damping term, the dead zone and the magnitude floor, because all three existed to fight the loop rather than to steer. Cruising bend dropped by more than half.

Measure the sign of your plant before you tune its controller.

Two more things the steering law needs once the body is a real body.

Aim the course, not the nose. A bent body sideslips, so pointing the head at something walks the fish past it in a widening spiral. While chasing a pellet, the error is measured against the direction of travel instead:

let error = angleDifference(fish.goalHeading, bodyAxis);
if (fish.targetPellet && fish.velocity > body.length * 0.25) {
  const course = Math.atan2(fish.velocityY, fish.velocityX);
  error = clamp(angleDifference(fish.goalHeading, course), -Math.PI, Math.PI);
}

Make the law nonlinear. A linear gain keeps feeding rudder for a 10° error, which keeps the body bent, which keeps the sideslip alive, which keeps the error. Shaping it decisive when far off and nearly straight once aligned breaks that loop:

const reference = fish.targetPellet ? 0.8 : 1.15;
const shaped = Math.pow(clamp(Math.abs(error) / reference, 0, 1), 1.7);
const steer = fish.turnSide ? fish.turnSide : -Math.sign(error) * shaped;
fish.bendBias += (steer - fish.bendBias) * Math.min(1, dt * bendRate);

turnSide is the one compensating rule that survived: past about 150° both directions are equally good, the shaped law has nothing to choose with, and a fish that dithers there looks broken. It picks a side and commits until the error is back under 85°.

Note what the controller writes: bendBias, a muscle term. It never touches fish.angle.

Burst and coast

A fish that undulates continuously reads as a machine however good the hydrodynamics are. Pond koi beat once or twice and then glide with the body straight:

fish.gaitTime -= dt;
if (fish.gaitTime <= 0) {
  if (fish.gait === 'burst') {
    fish.gait = 'coast';
    fish.gaitTime = 1.2 + Math.random() * 1.8;
  } else {
    fish.gait = 'burst';
    fish.gaitTime = (Math.random() < 0.5 ? 1 : 2) / Math.max(0.4, hz);
  }
}
const needPower = Math.abs(angleDifference(fish.goalHeading, bodyAxis)) > 1.2
  || fish.velocity < body.length * 0.18;
if (fish.gait === 'coast' && !needPower) {
  gain = 0.14;                 // muscles nearly off; the body straightens
  hz = SWIM.cruiseHz * 0.75;
}

This is the payoff for building thrust out of a body meeting water: cutting the muscle command is the entire implementation. The fish coasts and decelerates on its own, the body straightens on its own, the wave phase keeps advancing so nothing freezes, and there is no glide animation to blend into. Under the old model this would have been a second animation state and a transition between them.

If you would rather watch than read: juju.games/cozy-games

What we would tell ourselves at the start

A shape decided independently of its track will not read as swimming. Not for anything that has to turn, chase and stop. You can shape the wave forever; the artefact lives in the seam between the two, and moving the wave upstream of the motion is what makes the artefact inexpressible rather than small.

Instrument the thing the complaint is about. The centre of mass was the easiest point to reach and the one point that could not show the problem. The ugliest debug view that draws what you are actually looking at beats the cleanest number that does not.

A pile of interacting rules means a missing mechanism. When the fix list grows a dead zone, a damping term, a magnitude floor and a tie-break, stop adding rules and go measure the thing they are all compensating for. Ours was a minus sign, and three of the four rules came out with it. The fourth turned out to be a real one.

Most free mahjong games can deal you a board you can't finish. I built mine backwards.

DevNash — Mon, 27 Jul 2026 10:43:44 +0000

Mahjong solitaire is a matching game: you take pairs of identical tiles off a 144-tile pile, but only tiles that are free — nothing stacked on top, and at least one long side open.

The obvious way to deal a board is to shuffle 144 tiles and drop them onto the layout. It is also wrong. A random arrangement can easily be unwinnable — the last four tiles buried under each other, two of a pair locked in positions that can never both be free. You do not find out at the start. You find out twenty minutes in, when nothing matches and there is no way back.

Try a few free mahjong sites and you will hit it. It is not a rare edge case; forward dealing produces unwinnable boards routinely.

Deal the board by playing it backwards

The fix is to stop generating boards and then checking them, and instead generate a solution and derive the board from it.

Two steps:

On the empty layout, simulate a legal removal order. Repeatedly pick any two currently-free slots and remove them, until the layout is empty. The positions have no faces yet, so "free" here is purely geometric.
Paste the face pairs onto that order: the pair that lands on the two slots removed at step k is removable at step k.

Replaying that order clears the board. So a complete solution exists before the player touches anything.

"Free" is the only real predicate:

/** Free = nothing stacked on top, and at least one long side (left/right) is open. */
function isFree(i, goneSet) {
  const tl = tiles[i];
  const there = (z, hx, hy) => {
    const j = index.get(z + '|' + hx + '|' + hy);
    return j === undefined ? false : !goneSet.has(j);
  };
  // anything overlapping on the layer above blocks it
  for (let dx = -1; dx <= 1; dx++)
    for (let dy = -1; dy <= 1; dy++)
      if (there(tl.z + 1, tl.hx + dx, tl.hy + dy)) return false;
  const side = (dx) => there(tl.z, tl.hx + dx, tl.hy - 1)
                    || there(tl.z, tl.hx + dx, tl.hy)
                    || there(tl.z, tl.hx + dx, tl.hy + 1);
  return !side(-2) || !side(2);
}

Positions are in half-tile units, which is why the offsets are ±1 and ±2: a tile covers two half-units on each axis, and half-units are what let the single top tile of the turtle sit centred on the 2×2 block below it instead of on a staircase.

Then the walk:

function removalOrder(idxs) {
  for (let attempt = 0; attempt < 60; attempt++) {
    const gone = new Set(/* everything not in idxs */);
    const order = [];
    let stuck = false;
    while (gone.size < tiles.length) {
      const free = idxs.filter((i) => !gone.has(i) && isFree(i, gone));
      if (free.length < 2) { stuck = true; break; }
      const a = pick(free);
      let b = a;
      while (b === a) b = pick(free);
      order.push([a, b]);
      gone.add(a); gone.add(b);
    }
    if (!stuck) return order;
  }
  return null;
}

Note the retry loop. Choosing greedily at random can strand the walk — you can reach a state with tiles left but fewer than two free slots. I could backtrack; instead the whole walk is just retried, because on the classic turtle it succeeds almost immediately and the code stays readable. Sixty attempts is far more headroom than it has ever needed.

There is also a fallback branch if all sixty fail, which pairs adjacent positions and produces a board that may not be solvable. It has never fired. I left it in because a slightly worse board is better than a blank screen, and I would rather have the degenerate path be visible in the source than pretend it cannot happen.

Pasting is the easy half:

function paste(order, pool) {
  const pairs = shuffled(pool).slice(0, order.length);
  order.forEach(([a, b], k) => {
    tiles[a].face = pairs[k].faces[0];
    tiles[b].face = pairs[k].faces[1];
  });
}

The claim that is easy to overstate

"Every board is solvable" is not "you cannot lose". The deal is solvable. You can still take the wrong pair and strand yourself, exactly as in any mahjong solitaire — that is the game.

So the same construction runs again on demand. Shuffle collects the faces still on the board, builds a fresh removal order over the still-occupied positions, and pastes them back down:

const idxs  = tiles.map((tl, i) => (tl.gone ? null : i)).filter((v) => v !== null);
const order = removalOrder(idxs);
if (order) paste(order, poolFromTiles(liveTiles()));

Whatever position you have played yourself into is recoverable. Which quietly changes a design decision too: running out of moves is a message and a button, never a loss. There is no game over screen, because there is no state the player can reach that they cannot get out of.

Then the tiles turned out to be harder than the algorithm

Unicode has a mahjong block, U+1F000–U+1F02B. Render the characters, done — except it is missing or half-broken in the default font stack on a lot of Windows and Android, and a board of tofu boxes would be the end of the game. So the faces are SVG.

Public-domain (CC0) riichi artwork covers 33 of the 42 faces. But riichi mahjong has no flower or season tiles and leaves its white dragon blank, so nine faces simply do not exist in that set.

Noto Sans Symbols 2 does cover the whole block, so I pulled the outlines out of the font with fontTools:

from fontTools.pens.svgPathPen import SVGPathPen

gs   = font.getGlyphSet()
name = font.getBestCmap()[0x1F022]   # 🀢 plum
pen  = SVGPathPen(gs)
gs[name].draw(pen)
path = pen.getCommands()

Two things I did not expect.

Each glyph draws its own tile border, as the first two contours. They are the outer and inner edge of a stroked rounded rectangle, and they are byte-identical across all eight bonus tiles. Drop contours 0 and 1 and you have just the artwork. Better still, contour 1's bounding box is the drawing area the type designer composed inside — a much better box to scale every face by than each glyph's own ink extents, because a snowflake and a plum spray are supposed to fill that area differently and normalising each one's bounds would flatten the whole set.

The small character in the corner is separable. Every one of these tiles carries its character (梅, 春, …) in the top-left of the drawing area, so the contours whose bounds fall in that corner are the character and the rest are the picture:

x0, y0, x1, y1 = bounds(gs, [contours[1]])       # the designer's drawing area
char, pic = [], []
for c in contours[2:]:
    cx0, cy0, cx1, cy1 = bounds(gs, [c])
    corner = cx1 < x0 + (x1 - x0) * 0.46 and cy0 > y0 + (y1 - y0) * 0.58
    (char if corner else pic).append(c)

Which means you can colour the two separately — picture in one colour, character in another — out of a single monochrome glyph.

That mattered more than I expected. My first attempt kept the font's own border and scaled the artwork down inside it. It looked terrible, and it took a side-by-side render to see why: none of the other 33 faces has a border, so a bordered tile reads as a sticker stuck onto a tile rather than a tile. Dropping the frame, filling the face, and matching the existing set's two-tone look was the whole difference.

The boring stack

Vanilla PHP, vanilla JS, SQLite. No framework, no build step, no npm anywhere in the request path. Every page is server-rendered and the JavaScript only adds interaction on top. The tile body is CSS — that is what gives the stack its depth and its shadows; the SVG is only the face plate.

It is live at juju.games/mahjong if you want to try to strand yourself.

The thing I am still unsure about: is a solvability guarantee even perceptible? A player who never gets stuck cannot tell it apart from luck, and a player who does get stuck is using Shuffle either way. It may be one of those properties that only shows up as the absence of a bad afternoon. How would you even measure it?

discuss

AI coding made me fall back in love with PHP

DevNash — Tue, 23 Jun 2026 16:19:32 +0000

Hi DEV 👋 first post here.

I'm an indie developer, and lately I've been building web apps with an AI coding assistant doing a lot of the typing. Along the way I noticed something I did not expect: the stack that works best with AI, for me, is a boring old one — vanilla PHP, vanilla JS, and SQLite. No framework, no build step, no compile.

Here's the thing I've come to believe: when AI writes most of the code, the bottleneck stops being "how fast can I type" and becomes "how fast can I see it run." And that's exactly where an old, non-compiled language quietly wins:

No build, no compile. AI edits a file, I hit refresh, I see the result. The loop is instant. No bundler, no toolchain to babysit, no waiting.
PHP is "boring," so AI is great at it. Decades of training data means the model writes idiomatic, working PHP on the first try far more often than it does for the framework-of-the-month.
Each request is self-contained. Server-rendered page = one file, simple to reason about, little hidden global state. Easy for me to review what the AI wrote, and easy for the AI to stay correct.

Going framework-free in 2026 sounds a little crazy, but paired with AI it's been the most fun and fast I've had building in years. I'm putting it into practice on a small site of brain-training games — juju.games — built entirely on this stack.

Curious if anyone else has felt this: that AI tooling quietly makes the simple, old, non-compiled stacks more attractive again, not less. 👇