Resource description files

Standard XML declaration.

<?xml version="1.0" encoding="utf-8"?>

There’s nothing much to talk about here.  It’s a standard XML declaration:

The root XML node defines general attributes and namespaces used through importing.

<shx:resources version="9" compress="false" package="resources"
   xmlns:shx="http://mindless-labs.com/samhaxe"
   xmlns:img="http://mindless-labs.com/samhaxe/modules/Image"
   xmlns:font="http://mindless-labs.com/samhaxe/modules/Font">

Every resource description file has a root node called shx:resources.  Every XML node associated with SamHaXe (and not with some of its modules) uses the namespace shx.  Let’s see its available attrubtes first:

Besides the attributes there are two namespace decralations (except shx) in the root node: img and font.  You assign an import module to a namespace with a namespace declaration.  After that if SamHaXe encounters an XML node with namespace other than shx it’ll invoke the appropriate import module for that node.  The namespace URI reference and actual import module assignments are in SamHaXe’s configuration file called samhaxe.conf.xml.  See Configuration for more information.

An import module may support more than one module interface version.  If you need a specific version of a module you can specify it in the URI as an anchor.  For example:

<shx:resources version="9" compress="false" package="resources"
   xmlns:shx="http://mindless-labs.com/samhaxe"
   xmlns:img="http://mindless-labs.com/samhaxe/modules/Image"
   xmlns:font="http://mindless-labs.com/samhaxe/modules/Font#1.1">

Here you query version 1.1 of Font import module.  See Version numbers for more information.

Least but not last here is a list of standard import modules and their namespace URI:

Defines a new frame in the generated SWF file.

Why do we need frames anyway?  We only want to import images, sounds, fonts and other things and that’s it.  Well, it’s almost true.  But there’s an interesting feature called preloading which requires frames.

Suppose you have a web site with a flash animation embedded in it.  When someone opens your site in a web browser the browser detects that there’s a flash animation and passes the URL of the animation to flash player.  The flash player then starts downloading it but as soon as the first frame is loaded it starts playing the animation and executing AS3 code.  It won’t wait until every frame has loaded.  It has advantages and disadvantages.  If it’s a “traditional” flash animation then the animation can be jumpy on a slow internet connection becuase the download speed might be lower that required for a smooth animation.  On the other hand if you put only a few assets on the first frame you can display a message such as “Please wait...” and wait till the other assetes are loaded.  It’s much friendlier solution than to put everything on the first frame and have the user to watch an empty window while flash player is loading.

Now back to resource definitions.  In SamHaXe every asset resides on a frame.  It’s not a big surprise cosidering the design of SWF.  A frame can contain any number of assets (even zero).  You can define a new frame with the

<shx:frame>
  ...
</shx:frame>

XML tag pairs.  Frames are automatically numbered starting from 1 so assets imported between the first frame tags will reside on the first frame (important for preloading).

Imported resources of different kind.

Within frames you can import different kind of resources (assets) by specifying XML tags defined by import modules.  You reference an import module with it’s assigned namespace.  Let’s see an example from the above resource description file:

<img:image import="logo.png" class="Logo" />

Okay, what does it tell us?  The namespace is img which is assigned to the Image.hx import module.  This module defines the image XML tag which can be used to import a wide range of image file formats.  The attributes are:

There’s one more asset import on the first frame

<font:ttf import="simple.ttf" name="MinimalFont">
   <font:characters>
      <font:include range="a..z"/>
      <font:include range="A..Z"/>
      <font:include range="0..9"/>
      <font:include characters=" ,.:!?-()"/>
   </font:characters>
</font:ttf>

It imports the specified character images (glyphs) from simple.ttf with the name: MinimalFont.  We won’t go into details of ttf XML tag.  You can read the full documentation at Font.hx.

After flash player loads these two assets it starts executing AS3 code (it always resides on the first frame).  You can display the logo, and some simple message while the player is loading the remaining frames.