Go Back   Steam Users' Forums > Steam Game Discussions > M - P > Portal 2

Reply
Click here to go to the first staff post in this thread.  
Thread Tools Display Modes
Old 05-15-2012, 01:01 PM   #1
Catsy
 
 
 
Join Date: Sep 2011
Reputation: 83
Posts: 340
Lightbulb Too many items error: what it means and how to fix it

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 (or if you know precise entity counts for the items placed in PeTI), but keep in mind that I'm going to take some liberties with strict accuracy for the sake of simplification. If you're already experienced at working out of Hammer, chances are you don't need this post.


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? Each type of entity has specific behaviors unique to it, can be told how to talk to other entities when something specific happens, and can also have custom behavior using a special "think" function attached to the entity--all of which define the kinds of things it decides whether or not to do and under what conditions. At periodic intervals, the Source engine checks to see 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 or behaviors are composed of more entities than simpler ones. For example, the rising lifts 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, because there are different entities that do things like detect when an object passes through them, or receive and process input from buttons attached to them. A pane of glass, on the other hand, is just a simple transparent object that clips (blocks) certain others objects from passing through it.


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 Update 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 going to look like 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 PageUp 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 pain in the --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.

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

Update: Item Costs

I did some extensive testing in the name of Science tonight, and I believe I've determined the entity costs for the various items with a high degree of confidence.

As a test, I first tried adding incrementally more turrets, but I noticed that there was some small 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. 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 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 single connected pool of goo is (unless for some reason you dropped more than one goo hazard object in the same pool--delete the extra!)
  • 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, each of which will add at least two (and likely more) new pairs of entities
  • Whether those connections overlays take the form of blue lines (expensive) or symbols (cheaper)
  • 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--which can alter the way connections are drawn or result in the automatic placement of additional ambient light entities

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 (!!!)
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 paint/gel/tractor beams to flow 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--but be aware that glass panels can sometimes fizzle objects or kill the player if something is trapped on the wrong side of them
  • 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!

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. Hopefully it helps.

Happy Testing!

Last edited by Catsy: 06-04-2012 at 08:56 AM. Reason: new info
Catsy is offline  
Reply With Quote
Old 05-15-2012, 01:21 PM   #2
erlandssonh
 
Join Date: May 2012
Reputation: 54
Posts: 222
Cool article, am I wrong or did I miss any tips on how to keep the entity count low?

Would be nice if the editor kept a count and replaced the lefthand menu with a message when the limit is hit. I'm sure the devs wouldn't find it hard to do so I think we'll see it

But advice on how to keep the count low or at least a tally list of "heavy" items would be cool. Maybe it's on the Wiki? (Wiki page there seemed to say 4096 as limit... hm.)
erlandssonh is offline   Reply With Quote
Old 05-15-2012, 01:29 PM   #3
Catsy
 
 
 
Join Date: Sep 2011
Reputation: 83
Posts: 340
Quote:
Originally Posted by erlandssonh View Post
Cool article, am I wrong or did I miss any tips on how to keep the entity count low?
I did mention a few times that items with more complex animations or behaviors are, generally speaking, going to have a higher entity count than simpler items like a light bar. I even gave examples of some of the costlier items like rising stairs or moving lifts. It would indeed be helpful to have a list; at some point I think I'm simply going to go through and tally them all up the hard way.

Quote:
Would be nice if the editor kept a count and replaced the lefthand menu with a message when the limit is hit. I'm sure the devs wouldn't find it hard to do so I think we'll see it
That would be nice! And if that isn't possible, it would be really helpful if the "too many items" error also showed you your entity count (and reminded you of the limit) so that we wouldn't have to go hunt it down in the logs.
Catsy is offline   Reply With Quote
Old 05-15-2012, 02:29 PM   #4
Erestyn
 
 
 
Join Date: May 2012
Reputation: 3
Posts: 93
Thank you so much for this, Catsy. I got very tired of explaining this to people <3
Erestyn is offline   Reply With Quote
Old 05-15-2012, 06:25 PM   #5
Arctiq
 
Join Date: Feb 2012
Reputation: 6
Posts: 232
Quote:
Originally Posted by erlandssonh View Post
Cool article, am I wrong or did I miss any tips on how to keep the entity count low?

Would be nice if the editor kept a count and replaced the lefthand menu with a message when the limit is hit. I'm sure the devs wouldn't find it hard to do so I think we'll see it

But advice on how to keep the count low or at least a tally list of "heavy" items would be cool. Maybe it's on the Wiki? (Wiki page there seemed to say 4096 as limit... hm.)
I got an idea. How about try shortening things, getting rid of excess turrets or panels that have no rhyme or rythem Try to even shorten the lift panels a bit.
Arctiq is offline   Reply With Quote
Old 05-15-2012, 07:06 PM   #6
Catsy
 
 
 
Join Date: Sep 2011
Reputation: 83
Posts: 340
Quote:
Originally Posted by Arctiq View Post
Try to even shorten the lift panels a bit.
This has no effect at all on the entity cost of a lift (which is already extremely high, about 44 per lift).
Catsy is offline   Reply With Quote
Old 05-15-2012, 09:44 PM   #7
Southpaws
 
Join Date: Feb 2012
Reputation: 0
Posts: 30
After testing a default map build out for a while, I came up with this:

Current estimated item point scores:

Default Map build = 397

Companion Cube Dropper = 37
Franken Cube Dropper = 35
Stairs = 14
Tractor Beam = 11
Glass Panel = 10
Faith Plate = 8
Cube Button = 3
Light Strip = 2
Glass = 1
Portalable Panel = 0.25 points per panel?

Total Map Score may vary 1-10 points from one build to the next with absolutely no changes to the build.

