Common Navigation File

[alderaine]

There are a number of different book reader projects on the go, all of which suffer from the time it takes to interpret each book.

If we can get together to establish a single file format for the navigation rules, which can then be used by all the readers, we will be able to divide up the work of book interpretation.

Please post any ideas here, and we'll try to come to a consensus.

To get the ball rolling, mine uses a simple CSV file for each book with a series of columns used to determine what type of rule it is, and all the parameters.

[Dave]

Mine uses a crazy system of "Effects" and "Conditions". Buttons can have "conditions" directly, which affect whether or not you can click them (such as "Does Lone Wolf Have Sixth Sense? Yes, they can click this- No, they can't).
Effects are things like : Turn to section xxx, Pick a random Number, lose xx EP
Effects also can have conditions, which come into play such as a button which does the following:
1. pick a random number.
2. modify the value by +2, but only if Lone Wolf has hunting(that's the condition).

combat modifiers also can have conditions. e.g. in the burrowcrawler fight, Lone wolf get a -3 CS, unless he has a Lit Torch.

My system works pretty well and is pretty versatile, but I do have to add the occasional effect and/or condition as I discover more and more complex gameplay features in progressive books.

How does your CSV deal with, for example, the section in book 1, section 21, where you must pick multiple random numbers, depending on the result of the 1st and subsequent picks?

[alderaine]

It assigns a sub-reference number to the page - 21a, 21b

[alderaine]

Dave - if you are currently writing a front-end for building your navigation file, I might propose that we use your format as a starting point - it seems pretty generic.

[fredc]

Mine is rather similar and uses a system of conditions and actions. It as based on an XML grammar. Something like:

<?xml version="1.0"?>
<data>
 <option type="trigger">
   <actions>
     <deactivate_link>1</deactivate_link>
   </actions>
 </option>

 <option type="trigger">
   <conditions>
     <has_item>vordakgem</has_item>
   </conditions>
   <actions>
     <activate_link>1</activate_link>
   </actions>
 </option>

</data>

This first action deactivates the first link by default. If you have a Vordak Gem, the link will be finally activated.

XML generates some overhead though. And from what I just read above, Dave's format might be more advanced than mine.

[Dave]

Okay, well let me lay down some specifics and we can see if my system is something we would like to generalize and apply to multiple projects, or whether I'm just a crazy noodle!
I also apologize in advance for not using advanced formatting in this post - I'm sure it would make it easier to read, but I've got too much to write to bother with it!

I will refer to the navigational things in my program as "buttons" (the things that have conditions and effects), but depending on your program, I'd assume they could be just as easily applied to another object type, but I'm going to call things buttons here. Also, this system is dependent on a system which continuously checks the conditions for buttons each rendered frame, so that if something changes(they eat a meal), then the buttons will change appropriately (now they can click "Turn to xxx"). The only time that conditions on effects are checked is when a button is clicked (when the effect(s) are called). Each button also has a unique numeric ID - I only load one section of section text at a time, so I always start the numbering with 0.

First, we need a list of what I'll call Condition Types and Effect Types.
For example, condition types would include:
Have Endurance
Have Item (specifc Item, like Vordak Gem)
Have Gold Crowns
Won Combat
Have Item Type (general Item type, like Backpack Item, Weapon-Like Special Item)
Have Discipline
etc.

Effect types would be things like these:
Gain Discipline (when selecting them)
Lose Endurance
Gain Endurance (could be combined with above for a general "Change Endurance")
Turn to Section
Gain Item (specific item)
Lose Item (and Lose Item Type)
Pick Random Number (changes the "value" of a button)
Fight

There must be certain variables associated with both conditions and effects, in order to provide for the specific requirements of section text, and have decent functionality.
In my program, each condition has the following variables: (Not all of them are used by each condition type, but sometimes they are all used)
Type: the type of condition (Have Endurance, Have Discipline, etc.)
Value: the value to check for (a number), which could represent different things depending on the condition type (e.g. each discipline would be a different numeric value, and each item would have a specific ID number)
Equation ( <, <=, =, >=, > ) This is the formula by which the value of the condition should be compared, for example a condition of Have Endurance could check for whether Lone Wolf has less than 20 EP, or could check whether Lone Wolf has ten or more EP, or even check whether Lone wolf's EP equals zero (for those odd times when losing a battle doesn't kill him.)
ID to check: could be the ID of another button whose value we should check. (e.g. to check results of a random number)
Singular (boolean): if this condition is met, its results will supercede any previous condition checks (meaning it can be overridden by subsequent singular condition checks as well - sounds convoluted, but is very useful for constructing some of the more complex conditions that Joe Dever puts in his section texts.)
Reverse (boolean): if the condition is met, give the opposite result. (for example, my "Fight" Buttons have a condition of "Won Combat", but reversed, so the player can click it unless they have won the combat already.)

So, an example of how a random number pick currently works in the program:
A button with the text "pick" (and ID of, say, 0), that has an initial value of -1.
It has a condition that states it can only be clicked as long as its value equals -1.
It has an effect, when clicked, that is the "Pick Random Number" effect.
During the "Random number" animation, the button is assigned the value of the result (0-9).
The player can no longer click this button, because its value is no longer -1.

Two choices at the end of the text might read :
"If you pick 0-5, turn to 319"
"If you pick 6-9, turn to 58"
I would set these up as two seperate buttons.
The first has an effect that is "Turn to Section", and it would go to 319.
The button has two conditions:
#1 Check Value of button ID 0. if it is >= 0, good.
#2 Check Value of button ID 0. if it is <= 5, good.
That way, if button 0 (our number picking button) get a result of 3, you can see that both of these conditions are met, and the "turn to 319" button is now clickable.

A similar set of conditions would be set on the second button, with appropriate numbers.

Effects, like conditions, also have a set of variables, to make the effects be specific.
Type: which type of effect it is. (Gain Item, Change Value, Lose Endurance, Fight, etc.)
Value: this is a number, which can be the section number to turn to, or how many endurance points to lose, or the item ID of an item to gain/lose, etc.
ID to affect: If we are changing the value of another button, this identifies which. It could also be used to mean different things for different types of effects.
String: this contains text, could be used to change the text of a button, or a tooltip, or could be used by the effect to specify some kind of internal action. This isn't used very often, but sometimes!
Value2: A second number that can be used by more complex or esoteric effects, if you need to specify more things than you can with the above.

Yes, complex, yet like a said, highly functional. And no, I don't write these things out by hand - that would take forever! I already have been using a GUI, which I used to do my first 3 books. Mostly just point and click. However, as I mentioned in my main thread, I'm doing some core code changes. And it has started with defining these over again. Which means I have to start over with book 1 when I'm done, but I've learned enough with my first 3 books, that I have learned what things could be automated, and what things I have to do by hand. It'll make redoing the books a lot faster, as well as all of the subsequent books.

So, that's the basic scoop of what I'm doing. I don't know if it will work for everyone, though. If not, alas. If so, cool - we would need to come up with a standard list of conditions and effects.

[alderaine]

As long as your GUI writes a parseable text file, each programmer could write an interpreter to convert that file to their format (or simply change their reader code in the program)
I was debating writing a rule generator, but ended up just using columns in Excel as being easier and more adaptable when I found I needed to change something.

[jens]

You can find my implementation as used by Hyena through:
www.collectingsmiles.com/wiki/index.php?title=Hyena_AudioGame_specifications

Flight From The Dark in this format look as:
www.projectaon.org/staff/jens/01fftd.gamebook

All the logic is written in LUA, which makes the format extremely flexible. On the other hand it only outputs data suitable for text/voice-only applications, so it won't be of much used for more specialized applications.

I agree that a format as suggested above would be very nice. I would still have to convert it to make it fluent in Hyena, but I don't see a way around that. If using a format as suggested, I would prefer to have it integrated into the original .html files. Perhaps even make it directly runnable using JavaScript and a plain browser?

[alderaine]

It sounds to me like Dave's is the most advanced in most ways:
* A construction kit is coming
* He has the most books
* He seems to support the most flexible functionality approach

I would propose that we wait for the construction kit, and have a look at the output - if this is suitable useable for converting to the other formats we use, it could be a winner - any thoughts?

Dave - let us know if we can help in any way! The down side to this approach is twofold:
1/ You would have to keep the updated source code available to Aon (which is part of the agreement for using Aon material anyway
2/ There would need to be some flexibility to incorporate facilities needed by other programs

Are you happy with these?

Many thanks

[Dave]

I'm fine with those constraints. I'm thinking that it will be best for all parties involved if we decide on a "Master List" of Conditions and Effects that would be universal across all of the programs, and that represent only the most commonly occuring things.
e.g. Under Effects:
Turn to Section (By far the most common)
Change Endurance Points

Under Conditions:
Have Discipline
Have Endurance Points

My biggest worry is that if we get into the "Give Item / Have Item" realm (which is also very common), then we will also need to share common Item definitions, and then it becomes a big old interrelated mess...
So, I'm just going to work on the changes I'm currently undertaking, and when I'm finished, we'll see whether it's going to work to adapt the system to other existing projects.

[alderaine]

I think it needs to cover everything eventually.
I found it necessary to create an item file, numbering each item and storing attributes against them (modifiers, type, etc) so we will probably need to standardise item references at some point.
You are right though - get together what works for you, then we can have a look and suggest improvements.

[matthill]

Hiya, I'm the new boy around here. I posted in the other message about how awesome Seventh Sense is so I thought I'd check out this thread.

Having a read through it seems like there's quite an advanced system in place for creating all the gameplay mechanics for each book used in Seventh Sense. But I'm a little puzzled about the format -- you say that it's currently in CSV?

Would it not be better as XML -- this is an open standard that I think should still give the flexibility required, but be easily readable by anybody else without needing to develop a new format. You get the benefit that once you've established the exact format of all the XML structures you'll need, you can publish it and other people could even help simply by handcoding these structures.

I guess there would be many: XML for choices, items, special instructions, etc -- all the things you've currently established Dave in your SS dat format.

As I mentioned before, I'm no expert on this, so forgive me if it's a dumb question.

[alderaine]

Seventh Sense uses its own format. My program (on hold) was using CSVs.
It is what I'm used to and was extremely easy to build using Excel when I was toying with the first book.
I agree that XML would be the best to go for, but I think we should let Dave run with his for now - unless you are offering to write an XML construction kit?
The idea is to remove all handcoding from anybody who helps with the basic navigation either way - they'd just use the construction kit & highlight non-standard sections.

[matthill]

alderaine said:

I agree that XML would be the best to go for, but I think we should let Dave run with his for now - unless you are offering to write an XML construction kit?

Oooh, goodness no, I wouldn't have a clue how to do that! It was more an observation that by using an already accepted open standard, anyone else can also use it without having to learn a proprietary format, that's all.

[alderaine]

As Dave is very busy at the moment, I'm aiming to pick up the toolkit again.
I'll start by writing a formal requirements document - this will allow us all to agree on content and format before coding begins. I will look at all the files/formats mentioned here. If you have any more to add, post here and I'll include it.
James.