CYOA using tasks

From ADRIFT 5 Manual Wiki
Jump to: navigation, search

This method involves creating a general task for each of the pages of text in the interactive book, and using a variable with restrictions to control which tasks are valid at each point in the story.


The current version of ADRIFT is unable to function properly if the standard library is not loaded, so you will need to disable it by creating a general task for the wildcard command [*] which has a priority higher than any of the standard library tasks but lower than any of the tasks you create yourself. The message for this task should be "Please choose one of the options listed above."

An alternative to this is to use the Choose your own adventure Library INSTEAD of the standard library.

The current version of ADRIFT requires all games to have at least one location. Double click on the map to create a location called "New Location". It is not necisary to edit this location because we will not be using it.

The PAGE variable

At the end of each page we present the reader with a menu of choices, and we only want them to be able to choose those particular options, so we need a way to ensure that only the tasks corresponding to those options can be executed.

We do this by creating a variable that keeps track of which page of the story has just been displayed, and we add restrictions to the tasks that check the value of the page variable and prevent incorrect tasks from running.

We could simply number each page and use an integer variable, however as the story will have lots of branches and loops you may find it easier to sort the tasks and insert new pages if you use a hierachial numbering scheme, so create a new text variable and call it "page".

Set the initial value, in the example below i used 0 to represent the initial page.


The first page of the story is written in the introduction dialog, so select it from the main menu:

Main Menu.JPG

Note that we dont need to use locations because we are doing everything with tasks, so the "Display first room description" checkbox is not selected and "Start the adventure at location" drop-down is left set to "No location selected".


The first page of the story is written and at the bottom we provide a menu of choices for the reader to select from. In the example i have used a simple numbered list which makes it quick and easy for the reader to press a single key and enter to select an option. This technique is used by many CYOA authors but has one drawback, once you start using branches and loops it will be necisary to have gaps in the numbering, and sometimes you will need to rearrange the numbering because you have already used the number that you need to link back to an existing task. This is because a task is directly linked to a command, so every menu that links to it must use the same command.

An alternative is to have the reader type a word for each menu choice, so you could have:

  • [Mall] Go to the shopping mall
  • [Home] Go home
  • [Library] Go to library to borrow a book
  • [Park] Check out the local park

Now we need to create a general task for each of these choices. Here is the task for menu choice [1] from the introduction above.


For the task name i have given it a number followed by a short description of the page contents. The number is used to sort the tasks in the folder to keep related tasks together. This number will also be written to the page variable to keep track of the last page shown to the reader. A CYOA can contain hundreds of tasks so it is a good idea to use a hierachial numbering scheme to organise them. In the example 01AZ01 i used '01' for day 1, 'A' for the first scene on that day, 'Z' to signify the main story sequence (not a branch), and '01' for the task number within that sequence.

  • Always use a fixed-length format with leading zeroes if required, so the numbers sort correctly

The command is simply the name of the menu choice, here i used a numbered menu but you could also have used [hide] or [bed] if you preferred. The message is the next page of the story and the next menu.

  • Most of the tasks dont need "Task is repeatable" selected, but if you use quests and loop-backs then the task you go back to will need it selected.

On the restriction tab add the "Variable" restriction: [page][must be][equal to]["0"]

This ensures that this task can only be executed if page="0" and the reader types the command "1".

On the action tab add the "Variable" action: set[page]=["01AZ01"]

This ensures that the next menu choice that the reader makes will only execute a task which has the restriction [page][must be][equal to]["01AZ01"].

The combinatorial explosion

If each of the menu choices on each page links to a new page, then the number of pages that must be written quickly increases to unmanageable numbers. If each page only has two choices then you need at each level: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 pages. So you need to write a thousand pages just to give the reader 11 pages to read on any particular path, and over a million if you have 4 choices on each page.

Clearly we need to greatly reduce the number of pages, but without limiting the readers choices too much. The simplest is just to make many of the choices dead-ends. If the reader makes an obviously bad choice then the main character can die or fail in their task so that the story ends there.

