DEV Community: Sam Novak

A PixiJS level-up halo that stays behind the portrait when the HUD scales

Sam Novak — Fri, 16 Oct 2026 17:20:39 +0000

A level-up halo is easy to get right on the screen you're developing on. You place the renderer, set the projection origin to the portrait's position, and it sits nicely behind the face. Then the HUD scales for a phone or a TV, the card moves, and the halo stays where it was.

This post compares three ways to attach a NixieFX halo to a PixiJS level-up card, measured at three HUD scales. It also checks two things that come up once the card is part of a real UI: a resize while the halo is already playing, and a fade-in on the card.

Setup: PixiJS 8.22.0, nixie-fx 0.1.21, headless Chrome 155 with SwiftShader WebGL, fixed 1/60 s steps and a fixed seed. The card is 240 x 280 design pixels: a 56 px radius portrait, a LEVEL 8 label with no backing plate, and a Continue button. The full scene code and the effect JSON are at the end.

The effect

Two one-shot emitters, both additive, gravity and drag set to 0 explicitly:

glow: one soft particle, 0.9 s lifetime, 150 px across growing to 1.45x, alpha peaking at 0.6
motes: 16 small particles from a ring just outside the portrait, drifting outward

I built it as NixieFX authoring JSON. If you'd rather tune it by eye, a visual particle editor for PixiJS such as NixieFX saves the same JSON format to your project folder. npx nixie-fx validate . reported 0 errors and 0 warnings, and the export's support report says supported for both the Pixi and Three backends, with no partial or unsupported modules. Nothing in this effect gets silently dropped at runtime.

Three ways to place the renderer

A. Stage root, origin read once. The renderer lives in a layer under the card at the stage root. At startup the code reads the portrait's global position and uses it as the projection origin:

const g = portrait.getGlobalPosition();
const vfx = new PixiVfxRenderer({
  parent: stageHaloLayer,
  projection: createPixiVfx2dProjection({
    originX: g.x, originY: g.y, pixelsPerUnit: 100, yAxis: "up",
  }),
});

B. Stage root, projection updated on resize. Same layer, but every layout change calls setProjection with the portrait's new global position and a scaled pixelsPerUnit:

function relayout(scale, x, y) {
  card.scale.set(scale);
  card.position.set(x, y);
  const g = portrait.getGlobalPosition();
  vfx.setProjection(createPixiVfx2dProjection({
    originX: g.x, originY: g.y, pixelsPerUnit: 100 * scale, yAxis: "up",
  }));
}

C. Inside the card. The renderer gets its own container inside the card, added before the portrait, so it draws behind it. The projection origin is the portrait's local position, and the card's own transform does the rest:

const cardHaloLayer = new Container();
card.addChild(cardHaloLayer, portrait, label, button);   // halo first = behind

const vfx = new PixiVfxRenderer({
  parent: cardHaloLayer,
  projection: createPixiVfx2dProjection({
    originX: 120, originY: 100, pixelsPerUnit: 100, yAxis: "up",   // card-local
  }),
});

What happened at three HUD scales

The card starts at 1.0x. Then it's re-laid out to 0.75x (bottom left, as on a phone) or 1.5x (as on a TV), and a level-up fires. Measured 0.3 s after the level-up, from the glow particle's debug quad mapped to screen space:

Layout	A: stage, origin once	B: stage + setProjection	C: inside the card
desktop 1.0x	centred, 1.48x portrait	centred, 1.48x	centred, 1.48x
phone 0.75x	192 px off, 1.98x portrait	centred, 1.48x	centred, 1.48x
tv 1.5x	122 px off, 0.99x portrait	centred, 1.48x	centred, 1.48x

"1.48x portrait" means the glow's radius is 1.48 times the portrait's radius on screen, which is what the effect was designed for. In A the glow keeps its startup size and position. At 0.75x it floats in empty space. At 1.5x it's almost exactly the size of the portrait, so the opaque portrait hides nearly all of it.

0.75x layout, 0.3 s after the level-up. Same effect file, same seed.

B and C produced identical numbers in every case. I also resized the card to 0.75x while a halo was already 0.15 s in. In B, setProjection moved the particles that were already alive, and they finished centred on the new position. C needs nothing for this case. A stayed 192 px off.

The label and the button

The glow reaches below the portrait. In layout C at 1.0x its lower edge sits at y = 283 px. The label occupies 268 to 298 and the button starts at 322, so the halo passes behind the label and stops well short of the button. That held at every scale for B and C: the glow ends 29 to 58 px above the button.

For the label I measured worst-case contrast. Each frame, I hid the label, rendered, read the pixels inside the label box with app.renderer.extract.pixels, took the brightest one and computed the WCAG ratio against the label colour #ffe7a3. With no halo the label measures 14.97:1. With the halo it bottomed out at 9.77:1 at 1.0x and 0.75x, and 9.62:1 at 1.5x. Both are comfortably above 4.5:1.

One thing that will skew this measurement: extract only reads what's in the stage. The background you pass to app.init isn't part of it, so without an opaque background shape in the stage, additive particles get measured against transparent black and look higher-contrast than they really are. The demo's first child is a full-size background rectangle for that reason.

A fade-in separates the stage layer from the card layer

Level-up cards usually fade or scale in. I set card.alpha = 0.4, fired the halo and measured mean luminance in a small box just left of the portrait:

A (stage root): 0.0297 at alpha 1 and 0.0297 at alpha 0.4. The halo ignores the card's alpha. B uses the same stage-level layer, so it inherits nothing from the card either.
C (inside the card): 0.0297 at alpha 1 and 0.0128 at alpha 0.4, against a background of 0.0075. It fades with the card.

card.alpha = 0.4. On the left the glow also shows through the semi-transparent portrait.

You could also sync alpha in B by hand. That means one more property to mirror on every change, along with position and scale, so I'd use C unless the halo has to escape the card's bounds or masks.

Limits

Software rendering, fixed steps. No frame-time numbers and no real GPU or phone. The geometry and alpha results don't depend on the GPU, but performance does.
Uniform scale only. I used card.scale.set(s). A non-uniform scale would stretch the halo in C. I didn't test it, and B would need its own handling.
One resolution. resolution: 1, no autoDensity. I didn't test device pixel ratio 2.
Worst-pixel contrast is a comparison tool, not an accessibility audit. It ignores font weight and anti-aliasing.
Masks and filters on the card would also apply to the halo in C. That's usually what you want, but check it if the card has a mask tighter than the glow.

For loading the export bundle and the renderer options used here, the NixieFX PixiJS particle effects guide walks through the same loadVfxExportBundle and PixiVfxRenderer setup.

Source

Scene setup for layout C (PixiJS 8.22.0, nixie-fx 0.1.21)

import { Application, Container, Graphics, Text } from "pixi.js";
import { loadVfxExportBundle } from "nixie-fx/export";
import { PixiVfxRenderer, createPixiVfx2dProjection } from "nixie-fx/pixi";
import manifest from "./vfx/manifest.json";
import haloJson from "./vfx/effects/level-up-halo.json";

const bundle = loadVfxExportBundle(
  { manifest, effectsByPath: { "effects/level-up-halo.json": haloJson } },
  { requiredBackend: "pixi2d", requiredEffectIds: ["level-up-halo"] },
);
const halo = bundle.effectsById.get("level-up-halo");

const app = new Application();
await app.init({ width: 640, height: 480, background: "#17131f", antialias: true });
document.body.appendChild(app.canvas);

const bg = new Graphics().rect(0, 0, 640, 480).fill("#17131f"); // so extract() sees it
const card = new Container();
app.stage.addChild(bg, card);

const cardHaloLayer = new Container();
const portrait = new Graphics()
  .circle(0, 0, 56).fill("#3a2f4a")
  .circle(0, -12, 20).fill("#c8a27a")
  .ellipse(0, 34, 34, 22).fill("#5b4a78")
  .circle(0, 0, 56).stroke({ color: "#d9b25c", width: 3 });
portrait.position.set(120, 100);

const label = new Text({
  text: "LEVEL 8",
  style: { fill: "#ffe7a3", fontSize: 18, fontWeight: "700", letterSpacing: 2 },
});
label.anchor.set(0.5);
label.position.set(120, 183);

const button = new Container();
button.addChild(new Graphics().roundRect(0, 0, 120, 40, 8).fill("#d9b25c"));
const buttonText = new Text({ text: "Continue", style: { fill: "#1d1508", fontSize: 16, fontWeight: "700" } });
buttonText.anchor.set(0.5);
buttonText.position.set(60, 20);
button.addChild(buttonText);
button.position.set(60, 222);

card.addChild(cardHaloLayer, portrait, label, button);

const vfx = new PixiVfxRenderer({
  parent: cardHaloLayer,
  projection: createPixiVfx2dProjection({ originX: 120, originY: 100, pixelsPerUnit: 100, yAxis: "up" }),
});

export function layoutCard(scale, x, y) {
  card.scale.set(scale);
  card.position.set(x, y);
}

export function levelUp(level) {
  label.text = `LEVEL ${level}`;
  vfx.createEffect(halo, { position: [0, 0, 0] });
}

app.ticker.add((t) => vfx.update(t.deltaMS / 1000));
layoutCard(1, 200, 100);

Effect authoring JSON (vfx-src/level-up-halo.json)

{
  "app": "vfx-editor",
  "kind": "particle-effect",
  "version": 1,
  "targetProfile": "pixi-ui-2d",
  "id": "level-up-halo",
  "name": "level-up-halo",
  "emitters": [
    {
      "id": "glow",
      "name": "Halo glow",
      "loop": false,
      "duration": 0.9,
      "maxParticles": 1,
      "render": {
        "blend": "additive",
        "depthTest": false,
        "depthInk": false
      },
      "forces": {
        "gravity": 0,
        "gravityValue": {
          "mode": "constant",
          "value": 0
        },
        "drag": 0,
        "dragValue": {
          "mode": "constant",
          "value": 0
        }
      },
      "modules": {
        "color": true,
        "size": true,
        "velocity": false,
        "rotation": false
      },
      "spawn": {
        "rate": 0,
        "bursts": [
          {
            "time": 0,
            "count": 1,
            "cycles": 1,
            "interval": 0,
            "probability": 1
          }
        ],
        "shape": "point"
      },
      "initializeParticle": {
        "lifetime": {
          "mode": "random",
          "min": 0.9,
          "max": 0.9
        },
        "size": {
          "mode": "random",
          "min": 1.5,
          "max": 1.5
        }
      },
      "color": {
        "gradient": {
          "mode": "blend",
          "colorStops": [
            {
              "position": 0,
              "color": [
                1,
                0.93,
                0.62
              ]
            },
            {
              "position": 1,
              "color": [
                1,
                0.62,
                0.18
              ]
            }
          ],
          "alphaStops": [
            {
              "position": 0,
              "alpha": 0
            },
            {
              "position": 0.2,
              "alpha": 0.6
            },
            {
              "position": 1,
              "alpha": 0
            }
          ]
        }
      },
      "billboard": {
        "sizeValue": {
          "mode": "curve",
          "curve": [
            {
              "x": 0,
              "y": 0.95
            },
            {
              "x": 1,
              "y": 1.45
            }
          ]
        }
      }
    },
    {
      "id": "motes",
      "name": "Rising motes",
      "loop": false,
      "duration": 0.9,
      "maxParticles": 24,
      "render": {
        "blend": "additive",
        "depthTest": false,
        "depthInk": false
      },
      "forces": {
        "gravity": 0,
        "gravityValue": {
          "mode": "constant",
          "value": 0
        },
        "drag": 0,
        "dragValue": {
          "mode": "constant",
          "value": 0
        }
      },
      "modules": {
        "color": true,
        "size": true,
        "velocity": true,
        "rotation": false
      },
      "spawn": {
        "rate": 0,
        "bursts": [
          {
            "time": 0,
            "count": 16,
            "cycles": 1,
            "interval": 0,
            "probability": 1
          }
        ],
        "shape": "circle",
        "radius": 0.62,
        "radiusThickness": 0,
        "rotation": [
          90,
          0,
          0
        ],
        "sphericalDirectionAmount": 0
      },
      "initializeParticle": {
        "lifetime": {
          "mode": "random",
          "min": 0.6,
          "max": 0.9
        },
        "size": {
          "mode": "random",
          "min": 0.05,
          "max": 0.08
        },
        "velocity": {
          "mode": "shapeDirection",
          "speed": {
            "mode": "random",
            "min": 0.25,
            "max": 0.5
          }
        }
      },
      "color": {
        "gradient": {
          "mode": "blend",
          "colorStops": [
            {
              "position": 0,
              "color": [
                1,
                0.93,
                0.62
              ]
            },
            {
              "position": 1,
              "color": [
                1,
                0.62,
                0.18
              ]
            }
          ],
          "alphaStops": [
            {
              "position": 0,
              "alpha": 1
            },
            {
              "position": 1,
              "alpha": 0
            }
          ]
        }
      },
      "billboard": {
        "sizeValue": {
          "mode": "curve",
          "curve": [
            {
              "x": 0,
              "y": 1
            },
            {
              "x": 1,
              "y": 0.4
            }
          ]
        }
      }
    }
  ]
}

