Crash Reporting for Kaboom and KAPLAY Games

Kaboom is a friendly, beginner-loved JavaScript game library, and its development now continues under the community fork KAPLAY with the same component-based, scene-driven API. Both run entirely in the browser, building games from game objects assembled out of components like pos, sprite, area, and body. Because it is web JavaScript, crashes are JavaScript errors, and the web hides them: an uncaught error logs to a console no player opens, the canvas freezes, and the tab closes. Many of these games are made for jams and shipped fast, so crashes pile up unseen. This post covers how Kaboom and KAPLAY errors surface and how to capture them with context.

How errors surface in Kaboom and KAPLAY

Kaboom and KAPLAY structure a game as scenes, registered with scene and entered with go, each populated by game objects you add with the add function and a list of components. The library runs an internal frame loop calling your update callbacks and component behaviors. When your code throws, in an onUpdate handler, a collision callback, or component logic, the error propagates as an uncaught JavaScript exception. Depending on where it fires, the game may freeze on the canvas or continue in a corrupted state while the console records the throw.

The library provides an onError hook that catches errors raised inside its own loop and callbacks, which is the most game-aware capture point because it knows the error came from your game code rather than unrelated page scripts. But errors from async work, like a failed asset load returning a rejected promise, or from code outside the library loop, need the browser-level handlers too. Knowing both the library hook and the window events exist, and what each catches, is the basis of full coverage.

The jam-game blind spot

A large share of Kaboom and KAPLAY games are built for game jams and published on itch with little post-launch monitoring. The author tests in one browser, the build works, and they move on. Then players on Safari, mobile, or an unusual screen ratio hit errors the author never saw, and because the console is invisible and there is no crash dialog, none of it comes back. The game simply gets a few low ratings and a comment saying it did not load, with no detail to act on.

This blind spot is a missed opportunity, because these games often have a burst of players right at launch when feedback would be most valuable. A single early crash report could explain why a chunk of players bounced. The web variance is the same as any browser game: many browsers, mobile and desktop, varying GPU and canvas support, extensions, and context loss. Capturing crashes turns that launch-window burst from a source of silent churn into a short, fixable list while people are still playing.

Hooking the library and the browser

Use both layers. Register the library onError callback so errors inside Kaboom or KAPLAY scenes and component logic are captured with the library's awareness that they came from your game. Then add window listeners for the error and unhandledrejection events to catch async failures and anything outside the library loop, such as a rejected asset-loading promise. Set all of these up immediately after you initialize the context, before you register scenes, so no early failure escapes capture.

From each handler, capture the error message and its stack property, and ship source maps with your bundle so the minified frames resolve to real function names. Because these games are component-based, also record which scene was active and, where you can, the kind of object or component involved, by maintaining a small breadcrumb you update as scenes change. That gives the captured trace a place in your game, so a generic cannot read property of undefined becomes a known callback in a known scene.

Setting it up with Bugnet

Bugnet suits Kaboom and KAPLAY because it is web-native and the integration is a few JavaScript hooks. In your onError callback and your window handlers, hand Bugnet the error message, the stack trace, and a context object holding the active scene name and a breadcrumb of recent actions. The crash arrives as a readable trace, resolved through your source maps, with browser, version, and device fields attached. You can also add an in-game report button as a Kaboom or KAPLAY UI object so a player can flag a glitch while the current scene and state are captured automatically.

On the dashboard, Bugnet groups identical errors into one issue with an occurrence count, which is ideal for a launch-day burst: a thousand players hitting the same undefined read collapse into one ranked item rather than a flood you cannot read. Custom fields for browser, scene, and game version let you filter immediately, so you can see whether a crash is Safari only or tied to one scene. For a jam game with a short attention window, that means you can ship a fix while players are still around instead of discovering the problem weeks later.

Context for a component-based game

The context that disambiguates these crashes blends web and component fields. On the web side, capture the browser and version, desktop or mobile, and the WebGL renderer string, since rendering and context-loss errors cluster on specific mobile GPUs. On the game side, capture the active scene, because the scene-and-go structure maps neatly onto features, and a crash in the gameplay scene versus the menu scene tells you very different things about where to look.

Where practical, record the component or behavior involved. Kaboom and KAPLAY games fail often in collision callbacks registered with onCollide and in per-frame onUpdate logic, so noting the last collision pair or the object tag at fault sharpens the report. A short breadcrumb of recent player actions, the last input, and the time in the session rounds it out. With scene, component hint, and browser attached, even a terse JavaScript error becomes a precise record you can reproduce, rather than a console line lost to a closed tab.

Making capture part of shipping

Even for a jam build, wiring up crash capture is a small, one-time cost that pays off the moment the game has an audience. Add the hooks and source maps to your template so every project starts with them, then before publishing, throw a deliberate error from a scene and reject a test promise, and confirm both report with the right scene and browser context. Check a mobile browser specifically, because that is where most uncaught Kaboom and KAPLAY crashes actually live and where your local desktop testing tells you nothing.

Treat the launch window as your prime monitoring period. Watch the grouped reports during the first days when traffic peaks, and fix the loudest crash while players are still arriving. Because the library and browser hooks are reusable across projects, this becomes a default rather than a chore. The result is that your web games, jam entries and full releases alike, stop quietly losing players to invisible errors, and you build a habit of shipping with a real safety net instead of hoping the console stays empty.

Kaboom and KAPLAY crashes disappear into the browser console, and jam games lose players fastest at launch. Hook onError and the window, tag the scene, and group the rest.