Map Modding

A guide to map modding, AKA entity hacking. Written with Jedi Academy in mind, but applies to most games based on the Quake and Source engines.

About

Also known as entity hacking, map modding involves modifying the default set of entities that are included in a map. This technique is popular because it allows the alteration of maps for functionality or esthetics, without requiring players to download a new map. Customarily, this technique only allows the addition, removal, and alteration of entities. While brush modification is theoretically possible, it is difficult and extremely prone to errors, and the results likely won't be what you were hoping anyway.

Entity hacking is possible and practical because of two facts:

• Entity data is only used by the server. It does not matter what the entities a player has in the BSP file on his computer. When a server loads a map, the server will read the entity data from its own BSP file, and then it will tell the clients about the map's entities. This ensures that everyone on the server has the same set of entities.
  
  
• Although the map's brush information is stored in compiled binary form within the BSP, the entities are stored in plain text (human-readable) form. If the entity definitions weren't plain text, it would be harder to edit them, and if they weren't independent from the compiled brush data, a new BSP would have to be compiled, requiring players to download a whole new map.

If you are at all concerned about the legality of this, you can read more here[www.holonet.antarat.com]. Suffice to say, this doesn't violate any EULA or Terms of Service.

What You Will Need

• The BSP file of the Map you wish to edit
  This will commonly be found in one of the game's PK3 files.
  To create or extract files from pk3's, either use WinRar, WinZip, or pakscape.
  
  
• Compiler
  The easy way to acquire this is by downloading GTKRadiant, which includes the q3map2 compiler at the GTKRadiant Website[icculus.org]
  
  
• A text editor
  Notepad will do, Wordpad is better and easier, but if you're going to do this often, you'll want a more sophisticated text editor, such as RJ TextEd[www.rj-texted.se] or Notepad++[notepad-plus-plus.org].
  
  
• JA Multiplayer Map Entity Reference
  Available here[www.antarat.com], also see the Quake Wiki entity guide[quakewiki.org].
  
  
• Quark (Optional)
  Some people have a hard time extracting the entities from the BSP. To them I recommend QuArK, which can extract the entities for you (among many other things beyond the scope of this article). QUARK Website[quark.sourceforge.net]
  
  
• Some familiarity with using the command line
  For those of you using Windows, a good guide can be found at http://commandwindows.com
  
  
• The Game
  Yeah.

The Procedure

For a quick and dirty explanation, you're basically going to grab the entity data from the BSP, make your changes, then recompile the new entities into the BSP.

Step by Step:

• Get the BSP
  
  If the BSP is in a PK3 file, you will need to extract it. Always make a copy of the BSP and edit that, do not overwrite the original. Whenever doing any kind of mod, you should always work in such a way that all you have to do is remove your mod, then your game (and maps) should be just as before.
  
  
• Extract the Entities
  
  You will need the current entities because when you make your changes later, all of the current entity data will be replaced, so the best thing to do is to grab the current entity set and work off of that. Anything you don't want to mess with, you can just leave alone and it'll go right back in the map as before.
  
  As mentioned above, you can open the BSP file in a text editor or Quark. In a text editor, you'll see a lot of garbled illegible symbols and such, this is the compile binary brush data, ignore it. You'll know the entities because they'll be the part that is human-readable, with { curly brackets } enclosing each entity definition (you will want to keep these brackets intact).
  
  In Windows, some of the simple text editors like Notepad don't recognize the line ending characters, and replace them with little rectangles. You can either fix this after you paste it in the next step or use your text editor. Linux users should have no trouble in any text editor.
  Copy and paste the entities into a new blank text file. Save this file as a .ent file with the same name and in the same directory as the BSP file.
  
  
