How to build a browser mini game with Three.js, Blender and AI

Choose the stack around the rules

The same sequence works for a racer, platformer, exploration game or arena. Three.js supplies rendering. Your game still needs an update loop, rules, input and a user interface. Choose each layer below to match your game’s rules.

Add Rapier or Cannon-es when rigid bodies, jumping or collision behavior justify it. The starter’s simple collision does not need either. Keep Blender for authored meshes and rigs; procedural geometry can cover simpler scenery.

The Web Audio guide explains starting audio from a user gesture. Howler.js is an optional wrapper. Enable sound from Start and provide mute. Match the interface to the game: checkpoints for a racer, a collection count for exploration, health and cooldowns for combat.

Give the scene a coherent polish pass

Pick a visual theme, then repeat its materials, shapes and sound cues. Make routes and objectives readable before increasing foliage or effects. Use InstancedMesh for repeated geometry and materials, and levels of detail for distant objects. Measure transparent grass, shadows and postprocessing too; fewer draw calls alone do not guarantee a faster frame.

Three.js · Official documentation

InstancedMesh

Reuse geometry and materials across many transforms to reduce draw calls for repeated scenery.

threejs.org ↗

The Three.js postprocessing guide explains chaining effects and the final output pass. Add effects gradually; start with conventional lighting and fog before expensive volumetric clouds or water effects.

Improve one playable scene; preserve its rules and controls.
Theme: [one visual world; recurring shapes, materials and sounds]
Readability: clear routes, objectives, silhouettes and interaction cues.
Lighting: consistent sun/key light, restrained fog and tone mapping.
Effects: try bloom or ambient occlusion one at a time; measure each pass.
Scenery: instance repeated props; simplify distant geometry and shadows.
Environment: add water, wind or weather only when the scene needs it.
Feel: responsive input, readable weapon placement and clear action feedback.
Audio: enable from Start; add relevant cues and a mute control.
HUD: show live objective, timer, health or score from actual game state.
Optional hazards: telegraph danger with shape, light and sound.
Acceptance: compare the same views and input tests before and after.
Retain an effect only if it improves play within the measured budget.

For shooting, check aim visibility, recoil, reload timing and hit feedback. For a racer, check steering, landing and checkpoint cues. A shrinking hazard is optional: make its boundary and timing understandable through the HUD, light and audio. Camera shake should be restrained and adjustable.

Set the frame budget on named hardware. A 60 FPS target gives roughly 16.7 milliseconds per frame; it is a target, not a result from this guide. Compare the same camera path and quality settings, including the busiest effects and entity count.

The visual improvement loop

A reference becomes useful when it is tied to a testable change. The five steps below turn taste into a bounded review: freeze the target, build one change, capture the game, review fresh, then keep or patch. This is a reusable recipe. ParisRunner’s standalone inspection is working; the asset labs and automatic review/promotion described here remain proposed.

First, freeze the target before implementation. Keep approved front, three-quarter and detail references where relevant, plus their hashes. Specify silhouette, proportions, primary and secondary forms, materials, roughness, palette, lighting, scale, animation and gameplay readability. Set geometry, loading and frame budgets from the target device. “Make it look expensive” supplies no acceptance check.

{
  "kind": "template-not-a-completed-run",
  "target": "arc-plaza",
  "approved_reference_paths": [
    "art/references/arc-plaza/front.png",
    "art/references/arc-plaza/three-quarter.png"
  ],
  "reference_hashes": null,
  "baseline_commit": null,
  "owner": null,
  "allowed_files": [],
  "preserve": [
    "Paris/cyberpunk identity",
    "landmark silhouette",
    "first-person controls",
    "canonical Blender sources"
  ],
  "rubric": [
    "silhouette and proportions",
    "primary and secondary forms",
    "scale and gameplay readability",
    "material roughness and surface detail",
    "palette, lighting and animation",
    "loading and rendering budgets"
  ],
  "hard_gates": {
    "asset_bytes_max": null,
    "triangles_max": null,
    "frame_p95_ms_max": null,
    "controls": "must pass"
  },
  "acceptance": null
}

Create a small asset lab for the thing you are changing. A character lab exposes silhouette and animation; a firing range exposes weapon placement, recoil and targets; a vehicle track exposes handling; a neutral showroom exposes materials. Each is a proposed test scene with fixed conditions. Finish in the real level too: an isolated weapon can look good and still block the player’s aim.

Give a risky change its own branch and Git worktree. Record the committed baseline and any dirty files first: a worktree at HEAD does not include uncommitted edits. Give one owner a bounded file list. Independent code can run in parallel; shared integration files and a Blender scene need sequential ownership. Integrate accepted candidates one at a time.

Git · Official documentation

git worktree

Separate working trees and branches for independently reviewed candidates in the same repository.

