Suite 330, Boston, MA 02111-1307, USA.
-->
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<article xml:lang="en">
<title>SuperTux File Format Documentation</title>
<author><firstname>Ondra</firstname><surname>Hosek</surname></author>
</articleinfo>
-<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>
+<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 Flexlay.</para>
<sect1><title>Brackets, brackets, brackets (About the Language)</title>
<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>
-<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>
+<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>
<sect2><title>Basic Syntax</title>
-<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>
+<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>
<para>Language syntax is (nearly) always best consumable when demonstrated on an example, like so:
<programlisting>(supertux-lisp-example
; This is a comment. It is initiated by a semi-colon. (Yes, you un-believer.)
(sector ;; A level is divided into independent sectors that can be connected
;; by doors.
- (name "main") ;; Tux begins in the sector named "main".
+ (name "main") ;; Tux begins in the sector named "main".
(music "Ondras_chipdisko.mod") ;; Name of the music file. See the data/music/ directory.
;; apply the level design correctly).
(tilemap ;; Here come the files.
- (layer "background" ;; Currently, there are three layer types: "background",
- ;; "interactive" and "foreground".
+ (layer "background" ;; Currently, there are three layer types: "background",
+ ;; "interactive" and "foreground".
(solid #f) ;; Will Tux collide with tiles in this tilemap?
;; ...
)
)
+
+ (backscrolling #f) ;; You can prevent the camera from scrolling
+ ;; backwards with this setting.
)
(background
(layer 201) ;; -100 are background, 0 are interactive, 200 are foreground tiles.
;; Choose a number to put the rain between two layers. In this case,
- ;; the rain is in front of the foreground tiles. (see also src/video/drawing_context.h)
+ ;; the rain is in front of the foreground tiles. (see also
+ ;; src/video/drawing_context.hpp)
+ )
+
+ (leveltime
+
+ (time 300) ;; The player must complete this level
+ ;; within 300 seconds.
)
) ;; End of sector
(stay-on-platform #f) ;; Optional. Should the badguy do its best not to fall from the platform it's on? (NYI)
)
</programlisting></para>
-<para>Bouncing Snowballs, Flying Snowballs, Jumpies, Mr Bombs, Mr Iceblocks, Mr Rockets, Mr Trees, World 1 Noloks,
-Poison Ivies, Snowballs, Spikies, Stalactites, Yeti Stalactites and Zeeklings only require this list of
-parameters. Simply substitute <code><badguy-name></code> with one of the following:
+<para>Bouncing Snowballs, Flying Snowballs, Jumpies, Mr Bombs, Mr Iceblocks, Mr Rockets, Mr Trees, World 1 Noloks, Poison Ivies, Snowballs, Spikies, Stalactites, Yeti Stalactites and Zeeklings only require this list of parameters. Simply substitute <code><badguy-name></code> with one of the following:
<itemizedlist>
<listitem><code>bouncingsnowball</code></listitem>
<listitem><code>flyingsnowball</code></listitem>
(badguy random) ;; Valid values are "snowball", "bouncingsnowball", "mrbomb",
;; "mriceblock", "mrrocket", "poisonivy" or "random".
-)
-</programlisting></para>
+)</programlisting></para>
</sect3>
<sect3><title>Flame</title>
;; follows?
(speed 10) ;; How fast should the flame be?
-)
-</programlisting></para>
+)</programlisting></para>
+</sect3>
+
+<sect3><title>Lightning orb</title>
+<para>The lighting orb ("kugelblitz") ignores the <code>y</code> coordinate, spawning above the visible screen.</para>
</sect3>
<sect3><title>Spike</title>
-<para>Don't mistake this badguy for Spiky! Spiky is the snowball-like creature with
-spikes, whilst a spike is an object serving the same purpose like the stalactite.</para>
+<para>Don't mistake this badguy for Spiky! Spiky is the snowball-like creature with spikes, whilst a spike is an object serving the same purpose like the stalactite.</para>
<para><programlisting>(spike
(direction 2) ;; 0: north, 1: south, 2: west, 3: east
-)
-</programlisting></para>
+)</programlisting></para>
</sect3>
<sect3><title>Yeti</title>
-<para><programlisting>(spike
+<para><programlisting>(yeti
(dead-script "
// A squirrel script that is executed once the Yeti dies.
")
This is a line in a small font.
#This is a left-aligned line.
*This should be printed in a blue font.
+!Filename of the picture to be embedded into the scrolling text (relative to scrolltext file path)
")
)
-)
-</programlisting>
+)</programlisting>
</para>
</sect1>
+<sect1><title>Worldmaps</title>
+<para>Worldmaps are basically level files with a few nuances. To explain the syntax, let's just picture somebody with the idea to write a level set that takes place in London (represented by a lonely island):
+<programlisting>(supertux-worldmap
+ (properties ;; Global worldmap properties.
+ (name (_ "London")) ;; Name of the worldmap
+ (music "bigben.ogg") ;; Music to be played while on worldmap
+ )
+ (spawnpoint ;; At the moment, defining multiple spawnpoints on a worldmap is useless.
+ (name "main") ;; Call your spawn point "main".
+ (x 3) ;; Note that the coordinates are, unlike in a level, bound to the tilemap.
+ (y 3)
+ )
+ (tilemap
+ (width 5) ;; Number of tiles in a row. Four is just for demonstrational purposes.
+ (height 5)
+ (layer "interactive") ;; This has to be "interactive".
+ (solid #t) ;; This has to be true.
+ (speed 1.000000) ;; This has to be 1.0.
+ (tiles
+ 0 0 0 0 0 ;; The tiles as defined in data/images/worldmap.strf.
+ 0 11 16 12 0
+ 0 15 60 17 0
+ 0 14 18 13 0
+ 0 0 0 0 0
+ )
+ )
+ (level ;; Repeat this block for each level. Continuing from a level tile is only possible when the level is completed.
+ (x 3) ;; Coordinates of the level entry point.
+ (y 3)
+ (name "heathrow.stl") ;; Filename of the level, relative to the location of the worldmap file.
+ (extro-script "
+// A Squirrel script to execute once this level is completed.
+ ")
+ )
+ (special-tile ;; This is a sample message tile.
+ (x 4)
+ (y 3)
+ (map-message (_ "Hello.")) ;; Display the following text when Tux steps on this tile.
+ (passive-message #t) ;; Set to #f to stop Tux when he steps on this tile.
+ (apply-to-direction "north-west") ;; The message is displayed only when Tux comes from one of the specified directions (north, south, west, east, concatenate with a hyphen).
+ )
+ (special-tile ;; This is a sample portal tile.
+ (x 2)
+ (y 3)
+ (map-message (_ "Warp to the Tower"))
+ (teleport-to-x 1) ;; Worldmap coordinates to which Tux is teleported.
+ (teleport-to-y 1)
+ )
+)</programlisting></para>
+
+</sect1>
+
+<sect1><title>Level subsets</title>
+<para>Whilst creating a worldmap is optional, you'll need to write a level subset file to make your level package to appear in the contribs menu (or, ironically, inhibiting this behaviour). A file containing a level subset is called <code>info</code> and lies in <code>data/levels/<subset_name>.</code>
+<programlisting>(supertux-level-subset
+ (title "Domain of the Hosek siblings") ;; Give your levelset a nice name...
+ (description "Levels by Ondra and Klara, the Hosek siblings") ;; ... and a short description.
+ (hide-from-contribs #f) ;; Set to true if you don't want your levelset to appear in the "Contrib Levels" menu.
+)</programlisting></para>
+</sect1>
+
<!--
TODO:
-* Worldmap
-* Level subset
* Sprite definitions
* Tile definitions
projects / supertux.git / blobdiff