COSC 2P03 — Assignment 2 — I think we’re stuck in the 1980s...

Excuse me a moment, while I grab a cane to waggle.

Back in my day, we weren’t limited to well-designed, cohesive narratives in our stories! We had the freedom to choose
what we wanted to happen in books, albeit with no means of realistically knowing what the outcomes could possibly be
from those choices, defeating half the apparent purpose. But it was our choice!
Maybe our choice to pick up an apple determined whether or not the Earth was hollow, or if an asteroid had actually
been plummeting towards the planet the whole time, but it was never the same each time you read it! (Until you read it
a few times. Then you’d get repetitions)

...what’s that? You can already do that in vidya games? No clue what that is.

So anyhoo, what we’re not describing is the concept of a Choose Your Own Adventure©™® books. Because someone
owns the rights to that name. What we’re talking about is Select Your Story. The principle of a SYS book is simple: for a
given book you always start at the same place. However, after segments of story, the reader is then presented with a
choice to make, each of which leads to a different place in the book (traditionally done via page numbers, but that’s
secondary). This creates branching story lines, such that not only do the myriad outcomes typically vary quite a bit, but
the process of finding those end points entail very different story paths along the way.

In practice, this can be represented fairly well with a tree (in that, even when designing ‘the real thing’ on paper, you’d
probably draw out a tree of branching decisions). e.g. skipping the actual story parts:

Note that a single page might not lead anywhere (i.e. the end of one version of the story), or it could lead to two
outcomes to progress the story, or even more than that.

To that end, we’ll need a general tree.

The Task:
Rather than making ‘one thing’, you’re more making ‘a set of things around one topic’.

⚫ You’re making something to represent a complete multibranching story, to facilitate the creation of SYS stories:
◼ At each entry, there is some piece of the story (a description of that location within the story), and anywhere
from zero to ∞ possible story branches
◆ It’s safe to assume a ‘story’ will always have a root, and thus providing the initial description starting the
story should probably be part of creating the story
◆ If it’s helpful, it’s fine to assume a description will be only a single paragraph
◼ Each branch has an associated decision — simply a bit more text that will be displayed to the reader
◆ As each entry (other than the root) will have been reached from precisely one path, it’s probably best to
group the text associated with the action that lead to an entry with that entry
◼ A story ‘ends’ anywhere the reader has no more actions to take
 ◆ This means some stories could be longer or shorter than others, based on whether or not they continue
leading to more entries that still have additional actions
◼ You have a position (like a cursor) within the story. From any given point, you may:
◆ See the available decisions at the current location, as well as the number of decisions here (mostly for your
own convenience’s sake)
◆ Add new branches (decisions) from the current location
◼ There’s no direct need to help the reader ‘go back’ (beyond the obvious ‘starting over’), but you might
personally find later tasks easier if you include something to act as ‘bread crumbs’
⚫ You’ll need an Editor for creating and adding to the story, which will need:
◼ The ability to load/save, since nobody wants to write all of that at once
◼ The ability to export to a browsable HTML document (more below)
◼ A mechanism for both browsing and editing existing entries
◼ The ability to add new actions to any existing entry
◆ Note that adding an action doesn’t move into that action (meaning, at some location, you can easily add
multiple story branches to it)
◼ The ability to delete an entire subtree of actions (basically, if you’re at some entry and choose to delete from
that location, then every additional entry that entry led to should also be discarded)
◼ The ability to browse across ‘story ends’ (to make it easier to extend stories)
⚫ The primary final output will be the generated story, in the form of an HTML document, with links (the <a> tag) to
the associated choices
◼ Each ‘story end’ needs a link back to the start of the story
◼ For the sake of clarity: this document is effectively all possible stories

In terms of implementation:
⚫ The Story doesn’t need a method for ‘going up’, but it’s up to you if you’d prefer to allow for a parent reference at
each story node
⚫ You add ‘branches’ by adding children to whichever node is currently referenced by the cursor. If you want to add
‘sibling paths’, that’s done by adding more children to the parent
◼ This also means there’s no way to accidentally add siblings to the root node
◼ When adding additional children to a node that already has one, add new branches after the existing ones
⚫ The ability to browse across ‘story ends’ just means it can jump the cursor to the next node that has a null reference
for its first child
◼ This one’s potentially tricky, so make sure you include something even if you can’t get it fully
⚫ Beyond browsing (for the sake of editing), you don’t need any programmatic means of ‘playing/reading’ the story
◼ Being able to generate the HTML file is sufficient for that
⚫ This task doesn’t require any detailed knowledge of HTML
◼ You’ll need the HTML, BODY, and A tags, of course
◼ I’ll offer some help at the end of our next lecture for the HTML side
⚫ When creating the html document, anchor (A) tags work according to id attributes. There are many equally-valid
ways to do this, but you might find the easiest way to be simply keeping an incrementing counter (e.g. when
generating the document, or even when creating the nodes). Since the user will never see these (outside of clicking
‘view source’) it doesn’t matter what these look like, so long as they work
⚫ Of course, you’re implementing everything yourself
◼ You’re welcome to use BasicIO for the IO
◆ Otherwise, PrintWriter, BufferedWriter, FileWriter, File, IOException, and Scanner should work

Additional tidbits:
Everyone should already know these, and it’s literally impossible to provide an exhaustive list, but some common things
to watch out for:

⚫ Please develop the entirety of your solution on a single machine, from start to finish within the same instance of
IntelliJ. If for some reason this is not possible, include an explanation with your submission. Failure to do so will
result in a zero. You may not decide to submit additional components after the assignment closes
⚫ Similarly, when submitting, include:
◼ The entire project
◼ A sample ‘story’ (both the sample file and the .html it produces)
◆ Of course, your ‘story’ doesn’t have to actually be a story; just make sure it demonstrates the requirements
◼ Whatever other sample executions and/or whatever would help the marker evaluate your work
◼ (Don’t bundle the Brock library with your project. You should be able to configure an IDE’s SDK by now, or you
should seek assistance with that, in a prompt and timely fashion)
◼ Make sure everything’s glommed together into a single .zip file (not .rar, .7z, .tar.gz, etc.)
⚫ You’ll be using the static keyword for your main method, only. There are many valid uses in general for that
keyword, but not in this task. If you do it elsewhere, it’s wrong. Don’t be wrong
⚫ The permitted imports are itemized above
⚫ There’s a Help Desk, a tutorial leader, and an instructor who very very very much likes questions

You’ll notice this task doesn’t include as detailed of specifications. That’s because this is ‘the general tree assignment’;
it’s defined by the pieces you need, and reasonable development according to the standards we’ve been developing for a
year and change. But beyond that it isn’t quite as picky as the first assignment (since that one required a single precise
algorithm). Just work it out, plan carefully, and make sure you understand what you’re doing.