
    S I M E O N ' S   W O R L D
    ---------------------------
Copyright (c) 1998,1999 Sami Wilenius


       Custom levels manual


           Version 0.7


1.0 What you need
1.1 Basic level: pictures and the use of color index numbers
1.2 Let's make sprites
1.3 The Script file
1.4 Level memory
1.5 Special things
1.6 Own background musics
1.7 Simeon's Level Script Compiler (SLSC)
1.8 Building SLP file
1.9 Example files
2.0 Closing words


Instructions :
(This file is still under construction, full of all kinds of errors)


1.0 What you need :
-------------------
 -Simple bitmap-editor, which can save 256-color, 8 bpp, 1 colorplane,
  version 5.0 pcx-format pictures. Deluxe Paint does this,
  as does the freeware GrafX2.
 -Text editor which saves textfiles in plain ascii format.
 -Pencil and paper.


1.1 Basic level: pictures and the use of color index numbers :
--------------------------------------------------------------

One level consists of two pcx pictures, one which contains the level itself
and another where are all the sprites for the level. The script file defines
the sprites from the pictures and sets their behavior when game is played.
Both pictures must be shorter than 64kB (segment limit, didn't
have the time/interest to make code to round this..)

Both of these pictures must have identical palette, you can freely modify
the palette, few colors however is good to leave to their original rgb-values,
those are the colors used in bottom screen status bar.
The palette to the game is finally taken from the sprite-pcx.

Color index map :
0      : Transparent color.
1-63   : Enemy colors, kills Simeon.
64-127 : Bonus item colors, when Simeon touches this color, it checks
         collision with bonus or gizmo-sprite.
128-207 : Background color, no effect to Simeon, you can also use these
          colors in enemys and items, just make sure that the item
          is surrounded by enemy/bonus color, so collision detecting is
          flawless.
208-215 : Bottom screen status bar colors, 208 text background, 210 text
          color, 211 text shadow.
216-219 : Move Simeon left colors, when Simeon stands on this color, he will
          be moved to the left.
220-223 : Move Simeon right colors.
224     : Move Simeon up color, use this color in lifts going up.
225-231 : Brick wall colors, Simeon can not walk through these colors, and
          also bangs his head to pixel with these color. Brick wall collision
          detecting is inaccurate and not flawless.
232-239 : Platform colors, Simeon can walk on these pixels.
240-247 : Ladder colors, Simeon can climb areas covered with these colors
          up / down.
248-255 : Simeon colors, you can use other colors in Simeon too, but
          these are reserved to use in Simeon to provide "alien pixel"
          collision detecting, which, however isn't in the code (yet).

So, draw the level file and the sprites/animations using these colors.
To make static, but killing thing (like static pikes), draw them directly
to the level file, do not make sprites of them, less sprites, less
horsepower required.




1.2 Let's make sprites :
------------------------
All moving and/or animated things in Simeon's World are called sprites.
Take a glance to the example sprite picture, you just draw these little
pictures with transparent background color (0) somewhere on the canvas, to
make animations I suggest you to use paint program which has animation
capabilities like Deluxe Animation, so you can immediately see how the
animation looks like.
Remember to use transparent color as background color.
I suggest that you surround the sprites with single dark color, that makes
the sprites to stand out better from the background, this also allows you to
use non-enemy (or bonus) colors in the sprite.
After you have drawn some sprites you must map them to the script,
and it is not the fun thing. Because I wanted to make Simeon's World ready
fast, I didn't build any external level/sprite editors which could have
automated sprite mappings, you (and I) must make it manually, in this
section you use pencil and paper to write down the upper left and bottom
right coordinates, and later on you add these coordinates to the script file.

There are external example file for full script file where you can look
the structure. Here is however some of sections explained :



1.3 The Script file :
---------------------
And again, this game was programmed in fast schedule, so the form of
script file is quite tight, there are error detecting in
the compiler but try to stay in course..

First line :
#levelname "Simeon's Home"

This is name of the room.


This part defines the gfx-areas used in sprite-frames and all other things.
This line starts the gfx definitions :

#definegraphics

Then these comes the definitions (I write just few) :

#1 <0,0-9,17>     ;simeon right frame 1
#2 <10,0-19,17>   ;simeon right frame 2
#3 <20,0-29,17>   ;simeon right frame 3

