Building A Scene

This document describes the main concepts involved in building interactive media in VixML. Once you are familiar with these concepts, you can find more detailed information on the VixML format in the Reference Guide.

Table of contents

• VixML Media Format
• VixML Scene Overview
  • Object Ordering
  • Scene "State"
  • Tutorial: Building a Ringing Bell
    • 1. Assemble the assets
    • 2. Creating the VixML: Organize the scene
    • 3. Adding Sound
    • 4. Triggering animation based on a shake event.
    • 5. Animate the bell
  • Coding Guidelines
    • Coding Conventions
    • Image/Sound Size and Quality
  • Interpreting Coordinates, Colors and Inputs
  • Metadata

VixML Media Format

VixML media is stored as a directory containing an index.xml file that describes a scene, as well as any resources the scene requires. The VixML media directory may have any directory structure, though it is a common convention to place resources into separate subdirectories such as "sounds", "music" and "images".

To create a new piece of VixML media, create a new directory with a basic index.xml file, and add any resources your scene will require.

VixML Scene Overview

A Scene is the root element of all VixML files. It is used to contain all elements and events associated with the animations. VixML scenes are built using a couple of simple elements:

1. Objects are elements that appear in the scene
2. Controllers are elements which control the motion and display parameters of objects.
3. Triggers respond to input events or scene changes by sending messages.
4. Messages are used to communicate that a change should occur in a scene, typically by activating a different controller for an object.

Of the items listed above, objects, controllers and triggers are all persistent elements in the scene which are encoded in the scene file. Messages are not persistent elements in a scene, but are instead generated during runtime when a trigger fires or in response to other events.

Objects may be hierarchically grouped together in groups of zero or more objects. Groups are themselves objects, and may be added to other groups. All properties of objects (such as location, rotation, scale and color) are interpreted as relative to their parent objects, so if a group moves, all of the objects inside of it also move. This is true down the entire object hierarchy such that an object's ultimate state is affected by all of its ancestors.

Groups are not only used for holding multiple objects–they are also used as separate logical units that can have their own triggers and controllers. Used in this way, it is not uncommon for a group to contain only a single object or to contain no objects at all. An example of this usage of groups is described in this VixML cookbook entry.