• Edit the Entities
  
  Use the entity reference and the Best Practices below as your guide and start making your changes.
  
  If you are new to map modding, I recommend skipping this step for now (or at least not doing anything major), to make sure you understand the complete process before actually changing anything. Often beginners will start editing right away, and this leads to problems if they run into errors, because they don't know if the map would've compiled to begin with, or if they extracted the entities incorrectly. They can't tell if the errors they get are due to the changes they made or something that was there before.
  
  When you're ready to start making changes, I'd suggest starting small. First just try modifying what is already there and see how things change, then move on to more complex stuff when you're comfortable.
  
  
• Compile the Entities back into the BSP
  
  Before you start, make sure that both the entity file and the BSP are in the same directory as your compiler, usually this is the GTKRadiant directory.
  
  The word compile is a bit misleading here. I say "compile" because you will use the compiler, but you're not really compiling, you're just using a feature of the compiler to fold the new entities into the pre-compiled BSP.
  
  Open up a command-line terminal, navigate to the appropriate directory, then run the Q3Map2 compiler using the -onlyents switch. For example:
  
  

  q3map2.exe -v -game ja -fs_basepath "YOUR_PATH/Jedi Academy/GameData/" -fs_game base -onlyents MAP_NAME.ent
  

  
  
• If the Compiler Returns Any Errors, Fix them then try again
  
  For people having problems with this, here is an alternative method created by BobaFett, a compile script.
  
  To use it, open notepad, and copy/paste the following code:
  
  

  @echo off
  cls
  title Entity Recompiler - Wrapper made by BobaFett
  echo q3map2 entity recompile wrapper
  echo by BobaFett
  echo.
  m:
  cd X:\Program Files\GtkRadiant 1.5.0
  q3map2.exe -v -game ja -onlyents %1
  echo.
  echo Compiling finished, press any key to close this window
  pause>nul
  

  
  Change the 'cd X:\Program Files\GtkRadiant 1.5.0' line to reflect the location of your GTKRadiant directory. Save it as EntityCompiler.bat and put it in your GTKRadiant directory (where the compiler resides). To use it, simply drag 'n drop the entity file into the script and it will automatically start the compiler
  
  
• Test the Map
  
  If you followed my recommendation, you should still have the normal version of the map installed. We are not going to mess with it, we simply want to make sure that the game uses the modded map instead. The easiest way to do this is to put the BSP in a PK3 file, mirroring the directory structure of the original (so if the original is in /maps, put it in a maps folder, if its in /maps/mp, follow suit) then put this pk3 file in your base folder. A PK3 file is basically just a zip file with the PK3 extension. The game loads the PK3 files in alphabetical order, so make sure that the name of your PK3 file comes after that of the original map. The standard JA maps are in the asset files, so this normally won't be a problem.

Proper Syntax

Each entity has the following structure:

{
"property 1" "value 1"
"property 2" "value 2"
"property 3" "value 3"
}

Please note the following:

• The curly braces must be on separate lines, {"property 1" "value 1"} is not allowed and will cause compiler errors.
  
  
• Each line can contain either an opening/closing brace, a property, or a comment (preceded by //), these cannot be combined, therefore you cannot place comments after properties or after braces or put multiple properties on one line.
  
  
• Comments can be places either in between entities or inside entities as long as they're on a separate line.
  
  
• Properties must be enclosed in quotations, and each line must contain exactly 4 quotation marks, no more, no less. Please note that the compiler doesn't always detect quotation errors, but the server will, and that will result in a fatal error.
  
  
• Each entity must have a classname property, which defines which entity it is, invalid classnames won't cause errors, but will simply result in the entity not spawning and a warning in the server console.
  
  
• The properties that can be used for particular entities are listed in the Entity Reference linked above.
  
  
• A very important thing to realize is that worldspawn MUST be the first entity of a map, or the server will crash (well, get a fatal error) when loading the map.

Techniques

Got the hang of it? Ready to move on to more advanced things?

• Worldspawn Editing
  
  In every map, the very first entity is the worldspawn. This entity is essential to the functioning of the map, so editing most of its properties is not recommended and may produce unstable results. Editing the "message" key, however, can be done easily. This allows for the title of a map as it appears on the loading screen to be changed in any way, including the use of color codes. Worldspawns also have a "music" key that can be edited at will, but remember that if the music file referenced is not something that all clients have, it will not be heard by those clients who do not have it.
  
  
• Boons
  
  In this context, boons refer to the technique of using item entities as generic trigger relays to add additional functionality to a map. This technique was developed by Jahandar with Boba Fett as a way to add additional triggers without being able to add new trigger brushes, and the first map to feature it was Jahandar's modded T3_Byss[www.antarat.com]. The technique is named after the item_force_boon entity which is item most commonly used for this purpose. Other commonly used items are item_jetpack and item_ysalimari. The way to do this is to specify a target in your entity then set up the entities with that targetname. When the entity is used, it will call its target, and each of the entities with the given targetname will be activated. An example may better illustrate this.
  
  Note: Powerup items (force boons and ysalamiri's) create a global respawn sound when respawning, which canbe very annoying. If you use powerup items, disable respawn sounds using "noglobalsound" "1" (this setting is undocumented).
  
  
  

  {
  // This entity is the actual boon that the players see. 
  // When a player touches it, any entity with the targetname "msg_MapInfo1" will activate.
  "classname" "item_force_boon"
  "target" "msg_MapInfo1"
  "wait" "4"
  "origin" "180 -334 109"
  "count" "-1"
  "noglobalsound" "1"
  }
  {
  // This entity displays a message to the player's screen whenever activated
  "classname" "target_print"
  "targetname" "msg_MapInfo1"
  "spawnflags" "4"
  "message" "Hey, quit grabbing my boons!"
  }
  

  
  Here is a more advanced example, showing a boon used to teleport a player:
  
  

  {
  // Teleporter Boon
  "classname" "item_force_boon"
  "target" "teleToDisneyworld"
  "origin" "1039 1470 700"
  "count" "-1"
  "wait" "4"
  "noglobalsound" "1"
  }
  {
  // The teleporter activated by the boon
  "classname" "target_teleporter"
  "targetname" "teleToDisneyworld"
  "target" "teleToDisneyworld_spawn"
  }
  {
  // Message displayed to teleported players
  "classname" "target_print"
  "targetname" "teleToDisneyworld"
  "message" "I'm going to Disney World!"
  "spawnflags" "4"
  }
  {
  // The teleport destination
  "classname" "target_position"
  "targetname" "teleToDisneyworld_spawn"
  "origin" "1247 1740 858"
  "angle" "0"
  }
  

  
  Note that whenever using boons on a server with force disabled, you will need to use a small script to allow boons to be displayed. This script should be run by the server immediately after the map is loaded.
  
  

  // Enable Boons
  set g_forcepowerdisable 0
  map_restart 0
  wait 10
  forcetoggle 0 // Heal
  //forcetoggle 1 // Jump
  forcetoggle 2 // Speed
  forcetoggle 3 // Push
  forcetoggle 4 // Pull
  forcetoggle 5 // Mindtrick
  forcetoggle 6 // Grip
  forcetoggle 7 // Lightning
  forcetoggle 8 // Dark Rage
  forcetoggle 9 // Protect
  forcetoggle 10 // Absorb
  forcetoggle 11 // Team Heal
  forcetoggle 12 // Team Replenish
  forcetoggle 13 // Drain
  forcetoggle 14 // Seeing
  //forcetoggle 15 // Saber Offence
  //forcetoggle 16 // Saber Defence
  forcetoggle 17 // Saber Throw
  

  
  
  
• Brush Trigger Manipulation
  
  When modding maps, it pays to be resourceful. If the trigger brush's original function is no longer needed, you can alter it to do something you want. You can tell which entities are tied to brushes because they will have a model property that is set to a number preceded by an asterisk, like *23.
  
  While this technique can yield great results, it can be difficult for beginners because identifying which brush out of the thousands is referred to by a given model value can be troublesome. Jahandar's T3_Byss[www.antarat.com] map is one that has made use of this technique, if you'd like to view an example.
  
  
  
• Model Placement
  
  In order to place models (md3) files on your map, you'll have to 'abuse' health dispensers. Now, i see you asking why, which is logic. I'll tell you why: health dispensers are one of the very few entities that let you pick the model to display.
  
  Now, of course, health dispensers will heal you, so in order to fix that, you have to disable the health dispenser. The best way to do this is with an Icarus script that set SET_PLAYER_USABLE to false, and assign it as the spawnscript of the health dispenser. Keep in mind that the health dispensers come with their own fixed-size hit-box, which cannot be changed. So making models solid may, depending on the model you're using, be quite difficult.
  
  The entity for a health dispenser is misc_model_health_power_converter.
  
  
  

Advanced Techniques, Part 1

• Brush Duplication
  
  This technique allows you not only to alter existing brushes, but also to create new brushes by copying existing ones. This is done by creating a new brush-entity using an existing brush (noted by "model" "*<number>" as explained above). To move the brush, simply specify an origin. This origin has to be the RELATIVE position of the brush. An origin of 0 0 20 will place the new brush 20 units above its original location.
  
  This technique can be used to make new trigger brushes, or new doors. The new entity does not have to be of the same type as the original one. If you create an invisible entity (like a trigger_multiple) out of a visible brush (func_door for example), the brush will still be invisible and non-solid, despite the fact the original was solid. An example of this technique can be found on Seto's FFA3 map. Boba Fett has also been known to make use of this technique on some of his maps.
  
  
• Shader Remapping
  
  This technique lets you change shaders. Allowing you to make things look different, or even have things 'disappear' (only visually). Examples of the uses of shader remaps, would include displaying video's on 'TVs' (models/map_objects/rail/view_panel.md3 for example), or making lava disappear (or even change into something else). Please note that remapping shaders that contain a lightmap, might cause odd results. To do a shader remap, you need an entity that can trigger its targets, because a shader remap will only be triggered when the entity with the shader remap info wants to trigger its targets (Note: when it triggers its targets, not when it gets triggered!). For this reason, the best entity to use for this would be a target_relay, as it triggers its targets when it gets triggered, making it easy to control.
  
  The entity needs to contain two keys in order to do a shader remap: targetShaderName and targetShaderNewName, the first one being the original shader, and the latter the new one.
  To change a remap again, use the original shader name again. To illustrate: If you remap shader A to shader B, and you want it to remap to shader C, remap A to C, and not B to C
  
  
• Icarus Scripting
  
  Jedi Academy supports sequence scripting for both singleplayer and multiplayer using Icarus II. Please note that Icarus was developed for singleplayer only, and in multiplayer, its capabilities are very limited. BobaFett has been known to use Icarus scripting on his map mods frequently, and these provide the best samples to learn from.
  

Advanced Techniques, Part 2

• BSP Insertion
  
  One of the least used yet powerful entities in JA is the misc_bsp entity, understood largely thanks to Seto; his FFA3 map is a good sample to learn from. This entity allows for the placement of complete BSPs into another map at the specified origin, essentially allowing you to place a map within a map. Complete and proper usage of this technique is fairly complicated, however, so the following information must be kept in mind when attempting to use misc_bsp in your map mods.
  
  
  • The selected bspmodel is treated as one giant bmodel entity (like func_static), plus every additional entity contained within the map. Because of this, every misc_bsp added will increase your total entity count by the number of entities contained within the chosen BSP plus one for the misc_bsp bmodel itself (see Important Limitations below). Furthermore, since the entities from the misc_bsp are not originally a part of the base map you started with, the q3map2 compiler will NOT show the correct number of entities in your map. The number shown will always be lower than what you really have, so it is easy to exceed the max entity limit without realizing it.
    
    
  • Misc_bsps can be placed in the void outside of the normal map boundaries, but in order to successfully do so, you must locate "portaled void" first. This refers to a property of the voidspace that creates areaportals, which allows for the normal rendering of entities. If the misc_bsp is not placed within a region of portaled void, the entities contained within it will not show up in game. Generally, portaled void appears several thousand units away from the base map's boundaries and can be located by using noclip to fly far away from the map into the void, and then activating your saber. If you hear the sound of your saber activating, you are within a portaled void region; otherwise, you must keep looking. BSPs can also be inserted within the boundaries of the base map, but care must be taken to avoid creating architectural conflicts.
    
    
  • The areaportal void has a distinct visibility radius that impacts the size of bspmodels that can be used. This concept can be understood by imagining a large sphere around the player that moves with the player: every entity that has its origin inside the sphere can be seen by the player, while every entity that has its origin point outside of the sphere cannot be seen at all. Since the misc_bsp is treated in part as one large bmodel entity, this means that if the origin point of the misc_bsp is at any time outside the visible radius of the player, NONE of the bmodel will be rendered, even if you are inside it at the time. Because of this, using large BSPs as your bspmodels is not recommended, as they will undoubtedly become nonfunctional in certain places.
    
    
  • Under normal conditions, the misc_bsp's associated skybox will either conflict with the base map's skybox, or not render. If the misc_bsp has a skybox and is placed within the boundaries of the normal map, the two skyboxes will conflict in a way akin to z-fighting, unless a sufficiently large space is provided for the misc_bsp. If placed in the void, the misc_bsp's skybox will appear as void itself. To remedy this, a misc_skyportal entity must be used, which will cause every skybox to be the same. Misc_skyportals are placed at any location on the map, and they then take a 360 degree snapshot of their surroundings which then becomes the universal skybox at any location, even in voidspace. For this reason, the optimal base maps for using misc_bsps are those that were designed for and already contain a skyportal entity, such as duel6, duel9, t1_danger, t2_rogue, t3_hevil; though a skyportal could be manually placed within any map. Additionally, if the misc_bsp entity also contains a skyportal as part of its bspmodel entities, the skyportal that appears last in the base map entity list will be the one used in game (so if your misc_bsp comes after the original misc_skyportal and is placed in the void, the sky everywhere will be void).
    
    
  • The targets and targetnames of entities within the inserted BSP are changed as a result of being used in a misc_bsp. This means that you cannot normally have an entity in your base map that is linked to an entity from the misc_bsp. However, Icarus scripts can be used to set targets or targetnames to get around this, if needed.
    
    
  • Bmodel entities from the misc_bsp can still be manipulated as normal, but the bmodel IDs will be changed. If the base map contains any bmodel entities, the first bmodel entity from the misc_bsp will take on the bmodel ID number that follows the last one from the base map. In other words, bmodel IDs from the misc_bsp add to the bmodels from the base map. BobaFett's Ultra Utility is capable of recognizing the accurate bmodel ID from misc_bsps. Once the bmodel ID is known, manipulation can occur as normal, and as a bonus, the bmodels from the misc_bsp act as though they are centered at (0 0 0), making placement, movement, and rotation easy. At certain times, however, a glitch may occur in which bmodels from inserted BSPs take on undesired surface parameters, such as surface slickness, which may cause problems in map functionality. If this problem occurs in your map, reload the map repeatedly until the problem disappears.
    
    
  • Spawnpoints from the inserted BSP will be used in addition to spawnpoints from your base map, so the player will spawn by default at any spawn entity present, regardless of whether it comes from the base map or the misc_bsp. There are a number of ways to prevent players from spawning within the misc_bsp if that is desired, but in order to preserve the integrity of the misc_bsp so that it can still be played separately as a solo map, you must either place triggers on every undesired spawn location that will teleport the player elsewhere, or use scripting to set the target of the undesired spawnpoints to a teleporter. This step can be tricky and may be somewhat difficult to fully understand initially.
    # Every misc_bsp used will increase the overall loading time of the map by, on average, a few seconds. This is not normally a major issue but is still important to keep in mind, especially when considering clients who may have a slower connection or otherwise require more time to enter a map.

Limitations

• The server can only handle 1022 entities at any time! Any more entities will cause the server to get a fatal error. Entities that are not spawned on the server (info_null's, misc_model(_static)s, pickups that aren't spawned due to settings.. etc) do not count towards this limit as they're not spawned and therefore don't take up slots.
  
  
• Snapshots contain up to 1024 entities, which is no problem, but only 256 are sent to cgame for processing. Meaning if any area contains more than 256 entities, entities will start disappearing. This includes event entities! The results of this are for example: no more kill messages, NPCs disappear, no projectiles are seen, grapple (JA+) disappears and has no sound, entities disappear. If you happen to be in an area where you touch many viewportals, this can happen easily if you added a lot of entities. However, try to avoid these overflows at all costs!
  
  
• It may sound illogical, but if you use 'external resources' (sounds, effects, models.. etc) only use files that are in the assets, or, if you edit a map made by someone else, only the assets and the files that come with that map!

Tips

• Make notes, comments, whatever you need to keep track of what is what in your mod, so you can come back to your work in a year and still know your way around.
  
  
• Use a clear, logical naming scheme for your mods. This will help you keep track of your work. For instance, I could have JahMap_FFA3_v1.pk3, JahMap_FFA3_v2.pk3, etc. This keeps everything clear and also allows you to simply place any new versions in the base directory. You won't have to remove the old one, because the newest one will always be loaded last.
  
  
• Use logical target names. Target names like t32 are hard to keep up with, notice in the boon example I used the targetname msg_MapInfo1, so I can instantly see that the involved entities are related and are used to print a message with information about the map.
  
  
• Study other people's work. Using other maps as examples is a great way to learn.

Best Practices

When modding maps, here are some good guidelines to follow. Doctors follow the Hippocratic Code, which states "Do no harm," I think that applies here as well. Some of these may be a bit subjective by their very nature.

• Watch the FPS
  
  Remember that everything you add to the map is going to effect performance. Be careful what you add, and make sure it doesn't create too much lag. Test it with other people to get an idea of how your changes effect different people with different (often older) systems. JA is a relatively older game, so many of the people playing it don't have top of the line computers. Keep that in mind.
  
  
• Eye-Candy Overkill
  
  I know how it is, you've just learned how to mod maps, so you're anxious to impress the world, and show everyone what you can do, but please try not to go overboard. Excessive use of effects and other eye-candy looks tacky and causes lag. Before adding anything, ask yourself: How it will improve the game? Do the benefits outweigh the costs? Will people still appreciate this after the "coolness" factor wears off?
  
  
• Don't Interfere with Gameplay
  
  I know they can be fun once in a while, but try to avoid adding things that will interfere with normal gameplay, like airstrikes, eruptions, passage/area blocking, etc. It is very annoying to be interrupted and killed during a duel because someone triggers an eruption. And IF you decide to add something like this anyway, give the people on the server a warning and enough time to reach safety. Otherwise it will only annoy people.
  
  
• Fun For All
  
  Don't divide people into haves and have-nots. Yes, there are some things better off reserved for clanmates and admins, but overall try to focus on things that everyone can enjoy, not just a few people. New things you add will depend on what it is you're adding, so I grant that, but you should definitely have a good reason for taking away something (or some place) that players are accustomed to having.
  
  Something you can do, however, is to make a control room for admins, which affect things on the map availible for everyone. For example.. making a switch to make the lava on taspir safe to walk in. The lava is open for everyone, but the switch only to admins. But make the control room in a place which was normally not open to people anyway, instead of locking an area for it.
  

Credits

This guide was adapted and evolved from one that I (Jahandar) originally wrote on the JA Holonet Wiki[www.holonet.antarat.com] with very valuable contributions by Boba Fett[www.ultra-utility.com] and Seto[www.holonet.antarat.com]. They've both had some amazing projects over the years, and I encourage you to check out their work. Special thanks to them and anyone else who helped learn, collect, and explain this information.

[Synapsenklatsche]

Thanks m8

[draxman76]

Epic.