git-scm.com ↗

git status --short
git rev-parse HEAD
# Start from the recorded committed baseline; preserve dirty work.
git worktree add -b art/arc-readable ../game-arc-readable HEAD
# Adapt the branch and path. Integrate accepted commits one at a time.

For authored assets, use a deterministic bpy patch on the canonical Blender source. Preserve its rig, edits and catalog identity. Starting from an empty scene is appropriate for a new procedural asset, not an existing modeled character. Blender’s command-line arguments execute in order; --python-exit-code 1 gives the watcher a failing exit code for script exceptions.

Blender Manual · Official documentation

Command Line Arguments

Background execution, Python scripts, error exit codes and the order in which Blender applies arguments.

docs.blender.org ↗

blender -b art/generated/arc/source.blend \
  --python-exit-code 1 -P tools/blender/patch_asset.py \
  -- art/specs/arc.json
# Example contract: write the patch script for your asset first.
# It reads the spec after --, saves the candidate .blend and exports GLB.

Work on the existing canonical .blend when the asset is modeled or rigged.
Use a deterministic bpy patch script; do not replace the source with a new empty scene.
Factory startup is an option only for a newly procedural asset.
Save the candidate source under its isolated worktree; preserve the approved source.
Record Blender version, script/spec hashes, source hash, export settings and output hashes.
Produce source.blend and the runtime GLB.
Produce front, three-quarter and gameplay-distance renders, wireframe and collider preview.
Write metrics.json: dimensions, evaluated triangles, materials, texture bytes and available LODs.
Update the catalog/runtime manifest in the integration step.
Confirm that the browser requests the intended GLB hash and the object is visible at player scale.
Keep Blender reference review separate from real-game visual review.

Require the editable source and GLB, front and three-quarter renders, a gameplay-distance render, wireframe, collider preview and metrics: dimensions, evaluated triangles, materials, textures and LODs. Save script/spec/export hashes. After integration, verify the intended GLB is requested and visible in the browser at player scale. Keep the Blender reference judge separate from the game reviewer.

Freeze the capture: camera transform, FOV, viewport, device scale, pose, time of day, weather, random seed, LOD and postprocessing. Disable dynamic resolution for comparisons. Wait for required assets and completed rendered frames. Save loaded model URLs and hashes, transferred bytes, readiness time, median/p95 frame times, draw calls, triangles, errors, build identity and the rendering environment. A screenshot without this context can hide a changed test.

{
  "kind": "template-not-a-completed-run",
  "run_id": null,
  "view": "arc-plaza",
  "identity": {
    "commit": null,
    "dirty_files": [],
    "build_hash": null,
    "asset_manifest_hash": null
  },
  "camera": {
    "position": null,
    "quaternion": null,
    "fov_degrees": null
  },
  "viewport": {
    "width": 960,
    "height": 540,
    "device_scale": 1
  },
  "scene": {
    "seed": null,
    "time_of_day": null,
    "weather": null,
    "animation_pose": null,
    "lod_policy": null,
    "postprocessing": null,
    "dynamic_resolution": false
  },
  "readiness": {
    "required_asset_urls": [],
    "loaded_asset_hashes": null,
    "ready_time_ms": null,
    "settled_rendered_frames": null
  },
  "environment": {
    "browser_version": null,
    "os": null,
    "gpu": null,
    "webgl_renderer": null,
    "driver": null,
    "launch_flags": []
  },
  "measurements": {
    "sample_count": null,
    "median_frame_ms": null,
    "p95_frame_ms": null,
    "draw_calls": null,
    "triangles": null,
    "transferred_bytes": null
  },
  "errors": {
    "page": [],
    "console": [],
    "failed_requests": [],
    "missing_assets": []
  },
  "artifacts": {
    "screenshot": null,
    "network_receipt": null,
    "metrics": null
  }
}

A plain script watches exit status, errors, output files and hashes. It calls the model when new evidence is ready. Keep full-resolution originals, then send one comparison around 768 pixels wide. A fresh critic receives only the approved target, rubric, constraints, metrics and the same-view best/candidate captures. Leave out builder explanations and earlier review prose. The critic is read-only.

You are a fresh, read-only visual reviewer.
Receive only approved references, rubric, constraints, current metrics and same-view best/candidate captures.
Do not receive worker explanations or earlier reviewer prose.
Check capture validity first: readiness, camera, pose, settings, assets and renderer must match.
If invalid, return capture-invalid; request a capture fix before a game patch.
Judge silhouette, forms, materials, readability, animation and visual cohesion against the frozen target.
Check hard budgets and runtime errors separately from taste.
Return improved, unchanged or regressed with concrete evidence paths.
Return at most three prioritized deltas with area, observed defect, intended correction and acceptance.
Do not invent precise percentages unless a measurement supports them.
Do not modify files. A model score is advisory; the integrator owns promotion.