The structure is :

#number (the gfx number, 1 is the smallest and 255 is largest number)
<upper left x,upper left y-bottom right x,bottom right y>


Definition ends with line below :

#enddefinegraphics


Then there comes the area which defines the sprites, and so all the
information how the level works :

#definesprites        ;defines sprites

Below is very basic sprite :

#define 1             ;Sprite number is 1
#spritetype <simeon>  ;Sprite's type
#animationtype <thru> ;Animation type
#x 286                ;x-coordinate in level at startup
#y 80                 ;y-coordinate in level at startup
#defineframes         ;frame definitions starts
#amount 4             ;length of animation : 4 frames (max is 10)
                  
#right 1 #1       ;These four frames are used when Simeon walks right
#right 2 #2   
#right 3 #1   
#right 4 #3  
#left 1 #4      ;Left frames
#left 2 #5 
#left 3 #4 
#left 4 #6 
#up 1 #7     
#up 2 #8      
#up 3 #7      
#up 4 #8 
#down 1 #7    
#down 2 #8 
#down 3 #7 
#down 4 #8 

#enddefineframes    ;End frame definitions

#enddefine          ;End sprite definition


Okay, let's start to unwrap this code, the first line :
#define 1             ;Sprite number is 1

Defines the number of sprite, this is used when some other sprite
calls this sprite.
The first sprite defined must ALWAYS be type <simeon> and always with
number 1, because it defines the sprite which the player uses, I also
mention that the #delay-parameter does not have use in sprite type <simeon>.
Also note that the sprite's order does not need to be 1,2,3,4..
it can be like 1,27,6,12,3,15.. The order of sprites in the script-
file is also the order which they are drawn to the screen.

#spritetype <simeon>

This apparently defines the type of sprite, there can following types :

<simeon>: The player control sprite, "there can be only one".
<enemy> : If killing colors are used in this kind of sprite, touching it
         will kill Simeon, however you can make friendly animations with
         this type, which does not kill Simeon by using just background colors
         in this sprite.
<bonus> : This is collected item, but only if bonus-colors are used, when
         Simeon touches sprite with type of this, it deactivates (disappears)
         and the amount of items to be collected is decreased by one.
<ally> : There is little differences between <enemy> and <ally>, but
          <ally> suits better for moving harmless animations,
          the box controlled with two switches in the basement is
          <ally>-type sprite.
<gizmo> : This is also collected item, but unlike <bonus>, this sprite will
         be activated again when Simeon re-enters level which has this type of
         sprite, also other sprites can re-activate this sprite, so you make
         for example switches, like in the basement-level.
         Use bonus-colors in this sprite.
<key>   :When Simeon collects item with this type, one key will be added.
<door>  : This defines door which can be opened with key, and when Simeon
         if fully 'inside' the door area, Simeon travels to another level if
         Enter-key is pressed and the door is open.

#animationtype <thru> ;Animation type

There can be following #animationtypes :
<thru>  : Constant sprite, animates all defined frames to defined
          direction for ever.
<move>  : In fact this is almost %100 same as above, but there are some
          changes in the code which makes this sprite little better
          to move.
<thruonce> : All the frames defined for selected direction are being played,
          after that the sprite will be deactivated.
<moveonce> : When this sprite reaches any of its predefined borders, it
          will be deactivated.


#amount 4

This line defines the amount of frames, be sure to define all the frames,
at least as many as #amount defines.

