Blocks of Doom II Library Documentation

Welcome to Blocks of Doom II library documentation. This file is a reference designed to help levelmakers get familiar with the many features provided by the ACS library. Any parts of the library not mentioned in this documentation are not for design use and might lead to unexpected behavior if you use them yourself.

There are currently three files in the Blocks II library. The first file is BoD2Library.acs, the main library file. The second is BoD2_MSInitializer.acs, the map script initializer. The third is ExtLib.acs, the extended library, which it currently not used and might be discarded in the future.

Every map script must #import BoD2Library.acs and #include BoD2_MSInitializer.acs. The correct location for these lines in the map scripts can be seen in the template map, where lots of examples and comments are provided for levelmakers.

Block flags are the key features applied to blocks to make them interactive with the players. Tileset designers can combine block flags by using the OR "|" operator to give a tile several features. Most of the flags can be combined as you please, but incorrect or conflicting combinations will be reported as errors when the library loads the tiles.

Block flags are used in the array Local_BlockTypes, where all the tile definitions for that tileset are stored.

Base flags

BF_NONE
No flag. Must be applied if the block has no other flags.
BF_SECTORTRIGGER
The player will trigger something when he is inside the block's sector (on top of it, in other words).
BF_LINETRIGGER
The player will trigger something when he bumps into the side of the block.
BF_GIB
Will immediately kill the player and gib him.
BF_KILL
Will immediately kill the player.
BF_DMGFLOOREQUIP
Requires BF_GIB or BF_KILL. Player can be protected by a specific equipment (usually fire/slime boots) when he is inside the block's sector.
BF_DMGWALLEQUIP
Requires BF_GIB or BF_KILL. Player can be protected by a specific equipment (usually fireproof/slimeproof suits) when he bumps into the side of the block.
BF_DMGINAIR
Requires BF_GIB or BF_KILL. Player will be killed on entering the block's sector, even if he is above the block.
BF_FLOORSLOW
Floor moves slowly.
BF_FLOORFAST
Floor moves quickly.
BF_FLOORINSTANT
Floor moves instantly.
BF_FLOORLOWER
Floor will lower to the ground.
BF_LOWER64UNITS
Requires BF_FLOORLOWER. Lowers floor by 64 units (one whole wall height) instead of directly to floor height.
BF_CHANGETOWALL
Floor changes to wall after lowering.
BF_ELEVATOR
An elevator.

Sector specific flags

BF_S_NONE
No flag. Must be applied if the block has no other flags.
BF_S_EXIT
Exit square. (The level has to made exitable in the ACS for each map.)
BF_S_LOSEEQUIPMENTS (Deprecated old name: BF_S_LOSEBOOTS)
Lose all equipment (boots and suits).
BF_S_LOSEKEYS
Lose keys.
BF_S_LOSEITEMS
Lose equipments and keys.
BF_S_NOFRICTION [Changed in 0.3 alpha 7, see BF_S_SLIDING]
No friction floor (super slippery, in other words).
BF_S_NOFRICTIONEQUIP [Changed in 0.3 alpha 7, see BF_S_SLIDINGNOEQUIP]
Removed from 0.3 alpha 7.
BF_S_LOWFRICTION
Low friction floor (slippery, in other words).
BF_S_HIGHFRICTION
High friction floor (muddy, in other words).
BF_S_CARRYUP
Floor carries player upward. (North)
BF_S_CARRYDOWN
Floor carries player downward. (South)
BF_S_CARRYLEFT
Floor carries player leftways. (West)
BF_S_CARRYRIGHT
Floor carries player rightways. (East)
BF_S_CARRYEQUIP
Requires one of the BF_S_CARRY flags to be set. The carrying effect on this floor can be overcome by a specific equipment. (Usually suction boots.)
BF_S_SLIDING [0.3 alpha 7]
Slides the player to the other side of the block. Player cannot control movement when sliding on this kind of floor.
This flag is the alias of BF_S_NOFRICTION before 0.3 alpha 7.
BF_S_SLIDINGEQUIP [0.3 alpha 7]
Requires BF_S_SLIDING. Uncontrolled and sliding effects will be ignored by a specific kind of equipment. (Usually ice boots/skates.)
This flag is the alias of BF_S_NOFRICTIONEQUIP before 0.3 alpha 7.
BF_S_ENTERACS [0.3 alpha 7]
Runs S_BLOCKENTER script when player enters this block.
BF_S_STAYACS [0.3 alpha 7]
Runs S_BLOCKSTAY script when player stays in this block.
BF_S_LEAVEACS [0.3 alpha 7]
Runs S_BLOCKLEAVE script when player leaves this block.