Often a CYOA will have a small number of main branches that will follow a different story line, each one concluding in a different ending for the story.

To give the reader more valid choices and make it more interesting we can also add short branches that offer a different path to the same result and which merge back to the main story, and quests which dont have to be done in a particular order.

Writing the story

A good way to start writing a CYOA is to start with the main story sequence and first write the main path through the story from beginning to its successful conclusion. Extra menu choices can be put in as you go, but leave all of these branches until the main story is complete, then go back and add in one branch at a time, fleshing it out further as you go.

  • Don't make the main path the first menu choice every time or its going to be very easy for the reader to figure out that they just need to keep pressing "1" to get to the successful conclusion.
  • To better keep track of the tasks, put each 'Chapter' of the story into its own folder.

Bypass branches

A simple way to add extra choices is to insert an optional page between two other pages that the reader can either select to see or bypass. This is usually a menu choice that either leads to a failure or in which nothing of importance happens in the story. Its menu then gives all of the same choices as the previous page (except itself) so that the story continues the same way regardless of whether this page was read or not.

A more complex variation of this might allow the main character to obtain an object or do something which is then used later in the story to change the presented options. Alternately, if the reader misses obtaining an object this time then later in the story they could be given other chances to obtain it by adding bypass branches that only appear in a menu if the object has not been obtained yet.

A page that is the destination of multiple pages must have a restriction for each page that links to it. Click on the 'AND' at the end of the line to change it to 'OR' as we want the task to execute if ANY of the restrictions pass.

Restrictions ORed.jpg

Converging branches

After branching into two (or more) separate story lines, both are continued independently for awhile but the goal in both is the same. You could be trying to obtain a particular object or certain information, but using different methods in each branch. When successful, the two branches converge back into the same page of the main story.

If the two branches need to repeat the same section of text then you can use a system task like a subroutine. Just fill the system task with the text and call it from multiple general tasks using an execute task action. On the advanced tab of each general task use the "Display completion message Before/After executing actions" selection to determine if the text of the general task or system task is displayed first. The page variable is not usually set by the system task, unless it displays the menu and you want it to lead to the same destinations for both branches.

The system task can also be used as the converging page that brings the separate branches together. The last page of each branch would be set to "Display completion message BEFORE executing actions" and would not contain menu's, just a description of how you succeeded in your task, then the system task would tell you what can happen next, display the menu, and set the "page" variable to itself.


Quests are parts of the story which can be separated into self-contained sections which can be read in any order. This allows the reader to select which part of the story they read first, usually by choosing to go to a different location at a major branch point.

All of the quests in a group loop back to the original quest selection page, where the reader can then select one of the other quests to go on. Usually a certain number of quests, all of them, or particular quests, must be completed satisfactorily before the reader is offered the option to continue to the end of the main story.

Enabling Look and Examine

To increase the amount of interaction with the reader you may want to allow them to use "Look" to check out their current location in more detail, or allow them to examine characters and objects.

This is a lot more work though, as you not only have to create all of the locations, characters and objects that are mentioned in the story, you also need to manually move the character to each new location using an action, and also move other characters in and out of the location as described in each page of the story.

If you are going to go to all this trouble you might as well write a traditional ADRIFT game instead.

Advanced features

With all the branching and optional quests mentioned above you will eventually get to a stage where the description on a page may not be correct depending on how they got there. The character could be holding different objects or their relationship with another character may have improved or soured.

In this case you can use Alternate Descriptions in the text box to change part of the description. Using a restriction on a "Display after default" description you can conditionally insert a few lines of text based on whether a particular page was displayed (Task xx must be complete), or on the value of a variable, property etc.

  • This can be followed by an Alternate description, with no restritions, to display the rest of the page.
  • Extra choices can be added to the menu using another restricted alternate description after this.

Text variables can also be used to slightly alter any of these descriptions by changing their contents when circumstances change. eg. "Sally is smiling at you cheerfully" or "Sally is glowering at you in a very unfriendly manner" depending on how you treated her earlier.

<<< CYOA using locationsMain PageChoose Your Own Adventure >>>