* Tiles now have an alpha parameter for semi-transparency (useful in levels like...

[supertux.git] / docs / fileformats / fileformats.xml

<?xml version='1.0' ?>
<!--
$Id$

SuperTux Documentation
Copyright (C) 2005 Ondra Hosek <ondra.hosek@gmail.com>

This document is free; you can redistribute it and/or modify
it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program (see the file named 'COPYING'); if not,
write to the Free Software Foundation, Inc., 59 Temple Place -
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">

<article xml:lang="en">

<articleinfo>
<title>SuperTux File Format Documentation</title>
<author><firstname>Ondra</firstname><surname>Hosek</surname></author>
</articleinfo>
<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>
<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>&quot;That Crazy File Format&quot; 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. &quot;You'd like that, wouldn't ya?&quot; 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.)
    (some-integer 120)      ; Integer values are simple to input and to understand.
    (floaty-float 58.5)     ; Floating-point numbers should be self-explanatory too.
    (string-thong "omg")    ; Strings are simple and C-like.
    (intl-string _("wtf"))  ; Internationalised strings are implemented not unlike in C.
    (boo-bool #t)           ; That's a "true"...
    (second-bool #f)        ; ... and that's a "false". (Well duh.)
    (integer-list 10 20 30) ; A list of integers, much like an array.
)  ; Don't forget the closing bracket!!!
</programlisting>
</para>
</sect2>

</sect1>

<sect1><title>Level Files</title>
<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.
<programlisting>;; Generated by Flexlay Editor (or Emacs or Vi or whatever)
(supertux-level                      ;; This initiates a level.

  (version 2)                        ;; This document only describes version 2. Version 1 is deprecated
                                     ;; and I'm not going to teach it since it lacks a lot of features.

  (name _("Some demo level"))        ;; Name of the level. Call it a nice name. Note that this should be
                                     ;; internationalised (that's why the extra underscore and brackets).

  (author "Ondra Hosek")             ;; Put your name here unless you are me (very improbable)

  (sector                            ;; A level is divided into independent sectors that can be connected
                                     ;; by doors.

    (name "main")                    ;; Tux begins in the sector named &quot;main&quot;.

    (music "Ondras_chipdisko.mod")   ;; Name of the music file. See the data/music/ directory.
    
    (gravity 10.0)                   ;; Gravity of Tux. 10.0 is the default and sanest value (unless you
                                     ;; apply the level design correctly).
    
    (tilemap                         ;; Here come the files.
      (layer  "background"           ;; Currently, there are three layer types: &quot;background&quot;,
                                     ;; &quot;interactive&quot; and &quot;foreground&quot;.

      (solid  #f)                    ;; Will Tux collide with tiles in this tilemap?
      
      (speed  1.0)                   ;; If the tilemap is solid, this has to be 1. Basically sets how
                                     ;; fast the tilemap scrolls.
      
      (width  5)                     ;; Number of tiles you plan to put in a row...
      (height 5)                     ;; ... and in a column. (5x5 is pretty tiny; small Tux
                                     ;; takes up 1x1 tiles, big Tux 1x2 tiles).
      
      (tiles                         ;; Integer lists of which tiles you want to use.
        0 0 0 0 0                    ;; The tiles and their numbers are defined in
        0 0 0 0 0                    ;; data/images/tiles.strf.
        0 0 0 0 0
        0 0 0 0 0
        0 0 0 0 0
      )
    )
    (tilemap
      (layer  "interactive")
      ;; See the bacgkround layer definition.
    )
    (tilemap
      (layer  "foreground")
      ;; ...
    )
    
    (camera                          ;; Definitions of the camera paths

      (mode "autoscroll")            ;; This can be set to "normal" to deactivate
                                     ;; forced scrolling. Then you can omit the
                                     ;; "path" directive.
      
      (path                          ;; Forced scrolling path
        
        (point (x 2) (y 3) (speed 2) ;; Point to where camera will scroll.
          )
        
        (point
          ;; ...
        )
      )
    )
    
    (background
      (image "ocean.jpg")            ;; Background from data/images/background
      (speed 0.5)                    ;; Scrolling speed
    )
    
    (spawnpoint (name "main") (x 0)  ;; A spawning point for Tux. By default, he is
      (y 0)                          ;; spawned at spawnpoint named "main".
    )
    
    ;; THE FOLLOWING OBJECTS ARE OPTIONAL.
    (init-script "
// A Squirrel script
// See the scripting reference for more information.
")

    ;; Here you can add badguys of your choice.
    ;; A reference on badguy types and their parameters is a TODO.
    
    ;; Particle systems
    ;; ditto
  )
  
  ;; You can add other sectors here.
)</programlisting>
</para>
</sect1>

<!--

TODO:
* Worldmap
* Level subset
* Scrolling Text
* Badguy types
* Particle systems
* Sprite definitions
* Tile definitions

-->

</article>