{
  "kind": "template-not-a-completed-review",
  "decision": null,
  "best_run": null,
  "candidate_run": null,
  "comparison": "same view, settings and environment",
  "hard_failures": [],
  "strengths": [],
  "top_deltas": [],
  "evidence_paths": [],
  "notes": "Set decision to improved, unchanged, regressed or capture-invalid. Return at most three precise deltas. A score alone cannot approve promotion."
}

Ask for at most three precise deltas: the visible defect, the intended correction and its check. “The weapon covers the target when aiming; lower its idle placement while preserving the sights” is actionable. A claimed proportion error needs a measurement; a score alone cannot promote a candidate.

Keep the best verified version, not simply the latest. Compare it directly with the candidate under identical conditions. Promote only when the visual result improves and controls, loading, performance budgets, tests and build pass. Fresh model scores vary, so a lower number alone is not a reason to reset shared work. Preserve the best commit, build, asset hashes and captures; keep rejected candidates isolated.

Use the guide’s strict default: three executions, two consecutive attempts without improvement, or a material regression. Stop on a failed step. Five hours can be an additional session ceiling; it never overrides an earlier limit. The wrapper also needs a total token/cost cap and a per-run turn cap. Finish with a side-by-side report and remaining deficiencies, then check visual cohesion in the real game.

You coordinate one visual improvement to an existing browser game.
Start from the canonical checkout, instructions, task board and approved target.
Record the baseline commit, dirty files, build and asset identities.
Give one worker one scope in its own branch/worktree; do not touch unrelated files.
Never let two workers edit the same Blender scene or integration file.
Use Three.js for runtime behavior; patch the canonical Blender source for modeled assets.
Freeze camera, FOV, viewport, DPR, pose, lighting, weather, seed, LOD and effects.
Wait for required exports and settled rendered frames, then capture the real game.
Save full-resolution captures and metrics; send one compact comparison around 768 px.
Have a script watch exit status, errors, outputs and hashes. Call the critic only on new evidence.
Give a fresh read-only critic targets, rubric, constraints, metrics and best/candidate captures.
Exclude builder explanations and previous review prose. Require evidence paths.
Return improved, unchanged, regressed or capture-invalid, with at most three precise deltas.
Patch only the highest-value deltas. Diagnose capture infrastructure before altering game art.
Promote only after paired visual review, asset budgets, controls, tests and build pass.
Preserve best commit, build, asset hashes and captures. Keep rejected candidates isolated.
Do not reset a shared checkout or treat a changing model score as automatic rollback.
Default limits: three executions, two consecutive attempts without improvement.
Stop immediately on a failed step or material regression. Never retry indefinitely.
Optional session ceiling: five hours; any earlier execution or error limit still wins.
Builder cap: 30 turns per CLI run. Configure a total token/cost cap in the wrapper.
Do not start unattended until the wrapper can enforce every configured limit.
Begin with one capture job and one Blender render at a time; increase only after measuring capacity.
After asset-lab checks, verify cohesion and real input in the playable scene.
At the end, keep the best verified result, produce a side-by-side report and list remaining work.
Commit or publish only within the repository's existing authorization rules.

Download the complete visual review kit: target spec, capture manifest, review result, feedback example, builder/reviewer contracts and a README with adaptation steps. The eight templates include a SHA-256 manifest. They are starting contracts, not a preinstalled automation service. Fill empty fields from the actual project.

Verify the capture machine before changing the art

Headless Chrome can use a hardware GPU on supported setups. Chromium’s guidance explains that configuration matters. Record the actual GPU, driver, WebGL renderer, browser and launch flags, then compare representative shaders with the player’s browser. A broken capture is an infrastructure issue until reproduced in the game.

Chromium · Official documentation

Using GPU Hardware in Headless Chrome

Hardware rendering can work in headless Chrome on supported configurations. Verify the backend rather than assuming it.

chromium.googlesource.com ↗

Keep software-rendered timings separate from real-player performance. A changed GPU, driver or quality preset needs a new baseline. If shadows, foliage or transparency disappear only in the capture environment, fix that environment before sending an art patch to the worker.

Queue expensive GPU work. Start with one browser capture and one Blender render at a time, then measure GPU memory, RAM and reliability before raising concurrency. Those are initial queue caps, not a claim about this VPS’s capacity. Parallel coding can continue while capture jobs wait. Remote workers and a forwarded preview can keep long runs off a sleeping Mac; verify the renderer wherever the game runs.

Turn player feedback into reproducible tasks

Use your playtest notes, or a transcript you deliberately provide. Attach the timecode, build, location and screenshot to each observation. Separate “this street feels empty” from a confirmed defect and from a proposed fix. Reproduce and deduplicate before assigning work; large art-direction changes belong in a backlog decision.

