(Reposted from the Steam forum thread: http://forums.steampowered.com/forums/showthread.php?t=2703507)

If you've tried making a map of any significant size and complexity, by now most of you have probably run up against the infamous "too many items" error, which the editor shows you when it fails to build your level. There's a lot of confusion about what this signifies and how to fix it, so I thought I'd put together a post that would help people who might not be familiar with how the Source engine works and what the error means--written at a level that will hopefully be accessible to those without any game development experience. Those of you who do have that experience, feel free to chime in if anything I've written is egregiously incorrect, but keep in mind that I'm going to take some liberties with strict accuracy for the sake of simplification.


What does PeTI mean by "items"?
Items, in this context, is a simpler way of saying "entities", which is the name used in the Source engine (among others) for a type of object that is capable of behavior or interaction. They are called this to distinguish them from "world" objects, which basically means the geometry of the level: the ground, static walls, etc.


So why is there a limit?
I mentioned that entities can have behaviors assigned to them, right? These behaviors are processed using a special function attached to the entity, which defines the kinds of things it decides whether or not to do and under what conditions. At periodic intervals, the Source engine runs that special function to check whether or not the entity has any code it needs to execute--for example, to check whether or not a Turret can now see the player, or whether or not the player has pressed a button.

All that takes system resources--and lots of them! The Source engine has a hard limit to the number of entities it can handle, but long before it hits that limit the load of working through all those entities many times every second will start to slow down less powerful computers. Those of you with older machines can probably attest to this--it's one of the reasons why lasers tend to kill your frame rate; particles like the laser sparks are temporary entities spawned by the laser hitting an object. For a number of reasons, not least of which being kindness to those with slower computers, Valve decided to place a relatively low limit on the number of entities allowed in PeTI maps: 1750.


Wait, 1750? How do I keep hitting it? I don't have anywhere near that many items in my map!
When you drag an item from the left-side tab in PeTI and place it in your map, that item consists of one or more entities. Generally speaking, items with complex animations, behaviors or shapes are composed of more entities than simpler ones. For example, the rising stairs or the ceiling-mounted cube droppers--as cool as they are!--come with a steep hit to your entity limit. Even a seemingly simple item like a fizzler is more complex than you might think.


Okay, I get it. Sorta. But how do I fix it?
First, it's a good idea to get a sense of just how far over the limit you went. There's two ways to do this: the easy way, and the hard way.

The Easy Way
If you have the dev console enabled (it's in your Options menu), simply hit the key you've mapped to bring it up. The VBSP error that shows you what your entity count was should be right there in front of you, helpfully highlighted in red. If it is, you're golden; you can skip ahead to the [COLOR="Cyan"]Update[/color] where you'll find information on the entity costs of various items. If for some reason you can't access the dev console or you don't see the error, you'll need to find it...

The Hard Way
Fortunately, PeTI keeps a log of all the building activity it does--including when it fails. Let's go find that log.

What you want to do is open Windows Explorer and navigate to your Steam folder. The logs are located here:

%YourSteamInstallPath%\steamapps\common\portal 2\sdk_content\maps

Ugh, what's all that? You'd think they could name the log filenames to match the title of the map. Fortunately it'll be easy to find. This failure just happened, right? Then it's going to be the most recently updated file. Sort by the date modified and the timestamp should pop out at you. Most commonly it's going to be the file called "preview.log"--this is the log file PeTI uses when you're previewing the map in the editor. Open it up in your text editor of choice.

This is probably pure gibberish to most of you. That's okay. PeTI appends all new log information, so scroll (or use Ctrl-End) to the very bottom of the log. What you're looking for is a line that looks like this--you might have to hit PgUp a few times to find it:

VBSP: ERROR! '-entity_limit' exceeded (2257 out of 1750)

Ouch, I really blew that one, didn't I? More than 500 entities over the limit. That can happen faster than you think. Chances are you've got a lot of complex items in your map, like cube droppers, stairs, or lifts. You're going to have to get rid of some of them before you can build your map. So here's what I do: make a note of what your entity count is. Then start with what you think is the most complex item in your map, and remove it. Don't bother saving, just try to preview the map again.

It's probably going to bomb out, and when it does, you can Alt-Tab over to Explorer and re-open that log file. Find the last ERROR line again, and look at the number. The difference will tell you approximately how many entities you can cut by getting rid of that item--and that should tell you whether or not you can get back under the entity limit just by cutting more of that item. If not, you're going to have to look for other things to trim out. Repeat this process until you reach the magic number. If you only went over the limit by 15 or 20, your task is going to be easy, and that first item might've fixed it already. If you made a map like my example above, well... it's going to be a bit harder.

I know, it sounds like a real pain--and it is, especially if you have to wait a while to build the map preview each time. But it's the reality of the game engine and tool we're working with, and this basic troubleshooting process should at least let you salvage that map you've worked so hard on by taking a scalpel to it rather than a chainsaw.

I did some extensive testing in the name of Science, and I believe I've determined the entity costs for the various items with a high degree of confidence. One of the Portal developers posted in the Steam forum thread and confirmed that this information looks correct to him, so you can probably use it as a solid baseline.

As a test, I first tried adding incrementally more turrets, but I noticed that there was some variation in the entity usage of a given map from build to build which made my counts meaningless, even if I hadn't changed anything--which I suspect is due to minor variations in the entrance/exit chambers that the editor builds automatically (some people have reported that their count varies more than others). So I set out to determine a baseline from which to count everything else. What I found was that a modestly-sized rectangular room--anywhere from 2x2x1 to 25x25x5--with nothing else in it hovers right around 400 entities to start with, with some variation that puts it anywhere from 390 to a little under 410. That makes it hard to count individual items with any degree of confidence.

Armed with this knowledge, I started adding 20 of each item to that same 25x25x5 room. By using a multiple of 10 I could render the wildly varying ones place irrelevant, and by using a multiple of 20 I ensured that the correct number would always have an even number in the tens place. For items with very small values, I sometimes had to cross-reference this by using 40 items and comparing the two numbers to be certain of the count.

Based on this evening's experimentation, we can derive a number of generalizations about what you can alter to affect the entity count.

The following have NO effect on the entity cost of a map:

• Where you put the entrance, exit or mandatory observation room
  
• The location or facing direction of an object (except where it alters map geometry)
  
• Whether or not a floor/ceiling/wall is a portalable surface
  
• The length (not height!) of a light bridge, fizzler, tractor or laser beam (which are generated after the map loads--that's why you see/hear them turn on after you enter)
  
• Whether a contiguous panel of glass/grating is composed of a single large placed item or separately placed items joined seamlessly by the game
  
• Whether paint splats of the same color are a contiguous pool or separate splats
  
• Whether any moving object, emitter or dropper of any kind starts enabled/auto-drop or not
  
• How compressed or extended a lift is in its starting state
  
• How large a pool of goo is
  
• What kind of cube or sphere an item is
  
• Whether a floor button is of a type that reacts to cubes, spheres or weight
  
• Where the target of a faith plate is
  
• Whether a panel starts deployed or not

The following have a NEGLIGIBLE effect on the entity cost of a map:

• Minor variations in either map geometry or the size of a room of the same general shape

By negligible I mean you should generally worry about the items you've placed rather than the way you've shaped your map.

The following have a SIGNIFICANT effect on the entity cost of a map:

• How many items of a given type (except where mentioned above) you place in the map
  
• The number and nature of the connections you form between items
  
• Whether those connections are shown with blue dotted lines or matched symbols (the blue dotted lines which change color are themselves made up of entities, and can consume quite a few of them)
  
• The height of a fizzler or laser barrier emitter, if greater than one square
  
• Drastic and large-scale differences in the size or shape of your level

Item Cost Values
What follows are what I believe to be accurate entity costs for each placeable item, in descending order of cost and grouped by type:

Lifts: 44 (!!! watch out for these !!!)
Stairs: 13
Moving Platforms (vertical or horizontal, one square): 13 plus 1 or 2 (approximate) for each additional square of track
Faith Plates: 9

Cube Droppers (of all kinds): 33
Paint Droppers (of all kinds): 15

White Paint Splat: 9
Blue/Orange/Cleansing Splat: 8

Fizzlers: 5 base + 9 per unit height (including the first, so 14 for one-high, 23 for two-high, etc)
Laser Barrier Emitters: 14 (height changes not tested but probably similar to fizzlers)
Tractor Emitters: 8
Laser Emitters: 6
Light Bridge Emitters: 4
Laser Catchers: 4
Laser Relay: 3

Angle Panels: 13
Glass Panels: 12
Flip Panel: 8

Pedestal Buttons: 6
Floor Buttons (of all kinds): 3
Cubes and Spheres (of all kinds, including Franken): 4

Turrets: 3
Pools of Goo: 1

Decorative Light Bars: 3
Small Observation Window: 2
Grating: 2 per square
Glass: 1 per square

From this some general design principles can be stated, in terms of efficient use of entities:

• Complex, high-tech equipment with animated moving parts is ALWAYS going to be expensive
  
• Consider using faith plates or making the player portal if you don't specifically need to use a lift, moving platform or stairs
  
• If the player has no way of losing or destroying their cube, you DO NOT need a dropper--disable it to save a lot of entities
  
• It is cheaper to let the player spread paint than to place it yourself
  
• It is cheaper to use glass rather than grating if you do not need to a) expose the player to turret fire, b) allow the player to shoot portals or grab objects through the barrier, or c) allow gels/tractor beams/light bridges to pass through it
  
