Here is an example of a simple storyboard that shows just one picture for 5 seconds. If you are not already familiar with sprites and animations, please consult the spr and air docs before continuing.
;----------------------------------------------------------
[Info]
localcoord = 640,480 ;This storyboard is made for a 640x480 size screen
[SceneDef]
spr = sprite.sff ;Filename of sprite file to use
[Scene 0]
; Layers
layerall.pos = 319,239 ;Default position for all layers
layer0.anim = 0 ;Anim action number to show
; Total time
end.time = 300 ;300 ticks = 5 seconds
;Animation to use
[Begin Action 0]
0,0, 0,0, -1
;----------------------------------------------------------
A storyboard must always contain a [SceneDef] group. Within this group you must specify the name of the sprite file to use. This sprite file must exist in the same directory as the storyboard file. The sprite file should contain all the sprites you need for your storyboard.
A storyboard is broken up into scenes. How you choose to divide up your storyboard is up to you. In the example above, there is only one scene, the [Scene 0] group. All scenes must begin with a group that looks like [Scene ?], where the question mark (?) can be any identifier string. Typically, scenes are labeled in numerical order starting from 0.
Scenes are composed of up to 10 animation objects. Each of these objects exists on its own layer, and the layers are overlaid on top of each other. Layers are numbered from 0 to 9, with 0 being at the bottom, and 9 at the top. For instance, an animation on layer 0 is underneath another on layer 1, and the animation on layer 1 is under that of layer 2, and so on. Each animation object must make reference to an animation action using a "layerX.anim" parameter, where X is the layer number. Each action must be defined within the same storyboard file.
The simple example above has only one layer. Its drawing position is determined by the value of the "layerall.pos" parameter, and the action number of the animation is the value of the "layer0.anim" parameter. In this case, the action number is 0. Action 0 is defined right after the [Scene 0] group.
One important parameter is "end.time". This is the time to end the scene, measured in ticks. One tick is equivalent to 1/60th of a second. When one scene ends, it goes on to show the next. If there are no more scenes, the storyboard playback ends. In the example, "end.time" is 300 ticks, which is the same as 5 seconds. Since there is only one scene, the storyboard ends at the same time.
The next example will show a slideshow of pictures, along with text overlaid on top. Again, this only has one scene.
;----------------------------------------------------------
[Info]
localcoord = 640,480 ;This storyboard is made for a 640x480 size screen
[SceneDef]
spr = sprite.sff ;Filename of sprite file to use
font0 = myfont.def ;Filename of a font file to use for the text
[Scene 0]
; Layers
layerall.pos = 319,239 ;Default position for all layers
layer0.anim = 0 ;Anim action number for slideshow pictures
layer1.text = "Hello" ;Text to show
layer1.font = 0 ;Use font0
; Total time
end.time = 600 ;600 ticks = 10 seconds
;Animation to use for pictures
[Begin Action 0]
0,0, 0,0, 120
0,1, 0,0, 120
0,2, 0,0, 120
0,3, 0,0, 120
0,4, 0,0, 120
;----------------------------------------------------------
Note that there are 2 layers now. Layer 0 is used for the slideshow of pictures, and layer 1 is used for the overlay title. If you imagine the slideshow to be pictures of your vacation trip, the title might be an image with text that reads, "My summer vacation".
The new "fadein.time" and "fadeout.time" parameters specify fade-in and fade-out times respectively, measured in ticks.
This third example shows multiple scenes, with screen fades between each scene. Additionally, it plays music and a sound effect.
;----------------------------------------------------------
[Info]
localcoord = 640,480
[SceneDef]
spr = sprite.sff
snd = sound.snd
[Scene 0]
; Fade parameters
fadein.time = 30 ;30 ticks (0.5 seconds) for fade-in
fadeout.time = 30 ;30 ticks for fade-out
; Layers
layerall.pos = 319,239
layer0.anim = 0
; Music
bgm = mysong.s3m ;Filename for music
; Total time
end.time = 120
;Animation to use for scene 0
[Begin Action 0]
0,0, 0,0, -1
[Scene 1]
; Fade parameters
fadein.time = 30 ;30 ticks (0.5 seconds) for fade-in
fadeout.time = 30 ;30 ticks for fade-out
; Layers
layerall.pos = 160,120
layer0.anim = 10
; Total time
end.time = 120
;Animation to use for scene 1
[Begin Action 10]
10,0, 0,0, -1
[Scene 2]
; Fade parameters
fadein.time = 30 ;30 ticks (0.5 seconds) for fade-in
fadeout.time = 30 ;30 ticks for fade-out
; Layers
layerall.pos = 160,120
layer0.anim = 20
; Sounds
sound0.value = 0,1 ;Plays sound 0,1
sound0.starttime = 60 ;Starts playing the sound 60 ticks after the start of the scene
; Total time
end.time = 120
;Animation to use for scene 2
[Begin Action 20]
20,0, 0,0, -1
;----------------------------------------------------------
There is a "bgm" parameter in the first scene. This plays back a music file "mysong.s3m" at the start of the scene, and that music will continue playing until the end of the storyboard. In this case, mysong.s3m should be placed in the same directory as the storyboard file.
For full details on the parameters for Scenes and SceneDefs, see the sections titled "SceneDef parameter reference" and "Scene parameter reference" below.
