Document
| Title : | Xnfo Specification |
| Project : | Xnfo (http://xnfo.sf.net) |
| Reference : | xnfo-spec |
| Version : | 0.03 |
| Date : | 19/02/2003 |
| Author(s) : | Sanx |
|
Changes
| Date | Version | Author | Description |
| 20/02/2003 |
0.04 |
Sanx |
Adding details on production specific tags |
| 19/02/2003 |
0.03 |
Sanx |
Restructuring pass for 1.1 pre-release |
| 09/02/2003 |
0.02 |
Sanx |
Evolutions since 1.0 standard and possible future evolutions |
| 09/01/2003 |
0.01 |
Sanx |
Initialization of the document |
|
Subject
This document explains information you can find in an Xnfo file, and how it should be interpreted.
Basics
XML formating rules
This is not a XML tutorial. Just have a look at http://www.w3schools.com/xml/ if you need a refresh. Basically you create a tree, inserting tags and text in tags, a tag.
<tag>
<othertag>text</othertag>
</tag>
There is also a concept of attributes :
<tag attribute="att">text</tag>
All tag and attributes are case sensitive, so it only uses lower case. There is no constrain about indenting or spacing. Tag or attribute name with space get a - (minus) replacing it. Tag or attribute that is an id, is gets an _id postfix.
Concepts
Fully available text
In Xnfo, you don't have to refer to external files, or databases, all the information have to be available in the file. So it doesn't only use ids or codes, but it also include the full text CDATA for all human readable information.
As email protection becomes important, the protection is simple, but should be enough, so you can write : toto(at)trash(dot)net, instead of :
toto@trash.net.
When you can have multiple elements (usually a array), it uses a tag that represents the list (example : <authors>), and an other tags for each element (example : <person> or <group>). Usually the list tag name is plural.
Enumerated types represent a selection in a predified list. Each enumerated type tag is presented in this form :
<enum type="selected_code">Selected Value</enum>
Applying the concept of having all text available, each enumerated type is composed of a text giving a human readable string, and an attribute called type refering to a finished set of information.
Except for custom enumerated types where the type attribute is only a string.
Plus, enumerated type is extensible, you can set a custom type attribute, plus any text you want.
Online database linking
For the moment 4 databases are supported :
- pouet.net : with the use of the
pouet_id attribute, you can reference demo, person or group, using ids you find on the links.
- ojuice.net : using
ojuice_id attribute links a person or a group. Ids can be also found on the urls.
- scenemusic.net : using
scenemusic_id attribut you can link a music. Id are also on urls.
- scene.org : Scene.org is using archive filename as reference, so you have to fill the
<archive>/<file> tag.
Tags
Root tags
This tag is the root of any xnfo document. It it what it makes you identify that it's an Xnfo document and not any XML file. Attributes are the following :
- standard (float) : version of xnfo standard format.
- version (uint) : version of this document. The greater, is the most recent. Increese by 1 each time you modify your xnfo, in order to
- author (email) : email address of the author of this document, it's obliged, dont forget email encoding.
- mode (enum : complete | partial) : the amount of information available.
Usually there should be 2 .xnfo file, one is partial that would be on the web. And the complete one would be in the archive.
Behavior of tools should be to ask if you want a newer version of an .xnfo file, and a complete version of it when you just have a partial one (but it may force to download the full archive).
This tag contains only one of the following tags :
It tells that the production described in the document is a demo (in a large meaning). Attributes are :
- pouet_id (uint) : the id of the production on pouet database.
The production described in the document is a graphic (2d, 3d, composite, ...), an image.
The production described in the document is a music (tracked, streamed, ...). Attributes are :
- scenemusic_id (uint) : the id of the production on scene music database.
The production described in the document is a video.
This tag means that this document contains results of a party. The filename of the xnfo containing this information should finish by .results.xnfo.
See Results specific tags for detailed information.
Generic production tags
name
The name or title of the production.
category
Category is a production specific enumerated type. It presents the category of the production in a more precise way than the root tag. An intro 64k is a demo, but has the category of intro 64k. For a complete list of category supported look at the enumerations list, in your production category.
release
The release information of the production, containing following tags :
- party (tag, string) : the party where it was released, if it was released at a party.
- date (tag, string : dd/mm/yyyy) : the date of the release.
- rank (tag, uint) : the rank of the production at the party competition.
A party name, with the following attributes :
- url : the url to the party website.
authors
The authors tag is a list type, it contains the name of the group or the people that participated to the demo. Any element of this list, can be a <person>, or a <group>. If a group is in this list, only the people that participated to the demo and that is not of this group, should be given.
For detailed credits, see the credits tag.
group
It defines a demoscene group by its name. Attributes are :
- pouet_id (uint) : the id of the group on pouet database.
- ojuice_id (uint) : the id of the group on orange juice database.
person
It defines a demoscener by its nickname (and optionally groups he belongs to). Attributes are :
- pouet_id (uint) : the id of the scener (as a user) on pouet database.
- ojuice_id (uint) : the id of the scener on orange juice database.
Credits tag is a list type that contains the information about what people did in the demo. Each element of this list, are tags named person, but it's different than the <person> tag upper. This one presents a description of the job done by a person (in CDATA), and contains the following attributes :
- name (string) : the name of the person that did the job.
- email (email) : the email of the person.
The people you want to greet. It's a list type that contains <person> and <group> elements.
It's a list type that contains <message> elements.
message
A simple text message.
- from (string) : the name of the person that tells the message.
- to (string) : the name or definition of the potential listener.
Common messages are those used in the <compo> section, addressed to the orgas (the party orgas), and audience (the people enjoying the party).
runs
It's list list type that contains <run> elements.
Run tag gives the command line (in large meaning) to run the production. It's more an entry point. Attributes are :
- platform (code) : the platform on witch the command is dedicated.
- config (string) : the name of the configuration, by default it should be default.
If you're running a demo it's allowed to specify a run command per platform, it's possible to do multiple configs exposing different command line arguments. If the production is a graphic it's the name of the image to watch. If it's a music it's the name of the music to play, ant the same goes for video.
The <run> command that is on the <compo> is the command to run for the party competition on the big screen, in order not to have the setup screen, and just the good settings set.
archive
It gives information about the archive, it contains the following tags :
- url (tag, url) : an url to the production archive.
- file (tag, filename) : the archive name.
The archive name given here will be used to retrieve the production from the internet, when you have only the xnfo.
An url to the latest version of the xnfo. It permits to automatically get an update of the production, as the version changes.
This tag is the root of competition specific information. This information permit to identify the production as an entry of a party competition.
It contains general tags like :
- category (tag) : this is a category of the competition it participates. This is not an exact category tag.
- messages (tag) : a list of messages, here you put
orgas and audience addressed messages.
- run (tag) : a unique tag that define the command that runs the production, see run.
But also competition specif tags, you can find :
The category you find in the compo section is different, it refers the category at the party, it may be a specific category. For example, a 2d graphic which fundamental category is 2d;24bits has the ability to participate at 2 competitions : nature, which is drawing a nature scene. or classic, which is the classic 2d graphics competition.
As you guessed, codes are not available in the specification so this is not a classic enumerated type, because the type attribute is also a string and not a enumerated type.
Production specific tags
Production specific tags only apply to a set of categories.
version
Applies to : demo
It identifies the version of the production, tags are :
- major (tag, uint) : Should always be 1, it's only increased when it's a completely different production (not a sequel).
- minor (tag, uint) : Increased when there is little change in the demo.
- build (tag, uint) : Increased on bugfixes.
- preview (tag, bool) : if it's only a preview of the demo.
remix-of
Applies to : demo, music
When a production is a remix of an existing production, you can link to it using this tag. Attributes are :
- pouet_id (uint) : the id of the original production on pouet database.
Tags are :
- url (tag, url) : the url to the xnfo of the original production.
- file (tag, filename) : the filename of the archive of the original production.
Applies to : demo
This is a list type. It present all the configurations supported by the production. Elements are <configuration>
configuration
Applies to : demo (through support)
It describes the configuration of the hardware and the software needed to run the production. Tags are :
soundtrack
Applies to : demo, video
The url to the soundtrack of this production. Attributes are :
- scenemusic_id (uint) : the id of the soundtrack on the scenemusic database.
screenshots
Applies to : demo, video
This is a list type. Each element of this list is a screenshots.
Applies to : demo, video (through screenshots)
A filename of a screenshot of the production, this screenshot must be in the archive. Attributes are :
- desc (string) : a short description of the image.
Recommended resolution is 400x300.
format
Applies to : music, video
The format or codec used the de production. It's an enumerated type, see the enumeration list for supported formats.
Competition production specific tags
These tag are competition related.
Applies to : graphic
A list type containing <step> elements.
Applies to : graphic
Presents a step of making the graphic, mostly apply to 2d graphics, or composite. It's a filename of an image that is in the archive. Attributes are :
- desc (string) : the description of the step.
Recommended resolution is 400x300.
Applies to : graphic
Presents the wireframe version of a 3d rendered image. It's a filename of an image that is in the archive. Recommended resolution is 400x300.
Applies to : music
When possible, artist can add a cover to his music. It's a filename of an image that is in the archive. Resolution should be a square, and using a power of 2 is highly suggested. For example : 256x256.
<results> contains the folling tags :
- party (tag) : the party which results are from.
- date (tag, dd/mm/yyyy) : the date of the end of the party (result announce).
compo (in results)
A competition of a party.
- category (tag, enum) : the category of the competion, a custom enumeration, see compo tag.
- entries (tag, list) : a list where each element is an
<entry>.
Category code should be the directory name (like on scene.org, with in64, ...)
entry
An entry of the competition
Attributes are :
- xnfo (filename) : the filename of the xnfo of the production.
- archive (filename) : the filename of the archive of the production.
Tags are :
- rank (tag, uint) : the rank of the production in the competition.
- points (tag, uint) : the points (with votes).
- name (tag, string) : the name of the production.
- notshown (tag, bool) : tells if this entry was shown.
- disqualified (tag, bool) : tells if this entry was disqualified.
- authors (tag, list) : the list of the authors of this production. These elements can be
<group> or <person>.
Demo category
| Code | Name |
| intro;128bytes | Intro 128 Bytes |
| intro;256bytes | Intro 256 Bytes |
| intro;1k | Intro 1 Kb |
| intro;4k | Intro 4 Kb |
| intro;64k | Intro 64 Kb |
| demo | Demo |
| cracktro | Cracktro |
| invitation | Invitation |
| custom | |
Graphic category
| Code | Name |
| 2d;8bits | 2d 8bits Graphic |
| 2d;24bits | 2d 24bits Graphic |
| 3d | 3d Graphic |
| composite | Composite |
| custom | |
Music category
| Code | Name |
| tracked | Tracked Music |
| tracked;4ch | 4 Channels Tracked Music |
| streamed | Streamed Music |
| custom | |
Platforms
| Code | Name |
| win32 | Windows |
| msdos | Ms-Dos |
| .net | .NET |
| java | Java |
| flash | Flash |
| linux | Linux |
| macosx | Mac OS X |
APIs
| Code | Name |
| direct3d | Direct 3d |
| opengl | Open GL |
| software | Software |
Music format
| Code | Name |
| mod | .mod |
| s3m | .s3m |
| xm | .xm |
| it | .it |
| dbm | .dbm |
| dmf | .dmf |
| rns | .rns |
| sid | .sid |
| mp3 | .mp3 |
| ogg | .ogg |
| custom | |
Video format
| Code | Name |
| mpeg | MPEG |
| divx | DivX |
| real | Real |
| mov | Quicktime |
| custom | |
What is it possible to add in the future (maybe even before final)
- Possible multi archive support.
- Change on cover, to be available outside compo.
- A change about the credits/person conflict.
- A complete database of categories and platforms.
- Direct 3d and OpenGL caps. So that people that don't have thoses caps won't download the demo for nothing.
- Link to recorded versions of demos (divx, etc).
- Multiple archives support : I don't feel its a good idea, it may provide more problems.
- Support for scener information / profiles.
What has been removed from preliminary version (1.0)
- Package : it has been removed because it's the job of the archive system
(zip or what ever) to handle integrity of the archive, and know if all files are in
restored correctly.
- MD5/CRC : it was used in package information, but it was doubled as seen previously
The only interesting way to use that was to make a whole archive CRC/MD5 digest, but
it could have caused troubles when scene.org adds its file in the archive.
This document belongs to xnfo project.