Crash Reporting for Cocos Creator Games

Cocos Creator is a widely used engine, especially strong in mobile and mini-game markets, that builds JavaScript and TypeScript games to a range of targets: web, native iOS and Android, and mini-game platforms embedded in larger apps. Each target runs your game in a different environment, web in a browser, native through a runtime, mini-games in a host app sandbox, and each fails differently. Setting up crash reporting for a Cocos Creator game means capturing the script errors and native crashes with the build-target context that explains why a crash hits one platform and not another.

Cocos builds to very different targets

Cocos Creator builds one project written in JavaScript or TypeScript to several genuinely different targets. The web build runs in a browser, the native builds run on iOS and Android through the Cocos runtime, and mini-game builds run inside host apps with their own constraints and APIs. These environments differ enough that a crash on one target may not occur on another, and the nature of a crash depends on where it ran.

This diversity makes the build target the essential first piece of context for a Cocos crash. A crash on the web build is a browser failure, on a native build a runtime or device issue, on a mini-game platform a host-app constraint. Capturing which target a crash came from is what lets you interpret it correctly, because the same TypeScript code produces differently-shaped crashes depending on the target it was built for.

Capture script errors

Your game logic in Cocos Creator is JavaScript or TypeScript, so script errors, a null access, a wrong type, a logic error, are a primary crash source across all targets. Capture these by hooking the appropriate error handling for the target, the global error handlers on web, the runtime error handling on native, and record the error message, stack trace, and the component or scene context.

Capture the active scene and the component where the error occurred, since Cocos organizes games into scenes and components, which localizes the crash to a part of your game far better than the stack trace alone. For minified production builds, use source maps to keep the traces readable. This script-level capture handles the bulk of your game-logic crashes, the bugs in the code you wrote, consistently across the web, native, and mini-game targets.

Capture native crashes on mobile builds

The native iOS and Android builds run your game through the Cocos native runtime, which is native code, and crashes can occur at that native level, in the runtime, in a plugin, or in the rendering layer, that do not surface as clean script errors. These native crashes need to be captured at the native level, with whatever backtrace the platform provides, and symbolicated to be readable.

Capture these native crashes on your mobile builds, complementing the script-level capture, so a native runtime or plugin crash does not vanish silently. The native builds also need device context, model, OS, memory, just like any mobile game, since crashes cluster by device. Covering both the script layer and the native layer on mobile builds gives you complete crash visibility for the native targets, which are often the most important for a mobile-focused Cocos game.

Handle mini-game platform constraints

Mini-game platforms, games embedded in larger host applications, are a major market for Cocos Creator and have their own constraints: limited memory, restricted APIs, host-app sandboxing, and platform-specific behavior. A Cocos game running as a mini-game can fail in ways specific to the host platform, hitting a memory limit, calling a restricted API, or encountering a host-app quirk.

Capture crashes on mini-game builds with the host-platform context, so you can identify mini-game-specific failures. These are distinct from web and native crashes because the host app imposes constraints neither of the others does, and a crash that only appears on the mini-game build points at one of those constraints. Tagging the mini-game platform and capturing its context is what makes this important but constrained target debuggable, rather than a black box where your game mysteriously fails inside someone else app.

Setting it up with Bugnet

Bugnet captures Cocos Creator crashes at the script level by hooking the target-appropriate error handling, and at the native level on mobile builds, with the build target, scene, component, and platform context attached. Reports from your web, native, and mini-game builds flow into one dashboard tagged by target, so you see your whole multi-target game in one place.

Add custom fields for your game state and group identical crashes into occurrence counts. Because Cocos builds one project to such different targets, the ability to filter crashes by target is especially valuable, instantly telling you whether a crash is a shared logic bug across targets or a platform-specific issue on web, native, or a mini-game host, which determines how you investigate and fix it across the range of platforms Cocos serves.

Test each target market

Cocos Creator often serves several markets at once, web, app stores, and mini-game platforms, and each is a distinct target to test, since the worst platform-specific issues show up on the first run on that target. Test your web build in browsers, your native builds on real devices, and your mini-game builds on the actual host platforms, because each surfaces its characteristic problems quickly.

Then rely on your target-tagged crash data for the long tail of devices, browsers, and host-platform versions you cannot exhaustively test. Your testing catches the gross per-target issues, and the captured crashes, tagged by target, reveal the specific failures across the range players run. For a Cocos Creator game spanning web, native, and mini-game markets, this combination of per-target testing and target-tagged capture is what lets you support all those markets confidently from one project.

Cocos ships one project to web, native, and mini-games. Tag the target so each crash makes sense.