{
  "kind": "proposed-feedback-example",
  "area": "arc-plaza",
  "category": "environment-art",
  "observation": "The street feels empty from the player camera.",
  "requested_change": "Test a small set of props that preserve the walkable route.",
  "source": {
    "type": "player-note",
    "transcript_path": null,
    "timecode": null
  },
  "build": null,
  "view": null,
  "evidence_paths": [],
  "reproduced": false,
  "requires_art_direction_decision": false,
  "status": "needs-reproduction"
}

Separate character, environment, architecture, weapon, animation, UI, audio and performance reviews when their tests differ. Keep each target and scope small. After those checks, review the whole playable scene for a consistent identity. More workers help only when ownership and verification remain clear.

Practical traps: save the model for judgment

If the Mac sleeps, local agents stop progressing. Run caffeinate -i while working, or wrap the bounded command below. It prevents idle system sleep while the command runs.

Blender does not need its window open. Its command-line interface can render and check a scene in the background. Replace these example filenames with your actual scene and script:

blender -b file.blend -P script.py

Let a plain script watch process exit, errors and artifact hashes. Call the model only after a finished render or changed file needs judgment. Keep the full-resolution captures, but send one street/reference comparison around 768 pixels wide per review loop.

Split the work: Sonnet 5.5 for bounded implementation, Haiku 4.5 for simple checks and finished-log summaries. Anthropic lists both in its model catalog. The sonnet alias resolves differently by provider. Sonnet 5.5 requires Claude Code 2.1.284 or later. Confirm account availability and the resolved model; preserve explicit pane choices. Pin claude-sonnet-5-5 when that exact version matters.

Claude Code · Official documentation

Model configuration

Model aliases, provider-specific resolution, version requirements and explicit model selection.

code.claude.com ↗

caffeinate -i claude -p "Implement one scoped task, verify it, then stop." \
  --model sonnet --max-turns 30 --output-format json > run.json

Claude Code · Official documentation

CLI reference

Print mode, explicit model choices, structured reports and a hard turn limit for a single run.

code.claude.com ↗

A Claude Code checker subagent can use this file at .claude/agents/review-check.md. Invoke it only when the script has new evidence:

---
name: review-check
description: Summarize completed game and Blender checks.
model: haiku
tools: Read, Grep, Glob
maxTurns: 5
---
Read the completed check report and the changed artifact paths.
Report errors, missing output and the relevant acceptance result.
Do not poll, modify files or declare a visual improvement from logs.

Set a hard nightly limit in the wrapper: at most three review loops, 30 builder turns per run and two consecutive attempts without improvement. Stop on an error or material regression, and preserve the best verified result. --max-turns limits one CLI run; the wrapper must enforce the total loop count.

Add multiplayer when the game needs it

Run a small shared room before raising the player limit. Colyseus provides synchronized room state. Socket.IO provides bidirectional events; you implement the game simulation and state contract. Pick one approach. Express can handle HTTP routes, but it does not supply multiplayer authority.

Colyseus · Official documentation

State Synchronization

Server-owned room state, client messages and synchronized changes for a multiplayer game.

docs.colyseus.io ↗

The client handles input, presentation and any prediction. The server validates actions and owns positions, health, scores, round timing and shared hazards. Interpolate remote updates and reconcile prediction when the server disagrees. Server authority reduces trust in clients; it does not eliminate cheating. Define matchmaking, room capacity and reconnect behavior explicitly.

[ ] Two separate clients can join the same room and finish a round.
[ ] Clients send inputs/actions; the server validates and owns results.
[ ] Server checks movement limits, hits, damage, cooldowns and scoring.
[ ] Remote movement is interpolated; local corrections remain playable.
[ ] Late join, disconnect, reconnect and room cleanup have defined behavior.
[ ] Bots are identified and do not count as tested human connections.
[ ] HUD, round timer and any hazard zone follow authoritative state.
[ ] Test latency, packet loss and the declared connection target.
[ ] Record server tick time, bandwidth and client frame times separately.
[ ] HTTPS/WSS, permitted origins and production reconnects are verified.
Raise the room limit only after this contract passes under load.

Publish the static client separately from the live room service. A persistent Node.js process on a VPS or container host is one practical option. Verify the provider’s WebSocket support, connection lifetime, room routing and state storage. Vercel’s current guidance supports WebSockets but bounds connections by function duration, with no guarantee future connections reach the same function. Plan durable room state and recovery accordingly.

Vercel · Official documentation

WebSocket connections on Vercel Functions

Connection lifetime, function routing and durable state considerations for real-time hosting.

vercel.com ↗

An online game has browser rendering and server-owned shared state. Measure real concurrent connections, server simulation and network traffic. Test remote connections separately from local entities and bots before quoting room capacity.