Common Navigation File

[outspaced]

FYI: Are you aware of the implementation of the <typ> tags in the Freeway Warrior XML files?

For example:

<typ class="item">Binoculars</typ>

FW uses a much simpler item record system than LW or GS, but it's potentially a start.

[Dave]

One of the problems we must deal with is items with identical names. This happens in the first 2 books. One "Silver Key" is a Special Item, and the other "Silver Key" is a Backpack Item. This necessitates some other way of identifying items than by name. I don't know how many times this situation arises in the whole course of the 20 books, but it happens.

[beowuuf]

Is attaching the book of origin too much as a designator?

[jsager]

We should utilize part of the concept of the surrogate key in relational databases here:

en.wikipedia.org/wiki/Surrogate_key

Basically, what I mean by that is:

Each item in the game should have its own unique id that bears no relation to the item itself or any of its properties. Any properties of the item, such as a name, a class (i.e. "weapon"), where it is carried on the action chart, and so on are stored in separate fields.

An example would be that your first silver key might look like this:

<item id="329473" name="Silver Key" location="special"/>

and the second

<item id="428324" name="Silver Key" location="backpack"/>

Surrogate keys/ids have a ton of business sense to them in that they provide a way to uniquely identify an object even in the absence of any other distinguishing factor.

Then, and this is just me hodgepodging something together, but if we're using my <dependency> tags, we would have something like this:

<choice text="Blah blah turn to page XXX">
<dependency type="item" target="428324"/>
</choice>

Now, there is no question whatsoever as to which Silver Key we're talking about.

[jsager]

And again, we must remember that the item.xml must be available to all books... to pull a random example out of my head, in Shadow on the Sand it asks if you have a Crystal Star Pendant, and Kalte Firesphere comes up throughout the books, and of course let's not forget the Sommerswerd.

[jsager]

Having thought about this a little further, it raises an interesting idea... we should map out the Lone Wolf character sheet in XML as well.

Why? Because let's say that I just might be considering writing a lone wolf reader for the iPhone (or whatever mobile), and Dave's got his 7th sense program.

Then, let's say Joe Blow is playing his book on his desktop computer using 7th sense, and he's got to go on a trip but wants to keep playing, he could hit the "export character" function, have his action chart and game location export in a universal format, then upload it to the mobile phone site, and keep playing on his Blackberry.

[jsager]

Also, lacerated, I don't want to get into a long discussion about the merits of various programming languages, but let's just say I'm not a fan of perl when compared to compiled OO languages, but more than anything else I am expert in Java, and pretty good in C#.

If I was going to do something in perl, there would be a learning curve involved and I'd have to see a really shiny benefit for me to take that on.

But more important than any of that... I still don't understand what this interpreter is supposed to bloody do. Alderaine mentioned having stuff in a universal machine friendly format, but that's exactly what XML is in the first place so I'm just completely confused on that front. XML is a programming language agnostic way to store hierarchical data, which is pretty perfect for what we have going on here. The only potentially better format is "relational database" but that could some potential hobbyist developers out of the water, and really it opens up a whole can of worms... I think using an RDBMS for this is overkill.

The Aon XML as it stands is insufficient for a game interpreter, but what that basically means is that the XML needs to be upgraded, not that we need to pump stuff out in some other format altogether.

However, it's possible that I am missing the forest for the trees, and there is a goal that confuses me.

[alderaine]

ok lets get back to the point
Lets try to avoid discussions over which language is best. It really does not matter what language is used for the various programs as long as the algorithms are well specified so they can be re-used.
The reason we need some form of XML parser, or advice on how to parse it, is that very few people here are fluent in XML, and the Aon XML is rather complex! Having some kind of module, algorithm, etc to parse that and present the information in a more readable format would be extremely helpful.

To items tags - both methods work. An item name is specific to a book, so stating the book is sufficient. Having said that, item numbers are even more unique. I would personally start at 1 (or 0001) and increment from there. In theory though you could also kill two birds with one stone (while confusing everybody) by combining the item type into the item number (i.e. backpack items start 10001, special items start 20001, etc)
There are some cases where a certain name of potion, for example, may have different properties depending where it is found, so item numbers can be used to tie this down explicitly.

I'm not quite sure what you mean by an XML character sheet - I think that's one you will have to show us when it is finished.

PROJECT GOALS (in order of importance)

1/ Produce navigation files for all books (format unimportant as long as all the information is there)
2/ In order to achieve #1, write a toolkit
3/ Update the Aon XML to include all the information from the navigation files
Point 3 implies that the navigation files & toolkit should work from the existing XML so we do not back ourselves into a corner...

4/ Provide support for developers in reading the Aon XML. This may involve simplifying it, publishing some guidelines, or simply writing a conversion module.

Eventually, we might like to extend support to a variety of specific languages, but that is entirely unimportant at the moment I think so languages used now do not matter

There is no current project for a formal "Aon" book reader, as it seems better to support the variety of developers working on different platforms to get all the books out as fast as possible.

[alderaine]

jsager - I know everybody hates hearing this, but we need to relax a little!
This is a fun project. I am here to support developers, not to tell them what to do!
I have an awareness of the variety of projects out there (many of which are not yet listed on the boards due to being in early stages) and their needs.
Each developer tends to give priority to writing their own reader. Quite naturally, this is somewhat of a one-man thing so the only way other developers can help is to fill in the holes.
The one problem EVERY developer hits is how to navigate through the books using their readers and automating all the character sheet stuff - this is where the CNF project comes in.
It is entirely up to each individual if they would like to work on the CNF project (although only about 2 or 3 people really can at once) or to carry on with their own readers & ideas.

