View Full Version : Working with entities - general techniques and thoughts

23-02-2015, 06:10 PM
Entities are what makes a map alive. Without entities, a map is just a set of walls, between which the players can bore themselves to death. I personally love working with entities, because there are so many possibilities, so many options to create an entirely new game-expirience. However, there are not many mappers who share my passion for entities and too many maps are beautiful to look at but very lifeless and boring.
The reason for this is, because entities are really cumbersome to work with. Many mappers find them complicated, cryptic or even scary. Thats why im sharing my knowledge and expirience with you on how to work more successful with entities.

Knowledge is the key
Use the documentation
There is a lot of documentation for entities on the internet. Unfortunately there is no comprehensive entity-guide for SC and most guides are also out of date. First you will need a guide for regular HL-entities such as the TWHL entity-wiki (http://twhl.info/wiki.php?sub=1). SC-entities are based on those so you also need the Sven Coop entity guide (http://zyl.pestermom.com/external/entguide/index.html) which only explains the SC-specific entities. It may also be wise to read the sticky-threads such as New entities and mapping features in SC 4.6 (http://forums.svencoop.com/showthread.php/39939-New-entities-and-mapping-features-in-SC-4-6) here in the forums (http://forums.svencoop.com/forumdisplay.php/44-Mapping) because they explain some of the new entities in SC in more detail.
Ask for help
Those guides are a good start but you will also have to ask more expirienced mappers here in the forum. None of these guides are complete, some of the information is plainly wrong or outdated and EVERY entity has some bugs and quirks that the guides don´t tell you about. Also the guides can´t teach you how to combine the entities to complex functions. Ask here in the forums, you can also always reach me on steam and ask directly.

Keep it tidy
Arrangement of entities
In the Hammer-editor you must give every entity its place which is good and bad. It´s bad because it makes no sense (why does a multimanager need a position inside the map, a text editor for all map scripts would be much better). But it is also good because you can arrange all your entities in a matter that represents their functions and their order. I usually have an extra entity-room where I put all my entities, except the ones that need a position (e.g. ambient_generic). That way I can oversee, select and edit them all without moving the camera around in the editor. Then I arrange them in groups, for example entities that trigger each other are placed next to each other. I position them like words in a text, meaning they can be read from left to right. The entity on the left gets triggered first, it then activates the others to the right. I use the second dimension (entites above or below an another) for logical branches (e.g. one entity triggers two others which each set off another chain of entities). Here is a picture of what my entity-rooms look like. Note that I also added colored brushes to mark groups of entities more clearly.
Choose descriptive names
You can name your entities "Harry", "lol" or "sfhasfasodfo" but you wont get very far that way. Use descriptive names. You should be able to tell the function of an entity, simply by reading its name. I usually use prefixes and suffixes for that. The prefix determines, what group the entites belongs to, the suffix shows what type of entities this is. In the middle I have extra information.
An example: I have a complex setup where a remote detonator sets of a bomb which collapses a wall. I have plenty of special effects, such as sprites, env_explosions and func_trains for flying pieces of debries. One of my entities is called "wallbomb_debrie1_pc3". Lets dissect this name: "wallbomb" is the prefix, telling me that this entity is part of the group wallbomb, obviously the group of entities for blowing up the wall. "pc3" is the suffix, saying that this entity is the third path_corner on a track for a func_train. And "debrie1" means that this path_corner belongs to a func_train named "debrie1"... actually the full name of that train is "wallbomb_debrie1_train".
I use suffixes for many entities such as: mm = multi_manager, cnd = trigger_condition, iter = trigger_entity_iterator.
Do you get the point? You don´t have to use my system but it definitely helps to put as much information as possible into entity-names.

Know what your entities are doing
One of the problems with entities is that most of them are invisible and you cannot observe them functioning. Which means, ingame you can only hope that they do their work and wait for the correct outcome. If you have a complex setups with dozens of trigger-entities you get problems. What if you don´t get the right outcome? What if your map doesn´t do what it is supposed to? Which of your 78 invisible, non-audible entities is broken? What you need is a way to control if your entities are functioning or not.
Use the console
The developer-console will output debugging-messages for some of the entities. You can switch between different debug-levels by putting "developer 1", "developer 2" or "developer 3" in console. The higher the debug-level is, the more of your entities will start spaming information into your console. With "developer 3" you console with be cluttered with hundreds of pages of debug-information. Unfortunatly there is no real way to filter this information. You may have to copy-paste your console into a texeditor and use the search function to search for specific entity names. It also helps to assign hotkeys to switch between different debug-levels so you can turn on "developer 3" one second before your entity-bug occurs and switch it back to "developer 0" on second later. That way you will have much less text to go through.
Unfortunately this debug system is very inconsistent. Some entities will provide lots of information via the console, most entities will give you very little or no information at all (HINT HINT! Devs do something about it!).
Use game_text
The more powerful and dynamic way is to create your own debug-system with game_text. With that entity you can display your own debug-information ingame.
Example: You have a button and a door in your map. The button is supposed to open the door. However, as you press it nothing happens. How do you know which entity is broken? The button or the door? Simple: just add a game_text with the same name as the door. Now the button should trigger the door and the text. After pressing the button, if the text shows up but the door doesn´t open, the door is the problem. If the text does not show up, then your button is the problem.
Of course this example is silly, because with only two entities it is much quicker to check both their settings and find the error. However, once you have a complex setup with dozens of triggers, relays, branches you will want to know at what point the map is broken. Add a couple of game_texts saying "button was pressed", "multimanager has been triggered", "trigger condition says TRUE", "door should be open now". Now you can check ingame what your map is doing. (Dont forget to activate "All players" on the game_text).

It gets even more elegant when you start using custom_keyvalues. I already explained how to use custom keyvalues (http://forums.svencoop.com/showthread.php/41343-Entities-How-to-use-keyvalues) to make your map even cooler. But you can also use these techniques for advanced debugging. You can copy the keyvalues of one entity to a game_text and then display that information ingame. This is very useful if you have complex mathematical systems in your map (e.g. money system - 20 credits needed to buy weapons - why the hell does it not work - simply check by copying all the relevant information to game_texts and then display it on screen).

Test early, test often
Use onlyents
Ok here comes the most important part of this entire tutorial. To make changes in your bsp you must recompile. Compiling takes a lot of time, depending on the complexity of your map. If you have to compile 30 minutes everytime you change one entity, you will get frustrated very quickly (or slowly...). Thats why you need onlyents. This is a compile mode where only the entities in your bsp are updated and everything else is left untouched. Compiling with onlyents takes no more than 5 seconds.
You will find some documentation on the internet, saying that onlyents is unsafe and will break your map, but in my experience (using it for more than a decade) it works perfectly fine and even vluzacn, our compiler-god, recently confirmed that it is safe. (http://forums.svencoop.com/showthread.php/41671-Whats-the-deal-with-onlyents) While I sometimes had the feeling that onlyents caused funny troubles, it never caused any permanent damage. If in doubt, you can always do a full compile and the map is back to normal.
To compile with onlyents, simply hit "Run map" in Hammer, deactivate all tools except csg and switch csg to "Entities only". Remember that you must have done at least one full compile before this works.
So what changes can you make to your map with onlyents? You can add, delete or modify ALL point-based entities in your map. Obviously changing or adding light entities does not make sense because you must compile with rad to make changes to lighting. When it comes to brush-based entities, you can change their settings but you must not change the brush itself in any way, nor may you add or delete brush based entities. Editing world-brushes is also a no-go. Failure to follow these rules will result in your map being either unloadable or behaving very strangely.
Step by step
When adding more entities to your map, add only a handful and then test if they are working correctly. This is where onlyents comes in very handy. If you add 50 entities at once and it is not working then you will loose more time figuring out where the error lies than when you had tested it several times before. Some more complex map features require dozens of entities working together perfectly. The idea that you can add 50 entities without any errors such as typos is simply illusionary. I ALLWAYS make stupid errors when adding new entities. The only way to identify and fix them is by testing the map early. If you think you can not test your entity setup before it is complete because it does not create any visible results before the end, remember what I earlier said about game_texts. Add some game_texts that give valuable feedback such as "Phase 1 of super-complicated entity-frankenstein has been completed successfully!!!1".

It´s hard work
Working with entities is hard work. I spend at least the same ammount of time on my entities as I do on brushwork. You can set your priorities as you like but in my opinion a beautiful map with boring entity work is a waste of time and resources.
Trial and error
Now with all the nice techniques and tricks I tought you, you must be thinking "Working with entities is easy! Nothing can go wrong." Well unfortunately everything can and WILL go wrong. With all my knowledge and experience, entities still frustrate and perplex me everyday. Most problems I only solve by using trial and error: map does not work -> make changes even though they dont make sense -> still no luck -> more changes -> map unexplainably works now. The reason for this is that the Half-Life code is very.... creative in many ways and every entity has oddities and glitches that are not documented anywhere. They will surface, once you start using them in a non standard fashion, once you try to bend them according to your will. This is where you must prove your endurence and keep trying until the map does what you want. With a strong will and enough stayingpower you can torture entities until they break and and act as you like.
When stuck, take a break
With all that said I can guarantee you that you will get frustrated and you will be completely stuck. At some point you should just stop and take a break. Attend to other matters of life. Funnily enough the solution for my mapping problems usually pops up in my mind 5 minutes after I have left the house.

14-06-2015, 09:17 AM
This is Gold!Thanks for this Middleman - for years I believed mapping was beyond my level of skill, but as an Electronics person, I am really interested in the entities and their structure within complex maps, and your tut is very insightful. The system you outline it is the same process used in successful circuit design, especially for complex asynchronous state machines.. you can really lose control if you just have a great ball of spaghetti - logical structure, thoroughness and frequent testing with key point feedback is essential.

Very nice work! :D