Export it with npx nixie-fx export . from a folder that has a vfx-editor.prj. The game loads the generated vfx/manifest.json and vfx/effects/level-up-halo.json, not the source file.

This article was written with AI assistance and reviewed by me. Every number and both screenshots come from running the demo locally.

One task file, four owners: a worked handoff for an agent-written ops script

Sam Novak — Fri, 16 Oct 2026 17:19:05 +0000

Most handoff templates are written by one person and read by everyone else. This one works the other way: the task file has four sections, and each section belongs to a different person. The author fills in the first one, the runner the second, the reviewer the third, and whoever deploys or runs the change the fourth. A 60-line Python script reads the file and tells you whose turn it is.

The worked example is a small ops change that a coding agent can easily get almost right: adding --dry-run to a script that deactivates inactive users. The people are invented. The script, the fixture database, the commits and every output below come from a toy repo I ran locally (Python 3.13.5, SQLite 3.51.0).

The responsibility map

Role	Writes	Uses their own	Hands off when
Author	Section 1: outcome, scope, acceptance check, stop conditions	knowledge of why the change exists	the acceptance check is something another person can run
Runner	Section 2: environment, delivered commit, evidence, what wasn't tested	repo clone, coding agent, fixture data	there's a commit SHA to review
Reviewer	Section 3: commit reviewed, check run, verdict, reason	CI or a clean checkout	the verdict names a commit
Operator	Section 4: target, dry-run review, window, undo plan	production access	the change has run, or been rolled back

The third column matters most. Each person works with access they already have. The runner does the work in their own clone with their own agent and never needs production credentials. Only the operator touches the production database. If the runner finds they need something they don't have, that goes in "Stop and ask if", not in a borrowed login.

For a script, "deploying" means running it against real data, so the fourth role is an operator rather than a release pipeline. It is still a separate decision from "the code is correct".

Step 1: the template

# Task: [one line]

## 1. Author
- Owner: [who decides what done means]
- Outcome: [observable result]
- Allowed changes: [files or modules]
- Do not touch: [what stays as it is]
- Acceptance check: [command or steps the reviewer will run]
- Stop and ask if: [conditions]

## 2. Runner
- Runner: [name]
- Claimed: [date]
- Environment: [where you ran it, with whose access]
- Delivered commit: [sha]
- Evidence: [output, logs]
- Not tested: [be specific]

## 3. Reviewer
- Reviewer: [name, not the runner]
- Commit reviewed: [sha]
- Check run: [what you ran]
- Verdict: [accepted / sent back]
- Reason: [one or two sentences]

## 4. Operator
- Operator: [who runs or deploys it]
- Target: [environment]
- Dry-run output reviewed: [by whom, when]
- Window: [when]
- Undo plan: [how to reverse it]

Anything still in [brackets] counts as empty.

Step 2: the checker

handoff.py parses the - Key: value lines under each ## n. Role heading. The next owner is the first role with empty fields. On top of that it applies four rules:

if filled(run.get("Runner", "")) and run.get("Runner") == rev.get("Reviewer"):
    problems.append("runner and reviewer are the same person")
if "prod" in run.get("Environment", "").lower():
    problems.append("runner environment mentions production; runs against prod belong to the operator")
verdict = rev.get("Verdict", "").lower()
reviewed, delivered = rev.get("Commit reviewed", ""), run.get("Delivered commit", "")
if filled(reviewed) and reviewed != delivered:
    if verdict == "accepted":
        problems.append(f"acceptance is for {reviewed}, but the runner now delivers {delivered}")
    next_role = ("Reviewer", [f"review of {delivered} (last review was {reviewed})"])
elif verdict == "sent back":
    next_role = ("Runner", ["a new Delivered commit (sent back: " + rev.get("Reason", "") + ")"])
if any(filled(v) for v in op.values()) and verdict != "accepted":
    problems.append("operator section started before the reviewer accepted")

It exits 1 when there's a problem, so it can run in CI on the PR that carries the task file.

Step 3: the worked handoff

The author prepares. Nadia, the support ops lead, fills in section 1. The outcome: --dry-run prints the users that would be deactivated and writes nothing. The acceptance check is a script she wrote, acceptance.sh. It builds a fresh 8-user fixture database, dumps it, runs the dry run, dumps it again and compares the hashes. Then it does a real run and checks which IDs changed.

$ python3 handoff.py 1-prepared.md
next: Runner (missing: Runner, Claimed, Environment, Delivered commit, Evidence, Not tested)

The runner delivers. Arman claims the task and works in his own clone with his coding agent, against fixture.db only. The dry run looks right:

$ python3 deactivate_inactive.py --db fixture.db --today 2026-10-16 --dry-run
would deactivate ben@example.test
would deactivate dev@example.test
would deactivate gus@example.test
3 user(s), cutoff 2026-04-19

He fills in section 2 with commit ebe6594.

$ python3 handoff.py 2-delivered.md
next: Reviewer (missing: Reviewer, Commit reviewed, Check run, Verdict, Reason)

The reviewer sends it back. Kofi runs the author's check on ebe6594:

$ sh acceptance.sh deactivate_inactive.py
1. dry run lists 3 users:            3
2. dry run leaves the database as is: before 68cec51f91d1 after 3721c4144bf3
   FAIL: dry run changed the database
audit_log rows: 3
3. real run deactivates ids:         2,4,7
4. admin 5 still active:             1
5. second run finds:                 0 user(s), cutoff 2026-04-19
6. audit rows after real runs:       3
ACCEPTANCE: FAIL

The dry run printed the right names and correctly skipped the UPDATE, but it still wrote three audit_log rows saying those users were deactivated. The insert sat outside the if not args.dry_run: guard, inside a with sqlite3.connect(...) block that commits on exit:

for user_id, email in users:
    print(("would deactivate " if args.dry_run else "deactivated ") + email)
    conn.execute("INSERT INTO audit_log (user_id, action, at) VALUES (?, ?, ?)",
                 (user_id, "deactivate", args.today))
    if not args.dry_run:
        conn.execute("UPDATE users SET active = 0 WHERE id = ?", (user_id,))

The runner's own evidence couldn't show this, because it only looked at the printed list and the users table. The author's check compares the whole database, so it did.

Kofi writes "sent back" with the reason.

$ python3 handoff.py 3-sent-back.md
next: Runner (missing: a new Delivered commit (sent back: the dry run inserts 3 audit_log rows, so the log would say 3 users were deactivated when none were))

The runner fixes it. The fix moves both writes into a single block that only runs for a real run. Arman updates section 2 to commit 677d974. The old verdict is still sitting in section 3, and the checker won't let it carry over:

$ python3 handoff.py 4-redelivered.md
next: Reviewer (missing: review of 677d974 (last review was ebe6594))

The reviewer accepts. Kofi reruns the check on 677d974: the dump hash is 68cec51f91d1 before and after the dry run, the real run touches IDs 2, 4 and 7, and a second run finds 0 users. He updates section 3 to "accepted".

$ python3 handoff.py 5-accepted.md
next: Operator (missing: Operator, Target, Dry-run output reviewed, Window, Undo plan)

The operator plans the run. Ines is on call and holds production database access. She fills in section 4: production users DB, the dry-run output reviewed with Nadia before the real run, Tuesday 10:00 after the weekly backup, and an undo plan of UPDATE users SET active = 1 for the IDs in that run's audit_log rows.

$ python3 handoff.py 6-ready-to-run.md
next: nobody, handoff complete

The production run itself is outside the toy repo. Section 4 records the plan, and I'm not claiming a real run happened.

The undo plan depends on audit_log being accurate, which is exactly what the first commit would have broken. That's the reason the operator should see the reviewer's verdict before running anything, and the checker enforces it.

Two cases the checker refuses

The same file with Arman as both runner and reviewer, and a file where the acceptance names the old commit:

$ python3 handoff.py x-self-review.md
next: Operator (missing: Operator, Target, Dry-run output reviewed, Window, Undo plan)
PROBLEM: runner and reviewer are the same person

$ python3 handoff.py x-stale-accept.md
next: Reviewer (missing: review of 677d974 (last review was ebe6594))
PROBLEM: acceptance is for ebe6594, but the runner now delivers 677d974

Both exit with status 1.

Where a tracker fits

The task file is plain text so it can live next to the code and be reviewed in the same pull request. A tracker gives you the same structure with less typing. Work management for human and AI teams needs the claim, the delivery and the acceptance to stay separate records with separate people on them. Wagglet's write-up on making human and AI task pairs meaningful covers the people side: who chooses a task, how claim and release work, and why a delivery shouldn't silently become acceptance.

Limits

The checker trusts what people write. It can't tell whether Kofi really ran acceptance.sh. Paste the output, or run the check in CI and link the job.
Names are strings. "Arman" and "arman" count as different people. In a real setup, compare usernames from your auth system.
The prod rule is a substring match. It catches the obvious case, not a hostname that doesn't contain "prod".
SQLite only. The dump-hash comparison works for a small fixture. For a real database you'd compare the tables the script is allowed to touch, plus row counts on the ones it isn't.
The operator section is a plan. This example stops before production.

This article was written with AI assistance and reviewed by me. The team is invented; the code, the commits and every output above come from running it locally.

Audit a delivered task against git: a template, an event log, and a 100-line checker

Sam Novak — Thu, 15 Oct 2026 07:56:47 +0000

When a task comes back as "done", the reviewer usually checks the result. Much less often, anyone checks the path it took: which brief the runner actually worked from, which commit the evidence belongs to, whether the test output was produced by the code being accepted, and who made the final call. When something breaks a month later, that path is what you need, and it's rarely written down in a form you can check.

This tutorial builds that check. There are three parts:

A task template that the author fills in before anyone claims the work.
An append-only event log with one line per handoff: prepared, claimed, delivered, sent back, accepted.
A 100-line Python script that rebuilds the timeline from the log and checks it against the git history. It also re-runs each delivery's evidence on a clean checkout of the delivered commit.

Everything below comes from a toy repository I built for this post. The people are invented and the commit times were set by hand, but every commit, test run and audit output is real.

The roles

The task author prepares the work. Here that's Nare, a support lead. She writes TASK.md and commits it, so the brief has a SHA everyone can refer to.
The runner executes it with their own authorized tools. Lilit claims the task and works in her own clone, with her own git identity and push access, assisted by a coding agent. Nobody lends her a token, and the log never records one.
The reviewer judges acceptance. Hayk runs the acceptance check on the delivered commit and either sends the work back with a reason or accepts it. He is not the runner.

Step 1: the task template

# Task: export log shows "75m 00s" for long exports

## Prepared by
Author: Nare (support lead). Reviewer: Hayk (backend).

## Outcome
Durations of one hour or more read as hours, minutes and seconds:
4500 s -> "1h 15m 00s". Under one hour stays as it is: 125 s -> "2m 05s".

## Out of scope
Changing the log format for anything other than durations.

## Acceptance check (the reviewer runs this on the delivered commit)
    python3 -m unittest -v
Must include tests for 4500 s, 3600 s and 59 s, and pass.

## Evidence to attach
The delivered commit SHA and the exact output of the acceptance check.

Two lines in it matter for the audit. "Acceptance check" is a command, not a sentence, so it can be re-run. "Evidence to attach" asks for the SHA together with the output, so the output can't drift away from the code it describes.

Nare commits this as 0bc904f before the claim. If someone edits the brief later, the audit notices.

Step 2: the handoff, as it happened

The bug: the export log printed 75m 00s for a 75-minute export.