For BF_S_ENTERACS, BF_S_STAYACS, and BF_S_LEAVEACS, the library will pass two arguments to the script, which are (int tile, int blockIndex).
These scripts serves different purposes in compare with Run ACS. They serves as external tile functions binded to a script which are not available in the library, so they are also called tile events. If Run ACS and tile events were both going to be called, the library will call tile events first.

Line specific flags

BF_L_NONE
No flag. Must be applied if the block has no other flags.
BF_L_LOCKDOOR1
Locked door 1.
BF_L_LOCKDOOR2
Locked door 2.
BF_L_LOCKDOOR3
Locked door 3.
BF_L_LOCKDOOR4
Locked door 4.
BF_L_LOCKKEEPKEY
Requires any of the BF_LOCKDOOR flags to be set. The required key(s) will not be taken after the door is opened.
BF_L_BLOCKPLAYER [0.3 alpha 7]
Player cannot pass the lines of this block.
BF_L_BLOCKMONSTER
Monsters cannot pass the lines of this block.
BF_L_IMPASSIBLE
This block is impassible. The same as the combination of BF_L_BLOCKPLAYER and BF_L_BLOCKMONSTER.
BF_L_BLOCKPROJECTILE [0.3 alpha 7]
Projectiles cannot pass the lines of this block.
BF_L_BLOCKALL [0.3 alpha 7]
Blocks everything. The same as the combination of BF_L_BLOCKPLAYER, BF_L_BLOCKMONSTER, and BF_L_BLOCKPROJECTILE.
BF_L_SCROLLWALLUP
The side textures of this block scrolls upward.
BF_L_SCROLLWALLDOWN
The side textures of this block scrolls downward.
BF_L_SCROLLWALLLEFT
The side textures of this block scrolls leftways.
BF_L_SCROLLWALLRIGHT
The side textures of this block scrolls rightways.
BF_L_BUMPACS [0.3 alpha 7]
Runs S_BLOCKBUMP script when player bumps the lines of this block.
BF_L_BUMPACSONCE [0.3 alpha 7]
S_BLOCKBUMP will run only once.

BF_L_LOCKDOOR flags can be used on top of each other to make locked doors that require more than one kind of key.
BF_L_BUMPACS is one of the tile events. Please read the comments for sector specific flags for the information about tile events. But the library passes three arguments instead of two, which are (int tile, int blockIndex, int side). "side" represents the line on the block that triggers the script, which can be LINESIDE_EAST, LINESIDE_WEST, LINESIDE_NORTH, and LINESIDE_SOUTH.

Returns the index (a number between 1 and 256) of the block at the specified row and column.

Returns the array index of the block row on which the specified block lies. Essentially this is equivalent to doing B_GetRow(index) - 1.

Returns the array index of the block row on which the specified block lies. Essentially this is equivalent to doing B_GetColumn(index) - 1.

Creates a teleport between two blocks. Will override any other teleports that are already there.

Creates a trap button at the specified block with a certain trigger mode. Will override any other trap buttons that are already there.

Runs an ACS script on the specified block under the specified conditions. Any scripts already set to that block will be overridden if they are already there.

Sets the specified block's lines to block everything, including the player, monsters, and projectiles.

A generalized function that sets the block lines' passability for the player, monsters, and projectiles.

