6 Copyright (C) 2005 Ondra Hosek <ondra.hosek@gmail.com>
8 This document is free; you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as
10 published by the Free Software Foundation; either version 2
11 of the License, or (at your option) any later version.
13 This document is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
18 You should have received a copy of the GNU General Public License
19 along with this program (see the file named 'COPYING'); if not,
20 write to the Free Software Foundation, Inc., 59 Temple Place -
21 Suite 330, Boston, MA 02111-1307, USA.
24 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.3//EN"
25 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
27 <article xml:lang="en">
30 <title>SuperTux File Format Documentation</title>
31 <author><firstname>Ondra</firstname><surname>Hosek</surname></author>
33 <para>This document serves the simple purpose of a reference for the files specific to SuperTux (levels, worldmaps, ...). Some of these files can be modified using an editor such as </para>
34 <sect1><title>Brackets, brackets, brackets (About the Language)</title>
35 <para>As you might have already noticed, the SuperTux definition files (just about for everything) are full of brackets ('(' and ')'). I know that <acronym>BASIC</acronym> programmers already freak out when seeing the vast amount of brackets used in C. The truth is that you can never have too many brackets. (Okay, that's a lie, but I don't know how lenient your compiler is.)</para>
36 <para>"That Crazy File Format" used by SuperTux is Lisp. In most of its implementations, it is used as a programming language, but the devs simply thought why not to implement it as a data storage language. And so, the SuperTux data language, nearly fully based on Lisp, was born.</para>
38 <sect2><title>Basic Syntax</title>
39 <para>So now you expect me to teach you Lisp. "You'd like that, wouldn't ya?" Okay, okay, let me teach you a bit.</para>
40 <para>Language syntax is (nearly) always best consumable when demonstrated on an example, like so:
41 <programlisting>(supertux-lisp-example
42 ; This is a comment. It is initiated by a semi-colon. (Yes, you un-believer.)
43 (some-integer 120) ; Integer values are simple to input and to understand.
44 (floaty-float 58.5) ; Floating-point numbers should be self-explanatory too.
45 (string-thong "omg") ; Strings are simple and C-like.
46 (intl-string _("wtf")) ; Internationalised strings are implemented not unlike in C.
47 (boo-bool #t) ; That's a "true"...
48 (second-bool #f) ; ... and that's a "false". (Well duh.)
49 (integer-list 10 20 30) ; A list of integers, much like an array.
50 ) ; Don't forget the closing bracket!!!
57 <sect1><title>Level Files</title>
58 <para>The level format is a bit complex, which is why <ulink url="http://flexlay.berlios.de/">Flexlay</ulink> can prove itself very useful as an editor. If you are interested in how the levels look like or want to edit them manually (and find some of the parameters not self-explanatory enough), then you may read or skim through this section.
59 <programlisting>;; Generated by Flexlay Editor (or Emacs or Vi or whatever)
60 (supertux-level ;; This initiates a level.
62 (version 2) ;; This document only describes version 2. Version 1 is deprecated
63 ;; and I'm not going to teach it since it lacks a lot of features.
65 (name _("Some demo level")) ;; Name of the level. Call it a nice name. Note that this should be
66 ;; internationalised (that's why the extra underscore and brackets).
68 (author "Ondra Hosek") ;; Put your name here unless you are me (very improbable)
70 (sector ;; A level is divided into independent sectors that can be connected
73 (name "main") ;; Tux begins in the sector named "main".
75 (music "Ondras_chipdisko.mod") ;; Name of the music file. See the data/music/ directory.
77 (gravity 10.0) ;; Gravity of Tux. 10.0 is the default and sanest value (unless you
78 ;; apply the level design correctly).
80 (tilemap ;; Here come the files.
81 (layer "background" ;; Currently, there are three layer types: "background",
82 ;; "interactive" and "foreground".
84 (solid #f) ;; Will Tux collide with tiles in this tilemap?
86 (speed 1.0) ;; If the tilemap is solid, this has to be 1. Basically sets how
87 ;; fast the tilemap scrolls.
89 (width 5) ;; Number of tiles you plan to put in a row...
90 (height 5) ;; ... and in a column. (5x5 is pretty tiny; small Tux
91 ;; takes up 1x1 tiles, big Tux 1x2 tiles).
93 (tiles ;; Integer lists of which tiles you want to use.
94 0 0 0 0 0 ;; The tiles and their numbers are defined in
95 0 0 0 0 0 ;; data/images/tiles.strf.
102 (layer "interactive")
103 ;; See the bacgkround layer definition.
110 (camera ;; Definitions of the camera paths
112 (mode "autoscroll") ;; This can be set to "normal" to deactivate
113 ;; forced scrolling. Then you can omit the
116 (path ;; Forced scrolling path
118 (point (x 2) (y 3) (speed 2) ;; Point to where camera will scroll.
128 (image "ocean.jpg") ;; Background from data/images/background
129 (speed 0.5) ;; Scrolling speed
132 (spawnpoint (name "main") (x 0) ;; A spawning point for Tux. By default, he is
133 (y 0) ;; spawned at spawnpoint named "main".
136 ;; THE FOLLOWING OBJECTS ARE OPTIONAL.
139 // See the scripting reference for more information.
142 ;; Here you can add badguys of your choice.
143 ;; A reference on badguy types and their parameters is a TODO.
146 ;; It is advisable only to use one particle system at a time.
148 (particles-<type> ;; Valid values for <type> are rain, snow and clouds
150 (layer 201) ;; -100 are background, 0 are interactive, 200 are foreground tiles.
151 ;; Choose a number to put the rain between two layers. In this case,
152 ;; the rain is in front of the foreground tiles. (see also src/video/drawing_context.h)
156 ;; You can add other sectors here.
158 ;; End of level</programlisting>
161 <sect2><title>Badguys</title>
162 <para>This section describes the various badguys and their parameters.</para>
164 <sect3><title>Common parameters</title>
165 <para><programlisting>(<badguy-name>
166 (x 270) ;; The badguy's X coordinate.
167 (y 126) ;; The badguy's Y coordinate. (Note that the origin is in the top-left corner!)
168 (stay-on-platform #f) ;; Optional. Should the badguy do its best not to fall from the platform it's on? (NYI)
170 </programlisting></para>
171 <para>Bouncing Snowballs, Flying Snowballs, Jumpies, Mr Bombs, Mr Iceblocks, Mr Rockets, Mr Trees, World 1 Noloks,
172 Poison Ivies, Snowballs, Spikies, Stalactites, Yeti Stalactites and Zeeklings only require this list of
173 parameters. Simply substitute <code><badguy-name></code> with one of the following:
175 <listitem><code>bouncingsnowball</code></listitem>
176 <listitem><code>flyingsnowball</code></listitem>
177 <listitem><code>jumpy</code></listitem>
178 <listitem><code>mrbomb</code></listitem>
179 <listitem><code>mriceblock</code></listitem>
180 <listitem><code>mrrocket</code></listitem>
181 <listitem><code>mrtree</code></listitem>
182 <listitem><code>nolok_01</code></listitem>
183 <listitem><code>poisonivy</code></listitem>
184 <listitem><code>snowball</code></listitem>
185 <listitem><code>spiky</code></listitem>
186 <listitem><code>stalactite</code></listitem>
187 <listitem><code>yeti_stalactite</code></listitem>
188 <listitem><code>zeekling</code></listitem>
189 </itemizedlist></para>
192 <para>The next few sections describe the extra parameters for the other badguys.</para>
194 <sect3><title>Dispenser</title>
195 <para><programlisting>(dispenser
196 (cycle 3) ;; How often should a badguy be dispensed?
198 (badguy random) ;; Valid values are "snowball", "bouncingsnowball", "mrbomb",
199 ;; "mriceblock", "mrrocket", "poisonivy" or "random".
201 </programlisting></para>
204 <sect3><title>Flame</title>
205 <para><programlisting>(flame
206 (radius 3) ;; How big should the radius of the circle be that the flame
209 (speed 10) ;; How fast should the flame be?
211 </programlisting></para>
214 <sect3><title>Spike</title>
215 <para>Don't mistake this badguy for Spiky! Spiky is the snowball-like creature with
216 spikes, whilst a spike is an object serving the same purpose like the stalactite.</para>
217 <para><programlisting>(spike
218 (direction 2) ;; 0: north, 1: south, 2: west, 3: east
220 </programlisting></para>
223 <sect3><title>Yeti</title>
224 <para><programlisting>(spike
226 // A squirrel script that is executed once the Yeti dies.
228 )</programlisting></para>
235 <sect1><title>Scrolling texts</title>
236 <para>Scrolling texts are used for the credits and were used for the intro and extro in Milestone 1. The format is simple:
237 <programlisting>(supertux-text
238 (background "extro.jpg") ; Background image (see data/images/background)
240 (speed 1.5) ;; Default speed of text
242 ;; Here we demonstrate the formatting characters
246 <tab>This is a normal line.
247 This is a line in a small font.
248 #This is a left-aligned line.
249 *This should be printed in a blue font.