Storyboard Scripting Commands

Each object declaration is followed by one or more commands. These tell the object do do something, called an event, such as move or change color. You can think of each command as affecting a variable (or set of variables) for that object; once a command is finished, the object keeps those values until another command changes it. Objects who don't have a particular type of command used will use the default value for that variable.

A command under an object declaration looks like:

_<event>,<easing>,<starttime>,<endtime>,<params...>

where:

• _ can be a space instead of an underscore.
• <event> is a letter/pair of letters, corresponding to one of the commands below.
• <easing> indicates if the command should "accelerate". Valid values are:
  • 0 - no easing
  • 1 - the changes happen fast at first, but then slow down toward the end
  • 2 - the changes happen slowly at first, but then speed up toward the end
• <starttime> and <endtime> are the starting and ending times of the command, respectively.
• <params...> vary between specific values for <event>. This is usually what values the variables should take on.

An object stays active until its last command (time-wise) is done. After that, it disappears. If you simply want an object to stay on-screen, without anything happening to it, staying at its default location, use a command that "changes" a value from its default to its default. See the Fade command's example below.

Fade (F) Command

Affects: The opacity of the object (how transparent it is).

Value definition: 0 to 1, with decimals accepted. 0 is invisible, 1 is fully visible.

Default value: 1

_F,<easing>,<starttime>,<endtime>,<start_opacity>,<end_opacity>

where:

• <start_opacity> is the value at starttime
• <end_opacity> is the value at endtime

For example, to fade an object in 1 second (starting at 1 second after the map starts), wait 2 seconds at half-transparency, and then fade out in 1 second, we would write something like:

Sprite,Pass,Centre,"Sample.png",320,240
_F,0,1000,2000,0,0.5
_F,0,4000,5000,0.5,0

If we want an object to just appear on screen and nothing to happen to it for 2 seconds, we could write:

Sprite,Pass,Centre,"Sample.png",320,240
_F,0,1000,3000,1,1

See the shorthand section for an explanation of how to shorten this last line to just:

_F,0,1000,3000,1

Move (M) Command

Affects: The location of the object in the play area.

Value definition: An (x,y) position, as specified above. Decimals are not allowed.

Default value: The default value <x>,<y>, as specified in the object's declaration.

_M,<easing>,<starttime>,<endtime>,<start_x>,<start_y>,<end_x>,<end_y>

where:

• <start_x>,<start_y> is the position at starttime
• <end_x>,<end_y> is the position at endtime

For example, to move an object across the screen from the top left to bottom right (assuming the image is less than 200 pixels wide, otherwise it will appear to pop in and pop out of existence at the endpoints):

Sprite,Pass,Centre,"Sample.png",320,240
_M,0,1500,6000,-100,-100,740,580

Move X (MX) Command

Like Move, but only changes X-coordinate. Y-coordinate stays the same. For example, to move an object from the left of the screen to the right:

Sprite,Pass,Centre,"Sample.png",320,240
_MX,0,1500,6000,-100,740

Move Y (MY) Command

Like Move, but only changes Y-coordinate. X-coordinate stays the same. For example, to move an object from the bottom of the screen to the top:

Sprite,Pass,Centre,"Sample.png",320,240
_MY,0,1500,6000,580,-100

Scale (S) Command

Affects: The size of the object relative to its original size (as it appears in its file). E.g., for a file that originally is 100x100, a scale factor of 2 will make the object take up 200x200 pixels. The scaling is affected by the object's origin (e.g., Centre, TopLeft)

Value definition: The multiplier of the object's original size, from 0 upward. Decimals allowed.

Default value: 1

_S,<easing>,<starttime>,<endtime>,<start_scale>,<end_scale>

where:

• <start_scale> is the scale factor at starttime
• <end_scale> is the scale factor at endtime

For example, to have an object "zoom" (e.g., a background) from nothing to five times its original size:

Sprite,Pass,Centre,"Sample.png",320,240
_S,0,36500,37000,0,5

Vector Scale (V) Command

This is the same as S, except X and Y scale separately.

_V,<easing>,<starttime>,<endtime>,<start_scale_x>,<start_scale_y>,<end_scale_x>,<end_scale_y>

For example, to have an object widen to two times its original size, but lose half of its vertical size:

Sprite,Pass,Centre,"Sample.png",320,240
_V,0,36500,37000,1,1,2,0.5

Rotate (R) Command

Affects: The amount an object is rotated from its original image, in radians, clockwise.

Value definition: Any real number; negative is anti-clockwise/counterclockwise rotation, positive is clockwise. Exceeding 2*pi either way will continue rotating as many times as you'd like.

Default value: 0

_R,<easing>,<starttime>,<endtime>,<start_rotate>,<end_rotate>

where:

• <start_rotate> is the scale factor at starttime
• <end_rotate> is the scale factor at endtime

For example, to have an object rotate from -45 degrees to +45 degrees (45 degrees = 0.785 radians):

Sprite,Pass,Centre,"Sample.png",320,240
_R,0,47210,47810,-0.785,0.785

Or to have an object spin counterclockwise four times (4 rotations = 8*pi radians = 25.133 radians):

Sprite,Pass,Centre,"Sample.png",320,240
_R,0,47210,47810,0,-25.133

Color / Colour (C) Command

Affects: The virtual light source color on the object. The colors of the pixels on the object are determined subtractively.

Value definition: A color triple, written in decimal. The first value is red (R), the second green (G), and the third blue (B). Each can vary from 0 to 255. (0,0,0) indicates black, (255,255,255) indicates white (original image). Transparency is not affected.

Default value: (255,255,255)

_C,<easing>,<starttime>,<endtime>,<start_r>,<start_g>,<start_b>,<end_r>,<end_g>,<end_b>

where:

• <start_r>,<start_g>,<start_b> is the color at starttime
• <end_r>,<end_g>,<end_b> is the scale factor at endtime

For example, to make an object appear as a shadow (entirely black) and fade into its actual color:

Sprite,Pass,Centre,"Sample.png",320,240
_C,0,58810,59810,0,0,0,255,255,255

To make something appear the color of Link's tunic from the original Legend of Zelda (00CC00 - yes, that's where the name of the... thing... from Twilight Princess comes from):

Sprite,Pass,Centre,"Sample.png",320,240
_C,0,58810,59810,0,CC,0

Parameter (P) Command

Unlike the other commands, which can be seen as setting endpoints along continually-tracked values, the Parameter command apply ONLY while they are active. E.g., you can't put a command from timestamps 1000 to 2000 and expect the value to apply at time 3000, even if the object's other commands aren't finished by that point.

_P,<easing>,<starttime>,<endtime>,<parameter>

where <parameter> is one of the following:

• "H" - flip the image horizontally (NOT the same as rotating the object 180 degrees, i.e., pi radians).
• "V" - flip the image vertically
• "A" - use additive-color blending instead of alpha-blending

For instance, to flip an object horizontally and vertically for two seconds before returning to normal:

Sprite,Pass,Centre,"Sample.png",320,240
_P,0,60000,62000,H
_P,0,60000,62000,V