Skip to content

Creating a SBURBML File

Jump to bottom Edit New page
ZackBleus edited this page Sep 9, 2012 · 52 revisions

SBURBML is an XML based markup for constructing walkabouts. Every walkabout is actually loaded from a SBURBML file, and every walkabout can, at any time, be exported to SBURBML. Loading this should restore exact state in most cases, except for the action queue.

Table of Contents

Anatomy of a SBURBML file 

 <sburb ...>

  <assets>
    <asset ...>...</asset>
    ...
    <asset ...>...</asset>
  </assets>
 
  <classes>
    <sprite ...>...</sprite>
    ...
    <sprite ...>...</sprite>
  </classes>
 
  <effects>
    <animation ...>...</animation>
    ...
    <animation ...>...</animation>
  </effects>
 
  <hud>
    <spritebutton ... />
    ...
    <spritebutton ... />
    <dialogsprite>
       <animation ...>...</animation>
       ...
       <animation ...>...</animation>
    </dialogsprite>
  </hud>
 
  <rooms>
    <room ...>...</room>
    ...
    <room ...>...</room>
  </rooms> 

 </sburb>

Sburb

The <sburb> tag is the root node of the document. All other tags should be internal to this one. It must contain the following attributes:

  • curRoom: what room the player will start in
  • char: what character the player will control
It may also contain the following attributes:
  • bgm: the audio asset to play on initialization
  • startAction: an action to trigger on initialization
  • id: a reference name for the state encoded (i.e. "level1")

Assets

The <assets> tag denotes that all assets will be declared here. It must contain the following attributes:

  • name: the unique name of the asset
  • type: the type of asset (elaborated below)

Type='graphic'

This specifies the asset to be some sort of image. The body of the tag should be the path of the image. Ideally, all images used should be .png files.

Example 

<asset name='bestSpriteSheet' type='graphic'>resources/someSpriteSheet.png</asset>

Type='audio'

This specifies the asset to be some sort of sound. The body of the tag should be a list of potential paths, separated by semicolons. For compatibility reasons there should be both an .mp3 and .ogg version of every audio track. Opera and Firefox do not support mp3, and IE and Safari do not support ogg. The first compatible path in the list will be used.

Example 

<asset name='bestSong' type='audio'>resources/someSong.mp3;resources/someSong.ogg</asset>

type='movie'

This specifies the asset is a SWF (Flash) movie. The body of the tag should be the path of the SWF.

Example 

<asset name='bestMovie' type='movie'>resources/someMovie.swf</asset>

type='path'

This specifies the asset as a polygonal path. It is used by rooms to define various regions as walkable. The body should be a series of points separated by semicolons, with x and y separated by commas.

Example (of a square path) 

<asset name='bestPath' type='path'>0,0;0,10;10,10;10,0</asset>

Classes

The <class> tag denotes a custom template class. A template class is an otherwise normal tag that will specify new default values, as well as default contents, for any tag of this type that uses this class.

Any tag can be templated, although templating only effects the contents of other templates if the other templates came afterwards.

Example 

<sprite class='awesomesprite' width='100' height='10'></sprite>

Any <sprite> tag that specifies the class='awesomeSprite' will get a width of 100 and height of 10 if it does not specify its own height and width values.

Effects

This tag denotes that all effects will be specified here. Effects are just animation tags.

Hud

The <hud> tag is where all "heads up display" elements are defined. This includes the top menu bar where the volume controls are help menu are present, along with the dialogue menu. The <hud> will contain <spritebutton> and <dialogsprites> tags.

Spritebutton

This tag denotes a sprite button will be specified here. A <spritebutton> requires the following attributes:

  • name: a unique name
  • x,y: the location of the top-left corner of the button
  • width,height: the colSize and rowSize of the sprite button
  • sheet: the graphic asset used by the sprite button
This tag may also contain an action tag, which will be performed on click.

Example 

  <spritebutton name='volumeButton' x='9' y='9' width='54' height='36' sheet='volumeControl'>
    <action command='toggleVolume'></action>
  </spritebutton>

Dialogsprites

This tag denotes that all dialog sprites will be specified here. <dialogsprites> are just animation tags.

Rooms