Lilit's first delivery, fc29eb4, added an hours branch and one test for 4500 s. Her own run passed 3 tests. Hayk ran the acceptance check from TASK.md, saw that the 3600 s and 59 s tests it asks for were missing, and tried 3600 s by hand. It returned 60m 00s, because the code used > where it needed >=. He sent the work back with that reason.

The second delivery, 1bbebc9, changed the comparison and added both tests. Five tests passed, and Hayk accepted it.

Each handoff is one line in events.jsonl, next to the repo:

{"at": "2026-10-15T09:20:00+04:00", "type": "prepared", "by": "Nare", "commit": "0bc904f"}
{"at": "2026-10-15T09:35:00+04:00", "type": "claimed", "by": "Lilit"}
{"at": "2026-10-15T10:12:00+04:00", "type": "delivered", "by": "Lilit", "attempt": 1, "commit": "fc29eb4", "evidence": {"cmd": "python3 -m unittest -v", "result": "Ran 3 tests: OK"}}
{"at": "2026-10-15T10:40:00+04:00", "type": "sent_back", "by": "Hayk", "attempt": 1, "reason": "TASK.md asks for 3600 s and 59 s tests. 3600 s returns '60m 00s'."}
{"at": "2026-10-15T11:15:00+04:00", "type": "delivered", "by": "Lilit", "attempt": 2, "commit": "1bbebc9", "evidence": {"cmd": "python3 -m unittest -v", "result": "Ran 5 tests: OK"}}
{"at": "2026-10-15T11:30:00+04:00", "type": "accepted", "by": "Hayk", "attempt": 2, "commit": "1bbebc9"}

The log is append-only. The rejected first attempt stays in it, which is the point. Reading it later, you can see why >= matters.

Step 3: the audit script

"""Rebuild a task's timeline from its event log and check it against git.

Usage: python3 audit.py <repo> <events.jsonl>
Exits 1 if any check fails. Stdlib only, Python 3.11+.
"""
import json
import re
import subprocess
import sys
import tempfile
from datetime import datetime


def git(repo, *args, check=True):
    return subprocess.run(["git", "-C", repo, *args], check=check,
                          capture_output=True, text=True)


def run_evidence(repo, commit, cmd):
    """Re-run the evidence command on a clean checkout of the commit."""
    with tempfile.TemporaryDirectory() as tmp:
        git(repo, "worktree", "add", "--detach", "-q", tmp, commit)
        try:
            out = subprocess.run(cmd, shell=True, cwd=tmp,
                                 capture_output=True, text=True)
        finally:
            git(repo, "worktree", "remove", "--force", tmp)
    text = out.stdout + out.stderr
    ran = re.search(r"Ran (\d+) tests?", text)
    status = "OK" if out.returncode == 0 else "FAILED"
    return f"Ran {ran.group(1) if ran else '?'} tests: {status}"


def audit(repo, events):
    fails = []
    when = lambda e: datetime.fromisoformat(e["at"])
    times = [when(e) for e in events]
    if times != sorted(times):
        fails.append("events are not in time order")

    prepared = next((e for e in events if e["type"] == "prepared"), None)
    claim = next((e for e in events if e["type"] == "claimed"), None)
    if not prepared or not claim or when(claim) < when(prepared):
        fails.append("no preparation before the claim")
        return fails
    runner = claim["by"]
    task_at_prep = git(repo, "show", f"{prepared['commit']}:TASK.md").stdout

    deliveries = {}
    for e in events:
        if e["type"] == "delivered":
            n, c = e["attempt"], e["commit"]
            deliveries[n] = e
            if git(repo, "cat-file", "-e", c, check=False).returncode:
                fails.append(f"attempt {n}: commit {c} not in repo")
                continue
            if git(repo, "merge-base", "--is-ancestor", prepared["commit"],
                   c, check=False).returncode:
                fails.append(f"attempt {n}: {c} is not built on the task")
            made = git(repo, "show", "-s", "--format=%cI", c).stdout.strip()
            if datetime.fromisoformat(made) > when(e):
                fails.append(f"attempt {n}: delivered before {c} existed")
            if git(repo, "show", f"{c}:TASK.md").stdout != task_at_prep:
                fails.append(f"attempt {n}: TASK.md changed after prep")
            got = run_evidence(repo, c, e["evidence"]["cmd"])
            if got != e["evidence"]["result"]:
                fails.append(f"attempt {n}: evidence says "
                             f"'{e['evidence']['result']}', re-run gives "
                             f"'{got}'")
        elif e["type"] in ("sent_back", "accepted"):
            n = e["attempt"]
            if n not in deliveries:
                fails.append(f"{e['type']} for attempt {n} with no delivery")
            if e["by"] == runner:
                fails.append(f"{e['type']} by the runner ({runner})")
            if e["type"] == "accepted":
                if e["commit"] != deliveries.get(n, {}).get("commit"):
                    fails.append(f"accepted {e['commit']}, but attempt {n}"
                                 f" delivered {deliveries[n]['commit']}")
                if e is not events[-1]:
                    fails.append("events after acceptance")
    if not events or events[-1]["type"] != "accepted":
        fails.append("no acceptance at the end of the log")
    return fails


def main(repo, path):
    events = [json.loads(line) for line in open(path) if line.strip()]
    for e in events:
        extra = e.get("commit") or e.get("reason") or ""
        print(f"{e['at'][11:16]}  {e['type']:<9} {e['by']:<6} {extra}")
    fails = audit(repo, events)
    print("\nPASS" if not fails else f"\nFAIL ({len(fails)})")
    for f in fails:
        print(f"  - {f}")
    return 1 if fails else 0


if __name__ == "__main__":
    sys.exit(main(*sys.argv[1:3]))

It checks five things:

The events are in time order, and the brief was prepared before the claim.
Every delivered commit exists, is built on the prepared task commit, and existed before it was delivered.
TASK.md is the same in every delivered commit as it was at preparation, so the scope wasn't quietly edited along the way.
Re-running the evidence command on a clean git worktree of the delivered commit gives the same result as the log claims.
Verdicts come from someone other than the runner, and the accepted commit is the one actually delivered in that attempt.

Running it

On the log above:

$ python3 audit.py toy logs/events.jsonl
09:20  prepared  Nare   0bc904f
09:35  claimed   Lilit  
10:12  delivered Lilit  fc29eb4
10:40  sent_back Hayk   TASK.md asks for 3600 s and 59 s tests. 3600 s returns '60m 00s'.
11:15  delivered Lilit  1bbebc9
11:30  accepted  Hayk   1bbebc9

PASS

To see what it catches, here is a second log for the same repo, written the way logs often get written in a hurry:

{"at": "2026-10-15T09:20:00+04:00", "type": "prepared", "by": "Nare", "commit": "0bc904f"}
{"at": "2026-10-15T09:35:00+04:00", "type": "claimed", "by": "Lilit"}
{"at": "2026-10-15T10:02:00+04:00", "type": "delivered", "by": "Lilit", "attempt": 1, "commit": "fc29eb4", "evidence": {"cmd": "python3 -m unittest -v", "result": "Ran 3 tests: OK"}}
{"at": "2026-10-15T11:15:00+04:00", "type": "delivered", "by": "Lilit", "attempt": 2, "commit": "1bbebc9", "evidence": {"cmd": "python3 -m unittest -v", "result": "Ran 3 tests: OK"}}
{"at": "2026-10-15T11:20:00+04:00", "type": "accepted", "by": "Lilit", "attempt": 2, "commit": "fc29eb4"}

$ python3 audit.py toy logs/events-sloppy.jsonl
09:20  prepared  Nare   0bc904f
09:35  claimed   Lilit  
10:02  delivered Lilit  fc29eb4
11:15  delivered Lilit  1bbebc9
11:20  accepted  Lilit  fc29eb4

FAIL (4)
  - attempt 1: delivered before fc29eb4 existed
  - attempt 2: evidence says 'Ran 3 tests: OK', re-run gives 'Ran 5 tests: OK'
  - accepted by the runner (Lilit)
  - accepted fc29eb4, but attempt 2 delivered 1bbebc9

Every one of these looks fine on a task board. The first delivery was logged at 10:02, three minutes before the commit it points to was made, so the evidence can't be about that commit. The second delivery's evidence was copied from the first attempt, and re-running it gives 5 tests, not 3. The runner accepted her own work. And the commit that was accepted is not the one that was delivered.

Where the log lives

The event log is only useful if it lives with the task and nobody can tidy it up later. A tracker that already keeps these as separate events saves you writing the JSONL by hand. Wagglet's request-to-delivery workflow records the claim, the delivery report with the branch, and the reviewer's verdict as separate events. Send back keeps the same runner, and independent acceptance has to come from someone other than the runner. That is the same split the audit checks. Whatever tool you use, the test is the same: could someone who wasn't there take over this task from its history alone? If so, the work is transferable AI work and not one person's memory.

Limits

It checks the record, not the judgment. The audit passed Lilit's first delivery. The missing 3600 s and 59 s tests were caught by Hayk reading TASK.md, not by the script. Checking that tests exist for each case in the brief is still the reviewer's job.
It missed a gap in the sloppy log. Attempt 2 was delivered with no verdict on attempt 1, and the script didn't flag it. A rule like "every delivery after the first follows a send-back" would catch it. I left it out to keep the script short, and because some teams allow a runner to re-deliver before review.
Re-running evidence only works for deterministic commands. Unit tests are fine. Screenshots, flaky integration tests and anything that calls a live service are not. For those, the log needs an artifact hash and the reviewer's own note.
It trusts the log's names and times. Anyone who can write the JSONL can write "Hayk". In a real setup, the log should come from the tracker's own records, not a file the runner edits.
It's slow on big suites. Every delivery is re-run from a clean worktree. That's fine for a five-test toy, but in CI you would cache it or re-run only the delivered attempt.

This post was drafted with AI assistance. The toy repository, commits, test runs and audit output are real and were run locally; the people and times are invented.

"Make the import better" is not a task: a two-part template and a worked handoff

Sam Novak — Wed, 14 Oct 2026 13:51:27 +0000

"Make the CSV import better" is a real kind of request. It shows up in a backlog after a few support tickets, and nobody can finish it. An engineer could rewrite the parser, add a preview screen, or support three more file formats, and the person who asked still might not see their problem fixed. A coding agent given the same sentence will happily do any of those.

This tutorial turns that sentence into one task with a single outcome and a test that decides it. It uses a template with two halves: one for the agent, one for the person running and accepting the work. The example is a small fixture I wrote for this post. The test output in it is real.

Step 1: find the observation behind the request

Vague requests are usually a summary of something specific. Ask the person who wrote it what they saw, and get one example.

In this example, the support lead comes back with this: customers who export contacts from a spreadsheet app with "CSV UTF-8" get Missing column: email, even though the first column is clearly called email. Saving the same data as plain CSV works.

That's a byte-order mark. Some spreadsheet apps write three bytes (EF BB BF) at the start of a UTF-8 CSV. The importer reads the first header as \uFEFFemail, which isn't email.

Now there's something to test.

Step 2: write the outcome so nobody has to interpret it

One sentence, no "better", "cleaner" or "more robust":

A UTF-8 CSV that starts with a byte-order mark imports the same rows as the same file without one.

Then add the three things that keep the task small:

Check: the command that decides it, and what it should report.
Keep: behaviour that already works and must not change.
Out of scope: the nearby problems you're deliberately not solving yet.

The out-of-scope list matters more than it looks. "Better import" also covers semicolon-separated files, UTF-16 exports and quoted commas. Writing them down stops the agent from taking them on, and gives you three candidate tasks for later.

The template

Here's the whole template. The top block is the shared task card. The agent gets the full working context, and the human gets a short runbook for what only a person can do.

TASK CARD
Outcome:      <one observable sentence>
Check:        <command> -> <expected result>
Keep:         <behaviour that must not change>
Out of scope: <nearby problems, listed on purpose>
Prepared by:  <who wrote and owns this task>
Run by:       <who claims it, with their own agent, checkout and credentials>
Accepted by:  <who decides whether the delivery is done>

AGENT INSTRUCTIONS
Context:      <files, functions, fixtures>
Change:       <what may change>
Do not:       <what must stay untouched>
Stop and ask: <conditions where the agent hands back control>
Deliver:      <diff, commands run, their output, known limits>

HUMAN INSTRUCTIONS
Before:       <how to start: branch, workspace, data you may use>
Watch for:    <what only a person can notice or decide>
Verify:       <the check you rerun yourself before delivery>
Escalate:     <who to ask, and when>

