Lesson 11 - Adding Custom Entities to BSP

Now that Quake, Hexen2 and Quake2 have been out for a while, people are turning their attention to adding new monsters and weapons to the game, instead of just making levels. As a result, I get a lot of email asking about how to add custom entities to BSP, so you can use them in your maps. Hopefully this lesson will provide you with all the information you need.
The first thing you need to understand is what kind of information you need about the custom entity. Fortunately, it's not much. If you are making the entity yourself you'll have this information. If you are trying to use an entity made by somebody else, you may need to contact the author of the mod to get the information you need.
Basically the only information you need in order to let BSP work with the entity is:

- The name of the entity. This is the name of the function that controls then entity in the QuakeC/DLL source code. An example would be 'monster_superbadass'.
- The size of the entity's bounding box. This is the information that BSP needs in order to draw out the entity in the 3D and 2D editing windows. For example, your 'monster_superbadass' might be 82 units high and occupy 48 units on the X and Y axes. If you can't find this information anywhere, load the mdl file into a program like qME and see if it can tell you the info.
- What spawnflags the entity can have applied to it. These are things like 'silent', 'start_on', etc. and show up in the spawnflag boxes in the BSP entity window.
- The 'help' information for the entity (optional). This is usually any comments which are included in the source file so people will know how to use the entity. This information shows up when you click the '?' button on the entity window.

Now, armed with that information, what do we do with it? BSP reads it's entity information from a .qc file (or direct from the source files if you have it configured that way). For adding custom entities, it's easiest to use the .qc file. For Quake2, you'll want q2ents.qc; for Quake1 you most likely will use full4.qc; and in Hexen2, it's h3ents.qc. Of course you can make your own if you want and add it to the list of qc files that BSP loads (this is in the game.ini file for whatever game you happen to be working on). It's really up to you.
Whatever file you use, open it up now in Wordpad or some other text editor and look at an entity. You should see something like this:

> /*QUAKED monster_gladiator (1 .5 0) (-32 -32 -24) (32 32 64) Ambush Trigger_Spawn Sight
> ...may be some comments here...
> */

Now let's examine this statement. First of all, the /* and */ are critical. They delineate the beginning and end of the entity definition. The QUAKED is also required, but it's not used by BSP.
'monster_gladiator' is the name of the entity. (1 .5 0) is the R G B triplet for the color you want the entity to be in BSP's editing windows. Legal numbers are 0-1 representing the RGB value to be used for displaying the entity's bounding box.
(-32 -32 -24) (32 32 64) - this represents the size of the bounding box. In this case, the entity is 64 x 64 on the X/Y axis and 88 units high (64 + 24). The numbers are given from the origin point of the entity, which is determined by the mdl file (I think). This is for fixed size entities. However some entities are variable size (like triggers for instance). In that case replace '(-32 -32 -24) (32 32 64)' with '?' and BSP will take the size from whatever seed brush you are using to create the entity.
'Ambush', 'Trigger_Spawn', 'Sight' are spawnflags you can set. These need to be listed in order with each one being assigned the next progressive number in bit-wise progression. For instance in our example, 'ambush' is 'spawnflag 1'; 'trigger_spawn' is 'spawnflag 2'; 'sight' is 'spawnflag 4'; etc. Legal spawnflags for entities are 1, 2, 4, 8, 16, 32, 64, 128, meaning you can have 8 spawnflags for a particular entity.
Believe it or not, that's all there is to it. Save your file as a plain text file and fire up BSP. Your custom entity should display in the entity window now. Oh, by the way, the other information after the first line and before the closing '*/' is what gets displayed in the help screen on the entity window. You can put anything you like in here, but most people usually put legal key/value pairs that can be added to the entity along with any other information you might find useful.
Well, that's about all there is to it. Hopefully this will help you get custom entities up and running with BSP so you can make those kick-ass mods and TC's that we all love to play! Have fun!
| Return to the BSP Tutorial List | Return to the Main Page |

This site is designed for 800x600 resolution, and is best viewed in Netscape 4.0 or above with 16bit color or higher.
BSP is the sole creation of Yahn Bernier. I am only a dedicated user, reporting news and making tutorials so Yahn can spend more time enhancing BSP.
This web page was created and is being maintained by me (DeadMeat). Unless otherwise noted, all content appearing on this site was written by me. Also, 'DeadMeat's BSP Tutorials' were created entirely by me. All unauthorized use is prohibited. (c) 1997. So there :-P