This tag denotes that all rooms will be specified here. A <room> tag requires these attributes:

  • name: a unique name
  • width, height: the visible dimensions of room, constraining the camera to [0,width] and [0,height]

Example 

  <room name='stairRoom' width='999' height='2259'>
    <paths>
      <Walkable path="stairRoomWalkable"/>
      <MotionPath path="stairRoomStairs1" xtox = '0.7' xtoy = '-0.7' ytox='0' ytoy = '1' dx='0' dy='0'/>
      <MotionPath path="stairRoomStairs2" xtox = '0.7' xtoy = '0.7' ytox='0' ytoy = '1' dx='0' dy='0'/>
      <MotionPath path="stairRoomStairs3" xtox = '0.7' xtoy = '0.7' ytox='0' ytoy = '1' dx='0' dy='0'/>
    </paths>
    <triggers>
      .....
    </triggers>
    <sprite class='teleporter' name='stairRoomTeleporter' x='666' y='450' >
      <action name='teleport' command='teleport'>baseRoom,400,400</action>
    </sprite>
    <character name='sollux' x='360' y='1950' sx='-33' sy='-78' sWidth='63' 
       sHeight='81' width='42' height='21' sheet='taSheet' state='walkFront' facing='Front'>
      <action name='talk' command='talk'>
         <args>@! blahblahblah</args>
      </action>
      <action name='change room' command='changeRoom'>
         <args>baseRoom,300,300</args>
      </action>
      <action name='swap' command='changeChar'>
         <args>sollux</args>
      </action>
    </character>
    <sprite name='stairRoomBG'>
      <animation name='image' sheet='stairRoomBG' rowSize='2259' colSize='999'/>
    </sprite>
   </room>

In addition to sprites tags and characters tags, the room tag also has the following nested tags:

Paths

This tag denotes all the paths used by the room. The three tags to specify a path are Walkable, Unwalkable and MotionPath.

For Walkable and Unwalkable, the only attribute is "path", which is the name of the path asset to be used.

For MotionPath there are the following additional required attributes:

  • xtox, xtoy: how much a sprite's x-speed will contribute to its resultant x and y speed
  • xtoy, ytoy: how much a sprite's y-speed will contribute to its resultant x and y speed
  • dx, dy: how much a sprite's x and y speed will change regardless

Examples 

 <Walkable path="stairRoomWalkable"/>
 <MotionPath path="stairRoomStairs1" xtox = '0.7' xtoy = '-0.7' ytox='0' ytoy = '1' dx='0' dy='0'/>

Triggers

This tag denotes that all triggers for this room will be specified here. Trigger tags specify events that will occur inside the room based on user actions, such as clicking.

Triggers may have the following optional attributes:

  • restart: whether the trigger should reset itself when satisfied (false if not specified)
  • detonate: whether the trigger should be removed when satisfied (false if not specified)
The body of a <trigger> must begin with the specific event to watch for (see the trigger page for information on this syntax). Nested in the <trigger> tag can be another <trigger> tag, to be checked if the parent is satisfied, and an action tag to perform if the parent is satisfied.

Example 

  <trigger>spriteProperty,char,y>800
     <action command='deltaSprite'>
       <args>char,0,-12</args>
       <action command='talk'>
          <args>@! There's nothing over here!</args>
       </action>
     </action>
  </trigger>

Sprite

This tag defines a sprite that will be placed in the parent room. Sprites require a unique "name" attribute, which specifies what they will be referred to.

Sprites can also have the following optional parameters:

  • class: the template class which controls the sprite
  • x,y: the absolute location of the sprite in the room (0,0 if not specified)
  • width,height: the dimensions of the hitbox of the sprite, centred at (x,y) (0,0 if not specified)
  • dx,dy: the location of the sprite's depthing point, relative to it's absolute location (0,0 if not specified)
  • depthing: the layer on which the sprite will be rendered; 0=background, 1=midground, 2=foreground (assumed 0 if not specified)
  • collidable: whether it will block the path of other sprites (assumed false if not specified)
  • state: the current animation the sprite is showing (the first one declared if not specified)
In addition, the body of a <sprite> contains action and animation tags. A <sprite> must have at least one <animation>.

