//---------------------------------------------------------------------------
ADDP: A Dark and Deadly Path
by mouser@donationcoder.com
//---------------------------------------------------------------------------
//---------------------------------------------------------------------------
ADDP (A Dark And Deadly Path) is a tiny little interactive story game engine.
See the README.txt file for an overview of the system and what it does; this
document is a manual for authors wishing to make their own games using ADDP.
//---------------------------------------------------------------------------
//---------------------------------------------------------------------------
ADDP works using standard mp3 audio files that you as an author record
yourself. A single xml file defines the "script" for a story/game and
indicates which choices can be made at which times, and what should happen.
Making an ADDP story/game is a very low-tech process, and is entirely based
on audio. It is not complicated and requires no programming experience.
Nearly all of your work will be spent recording a good audio story.
//---------------------------------------------------------------------------
//---------------------------------------------------------------------------
Step-by-step Guide to Making a simple story/game for ADDP
//---------------------------------------------------------------------------
This example shows how to make a single-storyine game/story, where there is
no actual branching of stories. That is, there is only one single storyline
and only one correct choice at each choicepoint time window. All other
choices end the game (with death of character?).
It is possible to make more complicated branching games but we start with
the simplest case.
A complete sample game/story is included to help you see how things work.
//---------------------------------------------------------------------------
//---------------------------------------------------------------------------
STEP ONE: Create your game subdirectory
Each story is placed into its own subdirectory of the Stories\ directory.
The name of the subdirectory is the name of the game. Record a short
one sentence description of the game and save it as "ShortInfo.mp3"
in that directory. This audio will be played when the player selects your
game and considers playing it.
A good way to start creating a new game is simply to copy the contents
of the Test subdirectory and modify that test game.
//---------------------------------------------------------------------------
//---------------------------------------------------------------------------
STEP TWO: Plan out your main storyline audio, and record it.
This storyline should proceed as if the user made the right decision at
each point. Remember that this audio describes everything so it will
include any info the user should hear before they make their choice and
after they make the right choice.
For example, the story might say "You approach a tunnel, press C to crawl
into it, or J to jump over it.. You decide to crawl into and then you
begin walking in the tunnel.."
Notice how we presented the choice in the story, paused, and then described
the action they took.
Note that in the example above we used keys C and J which corresponded to
the words of the actions, and explained their use. Alternatively you
could have users always use keys 1,2,3,4,etc. to choose from the choices
in order. Or you might even write a game where the only action is to either
act by pressing the spacebar or do nothing.
By default you might name this file "story.mp3"
//---------------------------------------------------------------------------
//---------------------------------------------------------------------------
STEP THREE: Now record your bad-choice end-game audio files.
In addition to the main storyline, you will record short standalone mp3
audio files that describe the consequences of each mistaken chioce. For
example in the case above you might record a file "JumpTunnelDeath.mp3"
and it might say "You jump over the tunnel and land in a pit of snakes who
eat you. You are dead."
//---------------------------------------------------------------------------
//---------------------------------------------------------------------------
STEP FOUR: Write down time windows
Now listen to your main storyline in a program which shows you the precice
time counter as you play it. Write down for each decision time window the
start and end times you want people to be able to indicate their action
choices.
You might choose to make the window start as soon as you start describing the
choices or you might want to describe the choices and say "GO!" and give
them only a split second to act. It's up to you.
For each decision point you will need to specify which actions lead to
continuing the story, and which actions end the game/story with certain
endgame audio files being played.
//---------------------------------------------------------------------------
//---------------------------------------------------------------------------
STEP FIVE: Write the script xml file
Once you have recorded your audio files and make a note of all the choice
windows and endgame audio files that should play on each action, you are
ready to edit the story.xml script file to fill in these values.
Here is a complete story.xml script file for a game with only once choice
point:
main.mp3branch9.0013.50
1
In this story, the single choice point occurs from 9 seconds to 13.5 seconds,
and the choice 1 leads to the story continuing. Any other action (incl.
doing nothing) will end the game and play the file "1_die_t_car.mp3".
//---------------------------------------------------------------------------
//---------------------------------------------------------------------------
ADDP SCRIPT DOCUMENTATION
STORY NODE:
Your script will be enclosed within tags, and consist of
one or more nodes, and an optional node.
OPTIONS NODE:
An option node specifies some global options for the story, including
special sound files to play for certain things:
Ding.mp3Dong.mp3clickerx.wav
It's commong to have a quiet little ding-dong sound pair configured
to indicate audibly when choices can be made by the user. In fact you might
want to just explain to the user in the begining what they should do when
they hear these sounds and then never again in the story tell them
when they should make a choice, relying on the audio tones alone.
You can use the sample sounds above in your game or customize them if you
like.
CHAPTER NODE:
A story is made up of one or more chapter nodes. Most games may have
only one chapter, but support for multiple chapters is provided to help
you break your story into a few separate main audio files.
A chapter node is made up of a node and a series of
nodes. You can specify a name attribute for the chaper in order to refer
to it later.
MEDIATRACK NODE:
The node for a chapter specifies the main storyline audio file
for the chapter:
main.mp3
EVENT NODES:
Event nodes in the story script do all of the main work. An event has a
specific start time, and usually an end time. There are severel different
types of nodes:
"BRANCH" EVENT NODES:
The branch event types do the main work, they specify a choice point:
branch9.0013.50
1
As you can see the type is specified and then a and ,
followed by choice nodes.
CHOICE NODES:
A choice node specifies what to do depending on what key user presses at
a branch choice event.
The tages specify which inputs this choice works with. You can
specify multiple pairs for a single choice, and use
* to match any input, or TIMEOUT to
specifically match a timeout (user didnt type anything).
When any of the inputs match, *all* of the nodes associated with
a choice will be executed.
ACTION NODES:
There are several action types, each of which can specify certain attributes:
'RESUME' action just says to continue the main story - you can use this
when the right choice is made (no other actions will be run or input nodes
checked):
'PLAY' action just says to play the mfile specified, immediately (pausing
main storyline audio file first):
'DIE' ends the game. Usually you execute this after you play an endgame file:
'GOTO' jumps to a specific chapter and event:
"MARKER" EVENT NODES:
You can make a silent marker type even which can be used as the target of a GOTO
action:
marker27.38
//---------------------------------------------------------------------------