• Goo Pits are the cheapest hazard available, both because they themselves are cheap and because the pits you dig for them have little effect on the map's entity usage--turrets start adding up quickly
  
• You don't need to waste time replacing multiple panels of contiguous glass/grating with a single larger one--the cost is the same either way
  
• For a physical barrier or transparent walkway longer than 4 squares, light bridges are both cheaper and more compact than glass--their cost does not vary by length
  
• A pedestal button is more expensive than any of the floor buttons, but not once you factor in the cost of the cube/sphere to activate them (let alone the dropper if you need to use one)
  
• If you don't need a portal surface and don't care if the player sees through it, a glass angle panel is slightly cheaper than a regular angle panel. However, use caution if the panel is intended to move--glass panels are capable of fizzling objects and potentially even killing the player if blocked while in motion or touched on the wrong side/in the wrong way
  
• Consider using laser relays instead of catchers--they're slightly cheaper and you can chain them and use them in interesting combinations
  
• Decoration and lighting are cheap--use them to good effect!

If you want to learn more about entities in the Source Engine and aren't scared off by the prospect of wading through programming terminology, Valve maintains an outstanding developer wiki with a page that might help you understand this better:

https://developer.valvesoftware.com/wiki/Entity_limit

For those who don't, there's good news from one of the Portal devs, who posted in the forum thread:

Originally posted by "Tejeev":

"We are currently working on an update that will display the cost of each item as you place them into your map. This will be helpful in showing people what is causing their puzzle to go above the limit."

Update: Indicator Lights

The indicator light trails that change color and show the connections between test elements also consume entities, but determining their entity cost is not quite as straightforward. This is because the indicator lights are what is called a overlay--a special kind of decal that is "overlaid" on top of a surface and anchored to it using an entity called info_overlay. Normally overlays are static entities, which means they don't count towards the entity limit, but because the indicator lights change color, they need to be dynamic entities--which do count.


You can probably see where this is going. If you have a single long unbroken line of indicator lights that does not bend or go around a corner, it's probably one single overlay stretched out across that entire length, and thus is only consuming one entity over its length. But every time that line makes an "L", it's adding two more entities: the Aperture symbol in the corner, and the new line of indicator lights that continues beyond it.

Similarly, whenever an indicator line goes around a corner in the level geometry, one more entity must be used because the a new overlay must be added and attached to the new surface.

TL;DR: The more complex the level geometry the indicator lights have to wind around and the more bends there are in its path, the more the entities will start adding up.

Don't forget the "X" symbols beside the target, either--they change color when the source is activated, and thus each new connection consumes at least one additional entity for that overlay.

The glyphs on the white backgrounds, on the other hand, are static overlays--they do not change color, and do not count towards the entity limit. These glyphs replace the indicator lights whenever PeTI cannot draw a direct path between source and target--for example, if there are light bars or other objects blocking the path, or one is in the middle of an impassible hazard such as goo.

If all of this talk about overlays and indicator lights is confusing, I've put together a composite image that visually explains the relationship between indicator lights and entity usage[ayashi.net]. Hopefully it helps.

Happy Testing!