Crash Reporting for Twine and HTML Story Games

Twine and similar tools produce interactive story games as self-contained HTML that runs in the browser, with the story logic handled by a story format like Harlowe or SugarCube and any custom scripting in JavaScript. These games fail in characteristic ways: a JavaScript or macro error in a passage, a broken link to a passage that does not exist, a variable or macro misused. Like any web game, the errors land silently in the browser, and like any branching story, they are tied to specific passages. Setting up crash reporting for a Twine or HTML story game means capturing the errors with the passage and variable context that makes them reproducible.

Twine games are HTML in the browser

A Twine or HTML story game is a self-contained HTML file that runs in the browser, with the branching story logic handled by a story format, Harlowe, SugarCube, or another, and any custom logic written in JavaScript and the format macro language. This means the game runs as a web application and fails as one, with JavaScript errors that land silently in the browser console, plus the format-specific errors from macros and the story logic.

Like any web game, these errors are silent, the player sees the story stop or behave wrong, and you never learn unless you capture them. And like any branching story, a Twine game error is tied to a specific passage, the node in the story where it occurred, since the story logic and any scripting live in passages. Understanding that a Twine game is HTML in the browser, failing through silent JavaScript and macro errors tied to passages, frames the crash reporting: capture the browser errors and connect them to the passage where they occurred.

Capture the script and macro errors

Capture Twine game errors by hooking the JavaScript error handling, the global error and unhandled rejection handlers, so a JavaScript error that would break the story and land silently in the console is captured with its message and stack trace. This catches the script-level errors, including those from your custom JavaScript and from the story format runtime.

Story formats also have their own error handling for macro and logic errors, a malformed macro, a logic error in the story scripting, an undefined variable, and capturing these format-level errors complements the JavaScript capture. Where the format surfaces an error, capturing it gives you the format-specific diagnosis, and the JavaScript capture catches the rest. Capturing both the JavaScript errors and the story-format macro errors gives you complete coverage of the ways a Twine game fails, from custom scripting bugs to malformed macros and story-logic errors.

Capture the passage and variables

The essential context for a Twine game error is the current passage, the story node the player was at, since the error is tied to that passage and knowing it localizes the error to the specific piece of your story. Capture the current passage with every error, so a crash maps back to the passage where it occurred, which is the Twine equivalent of a script location.

Capture the story variables too, since Twine games track state in variables that the story logic and macros use, and an error often depends on a variable being in an unexpected state, a variable used before it was set, a value out of range. Capturing the variables, like the story flags of any narrative game, reveals the state that produced the error. The passage and variables together connect a Twine error to both the location in the story and the state that caused it, making it reproducible, which is what you need for a branching story game.

Watch for broken passage links

The signature Twine game bug is the broken passage link, where a passage links to another passage that does not exist, perhaps because of a typo in the passage name or a passage that was renamed or deleted, producing a dead end or an error when the player follows the link. This is the Twine equivalent of the dead ends that plague any branching story, and it can strand the player.

Capture broken-link errors with the link and the passage it was in, so you can see which link is broken and where, pointing you at the typo or the missing passage to fix. A broken link is a structural bug in your story, and capturing it tells you exactly which passage and link to correct. Watching for broken passage links, the dominant structural Twine bug, and capturing them with the passage context, surfaces the broken story structure that strands players, which combined with a structural validation of your story graph keeps the branching paths intact.

Setting it up with Bugnet

Bugnet web SDK hooks the JavaScript error handling and captures the browser context, and you attach the current passage, story variables, and any story-format error context as custom fields, so a Twine game error arrives with the passage-and-variable context that makes it reproducible. The errors flow into one dashboard, even from a self-contained HTML story game running in the browser.

Group identical errors into occurrence counts, and use the passage context to localize errors to your story nodes and see which passages produce the most errors. Because Twine games are silent in the browser and their errors tie to passages, the captured passage-and-variable context is what makes them diagnosable, telling you which passage and state to investigate, which is exactly what you need to fix the script errors, macro bugs, and broken links that a branching HTML story game produces, keeping the story playable.

Validate the story structure

Since broken links are the dominant structural Twine bug, validate your story structure, checking that every passage link points to a passage that exists and that the story graph is sound, no broken links, no orphaned passages, no unreachable content. This validation catches the broken links before players hit them, much as you would validate any branching narrative structure.

Combine the structural validation with your captured error data, which reveals the script errors, macro bugs, and any broken links that reached players, including the state-dependent errors that structural validation cannot catch since they depend on the runtime variables. Your validation catches the structural problems in the story graph, and the captured errors surface the runtime script and state bugs from real play. Together they keep a Twine or HTML story game working, with the branching structure intact and the script and macro logic free of the errors that would break the player journey through your interactive story.

Twine games are HTML stories failing by passage. Capture the error, the passage, and the variables, and validate the links.