The three roles are on the card on purpose. The person preparing the task is not always the person running it, and the person accepting it should be able to say no for a concrete reason. The runner uses their own access. If they don't have it, someone with the right permission grants it or takes the task. No one shares a login or token with the agent.

The worked handoff

Filled in for the import bug:

TASK CARD
Outcome:      A UTF-8 CSV that starts with a byte-order mark imports
              the same rows as the same file without one.
Check:        npm test -> 4 of 4 pass, including
              "UTF-8 file with a byte-order mark imports both rows"
Keep:         plain CSV imports; quoted/capitalised headers import;
              a file with no email column is still rejected with
              "Missing column: email"
Out of scope: semicolon delimiters, UTF-16 files, quoted commas,
              any UI change
Prepared by:  support lead (wrote the repro) + backend engineer
Run by:       backend engineer, own checkout, own coding agent
Accepted by:  support lead, who re-imports the customer-style file

AGENT INSTRUCTIONS
Context:      src/importContacts.js, test/import.test.js, fixtures/
Change:       importContacts() only
Do not:       change parseHeader() output for files without a BOM,
              change error messages, add dependencies
Stop and ask: if the fix needs a CSV library or touches the UI
Deliver:      diff, npm test output before and after, limits

HUMAN INSTRUCTIONS
Before:       use the fixtures only, never a real customer export
Watch for:    the agent "fixing" more than the BOM case
Verify:       run npm test yourself; open the diff, expect one line
Escalate:     anything about other encodings goes back to the
              support lead as a new task

The fixture has four tests: the new case and the three "keep" behaviours. Before any change:

✖ UTF-8 file with a byte-order mark imports both rows
✔ plain UTF-8 file still imports
✔ quoted, capitalised header still imports
✔ missing email column is still rejected with the same message
ℹ tests 4
ℹ pass 3
ℹ fail 1
  AssertionError [ERR_ASSERTION]: Missing column: email

That failing test is written before the fix, by whoever prepares the task. If it doesn't fail, you haven't reproduced the complaint, and the task isn't ready.

The fix is one line in importContacts(). It strips a leading BOM before splitting the file into lines:

-  const lines = text.split(/\r?\n/).filter((l) => l.length > 0);
+  const lines = text.replace(/^\uFEFF/, '').split(/\r?\n/).filter((l) => l.length > 0);

After:

✔ UTF-8 file with a byte-order mark imports both rows
✔ plain UTF-8 file still imports
✔ quoted, capitalised header still imports
✔ missing email column is still rejected with the same message
ℹ tests 4
ℹ pass 4
ℹ fail 0

One detail I ran into while building the fixture: my first version of the importer called trim() on every header, and trim() already removes \uFEFF, so the bug didn't reproduce. An importer that compares header names without trimming them shows the bug. That's another reason to write the failing test first instead of trusting a description of the bug.

What the delivery should contain

The runner's report back to the acceptor is short, because the task card already says what to look at:

Changed:   src/importContacts.js (1 line)
Ran:       npm test (before: 3/4, after: 4/4)
Not done:  other encodings and delimiters (out of scope)
Known gap: only a BOM at the very start is removed

The support lead doesn't need to read the parser. They re-import the customer-style file, see two contacts, and accept. Or they find something else, and that goes back on the same task with a concrete reason, rather than into a new "make it better" ticket.

Where to keep the template

Put it where the task lives, not in a chat thread. Most AI agent task management software has a description field, and that's enough for the task card. The agent and human halves work best as two separate fields, because they have different readers. Wagglet's write-up on writing one task with agent instructions and a human runbook explains that split in more detail.

Limits

The check proves one thing. Four passing tests show the BOM file imports and three existing behaviours didn't change. They say nothing about the import being "better" in any wider sense.
The fixture is small and made up. The importer is an 18-line toy written for this post, not production code. It doesn't handle quoted commas at all, which is fine here only because that's listed as out of scope.
The roles are an example. In a small team, one person may prepare and accept. Keep acceptance with someone other than the runner if you can.
Shrinking the task is a judgment call. Someone decided the BOM was the complaint worth fixing first. If that guess is wrong, a perfectly bounded task still fixes the wrong thing. Confirm the observation before writing the card.

This post was written with AI assistance and reviewed by me. The fixture and its test output are real and were run for this post.

Let the designer's spec be the test: a bounded UI change request for game UI

Sam Novak — Wed, 14 Oct 2026 07:23:13 +0000

"The quest reward toast feels cramped and is hard to read on phones."

That's a fair complaint, and a hard thing to hand to an engineer. "Cramped" and "hard to read" are real observations, but nobody can finish them. The engineer guesses, the designer looks at the result, and the next round starts with "closer, but still not quite."

This tutorial turns that sentence into a request the engineer can finish and the designer can accept without either of them arguing about taste. The trick is small: the designer writes the spec as a data file, and a short script runs that same file as the test. I built the whole thing as a toy fixture (one HTML toast, one CSS file, the spec, and a checker run in headless Chrome) so every result below comes from an actual run.

Who does what

Three roles, decided before anyone touches CSS:

Prepares the work: the UI designer. They know what's wrong and what "fixed" looks like. They write the intent in one sentence and the spec below.
Executes it: the UI engineer, in their own checkout, with their own tools. If they hand the CSS to a coding agent, that agent runs under the engineer's account and the engineer owns the diff.
Judges acceptance: the designer again. They read the check report and look at two screenshots. The engineer reviews the code, but doesn't decide whether the toast is right.

This split matters more once agents are involved. Human AI collaboration in game development tends to go wrong when the person who knows what "right" means isn't the one who checks the result, so the check has to be something the designer wrote.

Step 1: replace taste words with properties

Go through the complaint word by word and ask what you would measure.

"Cramped" becomes padding, the gap between icon and text, and icon size.
"Hard to read" becomes font size, line height and contrast against the toast background.
"On phones" becomes a viewport width (360px) and a rule that the toast stays on screen.

The designer also adds the case they worry about: the German string, which is the longest one in the localization sheet.

Step 2: write the spec as data

This is the whole template. It's the designer's file, written in the units they already use in their design tool:

{
  "change": "Quest reward toast: readable at phone width, roomier, nothing cut off",
  "requestedBy": "UI designer",
  "page": "toast.html",
  "viewports": [360, 1280],
  "checks": [
    { "name": "toast stays fully on screen with 8px to spare", "selector": ".toast", "insideViewport": 8 },
    { "name": "padding is 12px top/bottom, 16px left/right", "selector": ".toast",
      "style": { "padding-top": "12px", "padding-bottom": "12px", "padding-left": "16px", "padding-right": "16px" } },
    { "name": "12px between icon and text", "selector": ".toast", "style": { "column-gap": "12px" } },
    { "name": "icon is 40 x 40", "selector": ".toast__icon", "box": { "width": 40, "height": 40 } },
    { "name": "title is 18px on a 24px line", "selector": ".toast__title", "style": { "font-size": "18px", "line-height": "24px" } },
    { "name": "title contrast is at least 4.5:1", "selector": ".toast__title", "minContrast": 4.5, "against": ".toast" },
    { "name": "title shows all its text in at most 2 lines", "selector": ".toast__title", "maxLines": 2, "noClipping": true }
  ]
}

Each check has a plain-language name, because the designer reads the report, not the code. The selectors are the only part the designer needs help with, and the engineer can fill those in during a two-minute call.

Note what isn't in the spec: no CSS approach, no flexbox-or-grid, no "make it pop." The spec says what must be true on screen, and the engineer chooses how.

Step 3: a checker that reads the spec

The checker is one HTML page. For each viewport it loads the component in an iframe of that exact width, then runs every check against computed styles and layout boxes. The core loop, trimmed:

for (const el of doc.querySelectorAll(c.selector)) {
  const cs = win.getComputedStyle(el), box = el.getBoundingClientRect();
  for (const [prop, want] of Object.entries(c.style ?? {})) {
    const got = cs.getPropertyValue(prop);
    if (got !== want) failures.push(`${prop} is ${got}, want ${want}`);
  }
  if (c.insideViewport !== undefined && (box.left < c.insideViewport || box.right > vw - c.insideViewport))
    failures.push(`spans ${Math.round(box.left)}-${Math.round(box.right)}px, viewport is ${vw}px`);
  if (c.maxLines && Math.round(box.height / parseFloat(cs.lineHeight)) > c.maxLines)
    failures.push(`uses more than ${c.maxLines} lines`);
  if (c.noClipping && el.scrollWidth > el.clientWidth)
    failures.push(`text is cut off (${el.scrollWidth}px of text in ${el.clientWidth}px)`);
  // box sizes and WCAG contrast work the same way
}

A shell script serves the folder, renders the page with chrome --headless=new --dump-dom, and prints the JSON the page wrote. One detail cost me time: headless Chrome won't lay out a window narrower than its minimum, so the 360px viewport has to be an iframe inside a wider window rather than the window itself.

Step 4: the worked handoff

Before. Against the original CSS, 3 of 14 checks passed (7 checks at 2 viewports). The report said, among other things, .toast spans 16-412px, viewport is 360px, padding 6px/8px instead of 12px/16px, and title contrast 3.50:1.

Attempt 1. The engineer changed exactly the values the spec listed: padding, gap, icon, font size, line height, and a lighter title color. 11 of 14 passed. The three failures were the interesting ones:

At 360px the toast ran to 428px. Bigger padding on a fixed 380px content-box width made it wider than before.
At both widths the German title was cut off: 361px of text in 328px. The original CSS used white-space: nowrap with an ellipsis, which was harmless at 15px and clipped at 18px.

Nobody had asked for those to change, and both were caught without the designer opening a browser. Matching the listed numbers wasn't enough to fix the actual complaint.

Attempt 2. box-sizing: border-box, a width of min(380px, calc(100% - 32px)), and the title allowed to wrap instead of ellipsizing. 14 of 14 passed, with title contrast now 7.25:1.

Acceptance. The designer reads the report, then looks at the screenshot at 360px. This is where the last judgment happens, and the spec can't make it: in attempt 2 the short English title also wraps onto two lines at phone width, where it fit on one before. The spec allows that. Whether it's acceptable is the designer's call. If it isn't, that's a new check ("English title fits on one line at 360px") and a new round, not a vague "closer, but."

Limits

It checks what you wrote, nothing more. Seven passing checks don't mean the toast looks good. The screenshot review stays with the designer.
Computed styles aren't pixels. The checker would pass a toast hidden behind another element. Overlap, animation and z-order need a visual check.
One font, one browser. The fixture uses Arial in desktop Chrome. Real game UI with a custom font on a phone can wrap differently, so run the check where the font actually loads.
Contrast is only computed against a solid background. Toasts over the game scene need a worst-case background, which a static check can't pick for you.
Selectors are brittle. Rename a class and the check silently matches nothing. A real version should fail when a selector matches zero elements; this toy version doesn't yet.

If your studio splits work this way, with one person knowing what "done" looks like and another able to build it, Wagglet's write-up on closing team skill gaps with AI task handoffs covers the same prepare, execute, verify split for tasks beyond UI.

A Three.js sword-slash trail on a running character: mount it on the scene or on the hero?

Sam Novak — Tue, 13 Oct 2026 07:29:45 +0000

A sword-slash trail that looks right with the character standing still can turn into a long smear once the character runs and the camera follows. I measured why, with NixieFX 0.1.20 and three.js r185, and tried two places to put the trail. One fixed the smear and caused a new problem when the character turns. Both are below, with numbers.

The setup

Effect: a billboard particle trail with no velocity. simulationSpace: "world", rateOverDistance: 60 per unit, lifetime 0.2 to 0.3 s, shrink and fade over life. It's a NixieFX project exported to runtime JSON. NixieFX is a web game VFX editor, but nothing here depends on the editor UI, only on the exported file and the Three.js runtime.
Swing: the blade tip sweeps 150° to 30° on a 1.2-unit radius in 0.25 s. Each 1/60 s frame is split into 4 sub-steps so the arc doesn't clump.
Hero: a box with the hilt at (0.2, 1.1, 0) in hero space, running along +X at 6 units/s.
Camera: rigid follow at a fixed offset from the hero, so the hero stays in the same spot on screen and the world slides past.
End: allowCompletion() when the swing ends, while the hero keeps running.

The only difference between the runs is what the renderer is mounted on, and which space the tip position is passed in:

const vfx = new ThreeVfxRenderer({ scene, camera });
vfx.mount(mountMode === "hero" ? hero : scene);

// setTransform positions are in the space of the
// object the renderer is mounted on.
function tipForTrail() {
  const w = hilt.localToWorld(TIP_LOCAL.clone());
  return (mountMode === "hero" ? hero.worldToLocal(w) : w)
    .toArray();
}

// every sub-step during the swing:
placeHero(t);
setAngle(deg);
trail.setTransform({ position: tipForTrail() });
vfx.update(DT / SUBSTEPS);

What happened

Measured at the end of the swing. "Behind hilt" is how far the oldest particle sits behind the hilt, measured in hero space. "On screen" is the horizontal span of the particles on the 720 × 405 canvas.

Run	Live particles	Behind hilt	Arc around hilt	On screen
A: standing, renderer on scene	141	0.97 u	114°	184 px
B: running, renderer on scene	214	2.44 u	134.7°	306 px
C: running, renderer on hero	141	0.97 u	114°	184 px

B is the smear. In world space each particle stays where it was born, and the hero has moved by the time it dies. The oldest particles end up 2.44 units behind the hilt instead of 0.97. The follow camera makes it look worse: the hero stays still on screen, the posts in the background slide left, and the trail slides left with them. It reads as part of the background, not as part of the swing.

B also has 52% more particles. rateOverDistance counts the distance the emitter moved in world space, and in B that includes the 1.5 units the hero ran during the swing. Same effect, same seed: 214 particles instead of 141. If you budget particles from a standing preview, a running attack costs more than the preview showed.

C matches A exactly. With the renderer mounted on the hero root and the tip passed in hero space, the run speed drops out. Every number in C is identical to the standing swing. The tip still moves in hero space during the swing, so distance-based emission keeps working; only the run is taken out of it.

The catch: the trail turns with the hero

Mounting on the hero means the trail inherits everything the hero does, including rotation. In run D the hero turns 90° (yaw) over 0.1 s right after the swing, which is a normal thing for a player to do.

0.1 s after the swing	Live	On screen
B: renderer on scene	139	232 px
C: renderer on hero, no turn	90	152 px
D: renderer on hero, 90° turn	90	41 px
B with the same 90° turn	139	232 px

The hero-mounted trail swings around with the body and ends up edge-on to the camera, so it nearly disappears. The scene-mounted trail ignores the turn because it was never attached to the hero.

There isn't one right mount. If the attack is about reading the arc relative to the character (a combo, a parry window), C is easier to read and costs fewer particles. If the character turns sharply mid-fade, or the trail is long-lived, B can look more natural. With a 0.3 s lifetime the turn problem lasts 0.3 s at most. I didn't test a hybrid, such as switching the mount mid-trail, so I'm not recommending one.

Inspecting attachment and lifetime

The demo prints a version of this every frame (trimmed here). getParticleDebugTransforms() returns positions in the renderer's root space, so they go to world space through the root's matrix, then to hero space:

function inspect() {
  const root = mountMode === "hero" ? hero : scene;
  root.updateMatrixWorld(true);
  const toHero = hero.matrixWorld.clone().invert();
  const tip = hilt.localToWorld(TIP_LOCAL.clone());
  const ps = trail.getParticleDebugTransforms().map((p) => {
    const world = new THREE.Vector3(...p.position)
      .applyMatrix4(root.matrixWorld);
    return { world, hero: world.clone().applyMatrix4(toHero) };
  });
  return {
    live: ps.length,
    behindHilt: Math.min(...ps.map((p) => p.hero.x - HILT.x)),
    nearestToTip: Math.min(...ps.map((p) => p.world.distanceTo(tip))),
  };
}

Two checks came out of it:

Attachment: at the end of the swing the nearest particle to the blade tip is 0.000 units away in all three runs, so the newest particle is where the blade is. After the swing, B's nearest particle drifts away from the tip (0.30 units after 0.05 s, 0.60 after 0.1 s) because the hero keeps running and the trail doesn't. C's stays at 0.
Lifetime: after allowCompletion() the trail is empty 0.30 s later in A and C, and 0.283 s later in B. Both fit the 0.2 to 0.3 s lifetime, which is picked at random per particle.

What's supported, and what I didn't test

The renderer's getSupport() reports this effect as supported on Three.js, with no warnings. When I switched other modules on in a copy of the effect, it reported lights and subEmitters as blocked on the Three.js renderer in 0.1.20, so a trail that spawns sparks on death or lights the blade won't work in this setup. This trail uses only spawn, color and size. I didn't use the ribbon trails module.

The NixieFX Three.js runtime guide covers mount(), setTransform(), allowCompletion() and the support report used here.

Limits

One desktop Chromium browser, fixed 1/60 s frames with 4 sub-steps, seed 7. Particle counts will differ slightly with another seed.
The camera is a rigid follow. A smoothed or lagging camera changes B's on-screen numbers, though not the hero-space ones.
The hero is a box with a rotating blade, not an animated character. Root motion from a real animation clip would need the same "which space" decision for the root bone.
No mobile testing, and no measurement of frame time.

Drafted with AI assistance. The demo was built and measured in a Claude Code session, and the numbers above are from those runs.

Keep a speaking portrait aura out of your PixiJS dialogue text

Sam Novak — Mon, 12 Oct 2026 11:48:30 +0000

Disclosure: This draft was generated primarily with AI for NixieFX's marketing work. The source, screenshots and measurements come from the supplied local demo. Human technical and platform-policy review are required before publication.

A speaking portrait can have a little motion around it while the dialogue stays still. The effect should identify the speaker without becoming another bright object behind the words.

This example uses NixieFX with PixiJS 8.22.0 and nixie-fx 0.1.20. It keeps the aura behind an opaque portrait, clips it to the portrait area, and puts the dialogue in a separate opaque layer. The speaking state is a local control. There is no audio detection or lip sync.

Build the layer boundary before tuning the particles

The portrait occupies a 128-pixel circle. Its effect layer has a 96-pixel-radius mask around the same center. A separate plate holds the speaker name, a Speaking label and two lines of dialogue.

The relevant setup is:

const aura = new Container();
aura.position.set(40, 130);
dialogue.addChild(aura);

const clip = new Graphics()
  .circle(110, 110, 96)
  .fill('#ffffff');
clip.position.set(40, 130);
dialogue.addChild(clip);
aura.mask = clip;

// Add the opaque portrait and dialogue plate after the aura.
dialogue.addChild(portrait, plate);

const renderer = new PixiVfxRenderer({
  parent: aura,
  projection: createPixiVfx2dProjection({
    originX: 110,
    originY: 110,
    pixelsPerUnit: 80,
    yAxis: 'up'
  })
});

The mask belongs to Pixi's host scene. It is not a NixieFX emitter setting. Its position matches the aura container, while the projection maps the effect's origin to the portrait's local center. The text plate starts beyond the mask's right edge.

This gives the effect a limited region to draw into. Lowering opacity alone would still allow it to alter pixels behind the text if the layer order or geometry changed.

Use two small emitters

The first emitter is a soft blue circle that grows and fades behind the portrait. It emits two particles per second, gives each a 1.6-second lifetime, and has a capacity of four. The opaque portrait covers the bright center, leaving a visible halo around it.

The second emitter adds slow motes around a flat circle. It emits four particles per second with a 1.1-second lifetime and a capacity of six. The motes are small billboards, not light sources. Both emitters loop; together their configured capacity is ten particles.

The effect uses unlit additive compositing, color and size over lifetime, and small initial velocities. It needs no file textures or material provider. Its normalized authoring JSON and compiled export are both in the source kit.

If you use a pixi js particle editor such as NixieFX, keep the speaking-state controller and UI layering in the game. The NixieFX PixiJS particle-effects guide explains the export-bundle and renderer integration used here.

Let the speaking state own playback

The demo creates one reusable instance with autoStart disabled. Selecting a speaker resets that instance with a fixed seed, updates the portrait and name, and reveals the aura. The normal ticker advances the renderer once per frame:

const fx = renderer.createEffect(definition, {
  autoStart: false,
  seed: 398
});

app.ticker.add(ticker => {
  if (aura.visible) {
    renderer.update(ticker.deltaMS / 1000);
  }
});

Silence stops the ticker and hides the aura. Turning VFX off preserves the explicit Speaking label. The effect therefore supplements a readable state indicator instead of being the only way to identify the speaker.

The stop operation does not destroy the instance. In the captured silence check, four particles remained allocated in the paused instance. They were hidden and no longer advancing. Resuming resets the instance, and final page teardown destroys the renderer and Pixi application.

Compare the composited text pixels

Caption: Actual Chrome viewport, paused at 1.00 seconds with a fixed simulation clock. The geometric portrait and aura are rendered by the supplied PixiJS demo.

The verification control stops ordinary playback, captures the full scene's body-text region with the aura hidden, and compares that reference with 120 fixed 1/60-second updates of the aura. It extracts the full scene composition, not the text container alone:

const textRegion = new Rectangle(292, 222, 540, 100);
const pixels = () => app.renderer.extract.pixels({
  target: app.stage,
  frame: textRegion,
  resolution: 1,
  antialias: true
}).pixels;

The recorded crop contains 54,000 pixels, including 2,798 bright foreground pixels from the dialogue. Across all 120 frames, the maximum number of changed pixels was zero. Peak active particle usage was eight, against the configured capacity of ten, with one effect instance.

Validation and export produced no errors or warnings. Missing texture, material and sub-emitter references were empty, as were unsupported-module and unsupported-feature diagnostics. Switching to Mira reused the same instance. Silence and closing the dialogue stopped the ticker.

Pixel equality establishes that this animation did not alter this text region in this scene. It does not prove accessibility, readability on a smaller screen, or performance on a phone. The inspection path also performs extraction work that ordinary playback does not.

State the runtime limits

No unsupported settings are enabled in this effect. Lit particle shading requires the Three backend. Pixi depthWrite uses draw ordering and ink semantics rather than GPU depth-buffer writing; this source disables it.

The example does not test custom material graphs, trails, sub-emitters or Three.js rendering. It does not infer speech from audio. Real-editor visual review, mobile performance, reduced-motion preferences from the operating system, and a full accessibility audit remain untested. The supplied VFX switch is a local demo preference.

Run the source

Unpack the supplied source kit and enter its demo folder:

npm ci
npm run vfx:validate
npm run vfx:export
npm run dev

Open http://127.0.0.1:5199/. Inspect a fixed frame, run the 120-frame comparison, switch speakers, turn VFX off and close the dialogue. Download the complete source kit, including the authoring JSON, compiled bundle, screenshots and recorded checks.

A PixiJS map-pin pulse with an attention budget: three beats, skip off-screen, then stop

Sam Novak — Fri, 09 Oct 2026 10:57:17 +0000

An objective marker on a game map has one job: help the player find where to go. A pulse helps with that. A pulse that never stops turns into noise, and if every pin on the map pulses, nothing stands out.

This post builds a pulse for one tracked objective in PixiJS 8, with the particle effect from NixieFX, and gives it an attention budget. It pulses three times when the map opens, skips beats while the pin is off-screen, and then stops completely. Everything below comes from a demo I ran with pixi.js 8.22.0 and nixie-fx 0.1.20, stepped on a fixed 1/60 s clock.

One pulse, re-triggered from code

The effect is a single one-shot pulse with two emitters. A soft glow grows and fades over 0.7 s, and a ring of 14 sparks moves outward over about 0.8 s. It doesn't loop. The game decides when to fire it again, which keeps every stop condition in one place in your code instead of split between code and effect settings.

The relevant parts of the effect JSON:

{
  "id": "ring",
  "loop": false,
  "spawn": {
    "bursts": [{ "time": 0, "count": 14 }],
    "shape": "circle", "radius": 0.1,
    "rotation": [90, 0, 0], "sphericalDirectionAmount": 1
  },
  "forces": { "drag": 0.6 },
  "initializeParticle": {
    "lifetime": { "mode": "random", "min": 0.75, "max": 0.8 },
    "velocity": { "mode": "shapeDirection", "speed": { "mode": "random", "min": 0.95, "max": 1.05 } }
  }
}

Two settings in there are easy to get wrong on the Pixi side:

rotation: [90, 0, 0] and sphericalDirectionAmount: 1. A circle emitter's default direction is along +Y. Without these two settings the sparks don't spread outward on a 2D screen.
Drag versus lifetime. In 0.1.20, drag scales the distance travelled by 1 − drag × age. Sparks reach their furthest point at age = 1 / (2 × drag) and come back to where they started at age = 1 / drag. With drag 0.6, that peak is at 0.83 s, so I kept the lifetime under it.

The loop and its exits

Here is the controller. Every way out of the loop is a named line:

const PERIOD = 1.4;     // seconds between pulses
const MAX_PULSES = 3;   // the attention budget

function fire(p) {
  if (!p.fx) p.fx = vfx.createEffect(pulseFx, { position: [p.x / PX, p.y / PX, 0], seed: 100 + p.i });
  else p.fx.reset();                                   // reuse one instance per pin
  p.fired++; p.since = 0;
  if (p.fired >= MAX_PULSES) p.state = "draining";     // last beat: let it finish
}

function startPulse(p) {                               // objective assigned or map opened
  if (reducedMotion) { showStaticRing(p); return; }    // exit 1: no motion at all
  p.state = "running"; p.fired = 0;
  if (onScreen(p)) fire(p); else p.since = 0;
}

function stopPulse(p) {                                // exit 2: objective done or map closed
  p.state = "idle";
  if (p.fx) { vfx.removeEffect(p.fx, true); p.fx = null; }
}

function updatePulse(p, dt) {
  if (p.state === "idle") return;
  p.since += dt;
  if (p.state === "running" && p.since >= PERIOD) {
    if (!onScreen(p)) p.since = 0;                     // exit 3 (temporary): nobody can see it
    else fire(p);
  }
  if (p.state === "draining" && !p.fx.isActive) {      // exit 4: budget spent and particles gone
    vfx.removeEffect(p.fx, true); p.fx = null; p.state = "idle";
  }
}

app.ticker.add((t) => {
  const dt = t.deltaMS / 1000;
  for (const p of pins) updatePulse(p, dt);
  if (pins.some((p) => p.state !== "idle")) vfx.update(dt); // no VFX work once everything is idle
});

onScreen(p) compares the pin's global position with the canvas, plus a 24 px margin. An off-screen beat doesn't count against the budget, so a player who pans to the objective still sees it pulse.

Measured: one tracked pin vs. every pin pulsing

The demo map has 30 pins on an 1100 × 720 map, viewed through a 640 × 400 canvas, so 9 pins are on screen. Each run lasts 8 seconds. I counted real WebGL draw calls by wrapping drawArrays and drawElements. Each scenario ran three times, and the counts were identical every time.

Scenario	Pulses fired	Peak particles	Draw calls per frame	VFX work
Tracked pin, budget 3	3	15	3 while pulsing, 1 after	stops at 3.62 s
All 30 pins, no budget, no off-screen skip	180	450	61	never stops
All 30 pins, budget 3, off-screen skip	27	135	up to 19, usually 1	21 off-screen pins stay armed, 0 particles
Tracked pin, reduced motion	0	0	1	none

Three things stood out:

Each live pulse costs two draw calls in Pixi, one per emitter. NixieFX doesn't merge instances across pins, so 30 pulsing pins is 61 draw calls, against 1 for the map and pins themselves.
The budget makes the tracked pin free after 3.62 s. That's the third pulse at 2.8 s plus its 0.8 s of particles. After that, the controller skips vfx.update() entirely.
CPU numbers moved with machine load, so treat them as rough. With all 30 pins pulsing, vfx.update() took a median of 2.2 to 8.5 ms per frame across six runs on a busy Mac. With the budget it was 0 to 0.1 ms. The ratio held in every run, but the absolute milliseconds didn't.

Unsupported and partial settings

This effect only uses colour over life, size over life, velocity and drag, and the export marks it "supported" for pixi2d. If you build a fancier pulse, check support.backends.pixi2d in manifest.json first. In 0.1.20, turning on trails, noise, collision, lights, sub-emitters, texture sheet animation, custom data, external forces, force over lifetime, size by speed or colour by speed made the export report the effect as "partial" for Pixi.

I wrote the effect as JSON and exported it with npx nixie-fx export .. If you'd rather tune the glow and ring by eye, NixieFX is a visual particle editor for PixiJS that saves the same format. The PixiJS particle effects guide shows the bundle loading and ticker setup this demo uses.

Limits

Three beats is a design choice, not research. Pick your own budget. Restart it when the objective changes or the map reopens.
The off-screen check is a point test. A pin just outside the margin skips its beat even if part of the pulse would have been visible.
One machine, fixed steps. The draw-call and particle counts are deterministic. The milliseconds are not.
Reduced motion here swaps in a static ring. I didn't test it with a screen reader. The objective should also be announced as text somewhere outside the canvas.

A screenshot diff can't accept a UI change for you: a task template with visual reference, test plan and reviewer verdict

Sam Novak — Thu, 08 Oct 2026 09:12:56 +0000

Teams handing UI changes to coding agents often add a screenshot diff to the acceptance criteria. The thinking goes: the agent can't judge whether the result looks right, so let pixels decide. That's half right. A diff is a good test, but it's a bad verdict.

This tutorial builds a small, real example to show where the line is. It has a task template with a visual reference, a test plan that includes an automated screenshot diff, and a reviewer verdict. Then it runs a worked handoff with two implementations of the same change. The component and the task are invented. The diff script and every number in it are real, run with headless Chrome and pixelmatch 7.1.0.

Drafted with AI assistance and reviewed by hand.

The change

A "Draft saved" toast at the bottom of the screen. The designer's reference covers three states (a short message, a long message, and a message with an Undo action) at two widths, 375 px and 1280 px. The long message must stop at two lines with an ellipsis.

The task template

The preparer writes this before anyone runs an agent:

T-512  "Draft saved" toast: new layout

Visual reference
  reference/toast.html, approved by: design (Mira), 2026-10-06
  States: default, long, undo      Widths: 375, 1280
  Exact:  colours, radius, padding, Undo placement
  Rule:   message clamps at 2 lines, ellipsis, at every width

Test plan
  Automated (runner attaches output)
    - unit: toast renders each state
    - visual: node check.mjs <build>, 3 states x 2 widths,
      fail above 0.5% changed pixels
  Manual (reviewer)
    - screen reader announces the message once (role="status")
    - Undo is reachable by keyboard and has a visible focus ring

Delivery evidence
  Branch, check.mjs output, screenshots of all 6 cells,
  anything the runner could not check and why

Reviewer verdict  (one line per row; pass / fail / not checked)
  [ ] visual: default    [ ] visual: long    [ ] visual: undo
  [ ] screen reader      [ ] keyboard
  Decision: accept | send back (with reason) | accept with noted deviation

Three people touch this, and they don't swap jobs:

The preparer (here, the person who owns the toast) writes the template and attaches the approved reference.
The runner executes it with their own authorized tools: their own repo access, their own coding agent. They run the checks and attach the output. They don't decide what counts as close enough.
The reviewer (the designer, or whoever owns the reference) writes the verdict.

That split is most of what project management for coding agents means in practice. The agent can produce a delivery. A person still decides whether it's accepted.

The visual check

check.mjs takes a screenshot of every state at every width, for both the reference and the build, and compares them with pixelmatch. The core loop:

for (const state of STATES) {          // default, long, undo
  for (const width of WIDTHS) {        // 375, 1280
    const ref = shoot("reference", state, width);
    const got = shoot(impl, state, width);
    const changed = pixelmatch(ref.data, got.data, diff.data,
      ref.width, ref.height, { threshold: 0.1 });
    const share = changed / (ref.width * ref.height);
    console.log(`${share <= 0.005 ? "pass" : "FAIL"}  ${state} ${width}px ` +
      `${changed} px changed (${(share * 100).toFixed(2)}%)`);
  }
}

One trap I hit while building it: headless Chrome won't lay out a window as narrow as 375 px. My first run produced "375 px" screenshots that were really cut-off wider layouts. The fix was to render each state inside a frame of the exact width in a wider window, then crop to the frame. If your mobile screenshots look suspiciously like desktop ones, check this first.

The reference compared with itself gives 0 changed pixels in all six cells, so the check is stable on one machine.

The worked handoff

Two deliveries for T-512. I wrote both by hand to stand in for agent output, and each is one CSS line away from the reference.

Implementation A drops the two-line clamp on the message. Implementation B keeps the clamp but uses 14 px vertical padding instead of 12 px.

The check's output:

--- impl-a
pass  default  375px  0 px changed (0.00%)
pass  default 1280px  0 px changed (0.00%)
FAIL  long     375px  15665 px changed (20.89%)
FAIL  long    1280px  13236 px changed (5.17%)
pass  undo     375px  0 px changed (0.00%)
pass  undo    1280px  0 px changed (0.00%)
--- impl-b
FAIL  default  375px  1667 px changed (2.22%)
FAIL  default 1280px  2103 px changed (0.82%)
FAIL  long     375px  3363 px changed (4.48%)
FAIL  long    1280px  4686 px changed (1.83%)
FAIL  undo     375px  1799 px changed (2.40%)
FAIL  undo    1280px  2235 px changed (0.87%)

Read it as a pixel count and B looks worse: 6 failures against A's 2. Read it as a reviewer and it's the other way round:

A breaks a stated rule. A long message pushes the toast to four lines on a phone and covers more of the page. It also passes the default and Undo states perfectly. If the template had only listed the default state, A would have gone through green.
B is a 2 px difference in padding. Whether that matters is a design call. It may be a mistake, or the agent may have reused an existing spacing token instead of hard-coding 12 px, which some teams would prefer.

So the reviewer writes:

T-512 verdict, impl-a
  visual: default pass   visual: long FAIL   visual: undo pass
  screen reader: not checked   keyboard: not checked
  Decision: send back. Long message must clamp at 2 lines (rule in
  reference). Diff output attached.

T-512 verdict, impl-b
  visual: default/long/undo FAIL in check.mjs, 0.8% to 4.5%
  Cause: 14 px vertical padding vs 12 px in reference
  screen reader: ______   keyboard: ______   (reviewer runs these)
  Decision: if both manual rows pass, accept with noted deviation:
  14 px is the shared spacing token, so design updates the reference.

The manual rows for B are left blank on purpose. I didn't run a screen reader or a keyboard pass for this post, and a verdict template shouldn't arrive pre-filled. Two things here are the reason the verdict exists. "Not checked" is a valid entry: A was sent back before anyone checked the screen reader, and the verdict says so instead of leaving it blank. And "accept with noted deviation" records a human decision to overrule a failing check, with a reason someone can disagree with later.

Wagglet's request-to-delivery workflow guide treats a delivery and its acceptance as separate events with separate owners, which is the same split this template writes down for one UI task.

Limits

Pixel diffs depend on the machine. These numbers come from one Mac running one Chrome build. Fonts and anti-aliasing differ across machines, so run the reference and the build in the same environment, ideally the same CI image.
The threshold is a guess. 0.5% caught both changes here. At 5%, B would pass every cell, and A would still fail at 375 px (20.89%) and only just at 1280 px (5.17%). Pick it per component, and expect the reviewer to overrule it sometimes.
The diff only sees the states you list. It found A's bug because "long" was in the template. It can't find a state nobody wrote down.
Some checks can't be screenshots. Screen reader output, focus order and timing need a person or a different tool. They're in the template as manual rows for that reason.

A PixiJS shield-break burst that chips where it's hit, and the one spawn flag that makes the shards actually fly

Sam Novak — Wed, 07 Oct 2026 09:41:42 +0000

This is a small damage effect for a PixiJS 8 game: a hero has a 3-hit shield. The first two hits chip it at the point of impact, on the side facing the attacker. The third hit shatters the whole shield into spinning triangle shards.

Both effects are particle JSON files exported with the nixie-fx CLI and played by its PixiJS renderer. Everything below was run in PixiJS 8.22.0, nixie-fx 0.1.17 and Vite 6 in a Chromium browser on 2026-10-07. The screenshots are frames from the same code, rendered on a fixed 1/60 s clock so they can be reproduced.

Before and after

Hit 1 of 3: the chip. A short flare and 12 sparks at the impact point, 0.08 s after the hit. The shield stays up.

Hit 3 of 3: the shatter. A core flash and 28 triangle shards, 0.12 s after the hit. The shield ring is gone.

At 0.35 s the shards have spread wider and started to fall:

Two effects, one manifest

