zLevelsDesign.txt

INSTRUCTIONS FOR CREATING NEW LEVELS

Levels are made of one folder with two files inside, the scenario image cavern.png, and the objects configuration file items.txt. 
The level name would be the folder name.

First of all we need to create a new folder with his name, better to use the same pattern of uppercase letter and number, I do 
prefer to use letter "L" for my own levels, but I strongly reccomend to use a different one, as for example "X" as it do not interfer
with my own levels, so we can share.

Then we have to amend the (current) line 24 of cave.red file. That line contains the block holding the level names as: 
Levels: ["L1" "L2" "L3" "L4"] to Levels: ["L1" "L2" "L3" "L4" "X1"] for example. I do change this line for the first level to be 
the one I'm working, so the line would have this aspect: Levels: ["X1" "L2" "L3" "L4" "X1"] so you will start the game at the
desired level, and then, when level is done, restore the line the normal content.

SCENARIO IMAGE:

Then we have to copy the files cavern.png and items.txt from an existing folder, from that way we will not start from scratch. 
It is important not to modify the dimensions of cavern.bmp that contains the scenario of the game, since it would produce 
unpredictable results in the game, these dimensions are 1599x600 pixel.

Once this is done, we can begin to modify the appearance of the scenario, I always use paintbrush & pixelformer, but any
bitmaps editor works. It is important to preserve the color of the terrain and the stairs, since the game is based on that
color to stop the effect of gravity, but you may use any color combination and these colors values can be changed in the level
configuration file, items.txt, by using a line that starts with "&" such as: & TerrainColor 100.125.150.0 or & StairsColor1
200.200.200.0 and & StairsColor2 150.150.150.0 that way we can change the color of the scenario and set the desired value in a
for level basis.

The design of the scenario is free hand, you just have to bear in mind that you have to use those colors in the areas where 
objects move, for the subject of gravity. A part of this, is very important properly place the stairs, and make sure each upper
end of stair have a ceiling at the adecuate distance, 18 pixels by default, for the guards to detect end of climbing, this 
parameter may be also modifyied by the configuration file as setting & CeilingDist 25 for example. It is also noticeable not to
locate stairs at the side of walls not being external perimeter, there must be some space between the stair and the wall, so the
guards would be able to turn back and exit from dead ends. Finally, the scenario must be saved as cavern.png if the config file 
remains having that name for the cave file.

The kart handles must be placed near the x point where the kart stops, the vertical distance must be at no more than 45 pixels
from the boy y coordinate when it is located under the handle, as the handle routine will look up when action key is pressed to 
find the & HandleColor value, so we have some flexibility. Note that if the kart floor is too thin, as in L14 by design, the
wall checking routines will return false, thus the boy could release gold bags and load the barrow if present while on kart, this
is a non inteded trick I discovered by testing :-)

