Debugging your story

After you have built your story, the browser that is registered to open html-files will be started and the created html file is loaded.

In most cases one of two things might happen:

• your startpage of the story is displayed
• you get a blank page with a weird error text

In the second case the most likely issue is an error inside your global scripts/js-files that you have written.

But even if your start page is loading, that doesnt mean your scripts are working. Only if the code is executed, the interpreter will run into an error!
So its important to test every function-path you add.

How to find the error now? Most modern browser have a Javascript debugger that can be activated by pressing F12 or another command in the menus. There you can find an inspector for the html and a javascript-debugger.
In the html-inspector you can view the rendered html-code and view and even modify the style applied to it. In the debugger you can set breakpoints in code or activate break-on-exception. Note that breakpoints are only triggered while the debugger is activated. After your story is loaded, you might need to activate debugger and reload the page.

How to find your code to set breakpoints?
In the debugger you have a watch-panel. There you have to add a watched object that has one of your functions appended.
In my case its window.gm that has a initGame-function.
You can then unfold the variable, search the function, right-click and select goto definition. Now you should see your code in the debugger.

But:
Debugging code within Templates or even <script>-sections seems impossible. Since this data is embedded into passage sections, it is not recognized by the debugger until the page is rendered. If there happens an error then, the DOM will only contain the error message without the script.

Therefore, I stick to write scripts in js-files instead in <script>-sections within passages or within templates. Then you can set breakpoints in this script easily.

• If an error is triggered when cliking on a link/button, then the alled function or a sub-function might have an issue and you already know where to start debugging.
• If the start-page already shows an error you should try debugging beginning from your games init-function.
• If you then find that in your function some global variables are not present (f.e. the library of inventory-items), this meens some code was not executed properly before the initGamme-function. Sadly the problem there does NOT trigger an error and the code will silently be skipped and it can get tedious to find the culprit. You need to check in variable list which global object is missing, find the code in the debug view where your breakpoint is halting the execution, set another breakpoint in the objects construction function and restart the game.

Please note: The error message printed on screen doesnt give you much detail where the error occured. F.e. if you have somewhere function with code like "....var count = window.story.state.player.inv.count..." you will get: "reference-error on inv because player is undefined". But it will not tell you in which function or codeline the error occured which makes it very difficult to track down the position.
So I made a hack: the message is rendered by snowman so I changed the snowman script that prints the error to include the error-stack.
search for "$(window).on("sm.story.error"" in ..\tweego\storyformats\snowman-2\format.js and change in this function e.message to e.stack.