Effect	Emitter	What it does
`shield-chip`	`flare`	1 additive billboard, 0.14 s, grows and fades
	`sparks`	12 billboards from a tiny flat circle, speed 3 to 5.5 units/s, drag 2
`shield-shatter`	`core`	1 large additive flash over the hero, 0.2 s
	`shards`	28 triangle shards on a 0.9-unit circle (the shield's radius), random spin, gravity 4, drag 1.2

The projection maps 1 world unit to 100 px, so the 0.9-unit spawn circle sits exactly on the 90 px shield ring.

Validate and export from the project folder:

npx nixie-fx validate .
npx nixie-fx export .

Validation passed with one warning, and it's worth reading:

warning [unsupported-module] shield-shatter.json:emitters.1.mode: Mesh mode exports as Pixi 2D shard geometry semantics, not true 3D mesh rendering.
Validated 2 effects: 0 errors, 1 warning.

The shards use mesh mode with the built-in triangleShard template. On the Pixi backend that becomes flat 2D shard geometry, which is exactly what a 2D game wants here, but the export marks shield-shatter as partial for pixi2d because of it. shield-chip is plain billboards and exports as supported on both backends.

Loading and triggering

loadVfxExportBundle checks the manifest, hashes and validation before anything plays. With requiredBackend: "pixi2d" it accepted the partial effect; it refuses effects that are blocked on that backend.

import { loadVfxExportBundle } from "nixie-fx/export";
import { PixiVfxRenderer, createPixiVfx2dProjection } from "nixie-fx/pixi";
import manifest from "./vfx/manifest.json";
import chipJson from "./vfx/effects/shield-chip.json";
import shatterJson from "./vfx/effects/shield-shatter.json";

const bundle = loadVfxExportBundle(
  {
    manifest,
    effectsByPath: {
      "effects/shield-chip.json": chipJson,
      "effects/shield-shatter.json": shatterJson,
    },
  },
  { requiredBackend: "pixi2d", requiredEffectIds: ["shield-chip", "shield-shatter"] },
);
const chip = bundle.effectsById.get("shield-chip");
const shatter = bundle.effectsById.get("shield-shatter");

const vfx = new PixiVfxRenderer({
  parent: vfxLayer, // a Container above the hero and shield, below the HUD
  projection: createPixiVfx2dProjection({
    originX: HERO.x, originY: HERO.y, pixelsPerUnit: 100, yAxis: "up",
  }),
});

The impact point is on the shield ring, on the side facing the attacker, with up to 22.5 degrees of spread either way. It's in world units around the hero, y up:

function impactPoint(rng) {
  const toEnemy = Math.atan2(-(ENEMY.y - HERO.y), ENEMY.x - HERO.x);
  const angle = toEnemy + (rng() - 0.5) * (Math.PI / 4);
  const r = SHIELD_RADIUS / PX_PER_UNIT; // 0.9
  return [Math.cos(angle) * r, Math.sin(angle) * r, 0];
}

One damage event in, one effect out. The hit that leaves the shield standing plays the chip at the impact point. The hit that takes it to 0 plays the shatter at the hero's centre:

function takeHit() {
  if (shieldHp <= 0) return;
  shieldHp -= 1;
  const at = impactPoint(rng);
  if (shieldHp > 0) {
    live.add(vfx.createEffect(chip, { position: at, seed: seed++ }));
  } else {
    live.add(vfx.createEffect(shatter, { position: [0, 0, 0], seed: seed++ }));
  }
  drawShield();
}

Neither effect loops, so each instance is removed once it finishes:

app.ticker.add((ticker) => {
  vfx.update(ticker.deltaMS / 1000);
  for (const instance of live) {
    if (!instance.isActive) {
      vfx.removeEffect(instance, true);
      live.delete(instance);
    }
  }
});

The gotcha: a flat circle doesn't push particles outward by itself

My first export of both effects looked wrong. The sparks sat in a 6 px blob and never left the impact point. The shards appeared on the ring and then just dropped under gravity, keeping the ring's shape.

Both emitters spawn from a circle rotated [90, 0, 0] so it lies flat in the screen plane, with velocity.mode: "shapeDirection". In this setup that direction doesn't point outward along the screen, so on a 2D projection the particles get no visible outward speed. The fix was one spawn setting:

"spawn": {
  "shape": "circle",
  "radius": 0.03,
  "radiusThickness": 0,
  "rotation": [90, 0, 0],
  "sphericalDirectionAmount": 1
}

With sphericalDirectionAmount: 1, each particle moves away from the circle's centre, which on a flat circle means straight outward on screen. I measured the spread of the particles (the bounding box of their screen positions, from vfx.getParticleDebugQuads()) after 10 fixed steps of 1/60 s:

Emitter	Without the flag	With `sphericalDirectionAmount: 1`
chip `sparks`	6 × 6 px	95 × 112 px
shatter `shards` (gravity off for the test)	179 × 179 px	227 × 226 px

For the sparks, 6 px is the spawn circle's diameter, so they weren't moving at all. For the shards, 179 px is the 0.9-unit ring itself. With the flag and gravity back on, the shards go from 180 px wide on the first frame to 269 px wide half a second later, which is the spread you can see in the 0.35 s screenshot.

If your burst "doesn't burst" in PixiJS, check this flag before you start raising speed values. I raised the speed first and it changed nothing.

A second thing that didn't work: rotating an instance

I wanted the chip sparks to spray away from the shield, not in every direction. The obvious approach was to author a one-sided spray and rotate each instance towards the attacker. The Pixi renderer's createEffect options in 0.1.17 take position and seed but no rotation. I passed rotation: [0, 0, 90] anyway to check, and the particle positions after 10 frames were identical with and without it.

So this demo aims the chip by position only: it lands on the side of the ring facing the attacker, and the sparks spray in all directions from there. If you need a truly directional spray in PixiJS today, the options are separate exported effects per direction, or moving the emitter rather than rotating it.

Measured numbers

From the same fixed-step run, one effect at a time:

shield-chip: peak 13 particles, inactive after 22 frames (0.37 s).
shield-shatter: peak 29 particles, inactive after 60 frames (1.00 s).

That's small enough that I didn't benchmark frame time. The numbers are here so you know what one break costs in particle count, not as a performance claim.

What's supported and what isn't

Supported on pixi2d: billboards, color over lifetime, size over lifetime, velocity, gravity, drag, start rotation and spin on the shards, additive blending. No textures: both effects use the runtime's built-in procedural circle and triangle shard.
Partial on pixi2d: mesh mode. The shards are flat 2D geometry, not 3D meshes, and the export says so.
Partial on three3d: the same shield-shatter file. The export notes that Three.js renders true mesh particles only with mesh.renderMode: "meshAsset", so I'd re-author the shards before using this effect in a Three.js scene. I didn't run it there.
Not used: bloom, lit shading, trails, sub-emitters. Per the NixieFX docs, the Pixi backend has no lit shading and uses 2.5D draw ordering instead of GPU depth.
Tested in: this PixiJS page in a Chromium browser only. Not in the NixieFX editor preview, not on mobile, not in Firefox or Safari.
Art caveat: the core flash is additive and sits above the hero, so it briefly brightens the hero. Move the VFX layer below the hero or drop the core emitter if you don't want that.

If you're choosing a pixi js particle editor and want to see how authoring, export and the Pixi runtime fit together, the NixieFX PixiJS particle effects page covers the workflow this demo uses.

NixieFX vs three.quarks: the same 160-particle burst in one Three.js scene, measured

Sam Novak — Mon, 05 Oct 2026 13:55:50 +0000

If you're adding particle effects to a Three.js game, three.quarks is the library most people find first. NixieFX is a newer option that ships a Three.js runtime. "NixieFX vs three.quarks" comparisons usually stop at feature lists, so I built the same burst in both, put them in the same scene, and measured four things: whether a run repeats exactly, draw calls, CPU time per update(), and how much each adds to a production bundle.

The results go both ways, and one of them isn't flattering to NixieFX.

Note: I'm involved with the NixieFX project. The measurements were run by an AI agent in a Claude Code session, and this post was drafted with AI and reviewed by hand. Every number below comes from those runs, and the method is in the post so you can rerun it.

Setup

three 0.185.1, nixie-fx 0.1.17, three.quarks 0.17.1 (pulls in quarks.core 0.17.1), Vite 8.3.1
Chromium 152 on macOS, Intel Core i9-9880H, 8 threads. One machine.
Same WebGLRenderer, camera, grid and 480 × 320 canvas for both libraries
Fixed timestep of 1/60 s for every simulation step

The effect: a one-shot burst of 160 additive, camera-facing particles from a 0.05-unit sphere. Lifetime 0.5–0.9 s, start speed 2.6–4.2, size 0.12, warm white fading to orange and transparent, gravity 6 downward.

I matched the parameters by hand. They aren't identical, because the two libraries don't define drag the same way. NixieFX has a drag value; for three.quarks I approximated it with a SpeedOverLife curve. The bursts look alike but don't overlap exactly.

Correction (October 5): an earlier version said both bursts shrink from 0.12 to 0.03 over their life. Only the three.quarks one does. In the NixieFX effect I left the size constant at 0.12. The measurements below are from that version and are unchanged.

How each one is built

NixieFX effects are data. I wrote the effect as JSON (in a real project you'd author it in the NixieFX editor), then validated and exported it with the CLI:

npx nixie-fx validate .
npx nixie-fx export .

Validated 1 effect: 0 errors, 0 warnings.
Exported 1 effect to public/vfx.

The export includes a support report for each backend. For this effect it said three3d: supported. The game loads the bundle and asks the loader to refuse anything Three.js can't render:

import { loadVfxExportBundle } from "nixie-fx/export";
import { ThreeVfxRenderer } from "nixie-fx/three";

const bundle = loadVfxExportBundle({ manifest, effectsByPath }, { requiredBackend: "three3d" });
const effect = bundle.effectsById.get("ember-burst");

const vfx = new ThreeVfxRenderer({ scene, camera, captureDebugTransforms: false });
vfx.createEffect(effect, { position: [0, 0.4, 0], seed: 42 });

// every frame, in seconds:
vfx.update(1 / 60);

three.quarks effects are objects you build in code (or load from JSON made in its own editor). Every system is registered with a BatchedRenderer:

import {
  BatchedRenderer, ParticleSystem, SphereEmitter, IntervalValue, ConstantValue,
  ConstantColor, ColorOverLife, Gradient, SizeOverLife, SpeedOverLife,
  PiecewiseBezier, Bezier, ApplyForce, RenderMode, Vector3, Vector4,
} from "three.quarks";

const ps = new ParticleSystem({
  duration: 1,
  looping: false,
  worldSpace: true,
  shape: new SphereEmitter({ radius: 0.05, thickness: 1, arc: Math.PI * 2 }),
  startLife: new IntervalValue(0.5, 0.9),
  startSpeed: new IntervalValue(2.6, 4.2),
  startSize: new ConstantValue(0.12),
  startColor: new ConstantColor(new Vector4(1, 1, 1, 1)),
  emissionOverTime: new ConstantValue(0),
  emissionBursts: [{ time: 0, count: new ConstantValue(160), cycle: 1, interval: 0, probability: 1 }],
  material: new THREE.MeshBasicMaterial({
    map: dotTexture, blending: THREE.AdditiveBlending, transparent: true, depthWrite: false,
  }),
  renderMode: RenderMode.BillBoard,
  behaviors: [
    new ColorOverLife(new Gradient(
      [[new Vector3(1, 0.97, 0.8), 0], [new Vector3(1, 0.5, 0.15), 1]],
      [[1, 0], [0, 1]],
    )),
    new SizeOverLife(new PiecewiseBezier([[new Bezier(1, 0.75, 0.5, 0.25), 0]])),
    new SpeedOverLife(new PiecewiseBezier([[new Bezier(1, 0.66, 0.4, 0.25), 0]])),
    new ApplyForce(new Vector3(0, -1, 0), new ConstantValue(6)),
  ],
});

const batch = new BatchedRenderer();
scene.add(batch);
ps.emitter.position.set(0, 0.4, 0);
scene.add(ps.emitter);
batch.addSystem(ps);

// every frame, in seconds:
batch.update(1 / 60);

Both frames below were captured at t = 0.25 s (15 fixed steps).

The NixieFX burst is tighter at this moment. The likely cause is that its drag slows particles sooner than my SpeedOverLife curve does. I didn't tune the two to match exactly.

1. Does the same run come out the same twice?

Method: create the effect, step it 24 times (0.4 s), round every particle position to 5 decimals and hash them (FNV-1a). Do it twice from scratch.

	Run 1	Run 2	Same?
NixieFX, seed 42	`d43231ea`	`d43231ea`	yes
three.quarks	`5fa8d3fe`	`b7aeb6e5`	no
three.quarks, `Math.random` replaced with a seeded PRNG during the run	`058191a6`	`058191a6`	yes

NixieFX takes a seed per instance, and the same seed gave the same positions. three.quarks 0.17.1 draws its randomness from Math.random (the quarks.core ESM build has 52 call sites), so it can't be seeded directly. Swapping Math.random for a seeded generator around the update did make it repeatable in my test. But that replaces a global function, and the result depends on nothing else calling Math.random during the frame. Fine for a test harness, fragile in a game.

This matters if you snapshot-test effects, record replays, or want two clients to show the same burst from the same event. It doesn't matter if you only need a burst that looks good.

2. Draw calls

Measured with renderer.info.render.calls, minus the grid-only baseline:

	1 burst	20 bursts
NixieFX	1	20
three.quarks	1	1

three.quarks batched all 20 systems into one draw call, because they share a material and its BatchedRenderer is built for that. NixieFX drew each instance separately in this setup. I didn't find a way to batch separate NixieFX instances, so I'm not claiming there's one. If you spawn dozens of identical bursts at once, this is the number to watch.

3. CPU time per update()

Method: N bursts, step 30 frames from t = 0 (spawn and simulation), time only the update() call with no rendering. Median of 9 runs. NixieFX ran with captureDebugTransforms: false, as its docs recommend for production.

Bursts	Particles	NixieFX (ms/frame)	three.quarks (ms/frame)
1	160	0.74	0.13
5	800	3.08	0.40
25	4,000	15.41	2.63

three.quarks was roughly 6 to 8 times faster at every size I tried. At 4,000 live particles, NixieFX used nearly all of a 16.7 ms frame on simulation alone on this machine. three.quarks stayed under 3 ms.

The NixieFX debug default makes it worse. captureDebugTransforms is true unless you turn it off. In an earlier, longer run at 4,000 particles, the steady-state cost was about 18.6 ms with it on and 15.0 ms with it off. Turn it off in production builds.

Caveats: this is one machine. The page ran in a browser tab that wasn't on screen, so some of the earlier runs were noisy (I report the clean scaling run above). I measured CPU only, not GPU time.

4. Bundle size

Three separate Vite production builds of a tiny page: Three.js plus the scene only, then the same page plus each library. Gzip level 9.

Build	Minified	Gzipped	Added over Three.js alone
Three.js + scene	503.5 KB	123.9 KB	(baseline)
+ NixieFX (`nixie-fx/three` + `nixie-fx/export`)	692.4 KB	179.0 KB	55.1 KB
+ three.quarks	655.6 KB	158.1 KB	34.2 KB

NixieFX's number includes its bundle loader and validator. That's the code that rejected nothing here, but would refuse a three3d: blocked effect before rendering.

What I'd take from this

three.quarks was faster to simulate, batched identical systems into one draw call, and added less to the bundle. For a game that fires lots of bursts and doesn't care whether two runs match, those are the numbers that matter. (Small thing: it also logs a "powered by three.quarks" banner to the console on load.)

NixieFX gave repeatable runs from a per-instance seed with no global patching, and treated the effect as an exported, validated file with a per-backend support report. The same export also reported pixi2d: supported for this effect, so the file isn't tied to Three.js. Its CPU cost per particle was clearly higher in this test. Whether that's acceptable depends on how many particles you keep alive at once.

Not everything is supported on the Three.js side either. In nixie-fx 0.1.17, the lights module exports as blocked for three3d, and mesh-mode particles render as camera-facing quads unless you supply a mesh asset. The NixieFX Three.js runtime guide lists the supported modules and the support.backends.three3d report. Check your effect's report before you commit to it.

Limits of this comparison

One effect, one machine, one browser. Different effects (trails, textures, sub-emitters) could shift every number here.
I built the three.quarks system by hand. Someone who knows the library well might configure it more efficiently. The NixieFX effect was written by hand too, not tuned in its editor.
The two bursts are close but not identical, so neither the frames nor the timings are a pixel-for-pixel match.
No GPU timings and no mobile devices.

Rerun it

npm install three@0.185.1 nixie-fx@0.1.17 three.quarks@0.17.1 vite@8.3.1
Put the effect JSON in effects/ and a vfx-editor.prj with outputPath: "public/vfx" next to it. Run npx nixie-fx validate . and npx nixie-fx export ..
Build both systems as above in one module. Step each with update(1 / 60) in a plain loop, not requestAnimationFrame, so frame timing can't change the result.
For the repeatability check, read positions from instance.getParticleDebugTransforms([]) for NixieFX (this needs captureDebugTransforms: true) and from ps.particles.slice(0, ps.particleNum) for three.quarks. Hash them.
For timing, wrap only the update loop in performance.now(). Take the median of several fresh runs.
For size, build three single-entry pages separately so Three.js isn't shared between them, then gzip the output.

If you get different numbers on your hardware, I'd like to see them in the comments.

Snapshot-testing a particle effect in PixiJS 8: what has to stay fixed for the same frame twice

Sam Novak — Mon, 05 Oct 2026 09:07:58 +0000

Particle effects are random on purpose, which makes them awkward to review. Two people look at the same pull request, see two different bursts, and can't tell whether anything changed.

NixieFX, the particle runtime I used here, says its simulation is deterministic: the same effect with the same seed replays the same way. I wanted to know exactly what "the same" requires in practice. So I stepped one effect to a fixed time under different conditions, captured the particle positions and the rendered pixels, and compared them.

Short version: the seed isn't enough on its own. You also have to fix the timestep.

Note: I'm involved with the NixieFX project. The runs were done in a Claude Code session, and this post was drafted with AI and reviewed by hand. Every number and image below comes from those runs.

Setup

nixie-fx 0.1.17, pixi.js 8.22.0, WebGL renderer
A Chromium 152 browser on macOS, one machine
Canvas 320 × 240 (76,800 pixels), 1 effect unit = 60 px

The effect is a CLI-generated 2D effect, edited into a one-shot burst: 36 particles from a small circle, random speed 1 to 3 units/s, random lifetime 0.5 to 1.1 s, color and size over lifetime, additive blending.

npm install pixi.js nixie-fx
npx nixie-fx effect create --project ./vfx --name ember-burst --profile pixi-ui-2d
npx nixie-fx validate ./vfx
npx nixie-fx export ./vfx

effect create expects a vfx-editor.prj project file in the folder and errors without one. I wrote that small JSON file by hand.

The snapshot function

Stop Pixi's ticker so nothing advances on its own, then drive time yourself:

import { Application } from "pixi.js";
import { loadVfxExportBundle } from "nixie-fx/export";
import { PixiVfxRenderer, createPixiVfx2dProjection } from "nixie-fx/pixi";

const W = 320, H = 240;
const app = new Application();
await app.init({ width: W, height: H, background: "#15121a", antialias: true });
app.ticker.stop(); // tests drive time, not requestAnimationFrame

const projection = createPixiVfx2dProjection({
  originX: W / 2, originY: H / 2 + 20, pixelsPerUnit: 60, yAxis: "up",
});

const base = "./vfx/out/vfx/";
const getJson = (p) => fetch(base + p).then((r) => r.json());
const manifest = await getJson("manifest.json");
const effectsByPath = {};
for (const { path } of manifest.effects) effectsByPath[path] = await getJson(path);
const bundle = loadVfxExportBundle(
  { manifest, effectsByPath },
  { requiredBackend: "pixi2d", requiredEffectIds: ["ember-burst"] },
);
const ember = bundle.effectsById.get("ember-burst");

async function snapshot({ seed, t, dt }) {
  const vfx = new PixiVfxRenderer({ parent: app.stage, projection });
  const fx = vfx.createEffect(ember, { position: [0, 0, 0], seed });

  for (let elapsed = 0; elapsed < t - 1e-9; ) {
    const step = Math.min(dt, t - elapsed);
    vfx.update(step); // seconds, not milliseconds
    elapsed += step;
  }

  // 1) Particle state: position, size and alpha of every live particle.
  const state = fx.getParticleDebugQuads().map((q) => ({
    x: +q.x.toFixed(2), y: +q.y.toFixed(2), w: +q.width.toFixed(2), a: +q.alpha.toFixed(3),
  }));

  // 2) Pixels: read the canvas in the same task as render(),
  //    before the WebGL drawing buffer is cleared.
  app.renderer.render(app.stage);
  const c = document.createElement("canvas");
  c.width = W; c.height = H;
  const ctx = c.getContext("2d");
  ctx.drawImage(app.canvas, 0, 0);
  const pixels = ctx.getImageData(0, 0, W, H).data;

  vfx.destroy();
  return { state, stateHash: await sha256(JSON.stringify(state)), pixelHash: await sha256(pixels) };
}

async function sha256(data) {
  const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
  const d = await crypto.subtle.digest("SHA-256", bytes);
  return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, "0")).join("");
}