You must draw the kart cable and stop terminator marks, the lifters holes and cables (if any) to match theyr stop points related
at the configuration file, and use the & LifterCable value as color for them. The guards function looks for this color and stops to
wait for the platform to walk, feel free to change this on LifterCable word, but remember not to use it on walls or my guards will
wait forever  :-(

OBJECTS CONFIGURATION FILE:

This is where we locate te objects that appear in the level, including the scenario file. A line contains this: 

ItemType|ObjectName|FaceName|FaceSize|FaceOffset|Rate|Stops|TimeOfTool|Direction|Gravity|ImageFiles

ItemTypes start with: (A)gent (B)and (C)avern (D)rop (G)oldBags (J)ohnDoe (K)art (L)ifter (P)assage (R)Girl (S)pider (T)ools (W)barrow
ObjectName & FaceName must be different for the same object, as they holds different info and meaning
FaceSize must match the ImageFiles size to work properly
FaceOffset is the born location for the object
Rate is user for handler functions, I recommend to test the level with already defined ones Rate to check if works properly as desired
Stops for lifters (up-down) or karts (left-right) in the way 0x0,0x0,... or 0x0 alone for other objects
Location (Stop #)
Direction (Positive value Down/Right or negative value Up/Left)
For (B)and first stop indicates axis displacement 1x0 -> Horizontal displacement, Other value -> Vertical displacement
(P)assages must be grouped pairs of passage1 and passage2, then passage3 and passage4 ... (we use direction field for pairing)
For (A)gents first ObjectName letter must be "f" if agent is female so as "fagent3", "p" phantom "pagent" or
"y" for The TallMan "yagent", image files must be defined accordingly to the character using the provided images.
For (G)old bags first ObjectName letter imply their value, can be any, but "f" for fat (bag green neck) or "h" for heavy (24kt red)
but the image files can be any of the provided objects, that is: gold1 gold2 gold3 gold+ gold- gold! see imagefiles at DATA folder.
To modify default GameData/word values: & word value (value can be tuple! logic! or integer!)

Each comment line starts with "#", it is important not to set white lines in the whole file (as I did here for clarity) or the
game hangs.

EXAMPLE:

& TerrainColor 89.89.89.0         <--- Will override default terrain color when loading this level

& StairsColor1 200.191.231        <--- Will override default stairs color 1 when loading this level

& StairsColor2 63.72.204.0        <--- Will override default terrain color 2 when loading this level

& DropGravity 1                   <--- Will override default gravity value for drops when loading this level

CAVERN|cavern1|cave|1599x600|0x0|0:0|0x0|0:0|0|0|cavern.png      <--- Main scenario image

AGENT1|agent1|age1|22x34|945x30|0:0:0.05|0x0|0:0|0|1|agent-l1.png|agent-r1.png|agent-l2.png|agent-r2.png|agent-l3.png|agent-r3.png|agent-s1.png|agent-s2.png|agent-s3.png|agent-s4.png    <--- Male gent
AGENT2|fagent2|age2|22x34|645x300|0:0:0.04|0x0|0:0|0|1|fagent-l1.png|fagent-r1.png|fagent-l2.png|fagent-r2.png|fagent-l3.png|fagent-r3.png|fagent-s1.png|fagent-s2.png|fagent-s3.png|fagent-s4.png    <--- Female agent

GOLDBG|gold1|gld1|8x12|75x50|0:0|0x0|0:0|0|1|gold1.png      <--- Normal gold
GOLDBG|gold2|gld2|8x12|75x240|0:0|0x0|0:0|0|1|gold1.png     <--- Normal gold
GOLDBG|fgold3|gld3|8x12|1255x90|0:0|0x0|0:0|0|1|gold2.png   <--- Fat gold
GOLDBG|hgold4|gld4|8x12|1290x90|0:0|0x0|0:0|0|1|gold3.png   <--- Heavy gold

TPICKAX|pickax1|pkx1|9x10|350x320|0:0|0x0|0:0:10|0|1|pickax1.png     <--- pickax
TPICKAX|pickax2|pkx2|9x10|1400x230|0:0|0x0|0:0:10|0|1|pickax1.png    <--- pickax

LIFT1|lifter1|lif1|35x10|201x53|0:0:0.0001|201x53,201x185,201x257,201x337,201x417,201x586|0:0|1|0|lifter-1.png  <--- Lifters
LIFT2|lifter2|lif2|35x10|1205x109|0:0:0.0001|1205x110,1205x235,1205x312|0:0|1|0|lifter-2.png  
LIFT3|lifter3|lif3|35x10|1105x312|0:0:0.0001|1105x312,1105x400,1105x585|0:0|1|0|lifter-2.png

BAND|band1|bnd1|100x1200|750x-600|0:0:0.1|0x1|0:0|1|0|lavafall100.png     <--- Lava moving (horizontal) band

PASSAGE1|passage1|pas1|50x40|82x132|0:0:4|0x0|0:0|1|0|passage-G.png    <--- Passage teleporter pair-1  member 1
PASSAGE2|passage2|pas2|50x40|1196x55|0:0:4|0x0|0:0|1|0|passage-G.png   <--- Passage teleporter pair-1  member 2
PASSAGE3|passage3|pas3|50x40|82x132|0:0:4|0x0|0:0|2|0|passage-G.png    <--- Passage teleporter pair-2  member 1
PASSAGE4|passage4|pas4|50x40|1196x55|0:0:4|0x0|0:0|2|0|passage-G.png   <--- Passage teleporter pair-2  member 2

SPIDER1|spider1|spi1|9x7|510x325|0:0:0.15|0x0|0:0|0|1|spider-l1.png|spider-r1.png|spider-l2.png|spider-r2.png|spider-l3.png|spider-r3.png   <--- spider

KART1|kart1|krt1|35x19|1440x133|0:0:0.00001|124x133,1440x133|0:0|-2|0|kart1.png    <--- Kart 1
KART2|kart2|krt2|35x19|123x291|0:0:0.00001|123x291,1440x291|0:0|2|0|kart1.png      <--- Kart 2

WBARROW|wbarrow1|wba1|26x17|155x550|0:0|0x0|0:0|0|1|barrow-r1.png   <--- Barrow, can have more than once if scenario is so difficult

ROSE|rose|doer|22x34|500x28|0:0:0.06|0x0|0:0|0|1|rose-l1.png|rose-r1.png|rose-l2.png|rose-r2.png|rose-l3.png|rose-r3.png|rose-s1.png|rose-s2.png|rose-s3.png|rose-s4.png

JOHN|john|doe|22x34|160x15|0:0|0x0|0:0|0|1|thief-l1.png|thief-r1.png|thief-l2.png|thief-r2.png|thief-l3.png|thief-r3.png|thief-s1.png|thief-s2.png|thief-s3.png|thief-s4.png|thief-bl1.png|thief-br1.png|thief-bl2.png|thief-br2.png|thief-bl3.png|thief-br3.png  <--- Player object