Common Navigation File

[alderaine]

I would propose that we take the XML file used for publishing books as a starting point (http://www.projectaon.org/data/en/xml/01fftd.xml) as this already contains a lot of the information needed for our purposes. Aon are more than happy for us to update the XML with any additional information we need, so I would make that the single store for all the output from the construction kit.

[alderaine]

Requirements Analysis for the Lone Wolf Construction Kit
========================================================

OVERVIEW
--------

Lone Wolf book readers are being produced for a number of platforms. In addition, graphs are being produced to track the routes through the books. Both of these need information about the requirements for navigating from section to section.

Lone Wolf books are published from an XML file. This contains a lot of the required navigation information, and can be updated to contain any new attributes needed.

Aon are looking to expand the core navigation in this way:

<choice idref="sect100" requires="random:0-3">...
<choice idref="sect200" requires="skill:sixth-sense">...
<choice idref="sect300" requires="item:sommerswerd">...

It will be necessary for the item reference (name) etc to be unique, but at the same time readable as it will be used in the graphs. (Two references could be considered if needed.)

CURRENT XML
-----------

The following information is readily available in the current XML:

* Class for numbered sections (<section class="numbered" id="numbered">)
* List of navigable sections (<choice idref="sect85">) (<link-text>turn to 276</link-text> )
* Pick a random number (<a idref="random">Random Number Table</a>)
* Illustrations (<instance class="html" src="ill1.gif" width="386" height="676" /> )
* Combat (<combat>) (<enemy>Kraan</enemy>) (</combat>)
* Enemy CS (<enemy-attribute class="combatskill">16</enemy-attribute>)
* Enemy END (<enemy-attribute class="endurance">24</enemy-attribute>)
* Attribute, when mentioned (<typ class="attribute">COMBAT SKILL</typ>)
* Next Book ( <bookref series="lw" book="02fotw">Fire on the Water</bookref> )


MISSING ELEMENTS
----------------

The following key elements are currently missing from the XML

* Items - any collectible item needs to be identified. It may be helpful to the reader to utilise this XML update to highlight items on the page
* navigation restrictions, as noted in the overview
* Death
* Attribute modifications
* Conditional Attribute Modofications (item/skill/etc)
* Significant combat detail, such as evasion, mindforce, mindshield, weapon restrictions / bonuses, etc
* Mandatory page turns
* You must eat a meal
* Hunting works / does not work
* Pages where you heal (can deduce from combat, but better to be explicit)
* Losing items
* Regaining lost items
* Trading items (swaps, buying/selling, storage, retrieval from storage)

These elements will cover the majority of the basic book functions. More will come along as books grow more complex!

[Dave]

That just about sums it all up.
There needs to be provision for multiple random number pickings. (Like the horse sinking in the swamp in book 1.)

Oh yeah, and random number modification, like "Add 2 to the number you picked if you have Hunting", etc.

[matthill]

Cool, excellent decision to use and expand the existing XML.

[jsager]

Senior developer here. Let me know if I can help move this along. I am quite conversant with XML, but it's hard to tell from reading this who's leading the charge for sure.

I can be reached at [e-mail]

[jsager]

ok, having looked over this for a moment or two, I have a couple of suggestions.

First of all, without having a common "items" list, this idea will never fly. Without a common way to reference items, section dependency will never work.

I see no reason not to have an items xml file that contains all known items. It would be easy enough to do:

<item type="special" name="Seal of Hammerdal" discardable="false" id="sealofhammerdal"/>

or

<item type="weapon" name="Sommerswerd" discardable="true" id="sommerswerd">
<modifier stat="combatskill" value="8"/>
</item>


You are going to have to expand the <choice> tag to have a <dependency> child (or children).

The dependency would have types, targets, and ranges.

For example
<dependency type="discipline" target="hunting"/>
<dependency type="item" target="sommerswerd"/> or <dependency type="combatrounds" target="combat01" range="2"/>
<dependency type="combatwon" target="combat01"/>
<dependency type="random" target="random01" range="4-7"/>
<dependency type="event" target="liteTorch"> (see below for the "event" idea)

The type would explain how to process it. For example, if the dependency was of type discipline, then it would be easy enough to examine the character sheet, etc. etc.

You will also need to create an <event> tag. This event tag would have various type attributes that would indicate what it does.

<event type="meal" id="mealevent01"><dependency type="discipline" target="hunting"/><dependency type="item" category="meal"/>
<onsuccess>
<inventory type="remove" category="meal"/>
</onsuccess>
<onfail>
<statchange type="endurance" value="-3" permanent="false" healingdisc="false">
</onfail>
</event>

<event type="unique" id="liteTorch">
<dependency type="item" id="torch"/>
<onsuccess>
<inventory type="remove" id="torch"/>
</onsuccess>
<onfail/>
</event>


Then your choice items have dependencies on event outcomes.

[jsager]

I messed up my meal event now that I think about it. I guess events would have to have "branches" and you go from there.

[alderaine]

You're all exactly along the right lines
I'm working very closely with Jon, who essentially owns the Aon XML, with an eye to the destination XML.
We will definitely need a separate items XML file, or a sub-set of it contained in the book XML (like the footnotes for example.)

I am progressing well with a toolkit based on the XML - it reads in the book XML and splits out the section text from the various options. I'm currently building in the elements to add the more complex page actions. Eventually I will have a set of tables which can be output in any format - CSV, XML, or anything else we need. Once this is complete, I'll be able to crank out the navigation files for all the books in no time at all in any format anybody could ever need!

What would be really useful is if anybody knows XML well enough to write an interpreter for the Aon XML, and a definitive XML Schema "rulebook" for our final destination.

[alderaine]

To answer Jeremy's post above, I co-ordinate developer support in general, but this is mostly about enabling individual developers to work on their projects with Aon resources.
The only "core" project we currently have is this Common Navigation File project. All other projects are owned by individual developers on individual platforms at present.
For the Common Navigation File project, and expert in XML would be very helpful - give me a shout for details

[jsager]

ok so if you're talking about an XML schema rulebook, by that I assume you mean an .XSD file? I can do that, it's not my strongest point but I've certainly done it enough times.

As far as the items are concerned, it cannot be done on a book-by-book basis.

There are plenty of checks in lonewolf books for items that are found in prior books, the most obvious being Crystal Star Pendant and Sommerswerd, but with a gazillion other examples I'm sure people could dredge up (chainmail waistcoats, potions, and anything else you can carry from book to book).

[jsager]

alderaine, if you need any help from me, please let know. My email is [e-mail]

I would be glad to assist with the design of the XML files and/or the creation of an XSD file.

[alderaine]

Well, we don't get to design the XML file - Aon owns them - but we can certainly make suggestions for the enhancements we need.
Take a look at the Aon XML (http://www.projectaon.org/data/en/xml/01fftd.xml) - First of all, we need a way to read that XML in order to extract the section text, links, and anything else useful you can get hold of in a machine-readable format.
Secondly, we need to suggest how to update that XML to contain the information we need to do all the book navigation etc, and to link it into the item XML (which we can design)

[jsager]

Isn't reading and parsing the XML the job of the programmer? I mean, going through it in say .NET (LINQ and others) would be totally different than Java (20 different options).

Did I misunderstand what you were shooting for there?

[alderaine]

I thought you were offering to program?
As long as we have a set of routines for converting the XML to a more friendly format and back again, it does not really matter how they are written - they can be transforms, DLLs, independant modules, anything you prefer
ALternatively, you could write an algorithm that shows how to extract the information from the existing XML that people could embed in their programs.
The existing XML is nested very deeply, so is quite hard to process by any simply means - I've taken a run through it (and have a rough interpreter) but I'm no XML expert so I know there are better ways out there.

[jsager]

I am open to the idea of offering help in different ways, but I had misunderstood.

In my mind, XML *is* the easy way to represent complex hierarchical data, and what I had been offering was a way to expand the XML schema such that all of the information needed to program a lone wolf reader application would be contained within the XML. At current, the XML (which I looked over) is insufficient to do the job.

Let's put that aside for a moment. What sort of better format did you have in mind?