getParticleDebugQuads() is the useful part. It returns the screen-space quad for every live particle, so you can compare the simulation without reading back a single pixel.

What I compared

Baseline: seed 7, stepped to t = 0.35 s in steps of 1/60 s. Every other run changed one thing.

Run (vs. baseline)	Particle state	Pixels changed	Max position drift
Same seed, same step, again	identical	0	0 px
Same, reusing one renderer for two effects in a row	identical	0	0 px
Seed 8 instead of 7	different	2,772	104.35 px
Step 1/30 s instead of 1/60	different	1,915	3 px
Step 1/120 s instead of 1/60	different	1,686	1.5 px
One 0.35 s step	different	1,584	59.93 px

All runs had 36 live particles at 0.35 s.

Same seed and same step gave byte-identical pixels, which makes this usable as a test. A different seed gives a visibly different burst, as it should.

The step size is the catch. Changing only the step from 1/60 to 1/30 moved particles by up to 3 px. You can't see that by eye, but every particle's pixels changed, so a pixel hash fails. Doing it in one big step moved some particles by almost 60 px.

That matters because the usual game loop passes ticker.deltaMS / 1000, which varies frame to frame. That's correct for playing the effect, and it means a live frame won't match a stored baseline. Tests need their own fixed-step loop like the one above.

Checking more than one time point is cheap and catches different bugs. At 0.70 s only 20 of the 36 particles were still alive, so a lifetime change shows up there even if the 0.35 s frame looks fine.

Turning it into a test

Make the seed injectable. In the game, a random seed per trigger keeps every burst different. In tests, pass a constant.
Store the particle state JSON (or its hash) for two or three time points next to the effect file.
In the test page, re-run snapshot() with the same seed, step and times, and compare against the stored state.
When the effect is meant to change, regenerate the baseline in the same commit, so the diff shows up in review.

I'd make the state JSON the main check and keep the pixel hash as a second, stricter one. The state comes from the simulation. The pixels also depend on the GPU and browser.

One thing that surprised me

My first version of this effect also set gravity and drag. Its runs came out with exactly the same hashes as a copy with both set to zero. Looking at the runtime source, gravity is only sampled when the emitter's velocity module is enabled, and I had left that module off. The values were in the effect file and validation passed with no warnings, but the simulation ignored them. A snapshot test with a known baseline catches that kind of quiet no-op. Looking at the effect doesn't.

Limits

One machine, one browser. I didn't compare across GPUs, operating systems or browsers. Pixel hashes may not match across them; I'd expect the particle-state JSON to travel better, but I haven't verified that.
Rounding. I rounded state to 0.01 px and alpha to 0.001. Tighter rounding makes the test stricter and more fragile.
2D backend only. Everything here ran through the PixiJS adapter. The validator also flagged that depthTest and depthInk export as 2.5D draw-order rules on Pixi, not a real depth buffer, so don't expect depth-sorting settings to behave like they do in 3D. Per the docs, lit shading and mesh-surface emission aren't supported on the Pixi backend either.
Needs a browser. The test page loads Pixi and renders through WebGL. Running it in CI means a headless browser; I didn't set that up for this post.

Most Nixie FX + Pixi JS demos show an effect playing. This one is about pinning it down. The loading code and the per-frame update() call are the same ones the NixieFX PixiJS particle effects tutorial walks through. The difference is who controls time.