#right 1 #1 #delay 10     
This line sets the first frame for the sprite moving right, it uses
gfx-number 1 (#1), delays 10 cycles before going for next frame.

#right 2 #2 #delay 10 #move 2
This line is same except this also moves the sprite two pixels to the right

#right 2 #2 #delay 10 #move 2 #change #3 160,100 right
This line is same as above except changes the sprite number 3 to position
160,100 and sets its direction to the right.

These are the options what you can use in frame definition line :
first of all, the direction, frame number and gfx-number are mandatory,
other are not, here they are :

#delay n   : Delays the coming of next frame with n amount of 1/50 second,
             so n value 50 waits exactly one second, value 255 is maximum.
#move n    : Moves the sprite to the direction what the sprite have with
             amount of n pixels, value 10 is maximum.
#activate #n xx,yy direction
           : This activates sprite number n to screen position xx,yy and
             sets it's direction to direction, it can be :
              right, left, up or down.
             This is only done if sprite number n is currently deactivated,
             if it's active already, this does nothing.
             If you give coordinates 0,0, the original position of target
             sprite is preserved.
#change #n xx,yy direction
           : This makes the same thing as the above, but this works
             even if the sprite is already active.
#dontwipe  : This word can be added after the activate or change parameters,
             it does not clean the background of target frame when it's
             activated or it's direction/position is changed, use this if
             the sprite 'flickers', this is used for example in the
             'castle'-screen in the catapult's ammo, because they are
             constantly changing direction, which could otherwise cause
             flickering. 

After definitions :
These are the options what you can define after the #defineframes section :

#startframe n  : This sets the initial start frame to frame n, if you make
                 many identical animated sprites this is very useful, I
                 used this in the space lauch pad to three blades.
#direction n   : Sets sprites initial direction, n can be left, right,
                 up or down. If not defined, direction left is assumed.
#number n      : For <door>s only, defines the door number, so it can
                 memorized is the door open or not.
#leftborder n  : This sets the sprites left border to value n, so you can
                 control how the sprites move on the screen, there are also
                 some options which you can use in the same row :
 #activate #n xx,yy : The very same as in the frame definitions, so you
                 can for example activate the very same sprite you are calling
                 from if it's <moveonce>-type, you can for example change
                 sprites direction to up when left border is reached.
                 I used this on the space lauch pad to the lift which goes
                 square path.
 #change #n xx,yy  : The same than in the frame-section.
 #dontwipe         : - "" -
 #move             :
#rightborder : look leftborder..
#upborder    : look rightborder..
#downborder  : look upborder..

#ontake   : For collected sprites (bonus and gizmo) sets action what
            happens when the sprite is collected, these are the options :
  addstatic #n xx,yy : Adds static gfx to the background. After Simeon
                       dies or leaves the level static gfx is gone again.
  activate #n xx,yy dir : Activates sprite #n to pos xx,yy (can be 0,0 for
                          preserve original) and direction dir.
  open #n xx,yy : Open door without key (door number n) as introduced in
                  #number n line in the door sprite.
  travel #n xx,yy : Travels to another level (number #n) to coordinates xx,yy.
                    This must be in all <door> types, but can also reside in
                    <bonus> or <gizmo> items.
            Note that there are no #-character front of the first keyword,
            but in border and frame line the #-character is required.


1.4 Level memory :
------------------
To maintain information about which items has been collected and what is not,
and to memorize which door is opened and what isn't, there are memory.
It contain information about 100 doors and 30 sprites on 100 different levels.
This also sets the maximum size of Simeon's World to 100 different levels.

The memory is changed only when :
 1) <bonus> item is collected (ontake-activate or ontake-change).
 2) <door> is opened (ontake-open or enter-key).

So if you activate sprite from frame or border call, it isn't memorized
when the level is reloaded. Memorize that, if you activate must-be-collected
items.. You can always use 'virtual' sprites, for example virtual sprite
which is activated by ontake-call can do anything, it can activate/change
several sprites or do anything else possible, I used virtual sprites as
timers in the castle-level.
No sprite coordinates or moving direction are saved, only the information
is the sprite active or not.


1.5 Special things :
--------------------

<BONUS>es : All bonuses must be defined as sprite numbers 2-30.
<DOOR>s   : You must specify the door number, like :
#number 13
          It is usual that at least two doors have the same number, so
          for example when you open the door to the market, also the door
          IN the market opens, so you can walk back to your home.
          Number must be in 1-100.
          Door direction sets information is it initially locked or not.
           Left - the door is already open.
           Right - the door is locked, so key is needed.
           Up/down - the door is locked and key does not open it, it must
                     be opened with ontake-open command.

For better understanding look at the example files, which are used in
Simeon World, and uses almost all the things explained here (or not).


1.6 Own background musics :
---------------------------
You can compose your own background musics using FM-Kingtracker v1.06
You must leave channels 17 and 18 empty, because sound effects are been
played thru them. Also take note that the external player used in Simeon's
World may play some 4op sounds slightly different than what the tracker
plays.
The hiscore music should be quite short.