FWIW
Southpaws is offline   Reply With Quote
Old 05-15-2012, 09:44 PM   #8
Catsy
 
 
 
Join Date: Sep 2011
Reputation: 83
Posts: 340
Okay, I did a bunch of experimentation tonight and have added a ton of new data on entity costs. Give it a read and let me know what you think!

Quote:
Originally Posted by Southpaws View Post
After testing a default map build out for a while, I came up with this:

Current estimated item point scores:

Default Map build = 397

Companion Cube Dropper = 37
Franken Cube Dropper = 35
Stairs = 14
Tractor Beam = 11
Glass Panel = 10
Faith Plate = 8
Cube Button = 3
Light Strip = 2
Glass = 1
Portalable Panel = 0.25 points per panel?

Total Map Score may vary 1-10 points from one build to the next with absolutely no changes to the build.

FWIW
Thank you very much for trying to help! Unfortunately many of these numbers are inaccurate, most likely due to the abovementioned variations from build to build which throw them off. You need to use a larger sample size to mitigate that margin of error. See above for my methodology.

Last edited by Catsy: 05-15-2012 at 09:55 PM. Reason: to avoid double-posting
Catsy is offline   Reply With Quote
Old 05-15-2012, 09:59 PM   This is the last staff post in this thread.   #9
tejeev
 
tejeev's Avatar
 
Valve
Join Date: Mar 2012
Reputation: 2
Posts: 38
Great work Catsy! Your information seems correct and your advice should be helpful in getting maps within the limit.
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.
Keep up the good work!
tejeev is offline   Reply With Quote
Old 05-15-2012, 10:02 PM   #10
Southpaws
 
Join Date: Feb 2012
Reputation: 0
Posts: 30
Quote:
Originally Posted by Catsy View Post
Thank you very much for trying to help! Unfortunately many of these numbers are inaccurate, most likely due to the abovementioned variations from build to build which throw them off. You need to use a larger sample size to mitigate that margin of error. See above for my methodology.
Yeah, I discovered that a while back. Valve obviously has a few tricks to help keep the actual memory cost down on builds, which might explain why they haven't included a build score counter.

Ah, I just looked at your post again and it got massively larger since the last time I looked.

Nice work.

Quote:
Originally Posted by tejeev View Post
Great work Catsy! Your information seems correct and your advice should be helpful in getting maps within the limit.
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.
Keep up the good work!
Sheesh! I should hit Refresh more often. Thanks you, devs, for working on a counter for us, among many many other things.
Southpaws is offline   Reply With Quote
Old 05-15-2012, 10:35 PM   #11
Catsy
 
 
 
Join Date: Sep 2011
Reputation: 83
Posts: 340
Quote:
Originally Posted by tejeev View Post
Great work Catsy! Your information seems correct and your advice should be helpful in getting maps within the limit.
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.
Keep up the good work!
Thank you so much, Tejeev--for the comment and information, and especially for this wonderful, groundbreaking editor and game. I know that counter will be incredibly useful to me and every other mapper out there and I'm looking forward to the update. Would it be too much to ask for a sticky to keep this information readily available to everyone until that update is ready to ship?

Quote:
Originally Posted by Southpaws View Post
Ah, I just looked at your post again and it got massively larger since the last time I looked.

Nice work.
No worries, thanks again for your help.
Catsy is offline   Reply With Quote
Old 05-16-2012, 06:27 AM   #12
Charax
 
Join Date: Jan 2009
Reputation: 46
Posts: 531
This is without a doubt the most useful and necessary thread since the PTI was released, this info should have been posted by the devs on day 1. +Rep
Charax is offline   Reply With Quote
Old 05-16-2012, 07:03 AM   #13
Ls777
 
 
 
Join Date: Nov 2009
Reputation: 737
Posts: 2,058
Quote:
Originally Posted by Catsy View Post
  • For a physical barrier or transparent walkway longer than 4 squares, light bridges are both cheaper and more compact than glass, and have the advantage of blocking lasers (which glass does not)--their cost does not vary by length
You should probably clarify, they block the turret laser but not the "thermal discouragement beam." They are pretty much identical to glass in that regard (and turrets can't shoot through glass anyways)

Great post.
Ls777 is offline   Reply With Quote
Old 05-16-2012, 08:17 AM   #14
Catsy
 
 
 
Join Date: Sep 2011
Reputation: 83
Posts: 340
Quote:
Originally Posted by Ls777 View Post
You should probably clarify, they block the turret laser but not the "thermal discouragement beam." They are pretty much identical to glass in that regard (and turrets can't shoot through glass anyways)
Thanks, I've updated the post and removed that bit to avoid confusion. For some reason I could've sworn that they did.
Catsy is offline   Reply With Quote
Old 05-16-2012, 09:09 AM   #15
Zeodyn
 
 
 
Join Date: Aug 2011
Reputation: 0
Posts: 2
This is the Companion Cube of threads. Thank you Catsy. Now i can approximately anticipate whether a chamber will work or not long before it is finished.
Laughed @ the fact, that an Obs-Window is so cheap. I always started deleting those... silly me.

The fact about the Glass/Grating is the most usefull in my opinion, same with the Fizzler/Laser Barrier/Mov.Platforms. Knowing that the size and not the amount of single items counts is indispensable for larger maps.

Again: Thank you!
Zeodyn is offline   Reply With Quote
Reply

Go Back   Steam Users' Forums > Steam Game Discussions > M - P > Portal 2


Thread Tools
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is Off
HTML code is Off



All times are GMT -7. The time now is 06:39 AM.


Powered by vBulletin® Version 3.8.7
Copyright ©2000 - 2014, vBulletin Solutions, Inc.
Site Content Copyright Valve Corporation 1998-2014, All Rights Reserved.