Changes the specified block's tile and height. This function will not remove block parameters.

Builds a horizontal line of blocks with the specified tile and height factor. This function calls B_BuildBlock, so parameters will be reset.

Builds a vertical line of blocks with the specified tile and height factor. This function calls B_BuildBlock, so parameters will be reset.

Builds a rectangle of blocks of the same specified tile and height factor. This function calls B_BuildBlock, so parameters will be reset.

Sets the specified block's tile and floor height to 0 and resets all parameters.

Removes a horizontal line of blocks. This function also resets all blocks' parameters.

Removes a vertical line of blocks. This function also resets all blocks' parameters.

Removes a rectangle of blocks of the specified tile. This function also resets all blocks' parameters.

Moves the block upwards or downwards and changes its tile. A block will refuse to move if heightUnit is not a factor of its original tile's base height. (Base height is defined in Local_BlockTypes array.)

Returns the index of the block that the actor with the specified tid is currently in. A return value of zero means that the actor is outside the grid.

Returns true if the trap button at the specified block is currently activated or not.

Returns true if the trap button at the specified block is currently deactivated or not.

'Opens' any exit gates on the level (exit tiles created after this function is called will also be opened).

Calls a user-defined script when the world is finished instead of the standard script.

Takes the player to the next world. By default, the player is taken to the secret level as a reward for collecting every sphere.

Starts a timer which counts the number of seconds it takes a player to complete the level. This script can be called at the start of a level by levelmakers who wish to set a better timelimit for their level.

Works exactly the same as T_Spawn, except this function will not apply an action special to the thing.

Returns the TID of the spawned sphere. If the sphere fails to spawn, zero will be returned.

Returns the TID of the spawned item. If the item fails to spawn, zero will be returned.

Spawns an important pickup (keys, boots, etc.) at the specified block, without fog.

Spawning items with fog is not the default behavior, which is why a fog argument is not included in T_SpawnItem.

Returns the TID of the spawned decoration. If the decoration fails to spawn, zero will be returned.

Spawning decorations with fog is not the default behavior, which is why a fog argument is not included in T_SpawnDecoration.

Returns the TID of the spawned switch. If the switch fails to spawn, zero will be returned.

Spawning switches with fog is not the default behavior, which is why a fog argument is not included in T_SpawnSwitch.

Spawns a boulder at specified block. BE CAREFUL! If a boulder is spawned immediately in front of a wall which it is facing, it will bounce around the level hectically. Place your boulders carefully.

Noted that this function does not have a return value. This is because all boulders share the same TID, which is controlled by the variable BoulderTID and is reset at the end of every level. BoulderTID will be initialized once the first boulder is spawned.

Returns the TID of the spawned projectile. If the projectile fails to spawn, zero will be returned.

Returns the TID of the spawned trap thing. If the trap thing fails to spawn, zero will be returned.

Another way to get the TID of the trap thing is with its trap index - simply use TrapActorTID[trapIndex].

Registers a thing with the specified TID into the list of things that can trigger trap buttons. Things without prior registration cannot trigger trap buttons.

Returns true if the number of spheres left in the level is lower than or equal to the specified amount, and updates the 'spheres left' display on the status bar accordingly.

Returns true if the number of enemies left in the level is lower than or equal to the specified amount.

Returns true if the number of items left in the level is lower than or equal to the specified amount.

Returns true if the number of decorations left in the level is lower than or equal to the specified amount.

Returns true if the number of switches left in the level is lower than or equal to the specified amount.

Returns the block index from the player's current position. A return value of zero means that the player is outside the grid.

Moves the player to the map's starting point. If there are multiple starting points, the library will randomly choose one.

Returns the square root of an integer. If the input number is negative, zero will be returned.

Returns the least common multiple. Returns zero if the number cannot be found. (Usually caused by an overflowed number.)

Returns the fixed point angle that is closest to that of a circle divided into a certain amount of equal 'slices', specified by 'split'.