src/screens/cutscene.doc

   1 /**
   2
   3 @page cutscenes Cutscene file format
   4
   5  The new cutscene format is sight different to the original
   6 format. Now, it's lisp based, so you can indent text more freely, and
   7 you can have comments too :)
   8
   9 To start with, look at the following example!
  10
  11 @code
  12 ; Credits file example
  13 ; In lisp, everything after ; are ignored
  14
  15 (dirtyblobwars-cutscene
  16         (version 1)
  17         (music "music/sweetDreams.xm") ; optional
  18
  19         (page
  20                 (time 20)
  21                 (image "gfx/cutscenes/ending5.jpg")
  22                 (text (_"Some stupid, and meaningless text..
  23 Newlines are ignored when making the cutscene!
  24 So this wont cause a newline, except if the screen ends!"))))
  25 @endcode
  26
  27 As you can see, semicolon initializes a comment. Every tag start with
  28 a curly brace <strong>(</strong>, and end with an another
  29 <strong>)</strong>. Strings are between <strong>"</strong>-s. Maybe
  30 you note the special string tag in the example:
  31 <tt>(_("text"))</tt>. This syntax will tell the parser, to translate
  32 the string. So if you put <tt>(text "mirror")</tt> every user will see
  33 it as mirror. How ewer, if you write <tt>(text (_"mirror"))</tt>, a
  34 translator might translate the string, and the user may see the text
  35 in his language, it would become tükör in Hungarian, for example.
  36
  37 So, after the basics of the language, let's have a look at the tags!
  38
  39 First we start it @b dirtyblobwars-cutscene. This is the
  40 base tag. Every cutscene has to contain it.
  41
  42 After, we put a @b version tag into the root tag. Currently, only
  43 version 1 is exist and supported. So you have to put <tt>(version
  44 1)</tt> into every cutscene, otherwise, DirtY BLoB WaRs will exit.
  45
  46 After that, you can put an optional @b music tag. This tag will
  47 specify, what music to use in the cutscene. If you don't specify one,
  48 the default music (<tt>music/daisyChain2.mod</tt>) will used.
  49
  50 That's the end of the "settings", now you can start to specify
  51 pages. Each cutscene is made of pages. A page has a background, a
  52 maximum wait time and some text. In many cases, the background is same
  53 in all the pages. This case you only need to specify the background at
  54 the first page, every page after will use that background, unless you
  55 specify an another. This is because pages are read in order: from the
  56 first in the file to the last. This will also be the order in game.
  57
  58 Sub-tags of @b page:
  59 <ul>
  60         <li>@b image: Specifies the image to use in the page. This file is
  61         opened through PhysFS, so you can't use absolute paths to the
  62         system (like C:\ on windows, or /home on Unixes) </li>
  63         <li>@b time: Max time of the page in sec. After that time, the
  64         game will automatically change to the next page. Note, the user
  65         can change to the next page earlier by pressing a button. </li>
  66         <li>@b text: The actual text, that will shown on the
  67         screen. Usually you want to put it in <tt>(_"xy")</tt>, so the
  68         messages can localized.</li>
  69 </ul>
  70
  71 */