XML Scenes

This document describes the format of and scene XML files in the FFilmation Engine. A typical files looks like this:

<scene gridsize="50" levelsize="20" prerender="0">
<head>

      <definitions src="xml/definitions/western_gfx.xml"/>

      <definitions src="xml/definitions/poncho.xml"/>

      <light id="Global light" intensity="20"/>

</head>

<body>

      <floor src="Ground" width="1000" height="1000" x="0" y="0"/>

      <floor src="Ground" width="1000" height="1000" x="1000" y="0"/>

      <floor src="Ground" width="1000" height="1000" x="0" y="1000"/>

      <floor src="Ground" width="1000" height="1000" x="1000" y="1000"/>

      <wall src="Wood" x="200" y="200" size="400" height="220" direction="horizontal"/>

      <wall src="Wood" x="600" y="200" size="300" height="220" direction="vertical"/>

      <wall src="Wood_vdoor" x="600" y="500" size="100" height="220" direction="vertical"/>

      <wall src="Wood" x="600" y="600" size="300" height="220" direction="vertical"/>

      <wall src="Wood" x="600" y="900" size="400" height="80" direction="horizontal"/>

      <box id="Crate 1" x="300" y="100" z="0" sizex="200" sizey="100" sizez="100" src1="Crate" src2="Crate" src3="Crate" src4="Crate" src5="Crate"/>

      <box id="Crate 2" x="400" y="450" z="0" sizex="500" sizey="300" sizez="150" src1="Crate" src2="Crate" src3="Crate" src4="Crate" src5="Crate"/>

      <object id="Tree 1" definition="Tree" x="200" y="1300" z="0"/>

      <light id="L1" type="omni" x="1100" y="780" z="160" size="350" color="#00ff33" intensity="30" decay="70" bump="true"/>

      <light id="L2" type="omni" x="400" y="420" z="160" size="400" color="#00ffff" intensity="70" decay="50" bump="true"/>

      <character id="Poncho" definition="Poncho" x="50" y="50" z="0"/>

</body>

</scene>

SCENE

An scene contains two main nodes: HEAD and BODY. The HEAD node contains references to all resources, materials and object definitions used in the scene. The BODY node defines specific instances of these resources. Attributes for the SCENE tag are:

  • gridsize: size (in px) of the cells along the X and Y axis that form the grid to which all planes in the scene are snapped. Smaller values mean more accurate lighting calculations but increase memory usage and affect performance. Default size is 64px
  • levelsize: size ( in px ) of the cells along the Z axis. Also defaults to 64.
  • prerender: If true, light projections and visibility are precalculated at scene initialization instead of on-demand. For big scenes it is better to turn it off, whereas smaller ones will perform faster if enabled. If value is a Number, precalculations computed from 0 to that height. The default value of 0 means precalculations are done only for base floor cells. In a typical scene, where your character walks the floor, this is the best setting to have.

HEAD

The HEAD node contains references to all resources, materials and object definitions used in the scene.

DEFINITIONS

Paths to external XML definition files. Having the definitions in separate files allow different scenes to share object and material definitions.

LIGHT ( inside HEAD )

Global light. The global light defines the minimum amount of light an element will receive. If none is defined, unlighted elements will show 100% black. Parameters for the global light tag are:

  • id: use for id access from your classes.
  • intensity: 0 to 100.
  • color: any rgb in HTML format
  • bump: either true or false sets this light as bumpmap enabled

BODY

The BODY node defines specific instances of the loaded resources. Inside the BODY you can place floor cells, walls and objects. These are explained later. A base floor at Z = 0 is always created, wherever you place elements at Z = 0 or not. The position and sizes of your floors and walls will define the size of your scene. Elements will be enclosed in these dimensions. Positions outside won’t be accessible and won’t render properly.

FLOOR

This tag defines a floor cell. An scene can have unlimited floor cells of arbitrary sizes. You can make your floor cells as big or small as you want. Generally, bigger cells mean less calculations, unless those cells intersect with lots of walls. If you snap floors to your walls, trying not to have walls cross your floor cells but be inbetween them, the rendering engine will perform better. Remember that both position and size of the floor will be snapped to the scene’s grid. Parameters for the FLOOR tag are

  • id: use for id access from your classes
  • src: material Id
  • x,y,z: coordinates
  • width: width in pixels.
  • height: height in pixels.

WALL

This tag defines a wall. A level can have unlimited walls of arbitrary sizes. As with floors, you can have them as big or small as you need, but avoiding intersections is a good performance practice. Remember that both position and size of the wall will be snapped to the scene’s grid. Parameters for the WALL tag are

  • id: use for id access from your classes
  • src: material ID
  • x,y and z: coordinates
  • direction: “vertical” or “horizontal“. In both cases coordinates specify the top left corner of the wall
  • size: for vertical walls, this means the wall will extend along the Y axis, for horizontal ones, it will extend along the X axis.
  • height:height in pixels ( along Z axis ).

OBJECT

This TAG defines an Object, a solid sprite in the scene. By default, objects can’t be moved and this is useful for speeding up zSorting and lighting calculations. To create mobile objects ( people would be the most obvious example ) either use the dynamic attribute or use the “character” Tag. Both methods promote your element from the Object class to the Character class, and then it is able to move. Characters can be created dynamically at runtime, objects can’t. Attributes for this tag are:

  • id: So you can access it from your engine
  • definition: Definition id. Must match a definition in some of the definition XMLS included in the scene
  • x,y,z: Coordinates

BOX

This tag does not define a new element but it reduces the burden of creating complex scenes. In a typical environment you will use mainly rectangular shapes to define blocks, houses, crates, etc. A box is composed of 6 sides and you can define the 6 sides in one single tag. This TAG is decompiled into 4 wall TAGS and 2 FLOOR tags at runtime. The sides are enumerated this way. All sides are optional.

/|\1   /       \    2

/             \

/                   \

| \         5            \|

|    \                /   |

|       \          /      |

|          \    /         |

|            \|      3    |

|             |           |

\        4    |           |

\          |          /

\       |       /

\    |    /

\ | /      6

Parameters for the BOX tag are

  • id: use for id access from your classes
  • src1-6: material ID for this side (all sides are optional)
  • x,y and z: coordinates
  • sizex: size along X axis
  • sizey: size along Y axis
  • sizez: size along Z axis

LIGHT (Inside BODY)

A spot light of finite radius. Lights can be moved freely. They can be added and removed on the fly and its properties can be altered. Parameters for the light tag are:

  • id: use for id access from your classes.
  • intensity: 0 to 100.
  • color: any rgb in HTML format
  • size: The light’s reach. If none specified, the light is Infinite and never fades. The sun is a good example of Infinity lights.
  • decay: from 0 to 100. Distance from origin ( as percent of light radius ) at which the intensity starts to fade towards 0 this allows to setup harder or smoother lights. Decay doesn’t aplly to Infinite lights.
  • x,y,x: position. Unlike renderable elements, lights are allowed to be outside the grid. This helps simulate distant sources like the sun
  • bump: sets this light as bumpmap enabled.