Example 

  <sprite class='chest' width='80' height='30' depthing='1' collidable='true'>
    <animation name='closed' sheet='chestSheet' x='-70' y='-60' rowSize='84' colSize='123'/>
    <animation name='open' sheet='chestSheet' x='-70' y='-60' rowSize='84' colSize='123' 
       length='3'  loopNum='0' followUp='opened'/>
    <animation name='opened' sheet='chestSheet' x='-70' y='-60' rowSize='84' colSize='123' startPos='2'/>
  </sprite>

Character

This tag defines a character that will be placed in the parent room. All characters are a kind of <sprite> but with certain special behaviours that define them. All <characters> require a unique "name" attribute.

Characters can also have the following optional parameters:

  • x,y: the absolute location of the character in the room (0,0 if not specified)
  • width,height: the dimensions of the hitbox of the character, centred at (x,y) (0,0 if not specified)
  • sx,sy: the location of the characters's animations (0,0 if not specified)
  • sWidth,sHeight: the colSize and rowSize of the character's animations (0,0 if not specified)
  • sheet: the graphic asset to use for the character's animations
  • state: what animation to start the character in
  • facing: which direction the character is facing; Front, Back, Left, or Right (Front if not specified)
In addition, the body of a <character> contains action tags and animation tags. Characters implicitly have the 8 cardinal animations, which do not need to be specified.

Example 

 <character name='sollux' x='360' y='1950' sx='-33' sy='-78' sWidth='63' sHeight='81' width='42' height='21'
    	 sheet='taSheet' state='walkFront' facing='Front'>
   <action name='talk' command='talk'>@! blahblahblah</action>
 </character>

Action

This tag defines an action. When nested in a sprite tag, it will specify an action to be offered when the sprite interacts with its environment. An <action> requires a "command" attribute, which specifies what kind of action it is (see the action page for details). The actual command, be it dialogue text, or formatting must be surrounded by <args>. This helps ensure operability with Firefox.

In addition, an <action> tag may take the following optional attributes:

  • name: the name of the action to be displayed (blank if not specified)
  • sprite: the name of the character which can perform this action, null means any character can perform it (null if not specified)
  • noWait: perform this action regardless of the game state (false if not specified)
  • noDelay: if this action is chained after the current one (see below), perform it immediately, instead of on the next frame (false if not specified); currently implies noWait, regardless of noWait's value
  • times: the number of times to perform this action (1 if not specified)
  • soft: perform this action only if it would not interrupt anything (false if not specified)
  • silent: perform this action without logging it as the new current action (false if not specified). This also prevents it from being soft, using times, or chaining, it also makes it noWait. Some actions should not or cannot be silent.
The body of the <action> must first contain the actual action parameters (see the action page for details). In addition, the <action> tag may contain a nested <action> tag, which is called "chaining". A chained action will, unless otherwise specified, be performed on the next frame in which the player has control.

Example 

  <action name='startGame' command='talk'>
     <args>@! Let's do this!!!</args>
     <action command='playSong'>
       <args>karkatBGM, 6.7</args> 
     </action>
  </action>

Animation

This tag defines an animation. When nested in a sprite tag it will specify an animation that sprite can play.

An <animation> requires the following attributes:

  • sheet: the name of the graphic asset that is this animation's sprite sheet
An Animation may take the following optional attributes:
  • name: the unique name (with respect to its parent) by which the animation will be referred ("image" if not specified)
  • length: the number of unique frames in the animation (1 if not specified)
  • colSize, rowSize: the width and height respectively of a frame of the animation (sheet.width/length, sheet.height if not specified)
  • x,y: the location of the animation's top-left corner, relative to it's parent's location (0,0 if not specified)
  • startPos: the index the animation will start at on the sheet (0 if not specified)
  • frameInterval: the number of frames to display each unique frame for (1 if not specified, equivalent to 30fps)
  • loopNum: the number of times to loop this animation; -1 means loop forever, 0 play once, 1 play twice, etc (-1 if not specified)
  • followUp: the name of an animation to play if this animation has finished playing (none if not specified)

Example 

  <animation name='open' sheet='chestSheet' x='-70' y='-60'rowSize='84' colSize='123' length='3' loopNum='0' followUp='opened'/>
Add a custom footer
Add a custom sidebar
Clone this wiki locally