Each object may have any number of controllers and any number of triggers, though only one controller may be active at any time for an object. Affecting an object with more than one controller at a time can be accomplished by placing one of the controllers in a parent group (as described here). All triggers are always active for an object (unless they make use of optional "scene state" functionality, described here.

At the top-level, each scene must contain a single root object, which is typically a group (otherwise it would be impossible to include more than one object in the scene).



The above diagram is a representation of the scene. The labeled components are as follows:

1. The VixML scene object
2. The top-level group. There may be only one top-level object in a scene, so it's typically a group containing other objects.
3. Triggers, controllers and an object hierarchy (not detailed in this diagram).
4. Triggers, controllers and an object hierarchy (not detailed in this diagram).
5. A "leaf" object which contains no children (such as a sprite), but which does contain sets of controllers and triggers.
6. The active controller for the object. This controller determines how the object animates over time.
7. A message which is sent to the scene when a trigger fires. All objects and controllers in the scene will have the opportunity to observe the message.

Object Ordering

Objects are drawn in the order in which they appear in the scene, from top to bottom, such that objects which appear later in the scene are drawn on top of objects which appear earlier. Mouse clicks and other events give priority to the objects "in front" (i.e., those which appear later in the VixML definition).

Scene "State"

Complex scenes may include multiple modes of operation, or "states" and may require that certain events trigger different actions depending on this state. For example, a scene that has a "menu" state and a "gameplay" state may treat mouseclicks differently in each state. Scenes have a global "state" string which is used to indicate the current state of a scene, and triggers may specify an optional state to be active only when the scene is in the specified state.

States can be set using the statechange Steps of a sequencecontroller. If a trigger does not have a state string, then it is always active.

Tutorial: Building a Ringing Bell

To illustrate the base capabilities of VixML, let's animate a simple bell complete with motion and sound effects. For interaction, when the iPhone is shaken, we will trigger the bell to shake and play a ringing sound.

1. Assemble the assets

In order to assemble this animation, we'll need two assets: an image of the bell and a sound effect to play when the bell is shook. For the purpose of this example, these assets have been provided for you and are located under "Samples" >> "01 Bell" folder found in the VixML SDK bundle. They are called bell.png and jingle.wav.

2. Creating the VixML: Organize the scene

Let's start writing some VixML. We'll begin by creating a scene with the assets on stage. Within a text editor, add the following VixML code:

<?xm<x>l version="1.0" encoding="UTF-8"?>
<scene>
	<group>		
		<sprite image="bell.png" name="background" /> 
	</group>
</scene>

Save this file as index.xml within the same folder as your other assets.
Test that you have created this successfully by using the VxEngine to execute the index.xml file. Run the VxEngine and click "Open" and select the index.xml file. You should simply see an image of the bell displayed.

3. Adding Sound

All animations and sound effects within VixML are handled within a controller. Using your text editor, within the index.xml file, add the jingle.wav sound file using a sequence controller. The code should look similar to the following:

<?xm<x>l version="1.0" encoding="UTF-8"?>
<scene>
	<group>
		<sequencecontroller trigger="on<x>load">
			<sound file="jingle.wav" /> <!-- play a sound file -->
		</sequencecontroller> 		
 
		<sprite image="bell.png" name="background" />
	</group>
</scene>

Notice how the jingle.wav sound file will play when the scene is initially loaded because the "trigger" is set to "onload" (line 4). If you "Reload" the index.xml file within the VxEngine?, you should hear the sound play.

4. Triggering animation based on a shake event.

Let's change the bell to only play a sound when the iPhone is shaken. Within your index.xml file add a shake trigger to send out a shakemessage message when the iPhone is shaken. Then change your sequence controller to listen for the shakemessage instead of onload. When complete, the code should look similar to the following:

<?xm<x>l version="1.0" encoding="UTF-8"?>
<scene>
	<group>
		<!-- when we get a shake, send out the message "shakemessage" --> 
		<shaketrigger tolerance=".1" message="shakemessage" />
 
		<!-- when we get a shakemessage, play a sound --> 
		<sequencecontroller trigger="shakemessage"> 
			<sound file="jingle.wav" /> <!-- play a sound file -->
		</sequencecontroller> 
 
		<sprite image="bell.png" name="background" /> 
	</group>
</scene>

If you "Reload" the index.xml file within the VxEngine?, you can now press the "Shake" button at the bottom and that should play the sound file.

5. Animate the bell

Finally, we should animate the motion of the bell every time a user shakes their device. Within your index.xml file add various move steps within your sequence controller to rotate the bell image. When finished, your code should look like the following:

<?xm<x>l version="1.0" encoding="UTF-8"?>
<scene>
	<group>
		<!-- when we get a shake, send out the message "shakemessage" --> 
		<shaketrigger tolerance=".1" message="shakemessage" /> 
 
		<!-- when we get a shakemessage, animate the group back and forth and play a sound --> 
		<sequencecontroller trigger="shakemessage">
			<sound file="jingle.wav" />
			<move type="absolute" duration=".08" rotation="15" />
			<move type="absolute" duration=".08" rotation="-15" />
			<move type="absolute" duration=".08" rotation="10" />
			<move type="absolute" duration=".08" rotation="-10" />
			<move type="absolute" duration=".08" rotation="0" />
		</sequencecontroller> 
 
		<sprite image="bell.png" name="background" /> 
 
	</group>
</scene>

Within the VxEngine?, if you "Reload" the index.xml file you should see the bell animate and play a sound every time you press the "Shake" button at the bottom.

Coding Guidelines

Coding Conventions

Give every tag a descriptive name–all VixML tags accept name attributes. While these names are not widely used within VixML at the moment, it is still important to give descriptive names to all objects.

• Names are used in the VixML simulator debugging console.
• Names are used in the VixML simulator scene info hierarchy.
• Name attributes useful for external editing and XML processing tools.
• Names will be used in future VixML releases for object-to-object communication and other features.

Image/Sound Size and Quality

Targeting virtual goods to mobile devices presents a number of challenges when compared to content development on the desktop or the web:

• limited bandwidth
• limited CPU resources
• limited graphics card resources
• limited memory

In order to ensure that virtual goods run efficiently on mobile devices, the following guidelines should be followed:

• Use square power-of-two textures (e.g. 128x128, 256x256) whenever possible.
• Dynamic image scaling quality is quite good, so 256x256 images can be scaled up to fullscreen without major visual impact.
• Split animations up into multiple reusable components if this allows.
• Use animation controllers when possible to animate elements, instead of animated image frames.

Size limits and guidelines for deploying content on the iPhone.

• Maximum total VixML media size: 1000k (target size: 500k)
• Maximum still image size: 480x320
• Maximum animation size: 256
• Maximum animation frames at 256x256: 16
• Maximum animation frames at 128x128: 64
• Maximum animation frames at 64x64: 256

Interpreting Coordinates, Colors and Inputs

The default coordinate system is a 2D orthographic view centered at (0,0) and with the same width and height as the device. The "up" direction is represented by a positive vector on the Y-axis. On the iPhone, when in the portrait orientation, this means the size is 480x320 and that the coordinate at the lower left corner of the window is (-240,-160).

Colors are represented as a vector of 3 floating point values from 0.0 to 1.0 which represent intensity of the color channels red, green and blue respectively. The alpha value is also a floating point value from 0.0 to 1.0, but is encoded separately from the color vector.

Input values:

• Mouse coordinates are in real screen pixel values, with the center of the screen at (0,0).
• Microphone level input is a float normalized to the range 0.0 to 1.0.
• Accelerometer raw inputs are composed of three float values with each element ranging from -1.0 to 1.0.
• Accelerometer angles are composed of three float values with each element ranging from -pi to pi.

Metadata

In addition to the VixML content, scene files may also contain metadata tags at the start of any scene. These metadata tags contain information which is generally not used by the scene directly, but which may be interpreted by the specific player application. For example, the TrueFlirt application may expect scenes to contain flirtback data in the metadata section.

---