Making a 3D Browser Game With three.js and No Build Step: How Cosmic Starship Is Organized

You want to build a 3D game that runs in a browser tab, you would rather not set up a bundler, and you wonder whether three.js without a build step is a toy setup or something you can ship. It can be shipped: Cosmic Starship, our own game, is plain ES modules, a vendored copy of three.js and a handful of rules we wrote down after getting them wrong. This note walks through how the repository is organized and which parts hurt, using the files in the project and nothing we have not read there. The catch is that a build step also did jobs for you, and you have to do those jobs by hand.

Plain modules and a vendored library

The game’s index.html loads two module scripts and two stylesheets, and everything else is reached through import. The copy of three.js lives in engine/vendor; its three.core.js says REVISION = '180', so we ship r180 (the files carry a 2010–2025 copyright line). The add-ons we use (the glTF and EXR loaders, buffer-geometry utilities and the bloom post-processing passes) sit beside it in an addons folder, and they import the library by relative path, ../../three.module.js. That detail is why no import map is needed: every specifier is a real file path.

The three.js manual describes the other no-build route, which is to load the library from a CDN and declare an import map. We did not take it, so we cannot tell you it is worse. Our reason was control, since the game owns every byte it runs, but that is a preference, not a measurement. Two practical notes: module scripts opened from a file:// address typically fail with a CORS error in Chrome and Firefox (MDN’s CORS pages describe local files as opaque origins), so plan on a local web server even for a one-page prototype, and three.js moves fast (we found reports of newer releases than r180), so check the project’s migration guide before copying our add-on paths.

The cache-busting rule that decides everything

Without a bundler there are no hashed file names, so a returning player can run last week’s core.js next to today’s app.js. Our answer is blunt: every relative import and stylesheet link carries ?v=<release>, such as ./engine/loop.js?v=3.37.0, and a small script rewrites every query string in one pass when we cut a release.

The dangerous part is not a stale file. It is that a browser treats core.js?v=3.36 and core.js?v=3.37 as two different modules, each with its own copy of every variable. A registry or a seeded random generator then exists twice and the two halves of the game disagree without any error. So we wrote it as a rule, one URL per module, and a test enforces it: engine/tests/specifiers.py scans the sources, groups every import by resolved file, and reports any file imported under more than one query string, plus any import that points at a file that does not exist. The vendored three.js is excluded on purpose and carries no ?v= at all, because adding one on our side would load a second copy of the library whenever an add-on imported it by its plain path. The test is about fifteen lines long and is the single most useful thing in this note.

Keep the simulation away from the renderer

The engine’s FixedStep clock is fifteen lines. Real frames arrive at any rate, and the clock owes the simulation whole steps of 1/60 second. It runs at most eight per frame, and past that it drops the debt, so a tab that was in the background does not try to replay a minute of battle. The remainder is kept so the renderer can interpolate; in app.js the draw alpha comes from that remainder times 60. Everything that decides who wins sits in sim.js and its subclasses and needs no browser: the repository ships examples/arena.mjs, a complete small game that runs in Node and takes a seed on the command line. All randomness comes from a generator seeded at construction.

The README states the rule plainly: the renderer must never change the simulation, or replays and co-op stop matching. That separation is also what makes the regression hashes possible. A scripted pilot plays 93 battles, a hash of the whole field is taken every 60 ticks, and a refactor passes only if every hash is identical. The harness proved sensitive: changing one trait constant by 0.0001 changed 13 of the battles. We describe that net in how we know a change did not change the game and the split itself in taking an engine out of a running game, so we will not repeat them here.

Draw calls, merging and instancing

The three.js manual’s page on optimizing lots of objects makes the point that every mesh costs one or more draw requests and that merging meshes is a standard fix. Our ship builder takes that literally. The hull kit collects parts as geometry keyed by material, and a comment in models3d.js explains the reason: each material’s static parts are merged, so a detailed capital does not need a draw call per plate. Imported models are baked the same way, into one geometry per finish with the shade stored as vertex colors, and repeated models can go through an InstancedMesh wrapper that assets3d.js provides.

The number we have is narrow. In our validation notes, a seeded battle drawn in three camera views came to about 240 draw calls and 397,000 triangles per frame. That ran in headless Chromium (other entries in the same notes describe the test machine as drawing with software WebGL), with no real graphics card or phone in the test, so it says how much the scene draws and nothing about frame rate on your hardware. Our piece on why browser space games lag covers what those numbers tend to mean.

Loading models without trusting the network

Models come as GLB files through three.js’s GLTFLoader, whose loadAsync returns a promise, and assets3d.js wraps the whole load in a race against a 15-second timer. If anything fails, a flag is set and the game keeps the procedural models it can build in code, with one console warning. Materials that want the textured finish ask for it through a function that queues them until the files arrive.

Two bugs taught us the rest. Both appeared in release 3.37, when we added a civilization whose hulls were downloaded models.

The first bug was one no automated check could see. The 93 battle hashes matched and the data checks were clean, yet the hangar showed a gray slab where a ship belonged. In assets3d.js, a helper such as hullAsset(name) returns null until a hull’s files have arrived, and callers then draw a plain stand-in. The model builder caches what it builds, so a ship requested before its download finished was cached as the stand-in for the rest of the session. The fix is a rule, not a patch: a model that fell back is never cached. The browser test found it, which is the lesson. A hash of the simulation says nothing about a picture.

The second bug was a loading structure. Everything went through one Promise.all, so a single slow or missing hull file rejected the lot, and the game dropped to procedural models for every civilization. The new hulls now load in their own group: each file has its own .catch, and the group has its own 15-second race, so a failure leaves only those ships plain. The review that caught it is in our note on adding a civilization with ships we did not draw. If you take one pattern from this section, take that one: load optional assets in their own failure domain.

When WebGL is not there

The split exposed an older bug: with WebGL switched off, the game did not start, because a settings check ran before the object it needed existed. The same error was present in the version before the split. It now falls back to a 2D compatibility renderer, with 3D hull previews and 2D combat, and the label on screen says so. We check that case each release, because nobody finds it by playing normally.

What we would do differently

Only what the files support. The battle-hash harness dates from the engine split, not from the first release, and we would build it first: it was the thing that let us restructure a running game. And the validation notes list what we have not tested, a real GPU, a real phone and a slow connection on the 2.8 MB of Guild hulls, which is the first gap we would close if you asked us what to do next.

Questions people ask next

Should I use WebGPU instead? We use WebGLRenderer and have no WebGPU experience to report. The three.js manual says the WebGL renderer is still maintained and recommended for pure WebGL 2 applications, while WebGPURenderer falls back to WebGL 2 when WebGPU is unavailable.

Do I need a backend? Not for the simulation or the rendering. Our two-player co-op uses WebRTC and needs a small room service for the handshake, which in our project is PHP running on the host site, so that part is not static files. The rest of our engineering write-ups are in the dev notes hub.

Key sources: three.js installation manual, optimize lots of objects and GLTFLoader docs; project facts come from our own repository files.