Modifying a BSP (Binary Space Partitioning)

Written in March 2009 by Christian Sebastian Strahl aka Chrissstrahl

This technique was first used on the HaZardModding Coop Script Mod for STEF2 in 2008



INTRODUCTION

Have no map source Files? No problem, edit the BSP!
This Tutorial will show you how to Hex a bsp compiled level for ID-Tech3 based games like:
Q3, HL, HL2, COD, COD2 SOF2, JKA, STVEF, STEF2, and many more...
The file extension for these level-files is *.bsp and stands for Binary Space Partitioning.
The downside of a bsp is that you cannot simply load it into a Level Editor and edit it from there, it's a little more tricky than that. This tutorial will help you get through it.
For this Tutorial I will use XVI32 as Hexeditor and 7-Zip as archiver.


USABILITY

To give you a short impression, I've listed below a few things which can be achieved by modifying a BSP. Almost all entities can be changed in origin and targetname or even be deleted, just keep on experimenting, it's different for each game!

TOOLS:

Hex editor, like: XVI32, Notepad++(with Plugin)
Archiver, like: 7-Zip, WINRAR


NAME ALLIAS FOR BSP FILES

d3dbsp used in Call Of Duty 2


WHERE TO FIND A BSP

BSP level files are usually in the sub folder /maps of almost all games which are using bsp as levels. Some games have their files in Zip-Archives, these Zip-Archives do not have the file extension *.zip, they use *.pk3 or similar extensions. You can open these Archives with any Archiver capable of handling Zip-Archives.


EDITING RULES

A bsp is already compiled, so we have to follow strict rules to keep the file intact.

  1. Any inaccuracy will end in a game crash or shut down!

  2. You can't change the geometry of the level!

  3. You can change entities, but not(delete) game vital entities.

  4. You can't erase or add bytes from/to the BSP file, which means if you replace each character/values, you have to maintain the file size as it is!

  5. Maintain the syntax, be careful with brackets, spaces/breaks, quotes and such!




EDIT AN ENTITY

For this tutorial I will use a info_player_deathmatch entity node, this node tells the game where a player can be spawned. Let us now examine this entity line by line.

{

"classname" "info_player_deathmatch"

"origin" "768 4000 10"

"angle" "270"

}


LINE1: { opens up a new entity

LINE2: "classname" declares the class for this entity, defines the purpose of it

LINE3: "origin" current location vector, the player spawns at X=768, Y=4000 and Z=10 (AXIS)

LINE4: "angle" direction the player is looking at when spawned here (0 - 359)

LINE5: } ends the current entity




In the HexEditor the squares shown here are different special characters such as the following two, which are used to indicate the end of the current line:
LF, End of the line, Hex: 0A
CR, Carriage Return, Hex: 0D

NOTE: LF is used by Unix, CR is used by Mac OS-X, and LFCR is used by Microsoft Windows.


To keep this simple we change now the, Z-Axis of this spawn location. This will lift up the location where the player spawns. What we need to do is to alter the value of the attribute origin in line 3, from:

"origin" "768 4000 10"

to

"origin" "768 4000 99"


Then we would have the following code:

{

"classname" "info_player_deathmatch"

"origin" "768 4000 99"

"angle" "270"

}

In this case 99 is the highest and -9 is the lowest value we can use here



Now let us assume we need to have this Z-Axis value changed to 900 under all circumstances, the only thing we can do is to transform a non-vital attribute!
In the entity above the only non-vital attribute is the player facing direction, "angle" "270". We need to overwrite the current structure, so it would look like:



"origin" "768 4000 900"

angle" "270"


The syntax is now no longer valid, and the bsp would no longer work.
You can use two methods to transform this attribute correctly:

Method #1 - Fill up with SPACE

Simply replace each one of the 12 characters from angle" "270" with a space[HEX:20].





Methode #2 - Fill up with dummy data

Instead of filling up the leftover characters with SPACE we simply fill the vector with dummy data. You can make 768 to 768.0000 and 4000 to 4000.0000, there is no difference for the game in these two vectors, but you have added successfully the 12 leftover characters.


NOTE: You should not use more than 5 numbers behind the dot, for compatibility reasons, using less than five should not have any effect on the game.





EDIT A TEXTURE

For a texture it's almost the same procedure, but you can not use SPACE[20], use instead NUL[00] to fill up the leftovers, and you can overwrite the original texture text string or following NUL characters.


NOTE: If you change any textures and host a server with the modified bsp it will have no effect on the clients connection to your server, unless you provide them with your modified bsp.




TRANSFORMABLE ENTITIES

In almost every BSP are entities which are entirely useless, these entities can be transformed, including all their tributes without lousing any detail on the level. info_null is a classes which is always useless for the compiled map and can be replaced without any side effects .

Thanks for reading!







WARNING: All these modifications will be detected by most anti cheating tools!
Modifying a game's contents is only legal if the modified files will NOT be used to CHEAT in ANY way!