You made the argument yourself earlier as to why XML is not as easy a solution as it sounds - just as you have a learning curve for Perl, I have a learning curve for XML (along with most of the other programmers here!) I can read XML myself, and I can read simple XML in programs, but the AON XML gave me so many headaches that I reverted to text manipulation (which actually works really well!) This means we definitely need support for reading the XML - this can be in the form of guidelines, or some kind of toolkit.

No format is particularly better than any other for this project (well, OK, there are some very bad formats, and XML is definitely the right place to store the information, but every reader at the moment uses a completely different format and works just fine.)
A full-blown RDMS is definitely overboard, and would severely limit the portability of the files.
A flat file or CSV file format REPRESENTING an RDMS, however, works just fine. By this, I mean you have ITEMS.CSV which consists of a list of item numbers (1..n) item name, item type (backpack/special/weapon/gold/food/etc) and item attributes (depending on the type)
In the BOOKn.CSV items are simply referred to by number - voila, a very simple relational database without all the headaches of a supporting engine, and absolute full portability!

I absolutely acknowledge that this is no better than XML in terms of storing the content and portability, but anybody who does not know XML is likely to know how to use flat/csv files.

XML has one point that is both an advantage and a disadvantage. In CSV, an attribute is determined by its position in the file - this means the program simply looks at the postion and knows it will always be there for a particular record type.
XML names its attributes, meaning (from my limited XML knowledge) that you have to trace your way down the node tree looking for each attribute by name. This makes it one heck of a lot easier for humans to read, but with my limited XML programming one heck of a lot harder to code for!
If XML were perfect, there would be no need for transforms...

I probably know way too little about XML to be making this kind of argument, but thats not the point of this note - the point is to try to help the two "sides" of this discussion to understand each other, and point out why some help is needed in reading the XML.

We will definitely be storing all the navigation information in the XML (eventually) - Aon is 100% behind us on that, so we have a single point of reference - but we need to make sure that all programmers on all platforms and all languages can work with this information, even if they know no XML at all. Publishing a set of "simple" algorithms is one way to do this, publishing alternate file formats is another. I'm open to suggestions!

[alderaine]

Hi Outspaced

The items <typ> tag in FW is extremely useful for producing a list of items in the book, but unfortunately is nowhere near precise enough for any detailed use. Item names include things such as "6 rounds of .... ammunition" or "two knives" - what we really need is something along the lines suggested above:

id=00001, name="xxxxxx", type="backpack", quantity=2

Type (and name for that matter) are optional, but will help skim-reading. my only concern with them is that this kind of duplication can lead to problems - but as long as it is all automated, it should be fine.

[Doomy]

This thread wins the Kyle Reese Memorial Award for incomprehensible tech stuff.

[alderaine]

Well I don't know Kyle Reese, but it certainly is a technical thread I'm trying to keep the technical stuff here rather than leaking to the reader-specific threads too much

If you're not involved in the programming side, the Common Navigation Files are probably not of huge interest - they are the glue that sticks the book readers together

[Doomy]

Noted. I'll stop hijacking this thread now.

[jsager]

Hey Alderaine -

A couple thoughts:

1) Kyle Reese was the guy from Terminator who died after knocking up Sarah Connor.

2) Written text can be given incorrect emotional weight. I'm totally relaxed. My confusion was more of an 'arg, I'm confused' rather than an )%(*#)(*%#@ ARRRRRRRRGH DIE

3) Walking the nodes of an XML file is "oldschool" and modern programming languages have moved way beyond it.

Take a look at XPath and XQuery... again the language specific implementation is going to vary, but these days there are industrial strength XML Querying tools designed to simplify the lives of developers in every language worth its salt.

Here's an example of the *entirety* of the code I wrote to hunt down a specific node in an XML file and apply all of its properties to variables:

//Use LINQ XML to parse XML string and apply values to PhoneCall and its subcomponents.

XDocument xdoc = XDocument.Parse(xml);

//Grab information from the CallIDData element
var datas = from callIDData in xdoc.Descendants("CallIDData")
select new
{
CallID = callIDData.Element("CallID").Value,
AccountID = callIDData.Element("AccountID").Value,
CampaignId = callIDData.Element("CampaignId").Value,
AdSource = callIDData.Element("AdSource").Value
};


And, it's also possible to use "where" stuff with that so that you can specify, for example, "where sectionid equals 184" or "where itemid equals event.target"


4) I would be happy to write out a formatter for some specific implementation someone needs down the road, but let's cross that bridge when the time comes.


5) An interesting idea would be to write a back end "web service" project without a front end that provided all the functionality of Lone Wolf without being tied to a specific reader. I will have to think on that...

[outspaced]

Jun 27, 2008 11:32:49 GMT alderaine said:

The items <typ> tag in FW is extremely useful for producing a list of items in the book, but unfortunately is nowhere near precise enough for any detailed use. Item names include things such as "6 rounds of .... ammunition" or "two knives" - what we really need is something along the lines suggested above:

id=00001, name="xxxxxx", type="backpack", quantity=2

Type (and name for that matter) are optional, but will help skim-reading. my only concern with them is that this kind of duplication can lead to problems - but as long as it is all automated, it should be fine.

Ah, I see what you mean. I didn't implement the <typ> tags in the FW XML, I just noticed it while doing some editing, and I thought I'd point it out in case anyone was having to "reinvent the wheel". Its implementation does currently leave a little to be desired, though.

Oh, in case anyone's missed it, the best reason to use the source xml as the basis for any reader is that fixing such things as spelling mistakes or incorrect "turn to" links wouldn't affect the software parsing it.

Current software requires a complete re-download of an entire book .ZIP file each and every time a new version is released, even if it's just for a couple of fixed spelling mistakes; it also required re-downloading the image files every time, which seems redundant. This can be avoided if only the XML needs to be downloaded each time it is updated; in fact, it could mean the software readers are more up-to-date than the released versions!