(NOTE: If she's locked in her current state this will be indicated by a small lock symbol like this
).This tool has been written to provide an alternate way for debugging complete storylines written for Heartache 101 ~Sour into Sweet.
(It's assumed that you are familliar with this game, and that you are currently developping your own content for it)
Within the game you have exactly two ways to test your content: you could just play through a normal game or you could use the build in "Story Test" mode.
Both methods have their own drawbacks:
This means you might spend quite some time until you hit the few stories you're currently interessted in.
While it is possible to save your game, it's often impossible to pick "just the right" point in time to do so, since the player has only limited control over which stories are played when.
Worse still, every change to the game logic (i.e.: which stories are triggered by what) might invalided your savefiles, so you'll have to restart your play-through.
You can pick any one story you'd like to test and run it in test mode.
BUT: the story runs with out any context. Any conditional branch like "B: 23 DONE" will fail. Aside of this, you have no control over conditional branches involving a CHANCE condition - or based on the date or weekday, so it's not easy to test every single branch in your story.
This tool tries to address these issues.
While it's far from a complete simulation for Heartache 101's Game.exe it allows you to play through entire storylines, keeping track of which stories have been visited and of which stories would be currently considered by Heartache's story selection mechanic.
You can save your progress, and then return to test out a differnt route from any point in the storyline. In most cases save files should load just fine even if you made some modifications to your game logic.
You are given complete control over the state of your current playthrough: you can mark any story as "visited" or "not visited" you can run stories in any order you choose - no matter if their conditions are met or not.
And, of course, you can alter the state of any character as you wish (mark her as "name unknown", set her affection to "DISLIKE" ...
Along with the tool itself (and thus this document here) should have come an INSTALL.txt text file. Please follow the instructions in this file
After starting the tool you probably noticed a large black rectangle on the left side. This will be where your stories will be shown. It roughly corresponds to what you would be seeing if you played the same story with Heartache 101.
While playing through a certain STORY of a certain content it might for example look like that:
The scene is set in "Market Place" which is mentioned at the top of the view, it has an active PICTURE command and a tachie of a girl in the "RIGHT" position.
Below the scene is a line informing you, that this is STORY 7922 of a file named "WingGirl" (.txt).
To the right of this, you'll notice some VCR like controls for navigating through the STORY and a checkbox labeled "done".
By clicking on the main view or using the controls you can work your way through the story, forward as well as backwards. The checkbox allows you to mark the story as "not done yet" or "done".
Below this line, you are informed that the current speaker is "Mayumi", and that she's saying "So - that should be enough."
On the very top of the page you'll find a small menu with the following structure:
The file menu is used for starting a new session and for saving and restoring the current state. You can also delete one or more bookmarks you might not be needing any more.
NOTE:The tool automatically saves each time you start a new STORY or change anything else (that's the "-- autosave --" entry you might have noticed already). After reloading the page the last automatic save is silently loaded (so you will return more-or-less where you left before you hit F5 or closed the browser).
The menu entry "Options > Player info" is used for renaming the player (you can rename him anytime you like since this has no influence whatsoever on simulating stories), and of course for changing his stats and money.
You can use it to change the current day, too.
Note that the numeric values are implemented as "spinner controls" so you can either enter a new value or use the small litlle arrows or the keybord for incrementing or decrementing the value. By the way: the PAGE-UP and PAGE-DOWN increment/decrement by 10 ...
The entry "Options > Content selection" works pretty much like the "Custom Content" entry in Heartache's main menu. The main difference is probably that Built-In is treated like any other content - instead of activating "Clean Mode" you'd just deselect the Built-In content.
The help menu contains links to this document and the quick install guide.
In addition you could use "Help > About" for finding out the version numbers.
The last entry in the help menu lets you revisit the errors that have been found while loading the content files.
Note: If you installed the "officially released content" and just started the STORY-debugger, this will probably look like this (as for August 2016):
This indicates that there are two uncorrectable errors in the content. These are discussed here. You'll have to either fix them or exclude this content from your installation.
You'll notice several warnings, too. Most of these would not appear if you ran the content with Heartache 101 itself. Some are implementation limitations like "randmom names not supported" others are minor errors which are silently ignored by Heartache 101.
For example: the helpfile explicitly states
"A condition can contain both Logical Or and Logical And provided parenthesis are used. The parenthesis are required in such a case; Heartache 101 will not evaluate the condition correctly without them."
Nonetheless: the engine will load stories containing such a mixture without complaining. Unlike the Heartache 101 engine, STORY-debugger does define a precedence (AND is stronger binding then OR), but issues a warning since the in-game behavior is explicitly left undefined.
As a rule of thumb: If you find warnings related to your own content, you should probably have a close look at them and fix them (or contact the author of this tool, if you think the warning is unjustified.
In any case: it's only important how THE GAME is handling your content. This is only a tool for helping you develop own content. So the final test for your content will still be if and how it's playable by Heartache.
To the right of the main view you will find the story browser. It might look like this:
You probably noticed that it has four tabs ("Active", "Related", "Switches" and "Search")
In the above screenshot the "Active"-tab is currently visible. It represents an overview of all stories a normal Heartache 101 game would consider as candidates for running next, grouped by event type.
(NOTE: Front A and Front B stories would be under "school events", "Nighttime events" include both PHONE calls and "Bedroom" stories. An INTRODUCTION or an ENDING would be
under "special event".)
You could click on the group headers to hide or show the stories of a given group.
The "Related" tab would present all stories that are related to the last story or profile that has been selected. Relations between stories include jumps between two stories, conditions in one story involving the other one, and conditional branches (involving the other story as a condition). For a profile the relations might contain her introductory stories, her ending, her PHONE and DATING stories and of course any story she appears in.
In the "Switches"-tab you'll find all switches in the currently installed content. A switch is any story of the form:
STORY 171 CONDITION = 171 DONEIE: the current story is dependend on itself (and thus can only be reached via JUMP), does not define a PLACE, and does not have a type; it might contain only a very small body as in:
STORY 177 CONDITION = 177 DONE ID = -- * End of the world ENDING available *
The "Search" tab allows you to - well - search for stories. You could just search for a story ID (like with Heartache's Story Test mode) or for a range of story ID's (like in this screen shot)
Any other text entered into the search form will start a search for conversations containing each of the words.
NOTE: This search doesn't list all stories containing the exact phrase "favorite teacher" but rather it search for both words independently. Somewhere in story 13 of game_stories_7 the word "teacher" can be found as well as the word "favorite". In the above example they start talking about the teacher's office and the word favorite isn't mentioned unless Kazuhiko fails to give the correct answer (which would be in BRANCH D).
In any of the tabs the stories are represented by a number-plate followed by the name of the story file where it's defined.
The tool uses colors to indicate high or low priority stories, stories that have been visited
or stories that are not part of the currently selected content. Of course this can be combined to indicate a
high priority story which has been played even though it's disabled.
If you want a short impression about a story you could just let the mouse hover above it for a few seconds. A small tooltip like this will appear.
It contains the type of the STORY and the first few lines of conversation (if any) of the main branch. Most of the time this should be enough to recognize a story.
Left clicking on the number would select the story (so it's connections to other stories would be handled by the "Related" tab), run it (it is displayed in the main view for you to click through it) and mark it as "done".
A right click pops up a small menu where you could play the story (same as with a left click), select it without running it, mark it as done (or revert this mark) or analyze the conditions needed for that story to be run by Heartache 101's engine.
To the right of the story-browser you'll find a view labeled "Cast", structured by two headers reading "Active cast" and "inactive". You can click on either header to show all characters
who have or who haven't been introduced yet. You get a small version of the current tachie, her first name and her current affection state for each character defined in the currently selected content.
(NOTE: If she's locked in her current state this will be indicated by a small lock symbol like this ).
Left clicking on an entry in the cast view will open a dialog where you can check and manipulate her status: make her name, sign or phone number known or unknown, (un)lock her affection state, enable or disable random encounters. ... most importantly: you can use the slider below the textual representation of her affection state to directly set her affection to any value you like.
While chancing her affection or (un)checking her "Phonenumber: Known"-checkbox you might notice the story-browser reacting to these changes ... (Because you can't have PHONE- or DATING-stories if you don't know her PHONE number, and of course some stories are only available on a certain affection level).
You could, for example, use the "Stories > Search"-tab for finding the story or the stories you want to debug and step through them, similar to what you'd be doing with the in-game Story Test mode.
Unlike this mode, you'd be presented with any conditional jump and offered to override what normally would be happening. So you can quickly check all the different ways through the story.
Another difference is that you can really go backwards after each decision within the story, while Story Test mode would only scroll back the conversation as it happened.
Furthermore, this tool is stateful: it will remember which stories were seen even if you're just "clicking through" single, unrelated events. You can use this for checking the influence of stories on each other.
You can manipulate the standing with any of the characters and your players stats while browsing through a story, too. (If needed you can lower your stats as well ...)
Besides just clicking through a story you could use the "Related"-tab to check on which stories are influencing your current debugee or are influenced by it.
And you can check which conditions of the debugee are currently satisfied and which are not ...
Try this:
This should quickly give you an impression on how your complex conditions are really playing out.
Caution: you can't really check stuff like pacing with a simulated play-through; only the "density" or "depth" of the currently selected content.
It's especially easy to miss things like a repeatable PRIORITY = HIGH story which would be very annoying in-game. Or you might end up with something like a low prio FRONT B story which plays only on mondays - without noticing that this would take ages to appear in a real game.
You should run a real play-through in Heartache 101 from time-to-time just to be sure.
Using the "Stories > Related"-tab you could follow a thread in any way you want to. Select any story, then look at the "Related"-tab to find stories jumping to it - or stories needed in it's condition to move backwards.
Or follow the thread by looking where the currently selected story jumps to or which stories need it in their conditions.
Note:I'm still considering a way to present some kind of "flowchart" or something to the user ... it's simply not there yet.