Post tutorial RSS Modifying a BSP File (Binary Space Partitioning)

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, SOF2, JKA, STVEF, STEF2, HM-FAKK2, and many more...

Posted by on - Advanced Mapping/Technical

Modifying a BSP (Binary Space Partitioning)

Written in March 2009 by Christian Sebastian Strahl aka Chrissstrahl


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.


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!

  • Doors
    - move speed
    - open/close events
    - wait time before the door closes again
    - door looked and move sounds
  • Triggers/Buttons
    - trigger events (script/level)
    - trigger effects

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


d3dbsp used in Call Of Duty 2


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.


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 must maintain the file size as it is!
  5. Maintain the syntax, be careful with brackets, spaces/breaks, quotes and such!

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.

BSP code:
"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, value is usually from 0 to 359
LINE5: } ends the current entity

Hex Editor View of the bsp code
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"
"origin" "768 4000 99"

Then we would have the following code:

BSP 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

UPDATE: You do not need the spaces between each quote, this means you can also transform them.
Example: "origin""768 4000 900" instead of "origin" "768 4000 90" (between "origin" and the vector)

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].
Hex Editor View of the bsp code

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, using less than five should not have any negative effect on the game. How ever if you are keen you can try it with more.

Hex Editor View of the bsp code


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.

Hex Editor View of the bsp code


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!

See to edit entities completly free of constraints, meaning you can add new entities, change values, etc. without having to keep the number of bytes the same.

Reply Good karma Bad karma0 votes
Chrissstrahl Author

Thanks I am probably going to try it out in the next few days

Reply Good karma+1 vote

I have been messing with this for some time but would have a followup question related to it.

For example lets say a map has a ladder on one side of a wall. I can successfully move the ladder by editing the coordinates but The ability to climb the ladder stays with its original position.

Is it possible to move the climb position also?

I have also successfully deleted objects from map (such as a row of barbedwire) but the space that it blocked remains.

As a side not I would emphasize that if you edit a map you should rename the entire map or we run the risk of creating a world of corrupted and conflicting maps with the same name.

Reply Good karma Bad karma+1 vote
Chrissstrahl Author

I suppose the climb part of the ladder is a brush, and they usually do not have their origin in plain text if I recall correctly, so you are not able to edit this with a simple hexeditor.

I think the issue originates from a additional bush or patch that has a clip/move/playerclip/ or what ever kind of clip texture. I know there is a way to make all of the textures work as you want them to, so you could remove that clip, but it would count for every brush/patch that uses the same clip texture.

Reply Good karma+1 vote

I manage to incorporate sd in a map without problem the problem is that it works well for the allies but for the Germans it can not defuse the bomb..
Insurance is a brush problem at the pump for that, but does anyone know how to change this?

Reply Good karma Bad karma+1 vote
Post a comment
Sign in or join with:

Only registered members can share their thoughts. So come on! Join the community today (totally free - or sign in with your social account on the right) and join in the conversation.

Related Games
Star Trek: Elite Force II
Star Trek: Elite Force II First Person Shooter
Related Groups
HaZardModding Developer & Publisher with 5 members
Star Trek: Elite Force II - Developers
Star Trek: Elite Force II - Developers Fans & Clans with 16 members