doc/HACKING

   1 Blob Wars : Metal Blob Solid
   2 Copyright Parallel Realities 2004
   3 Licensed under the GNU General Public License
   4
   5 Last Updated: 9th December 2004
   6
   7 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
   8 +++ Contents
   9 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  10
  11 1) Introduction
  12 2) The PAK File
  13 3) The FileData Object
  14 4) The Map File
  15 5) Map Entites
  16 6) Other Files
  17 7) FAQ
  18 8) Closing comments
  19
  20
  21 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  22 +++ Introduction
  23 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  24
  25 Contained within are pieces of information to do with the game, the map structure
  26 and the structure of the pak file that is used in BW:MBS. I have created this
  27 document for educational purposes.
  28
  29 This document is completely unsupported.
  30
  31 Thank you in advance for understanding.
  32
  33 To build the game without needing to recreate the PAK file each time to can
  34 build using the following command,
  35
  36 make USEPAK=0
  37
  38 The binary created will load files from the directory it resides within (so it
  39 will look for data, sound, gfx and music in the local dir). When building the
  40 game without using the PAK file you will get debug information to the console
  41 and an FPS counter. You may also use the following additional command line
  42 options,
  43
  44 -map <filename> Start the game using the specified map
  45
  46 -skill <skill level> Start the game using the specified skill (0, 1, 2, 3)
  47
  48 -showsprites Show the sprites that have been loaded. Use in conjunction with
  49                          a map file for best results
  50
  51 -hub Jump directory to the hub. Will automatically load the first available game
  52
  53 -randomscreens Takes random screenshots and dumps them into a directory called
  54                            screenshots. You might not want to use this(!)
  55
  56 -nomonsters        Does not add monsters to levels (does not affect Boss missions)
  57
  58 -credits           Show the credits
  59
  60 Stephen Sweeney
  61
  62
  63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  64 +++ The PAK File
  65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  66
  67 The PAK file used in BW:MBS differs from the one used in Project: Starfighter where
  68 as it is compressed and contains a lot more metadata making it a lot more effecient.
  69 The format is as follows,
  70
  71 NB: All binary data is little endian
  72
  73 <variable length data> (char)
  74 <varibale number of binary strutures> (FileData)
  75 <offset of FileData structures> (unsigned long)
  76 <number of file data structures in archive> (unsigned long)
  77
  78 BW:MBS will open the pak file, seek to the end, two back two unsigned longs and read
  79 them. It then have information regarding the file structure and can read in all the
  80 FileData objects that exist. These are stored in memory for the duration of the
  81 program and stepped through when a file needs to be loaded from the PAK.
  82
  83
  84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  85 +++ The FileData Object
  86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  87
  88 The FileData object holds the metadata for each file in the PAK archive. The object
  89 itself has the following format,
  90
  91 NB: All binary data is little endian
  92
  93 char filename[60];
  94 uLongf cSize;
  95 uLongf fSize;
  96 uLongf location;
  97
  98 Filename is the filename of the file (including the path). It is limited to 56 characters
  99 since it is loosely based on the original PAK file spec for Quake. This could obviously
 100 be changed if more characters were required.
 101
 102 cSize is the compressed size of the data. All the data in the PAK file is compressed using
 103 zlib compress at a strength of 9. This number is used to tell uncompress how much data there
 104 is and also used by CPak.cpp when loading the data from the pak file into a buffer in
 105 memory.
 106
 107 fSize is the full uncompressed size of the data. This is used by uncompress and also when
 108 allocating a memory buffer save uncompress the data into.
 109
 110 location is the offset of the data within the PAK archive. When a match for the filename
 111 has been found in stepping through the filedata array, the PAK file is opened and then
 112 seeked to the appropriate location. The appropriate amount of data is then read.
 113
 114 When working with big endian machines it is neccessary to convert the values in the FileData
 115 object o little endian so they may of proper use.
 116
 117
 118 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 119 +++ The Map Files
 120 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 121
 122 The maps are BW:MBS are plain text. They contain the data for the map, the objectives,
 123 enemies, doors, and pretty much everything else you see during the game. Sprites and
 124 new enemies can also be configured within the map data.
 125
 126 The map data beings with a large set of numbers. 400 columns and 300 rows allowing for
 127 very large maps. This, in hindsight, was overkill. But the reason this was because the
 128 map blocks used to be 16 x 16 pixels whilst they are now 32 x 32 pixels. After these
 129 rows the entity data starts.
 130
 131 The map entities take the following format,
 132
 133 <skilllevel> <entityname> <entity arguments>
 134
 135 Skill level is required and should contain a combination of E, M or H to represent
 136 whether that entity should appear on Easy Medium or Hard. Pretty much all the entities
 137 appear on Hard. For example,
 138
 139 MH ENEMY "SpiderBlob V1.0" 1000 1000
 140
 141 This will place a Spider Blob enemy at 1000, 1000 on the map on difficulities Medium
 142 and Hard, but not Easy.
 143
 144 Comments can be represented with C++ still slashes,
 145
 146 // here is a comment
 147
 148 Note: Bosses are hard coded. They do not live in the map data.
 149
 150
 151 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 152 +++ Map Entities
 153 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 154
 155 STAGENAME <"stagename">
 156
 157 The stage name of the map. Must have within quotes.
 158
 159
 160 BACKGROUND <filename>
 161
 162 The filename of the background to be used in this level.
 163
 164
 165 MUSIC <filename>
 166
 167 The music to be used in this level.
 168
 169
 170 TILESET <path>
 171
 172 The path to the tiles to be used in this level.
 173
 174
 175 REQUIRED_MIAS <initial number to rescue>
 176
 177 The initial number of MIAs required to complete the stage.
 178
 179
 180 MIA <"name"> <x> <y> <type>
 181
 182 Defines an MIA for this level. The type of MIA is either MIA_NORMAL or MIA_AQUA
 183
 184
 185 START <x> <y>
 186
 187 Determines where Bob will initially start on this level. Ignored when returning to a
 188 level.
 189
 190
 191 CLIPPING <x1> <x2> <y1> <y2>
 192
 193 Determines the scroll limit for the map. The map will not scroll further than the
 194 specified coordinates.
 195
 196
 197 AMBIENCE <sound file>
 198
 199 The sound effect that will be played in the background to represent the ambient sound
 200 in the level (like the bubbling sound in the Caves levels).
 201
 202
 203 ALPHATILES <variable length list>
 204
 205 Tile numbers that should be made transparent. Ideally this should have been in the tileset
 206 directory. Numbers should be seperated by spaces with -1 to determine the end of the list.
 207
 208
 209 OBJECTIVE <"description"> <"target"> <requiredAmount> <optional>
 210
 211 Defines an objective for the level.
 212
 213
 214 ITEM <type> <"name"> <x> <y> <sprite>
 215
 216 Creates an item of given type, name and sprite at the given coordinates. Types 0 - 4 are
 217 used for weapons. 5 - 7 for cherries and 8 - 14 for points pods. Types 100 and 101 are items
 218 that can be picked up and carried in the inventory. Items are type 101 are not shown in
 219 the inventory (for example, Crystals and Cherry Plants).
 220
 221
 222 ENEMY <"name"> <x> <y>
 223
 224 Places the specified enemy (via their name) at the specified coordinates.
 225
 226
 227 SPAWN_POINT <name> <x> <y> <type> <subtype> <min wait> <max wait> <active / inactive>
 228
 229 Used to spawn an item / entity at a random interval. For example, the lava balls that jump
 230 out of the lava in Inner Cave Network, Part 1 are spawned by having a type of SPW_HAZARD
 231 and a subtype of HAZARD_LAVABALL. They appear every 1 to 10 seconds. The type and subtype
 232 are dealt with in defines.h and processed in spawnPoints.cpp. x and y coordinates are also
 233 supplied to tell the game where the item should be spawned. The only exception to the rule
 234 are enemies. They have an x and y as -1 and -1 since they simply teleport in around the
 235 player's location.
 236
 237
 238 TELEPORTER <name> <x> <y> <destination x> <destination y> <on / off>
 239
 240 Simply sets up a teleporter with an origin and a destination. Can be on or off by default.
 241
 242
 243 LINEDEF <"type"> <related object> <"message"> <x> <y> <width> <height> <active / inactive>
 244
 245 Sets up a line that is actived when the player crosses it. Common types can be of "Checkpoint",
 246 "Message, "Exit". "Exit" will prevent the player from crossing until it is the last required
 247 objective remaining on the level.
 248
 249
 250 SWITCH <"name"> <target object> <required item> <"message"> <switch type> <x> <y> <active / inactive>
 251
 252 Creates a switch that can be triggered by the player (or other entities depending on the type)
 253 to toggle activate an object. Possible switch types are,
 254
 255 SWT_NORMAL
 256 SWT_TOGGLE
 257 SWT_TIMED
 258 SWT_PRESSURE
 259 SWT_RESET
 260 and SWT_WATERLEVEL.
 261
 262 Note that for switches that reset Obstacles the obstacle name should
 263 be placed into the "message". SWT_RESET switches are timed by default. Also, SWT_NORMALs become SWT_USEDs
 264 when they are activated. This is to aid in the persistence of the level.
 265
 266
 267 TRAIN <name> <start x> <start y> <end x> <end y> <wait time> <start location> <active / inactive>
 268
 269 Creates a train (a moving platform) with start and end locations as specified. The wait time states
 270 how long the platform will wait (in 60ths of a second) at each end before changing direction. Start
 271 location specifies which end the train will start at (either TR_AT_START or TR_AT_END). Note that
 272 end locations must be the same value as or greater values than the start locations.
 273
 274
 275 DOOR <"name"> <type> <open x> <open y> <closed x> <close y> <open / closed>
 276
 277 Creates a door with the specified open and close coordinates. Available door types are,
 278
 279 TR_DOOR
 280 TR_LOCKED_DOOR
 281 TR_GOLD_DOOR
 282 TR_SILVER_DOOR
 283 TR_BRONZE_DOOR
 284 TR_SLIDEDOOR
 285 TR_LOCKED_SLIDEDOOR
 286 TR_GOLD_SLIDEDOOR
 287 TR_SILVER_SLIDEDOOR
 288 TR_BRONZE_SLIDEDOOR
 289
 290 As their names suggest the doors are either normal doors, locked or require a certain key to
 291 open them. Locked doors can be in conjunction with switches and other triggers in order to make
 292 them open. Like trains, the closed x and y coordinates much be greater than or equal in value to
 293 the open coordinates.
 294
 295
 296 OBSTACLE <"name"> <x> <y> <sprite>
 297
 298 Sets up an obstacle with the given name and sprite than can be pushed. The name of the obstacle
 299 can be used in conjunction with reset type switches to return them to their original location.
 300
 301
 302 TRAP <name> <type> <damage> <speed> <startX> <startY> <endX> <endY> <wait1> <wait2> <sprite> <active>
 303
 304 Creates a trap in the location specified by start X and start Y. For traps such as the swinging ball
 305 and spikes, the end X and end Y specifies the second location to move to. Wait 1 and Wait 2 tell
 306 the trap how long to wait for each state (the energy beams have off and on times for example). Trap
 307 types available are,
 308
 309 TRAP_TYPE_SPIKE
 310 TRAP_TYPE_MINE
 311 TRAP_TYPE_SWING
 312 TRAP_TYPE_CRUSHER
 313 TRAP_TYPE_BARRIER
 314 TRAP_TYPE_FLAME
 315
 316
 317 SPAWNABLE_ENEMY <"name">
 318
 319 Only ten of these may be defined. Used with enemy spawn points this list details which enemies
 320 can be spawned on the map.
 321
 322
 323 SPRITE <name> <frame name> <wait time> * 8
 324
 325 Can be used to define a new sprite to be used specifically on this level. It supports up
 326 to 8 frames and wait times. When there are no more frames to be read, @none@ -1 is used
 327 to denote no more reading it required.
 328
 329
 330 DEFENEMY <"name"> <left sprite> <right sprite> <death sprite> <"weapon name"> <health> <score> <flags>
 331
 332 Create an enemy. Flags should be from the ENT_* flags are defined in defines.h
 333
 334
 335 WATER_LEVEL <level>
 336
 337 Specifies the water level within the level. Use in conjunction with water level switches to
 338 raise the water level
 339
 340
 341 TIME_LIMIT <minutes> <seconds>
 342
 343 The time limit for this level when playing on Extreme Mode.
 344
 345
 346 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 347 +++ FAQ
 348 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 349
 350 Q.      Can you give me some help modifying the source?
 351
 352 A.      Unfortunately I have other commitments, mainly in the real world, that would prevent me
 353         from setting aside the time the do so. In the time I do have spare I prefer to work on
 354         new projects.
 355
 356
 357 Q.      Why package up all the data into one file instead of leaving it loose?
 358
 359 A.      Three reasons - 1) It takes up less room on disc ; 2) It's easier to deal with one large
 360         data file rather than lots of file scattered all over the place ; 3) It stops people
 361         digging around in the data and potentially spoiling the game for themselves.
 362
 363
 364 Q.      How long did the game take to make?
 365
 366 A.      About 18 months from beginning to end.
 367
 368
 369 Q.      Why did so much change during the game, like the saves becoming incompatible around 0.91?
 370
 371 A.      Metal Blob Solid was very much a make-it-up-as-you-go-along game. It was only decided later
 372         on that the levels should be kept within a persistant state so as to not force the player
 373         to reopen doors, redo puzzles, etc. This in itself was a bit of a headache and due to a
 374         small cockup when creating the persistance data the game would crash if you returned to a
 375         previous level, left, saved, quit the game and reloaded.
 376
 377
 378 Q.      Why can't you see all the game or fight the bosses on Easy?
 379
 380 A.      It's easy mode(!) The bosses aren't exactly a walk in the park and bits of the game (such as
 381         battling Galdov for the Reality Crystal) are part of the game's plot. Because on Easy there
 382         is nothing to do except rescue MIAs, it was decided that you should get an ending, but not
 383         *the* ending after finishing the game on Easy. Also, a hell of a lot of work went into the
 384         bosses, other objectives, cutscenes, etc so it also has to do with appreciation.
 385
 386
 387 Q.      Are there any secrets in the game?
 388
 389 A.      No. If you finish the game on Normal or Hard you see everything the game has to offer.
 390         Although you do unlock Extreme mode which is the whole game again but with a time limit on
 391         each mission.
 392
 393
 394 Q.      Are you going to make any other games?
 395
 396 A.      There are plans, but nothing set in stone. Again, real life commitments can change
 397         everything.
 398
 399
 400 Q.      Will there be a sequel to Metal Blob Solid?
 401
 402 A.      See above.
 403
 404
 405 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 406 +++ Closing Comments
 407 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 408
 409 Metal Blob Solid was fun to make more often than not. There was some hair pulling and
 410 frustation involved in making the game, but that's natural in any project. In the end
 411 I grew quite fond of the bandana wearing Blob and decided to give his adventure more
 412 meaning, which was why the plot suddenly appeared, along with the bosses and cutscenes.
 413
 414 I hope you've all enjoyed playing the game and I hope to bring you some more games in the
 415 future.
 416