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

* Yet Another Scripting Doc Update
* Added a WIP document discussing the various file formats of SuperTux (currently only describes level format)

SVN-Revision: 2498

diff --git a/docs/fileformats/fileformats.xml b/docs/fileformats/fileformats.xml
new file mode 100644 (file)
index 0000000..f8d6e3a
--- /dev/null
+++ b/docs/fileformats/fileformats.xml
@@ -0,0 +1,167 @@
+<?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>

diff --git a/docs/scripting/scripting.xml b/docs/scripting/scripting.xml
index bb5b15f..637de97 100644 (file)
--- a/docs/scripting/scripting.xml
+++ b/docs/scripting/scripting.xml
@@ -58,10 +58,34 @@ When this level loads, the screen fades out completely during two and a half sec
 
 <sect1><title>Object reference</title>
 <para>If you are interested in an object and what cans of worms you can open with it, this section is for you.</para>
-<para>&quot;(NYI)&quot; after the function name symbolises functions that haven't been implemented yet. Calling them will result in a line being printed to standard output informing anybody who reads it that the script is using a function that actually doesn't exist. (Win32 users will happily ignore this, because they simply start the application by opening it with Explorer. Unix users are going to be more interested of what SuperTux can actually tell them, so it's better if you don't use non-existent functions in your scripts.)</para>
+<para>&quot;(NYI)&quot; after the function name symbolises functions that haven't been implemented yet. Calling them will result in a line being printed to standard output informing anybody who reads it that the script is using a function that actually doesn't exist. (Win32 users will happily ignore this, because they simply start the application by opening it with Explorer. Unix users are going to be more interested in what SuperTux can actually tell them, so it's better if you don't use non-existent functions in your scripts.)</para>
+
+<sect2><title>Global Functions</title>
+<para>These global functions access basic or generic methods of SuperTux. They are called without an object name.</para>
+
+<sect3><title>display_text_file</title>
+<para>Usage: <code>display_text_file(string filename)</code></para>
+<para>Effect: Displays the SuperTux text file named <code>filename</code>. (The path is relative to the level file.)</para>
+<para>See also: SuperTux file format reference, SuperTux texts</para>
+</sect3>
+
+<sect3><title>set_wakeup_time</title>
+<para>Usage: <code>set_wakeup_time(float waketime)</code></para>
+<para>Effect: When used before a call to <code>suspend()</code>, the script only stays suspended for <code>waketime</code> seconds.</para>
+</sect3>
+
+<sect3><title>translate</title>
+<para>Usage: <code>translate(string text)</code></para>
+<para>Returns: Translated string</para>
+<para>Effect: Translates <code>text</code> into the user's locale.</para>
+<para>Note: This construct is not yet recognised by XGetText, and so is subject to change.</para>
+</sect3>
+
+</sect2>
 
 <sect2><title>DisplayEffect</title>
 <para><code>DisplayEffect</code> is an interface for toying with the display.</para>
+
 <sect3><title>fade_out</title>
 <para>Usage: <code>DisplayEffect.fade_out(float fadetime)</code></para>
 <para>Effect: Gradually fades out the screen to black for the next <code>fadetime</code> seconds.</para>

diff --git a/src/tile.cpp b/src/tile.cpp
index bdf92ff..2befbbf 100644 (file)
--- a/src/tile.cpp
+++ b/src/tile.cpp
@@ -89,6 +89,10 @@ Tile::parse(const lisp::Lisp& reader)
   if(reader.get("slope-type", data)) {
     attributes |= SOLID | SLOPE;
   }
+  
+  if (!reader.get("alpha", alpha)) {
+       alpha = 255;
+  }
 
   const lisp::Lisp* images = reader.get_lisp("images");
   if(images)
@@ -168,11 +172,15 @@ Tile::get_editor_image() const
 void
 Tile::draw(DrawingContext& context, const Vector& pos, int layer) const
 {
+  context.set_alpha(this->alpha);
+  
   if(images.size() > 1) {
     size_t frame = size_t(global_time * anim_fps) % images.size();
     context.draw_surface(images[frame], pos, layer);
   } else if (images.size() == 1) {
     context.draw_surface(images[0], pos, layer);
   }
+  
+  context.set_alpha(255);
 }
 

diff --git a/src/tile.h b/src/tile.h
index cfddd02..c221003 100644 (file)
--- a/src/tile.h
+++ b/src/tile.h
@@ -90,6 +90,9 @@ private:
   
   /** General purpose data attached to a tile (content of a box, type of coin)*/
   int data;
+  
+  /** Alpha (opacity) of tile */
+  int alpha;
 
   float anim_fps;