Ben-design

This page needs clean-up and editing for coherence, clarity, and completeness.

Please improve this article if you can.

Incredibly Simple Interactive Storytelling 
(ISIS)

Roberto... needs work - will update again tonight and tomorrow...

The goal of ISIS is to create a very simple and usable interactive storytelling system aimed at young kids using the XO Laptops.

The system is an authoring platform that stores data in XML files for easy access and understanding.

A python interpreter plays back the files.

The game treats everything in the game as much as possible as a generic node in a tree of nodes are called...

Story Nuggets:  These are essentially universal nodes on a tree for the story.  Nuggets can be labeled as specific items for further embelishment

Every node or element put into the game is a unique record in a DB

Story nuggets are basically the low-level text blocks in the system they each have a unique ID and a code block element, and text.

	Unique ID:	Universally Unique ID
	
	Name:	[128 chars]
	
	Code Block: [Contains Script Code to Run Before Nugget is Displayed]
	
	Display Text:	[4K-8K chars]
	
	Icon: Icon ID to  display -- maybe be filename or a unique id to a list of pictures in a database - note all icons should have a standard size they are displayed at.
	
	Picture: Defualt picture for that story nugget  -- other pictures could also be added to a list and associated to the nugget...
	
Aside from Story Nuggets the game has People & Things which are essentially the same thing from an object framework as they may be independently located in the story irregardless of the placement of Story Nuggets.

These objects have the following structure:

	Unique ID: Universal Unique ID
	
	Name: [128 chars]
	
	Type:	Being or Object [for interface purposes]
	
	Location: Unique ID of Story Nugget where the object is Currently Located   (-1 could equal with player)
	
	Icon: Icon ID to  display -- maybe be filename or a unique id to a list of pictures in a database - note all icons should have a standard size they are displayed at.
	
	Picture: Defualt picture for that story nugget  -- other pictures could also be added to a list and associated to the object...
	
Note: objects don't have associated code blocks.

Options/Choices
Options in the game are choices the player is given on a menu the game displays.  

All options available to the player at any time are displayed on the screen.  There is no need to guess at an action.  If you can do it then the action is present in a smart list of actions on the screen.

The trick is that some actions won't show themselves unless a particular state in the game is met.

In general options are are individual records that bind to either story blocks, are conditional, are universal.  They govern a single option available to the player at any time and what story nugget to go to if executed.  Option nuggets have text, a goto ID (i.e. where do you go as a result), a time to execute amount, a flag to display time to execute (y/n), and a conditional block id.

There are four stacks of options:

	Universal actions:	Always available anywhere / anytime in the game
	
	Universal conditional: Always available anywhere / but only when certain conditions are true
	
	Nugget actions: Always executable if you are in the right place on the story tree
	
	Nugget conditional:  Must be in exact place on the story tree and other conditions must also be met
	
When a player makes a valid move of any kind from the move options the game's state changes and the following happens:

	The game evaluates and lists all universal actions
	The program runs each universal conditional's evlauation script to see if it qualifies.
		If it does then that move label makes it into the choices available.
		
	The program checks the list of options associated with a particular story nugget action list and puts them in the option list or...
		For conditionals 
			program checks to see if expression attached is true and if so displaus that choice
	
	if not then it doesn't.
	
	Such conditionals are very simple pieces of code that are written into the system...
	
		e.g.
		
		If sword_inventory == true then... [display option]
			[Option might be] Swing Sword and bound to story nugget #54
				Story Nugget #54 resolves swinging the sword

Option Structure

	Unique ID
	Association [U = universal]  or the ID of the story nugget or people/things nugget that it is associated to 
	Condition Block : Conditional Code to evaluate - if true then display - if not true don't display
	Result: ID of story nugget to land on when the option is presented

Media

	Various pieces of media may be associated with elements in the game
	
Variables

	Variables exist in the game to help code blocks and conditional blocks be more sophisticated
	
	Users can declare variables in a section of the game.  Variables may be:
	
		True or False
		A number
		Text

	All variables are global to the story
	
	Users may embedd the value of a variable into any text displayed in the game by wrapping it between << >>.
	
Game Over State

	The game over state is invoked when you land on any Story Nugget  whose code block has the "GAME_OVER" command.
	
Code Blocks

	Code blocks contain incredibly simple "assembly" like syntax for code...
	
	by assembly I mean one simple command per line.
	
	There is no looping - a code block simply executes upon entry into the nugget and BEFORE the text of the nugget is displayed
	
	commands
	
		[variable name] =  set variable to value
			[variable name]  + - * /  = basic math applied to variable name
		play [media name] :: plays associated media - could have loop, amount,
		show [picture]	:: prominently show picture
		add [picture]	:: add picture to available to show but don't show
		take [item] :: if item/person is in inventory take it
		give (once) [item]  :: Add item to inventory if once is invoked don't add if already in invetory
		
		goto nugget [xx] used to auto forward to another nugget in the game which essentially renders the code block as just a code block and not a landing node
			must insure that the a code block can't be recursive
			
		no branching in a code block for now
		
		[WE will need a complete command list which is forthcoming]

				

XML Files

The entire game in its first pass form could be setup with XML files that mimic the DB structure we might use if we decide to create a database backed version.

The XML files would be:

[STORYNAME]_nuggets.XML 	:: Stores the flat database with all the story nugget records
[STORYNAME]_options.XML :: Stores the flat database with all the option records
[STORYNAME]_peoplethings.XML :: Stores the flat database with all the peoplething records
[STORYNAME]_conversations.XML :: Stores the flat database with all the conversation records
[STORYNAME]_media.XML :: Stores the flat database with all associated media in the game
[STORYNAME]_variables.XML :: Stores the name and type of variables in the game
[STORYNAME]_story.XML :: Core variables relevant to the loading and execution of the entire game