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>So you've got a text editor and want to play around with the SuperTux files, eh? Then I suppose you'll find this reference informative. (At least I hope so.) Toying around with SuperTux files using nothing but a text editor is not everyone's hobby... and writing documentation for toying around with a text editor is a sign of masochism. ;-)</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, so unless you really want to write a level using a text editor, get <ulink url="http://flexlay.berlios.de/">Flexlay</ulink> and don't strain yourself too much.
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.
149 ;; You can add other sectors here.