1.7 Simeon's Level Script Compiler (SLSC)
-----------------------------------------
With this little thing you compile the level script files to .swl
(Simeon's World Level) files, the compiler itself is easy to use,
just give the script file name as parameter, like "SLSC MYLEV1.SCP",
and the compile starts.
If there are some critical errors which could possible crash the computer
when the level would be played, then compiler stops and gives you
information about the error, sometimes even with the line number
where the error lies, but usually gives you the sprite/frame number to look
at.

After Pass 3 it is very common to have several warnings (sometimes several
hundredts of warnings) for missing frame definitions, but you don't have to
be worried because if you make sprite which do not move, only
frames for one direction are really needed..

If the script passes all tests, it will be compiled and written to the disk,
and it will have name like MYLEV1.SWL, it takes the name part of the script
file and changes the extension to .SWL.


Error detecting :
SLSC gives error message if error is found, note that for example error :
 'number too small', does not automatically mean that you have defined too
 small number to some point in the line, you may have totally forgot to
 write the number to the line.
The error detecting for misspelled words is not so good, so if compiler
says everything is ok, but the level doesn't work, check the script again.


1.8 Building SLP file
---------------------
SLP (Simeon's Level Pack) file contain whole set of levels to Simeon's
World. You create this kind of file using program SIMBUILD.
SIMBUILD needs definition file, so it knows what to build, you give the
filename as parameter to SIMBUILD.
After that SIMBUILD builds the SLP file which can be played from Simeon's
World.
Before can you build you must compile all the levels using SLSC and name
all the levels like ?????1.SWL ?????2.SWL .... ?????37.SWL.
That number tells the level number.
All the pcx files for the files must named like this :
level???.pcx for all the level pcx's and anims???.pcx for all the
sprite pcx's.
All the levels, pictures and musics to be builded must reside in the same
directory.

The definition file can be any name and it must be normal text file,
it could hold following lines :

#message "????" Here you can write description for the level pack.
#author "????"  Here you can write the names who made these levels.
                You can use characters A- 0-1 , . - + ! / ' and &.
                Maximum length of these two strings are about 60 chars..
                If all the makers cannot be included to this line, you
                can for example make the first level 'credits'-screen by
                writing all the names to the pcx and just add one door where
                the game really begins..

#lives <number> How many lives the player have.
#bonus <number> How many bonuses the player must collect.
#levels <name>  Name must be shorter than 6 characters since you must
               preserve three characters for the level number.
               This line must be defined.
  Example : #levels <mylev>

#music n <filename> You can define up to six musics.
  Example : #music 4 <mytune.fmk>

If no musics were defined, the original musics will be played.
Music #1 is the tune used in the 'best times'-screen.
Important is that you define all the musics, just not numbers 1,3 and 4,
it does not work. You must define the musics starting from number 1 (hiscore)
to number 10.

Example definition file :
#message "Just testing how things work out.."
#author "Me"
#lives <3>
#bonus <43>
#levels <test>
#music 1 <tune1.fmk>
#music 2 <tune2.fmk>

When you make new level, it's wise to make it temporarily number 1, since
it's not practical to walk thru all your levels to see how the new level
is working.


1.9 Example files
-----------------
Two full levels are included with sources (2*scripts, 2*animation,
2*level pcx, 2*musics and build definition file), so you can train compiling
and building SLP-files and see how things work out.
First compile both scripts (SLSC examp1.scp and SLSC examp2.scp) then
build slp using definition file example.txt (SIMBUILD example.txt), the
result is EXAMP.SLP, place this to the Simeon's World directory and you
see it when you start playing, choose 'Example' from the list, and now
you are now playing levels which you have compiled and builded.

It is wise to use 'work' directory which has SIMBUILD, SLSC and all the
PCX and script files in same place.

You can take Simeon's animation from the example files and use it, or
you can make your own character, just remember that the size of all frames
should be equal, otherwise things can go wrong..


2.0 Closing words
-----------------
That's it. I hope you got something useful information from this text.
If you are doing new levels and you discover that certain things doesn't
work like they have been reported here, don't get puzzled, WYSIWYG. 

