DataPack

This is a brief introduction to DataPacks.

The Quick And Dirty

A DataPack can be used for many things. Most importantly is that they are editable. The Whirled team is building tools that will enable all users to edit DataPacks, to create new levels for your games, or to change a remixable avatar. Not all of these tools are in place yet, but by using DataPacks now you can ensure that your creation can benefit from these future enhancements.

• Create a directory to hold the files you want in each DataPack. Let's say I call my directory "blackbird".
• In that directory create a text file called "_data.xml" (it has to be called that, it's the special name of the data file inside a DataPack).
• Edit _data.xml with a text editor:

<geshi lang=xml> <datapack>

<file name="level" info="Level image" type="Image" value="blackbird.png"/>

<file name="map" info="Level map: black pixels are road, white is blocked, shades of gray are 'muddy', they drive at their percent black" type="Image" value="blackbird_map.png"/>

<file name="intro" info="Intro movie to play" type="DisplayObject" value="blackbird_intro.swf"/>

<file name="outtro" info="Outgoing movie" type="DisplayObject" value="blackbird_outtro.swf"/>

</datapack> </geshi>

• Place the referenced files in the same directory: blackbird.png, blackbird_map.png, blackbird_intro.swf, blackbird_outtro.swf"
• Zip up all the files in that directory with any zip creator, making sure not to save any directory structure (the files should all be "flat" at the top) and with compression off (store only). For example on the unix command line I'd type "zip -0 blackbird_level.zip blackbird/*".

Because the bulk of the bytes (images and such) are already compressed, the fact that the overall datapack isn't compressed isn't such a big loss.

Common attributes

Both <file> and fields have a few shared attributes:

• name - The name of the file or data field.
• info - A String description of the field, shown to users when remixing.
• optional - Not required, but if optional="true" then the field can have no value, and will return null to your code.
• type - The type of the data or file field.
• value - The value of the file or data field, see below for more details.

Data Types

Data fields provide access to a small piece of data.

• type="String" - value is a String
• type="Number" (optional attributes: min and max.) - value is interpreted as a Number
• type="int" (optional attributes: min and max.) - value is interpreted as an int
• type="Choice" (required attribute: "choices", an Array of values) - the value is a duplicate of one of these elements
• type="Boolean" - value is "true" or "false"
• type="Color" - value is a uint representing a color
• type="Array" - value is a comma-separated array of Strings
• type="Point" - value is two Numbers separated by a comma (x,y)
• type="Rectangle" - value is four Numbers separated by a comma (x,y,width,height)

File Types

File fields provide access to files included in the DataPack. Note that the name of a file field is the convenient name with which you will look up the file. Multiple file fields can have the same filename as their value, and that file will only need to be included once.

• type="Image" - value is a filename, the file should be a gif, jpg, or png ONLY. (optional attributes: width and height to force a particular size, or maxWidth and/or maxHeight to restrict the size)
• type="DisplayObject" - same as Image, only swf files are also applicable. Note that with the move to flash 10, you cannot use DataPack's getContents() to get and reparent a SWF that is AVM1 (flash 8 or earlier, or just compiled to actionscript 1 or 2). To add a remixable swf to your display hierarchy safely, you'll want to use getLoaders() and add the Loader.
• type="XML" - the file contents will be returned as XML.
• type="Text" - the file contents will be returned as one large String.
• type="Blob" - the file may contain anything

Related Discussion Threads

• http://www.whirled.com/#groups-t_24755_0_147699