added comment about SHOWFRAME code alternative.
[swftools.git] / doc / fileformat.sc
1 # ===========================================================================
2 #
3 # swfc(1) File format specification
4 #
5 # Warning: not all of this is actually implemented yet- if there's a
6 # "TODO" behind a command, it has yet to be integrated into swfc.
7 #
8 # ===========================================================================
9
10 # File header
11 # -----------
12
13 .flash bbox=200x200 version=6 fps=50 name="spec.swf" compress
14
15 # bbox=200x200         : set bounding box to 200x200
16 # bbox=200x200:100:100 : set bounding box to (100,100)-(300,300)
17 # bbox=autocrop        : (default) - make bbox just big enough so that nothing ever get's clipped
18 #
19 # all coordinates are in pixels, not in twips. fixed point values like 1.25, 333.40 are allowed.
20 #
21 # version=6    : generate flash mx movie
22 # fps=50       : set framerate to 50 frames/second
23 # name="..."   : save result to spec.flash. (Default: input file with extension 
24 #                                          changed to .flash, or the value of the -o command line 
25 #                                          parameter if given)
26
27 # inherit swf movies:
28 # ---------------------
29
30 .swf mymovie1 "choo1.swf"
31 .swf mymovie2 filename="choo1.swf" # long form
32 .swf mymovie3 filename=choo1.swf # long form, without quotes
33 .swf mymovie4 choo1.swf # short form, without quotes
34
35 # Notice: An embedded animation can't have a different framerate than
36 # the frame rate from the surrounding animation.
37
38 #TODO: Those files currently come from the current directory- they should come from the script directory.
39
40 # load an image:
41 # --------------
42
43 .jpeg background "panorama.jpg"
44 .jpeg background2 "panorama.jpg" quality=30% #reduces jpeg quality
45
46 .png background3 "choochoo.png" #TODO
47
48 # (you can put this directly (generating a shape), or insert it into a shape via the fill= argument
49
50 # define a texture from an image:
51 # -------------------------------
52
53 .texture text1=background scale=50% rotate=45
54
55 # define a gradient
56 # -----------------
57
58 .gradient mygradient:
59     0% red
60     50% green
61     75% aquamarine
62     100% #ffffff
63 .end
64
65 # Create simple objects:
66 # ----------------------
67
68 .box mybox1 width=100 height=50 color=black fill=none #unfilled rectangle (just the lines)
69 .box mybox2 width=100 height=50 color=black           #same as above
70 .box mybox3 width=100 height=50 color=black fill      #filled black rectangle
71 .box mybox4 width=100 height=50 color=red line=2 fill=blue #blue rectangle with red edges
72 .box mybox5 width=100 height=50 color=red line=2 fill=background #part the background image, with red edges
73
74 .circle mycircle1 r=50 color=#aa33ff fill=mygradient # filled with gradient (defined above)
75
76 # Sounds:
77 # -------
78
79 .sound sound1 "LocoStart.wav"
80
81 .frame 16
82     .play sound1 loop=1 #other arguments supported: nomultiple (don't start if already playing)
83 .frame 55
84     .stop sound1
85
86 .frame 66
87     # this starts a synchronized soundtrack at this frame position. The command
88     # expects a filename, not a sound object, as it would be duplicating the
89     # sound object otherwise, and I'd rather have that done explicitly.
90     .soundtrack "LocoStart.wav" # TODO
91
92 # Elements of the movie should be animated by various means 
93 # moving (x,y and zoom) 
94 # ---------------------
95
96 .box obj1 width=200.0 height=100.0
97
98 .frame 100
99     .put obj1 x=0 y=0 #object starts at (0,0)
100
101 .frame 140
102     .change obj1 x+=100 y=0 scale=120% # smoothly move obj1 100 pixels to the right over 40 frames,
103                                        # scaling it to 120% of it's original size
104 .frame 170
105     .jump obj1 x=200 y=200 # make object to suddenly change to 200,200 at frame 70.
106
107 .frame 190
108     .qchange obj1 x=300 y=200 # TODO # make obj1 move towards 300,200...
109 .frame 210
110     .qchange obj1 x=300 y=300 # TODO # ... and then smoothly over to 300,300 using bspline interpolation
111
112 #.frame 220   #TODO
113 #    .jump obj1 x=reset y=reset
114
115 .frame 230
116     .del obj1   #Remove object again
117
118 # morphing
119 # --------
120
121 .morphshape morphthing start="start.fig" end="end.fig" #TODO
122 .frame 250
123     .put morphthing ratio=0%
124 .frame 270
125     .change morphthing ratio=100%
126
127 # interpolation between crude manual animation frames
128 # ---------------------------------------------------
129
130 .circle ball r=50 color=blue fill=violet
131
132 # now draw two balls, which fly around each other.
133
134 .frame 300
135 .put myball1=ball x=0 y=100 blue=0
136 .put myball2=ball x=100 y=100 red=0
137
138 .frame 310
139 # the .qchange means, "interpolate to this position and frame, using quadratic splines".
140          .qchange myball1 x=50 y=0 #TODO
141          .qchange myball2 x=50 y=100 #TODO
142
143 .frame 320
144 # We could also use coordinates relative to start position: .change myball1 x+=100 y+=0
145          .qchange myball1 x=100 y=100 #TODO
146          .qchange myball2 x=0 y=100 #TODO
147
148 .frame 330
149          .qchange myball1 x=50 y=100 #TODO
150          .qchange myball2 x=50 y=0 #TODO
151  
152 .frame 340
153 # Hmmm. This frame is the same as frame 0. How to prevent duplicating that one?
154          .qchange myball1 x=0 y=100 #TODO
155          .qchange myball2 x=100 y=100 #TODO
156
157 # color transforms (fading)
158 # -------------------------
159
160 # .put, .change, .qchange, .jump all support params which result in color transform.
161 # Everything up to the + is multiplicated, the rest summed.
162
163 .put obj1 blue=50% #(scale blue color component to 50%)
164 .change obj1 blue=128 #(same as above)
165 .change obj1 red=+25% #(shift blue color component by 25%)
166 .change obj1 red=+64 #(same as above)
167 .change obj1 green=50%+50% #(scale green color component to 50% and then shift it by 50%)
168 .change obj1 green=128+128 #(same as above)
169 .change obj1 green=-1+255 #(invert green color component)
170 .change obj1 green=2-128  #(reduce spectrum for green to the upper 50%)
171 .change obj1 luminance=50% #(fade all color components 50% to black, same as red=50% green=50% blue=50%)
172 .change obj1 alpha=50% #(make object 50% transparent)
173
174 # scaling
175 # -------
176
177 .change obj1 scale=50%   # change an object to 50% of it's size
178 .change obj1 scaley=50%  # flatten object to 50% of it's height
179 .change obj1 scaley=110% scalex=75% #(funhouse mirror!)
180
181 # rotating
182 # --------
183
184 .change obj1 rotate=45  # tilt object, counterclockwise
185
186 # shearing
187 # --------
188
189 .change obj1 shear=100%  # shear object
190
191 # sprites (a.k.a. movieClips)
192 # -------
193
194 .sprite spr1
195     .frame 1    .put ball1=ball 0 0
196     .frame 2    .change ball1 100 100
197 .end
198
199 .sprite spr2
200     .frame 1    .put ball2=ball 100 0
201     .frame 7    .change ball2 0 100
202 .end
203
204 .frame 400
205     .put spr1
206     .put spr2
207
208 # so spr1 has three frames, spr2 has seven. The whole animation loops after 21 frames.
209
210 # multi-level nesting: (sprites can be nested to any depth)
211
212 .sprite mspr1
213     .sprite mspr2
214         .sprite spr3
215         .put ball 100 0
216         .end
217     .end
218 .end
219
220 # clipping an animation inside a star-shaped sprite:
221
222 .swf mystar1 "star.swf"
223 .swf anim1 "penguins.swf"
224
225 .sprite cspr1
226     .startclip mystar1
227         .put anim1
228     .end
229 .end
230 .frame 401
231     .put cspr1 rotate=0
232 .frame 402
233     .change cspr1 rotate=360
234
235 # buttons
236 # -------
237
238 .png play "Play.png" #TODO
239 .png play_pressed "Play_pressed.png" #TODO
240 .png stoplogo "Stop.png" #TODO
241
242 .button playbutton
243     .show play as=idle
244     .show play as=area
245     .show play_pressed as=pressed
246     .show play_pressed as=hower
247 .end
248
249 .button playbutton2
250     .show play as=idle
251     .on_press inside
252     .on_release inside
253     .on_release outside
254     .on_move_in pressed
255     .on_move_out pressed
256     .on_move_in
257     .on_move_out
258     .on_key "a":
259         # actionscript...
260     .end
261 .end
262
263 .button mybutton
264     .show play as=idle
265     .show obj1 x=300 y=400 scale=110% pivot=center 
266          as=pressed
267 .end
268
269 .box blueshape 10 10
270 .box greenshape 10 10
271 .box whiteshape 10 10
272 .box activearea 10 10
273 .box emtpyshape 10 10
274 .box window1 10 10
275 # button which is blue, get's green when the mouse hovers over it, and
276 # white when it is pressed:
277 .button b1
278     .show blueshape as=idle
279     .show greenshape as=hower
280     .show whiteshape as=press
281 .end
282
283 # button where the button position is not identical to the active area:
284 .button b2
285     .show activearea as=area
286     .show blueshape as=idle
287     .show greenshape as=hower
288     .show whiteshape as=press
289 .end
290
291 # (if area is not set, it's the same as shape)
292
293 # the above put into use: pop up a window if the mouse cursor enters a certain
294 # area:
295 .button b3
296     .show activearea as=area
297     .show emtpyshape as=idle
298     .show window1 as=hower
299 .end
300
301 # fonts
302 # -----
303 .font font1 "myfont.swf"
304 .font font1 "myfont.ttf"
305 .font font1 "myfont.pfa"
306
307 # text fields
308 # -----------
309 .text mytext1 font=font1 text="I am a happy little scroll message" color=blue size=100%
310
311 # edittext
312 # --------
313 #(field where the flash animation can get input from the user)
314
315 .font helvetica "helvetica-bold.swf"
316 .edittext edittext1 text="Type something here" color=blue maxlength=200 font=helvetica size=24 width=320 height=200 #TODO
317 # width/height: dimensions of the box
318 # text: The text which appears initally in the box, and can be overwritten by the user
319 # maxlength: max. length of the text the user can type
320 # color/font/size: Font appeareance
321 # variable: Name of the actionscript variable the text is stored in
322 # The following boolean options are also supported:
323 # password (show input only as stars), wordwrap, multiline, html, noselect, readonly
324
325 # actionscript
326 # ------------
327
328 .action:
329     _root.play();
330 .end
331
332 # depth control
333 # -------------------
334 # .put, .change, .qchange, .jump, .startclip take before and after parameters,
335 # which can be used to specify the depth of an object
336
337 .put o1=obj1 #TODO
338 .put o2=obj1 below=o1 x=50 #TODO
339 .frame
340 .change o1 #TODO
341 .change o2 above=o1 x=50 #TODO
342
343 # newline conventions
344 # -------------------
345
346 # All Newlines are treated as normal whitespace. Therefore, splitting
347 # commands over several lines, like
348 .put obj2=obj1 x=300
349              y=300
350              red=100%
351              green=50%
352              blue=50%
353 # is allowed.
354
355 # Furthermore, having more than one command in one line is also possible:
356
357 .frame 600  .change obj1 x+=700  .change obj2 x+=300
358 .frame 601  .change obj1 x+=500  .change obj2 x+=500
359 .frame 602  .change obj1 x+=300  .change obj2 x+=700
360
361 .end # end of first file
362