Difference between revisions of "Leak"

From Valve Developer Community
Jump to: navigation, search
(Finding leaks)
(updated with some new information, cut down on redundancy in language and linking, improved accuracy)
Line 4: Line 4:
 
}}
 
}}
 
== What is a leak? ==
 
== What is a leak? ==
Levels created with the Source Engine must be completely internally sealed. No part of the interior of the level, the "world", must connect with the outside, the "[[Void]]". Even the sky must be sealed off with a brush using the <code>tools/toolsskybox</code> texture. When there is any kind of gap to the void, a '''leak''' is generated when the map is compiled by <code>[[Vbsp|vbsp]]</code>. When a leak occurs, the tools cannot know which part of the level is inside, and what part is outside, and <code>[[Vvis|vvis]]</code> cannot be run. If vvis is not run several effects may not work or look right including water and some surface properties like dust puffs.
+
[[BSP]] maps must be completely internally sealed. No part of the interior of the level, the world, should connect with the outside, the [[void]]. Even the sky must be sealed off with a brush using the <code>tools/toolsskybox</code> texture. When there is any kind of gap to the void, a '''leak''' is generated when the map is compiled by [[VBSP]]. When a leak occurs, [[VVIS]] cannot tell which part of the level is inside, and what part is outside, and it will not work properly.
  
 
This example shows a map with an obvious gap in the geometry, leading to the void. This will generate a leak error message when it is compiled:
 
This example shows a map with an obvious gap in the geometry, leading to the void. This will generate a leak error message when it is compiled:
Line 10: Line 10:
 
[[Image:hammer_leaks1.jpg|frame|left|A gap in geometry that leads to the void will cause leaks.]]{{clr}}
 
[[Image:hammer_leaks1.jpg|frame|left|A gap in geometry that leads to the void will cause leaks.]]{{clr}}
  
When a map like this is compiled, with a gap to the void, [[Vbsp|vbsp]] generates an error similar to this in the compile log:
+
When a map like this is compiled, with a gap to the void, VBSP generates an error similar to this in the compile log:
  
 
<pre>
 
<pre>
Line 18: Line 18:
 
</pre>
 
</pre>
  
With this error message, vbsp is telling you that there has been a leak in the level, and the first entity it found when attempting to get into the level from the void (in this case, a light entity). It also gives you the location of that entity, expressed in X, Y, and Z world unit coordinates.
+
With this error message, VBSP is telling you that there has been a leak in the level, and the first entity it found when attempting to get into the level from the void (in this case, a light entity). It also gives you the location of that entity, expressed in X, Y, and Z world unit coordinates.
  
 
{{note|Often the mentioned entity is not the cause of the leak - it's the one that the leak trace originated from. Deleting it will simply make the report mention another entity, it won't solve the problem! There is one situation when deleting an entity does solve the leak: when it's placed outside the playable area. This is covered later in this article.}}
 
{{note|Often the mentioned entity is not the cause of the leak - it's the one that the leak trace originated from. Deleting it will simply make the report mention another entity, it won't solve the problem! There is one situation when deleting an entity does solve the leak: when it's placed outside the playable area. This is covered later in this article.}}
  
{{note|If you have no point entities in your map when you compile it, [[Vbsp|vbsp]] may report a leak, because it has no way of deciding whether the interior or exterior of the map is the playable area..}}
+
{{note|If you have no point entities in your map when you compile it, VBSP may report a leak, because it has no way of deciding whether the interior or exterior of the map is the playable area.}}
  
 
{{note| [[Portal 2]] maps will not compile if there is a leak.}}
 
{{note| [[Portal 2]] maps will not compile if there is a leak.}}
  
{{note| In [[Portal 2]], [[Counter-Strike: Global Offensive]] and [[Alien Swarm]], if you have a leak and you skip [[vvis]], the map will not compile the skybox.}}
+
{{note| In Portal 2, [[Counter-Strike: Global Offensive]] and [[Alien Swarm]], if you have a leak and you skip VVIS, the map will not compile the skybox.}}
  
 
== Effects of leaks ==
 
== Effects of leaks ==
  
A leak in a level has a number of bad effects. First, the <code>vbsp</code> process will report the leak, and it will not produce a ''portal'' file (<code>''mapname''.prt</code>). The portal file is used by the <code>[[Vvis|vvis]]</code> process to perform its visibility calculations. Since there is no portal file, <code>vvis</code> will not run at all. When <code>vvis</code> doesn't run, it doesn't produce the files necessary for the <code>[[Vrad|vrad]]</code> process to calculate its light bounces. Due to this, the <code>vrad</code> process will only perform direct lighting - no light bounces.
+
A leak in a level has a number of bad effects. [[VBSP]] will report the leak, and it will not correctly produce a portalfile (<code>mapname.[[prt]]</code>), if at all. The portal file is used by [[VVIS]] to perform its visibility calculations. Since there is no portal file, VVIS will not run correctly/at all. When this happens, [[VRAD]] will also work incorrectly, or only perform direct lighting - no light bounces.
  
The most serious effect by far is that the <code>vvis</code> process will not run when a leak is present. When the level is run in the game, the rendering engine will not have any visibility info available with which to limit itself, so it will attempt to draw the entire level. This will most certainly lead to high polygon counts and may lead to sections of the map to render incorrectly or not at all.
+
Maps are usually not playable at all. VVIS may tell the engine to render the entire map at once, which is bad for framerates, or have entire areas be invisible. At worst, a leak can make VRAD render your entire map black.
  
== Checking for leaks the fast way ==
+
== Wasting time with leaks ==
  
The BSP part of your compile will always report any leaks it finds, but spending hours of full compile time and game execution just to find out that your map is broken ''after'' compilation, simply isn't efficient. If you have the slightest suspicion that your map might have a leak - normally when you've expanded the brushwork borders of the map - you can run a fast compile to check for BSP errors by opening the ''Run Map'' dialog, turning off VIS and RAD compile tools, and checking the ''Don't run game after compiling'' flag. The process of checking your entire map for leaks will only take about 8 seconds with this method.
+
[[VBSP]] will always report any leaks it finds, but spending hours of full compile time and game execution just to find out that your map is broken ''after'' compilation, simply isn't efficient. Make sure you've tested that your map doesn't have a leak ''before'' you even begin to worry about your map's visibility and lighting. If you notice that VBSP leaked while the compile is happening, press Ctrl+C to abort the compile.
 
 
Alternatively, you can use the advanced compilation mode and take advantage of the "check if file exists afterwards" feature. You can then simply check if the portal file was created or not. This will let you abort the compile, skipping vvis, vrad and launching the game, if there were any leaks. Note that this does not catch area portal leaks, but those are relatively rare.
 
  
 
== Finding leaks ==
 
== Finding leaks ==
  
Sometimes these gaps aren't quite as obvious as the above example. They can be a fraction of a unit wide and still cause a leak. The compile tools provide you with a ''pointfile'' to help you locate the leak. A pointfile is a file generated by <code>vbsp</code> that draws a line between the void of the map to the entity it found during the leak check. After receiving a leak error in <code>vbsp</code>, a <code>''mapname''.lin</code> file will be created in the same directory as your .vmf map file.
+
Sometimes these gaps aren't quite as obvious as the above example. They can be a fraction of a unit wide and still cause a leak. [[VBSP]] provides you with a [[pointfile]] to help you locate the leak. It draws a line from the void of the map to the entity it found during the leak check. After receiving a leak error, a <code>mapname.lin</code> file will be created in the same directory as your .vmf map file.
  
 
=== Loading a Pointfile ===
 
=== Loading a Pointfile ===
  
The pointfile can be loaded into the '''Hammer Editor''' to show you precisely where the leak is inside the level. To load a pointfile for the level, use the [[Hammer_Map_Menu#Load Pointfile|Load Pointfile]] command in the '''Map''' menu.
+
The pointfile can be loaded into the Hammer Editor to show you precisely where the leak is inside the level. To load a pointfile for the level, use the [[Hammer_Map_Menu#Load Pointfile|Load Pointfile]] command in the '''Map''' menu.
  
 
[[Image:hammer_leaks5.jpg||thumb|400px|right|The '''Load Pointfile''' command shows the path to the leak in the Hammer viewports.]]
 
[[Image:hammer_leaks5.jpg||thumb|400px|right|The '''Load Pointfile''' command shows the path to the leak in the Hammer viewports.]]
 
This image shows the pointfile loaded into the previous example. Notice that the red line appears in both the 3D and 2D views, and is traced back from the entity through the gap.
 
This image shows the pointfile loaded into the previous example. Notice that the red line appears in both the 3D and 2D views, and is traced back from the entity through the gap.
  
Using this visual aid, you can find the source of the leak by following the red line to the outside of the level. It's best to start at the entity specified in the <code>vbsp</code> error message, and then follow the line until you find the gap in the geometry. Close the gap and recompile the level to see if you have fixed the leak.{{clr}}
+
Using this visual aid, you can find the source of the leak by following the red line to the outside of the level. It's best to start at the entity specified by [[VBSP]], and then follow the line until you find the gap in the geometry. Close the gap and recompile the level to see if you have fixed the leak.{{clr}}
  
 
=== Finding the endpoint ===
 
=== Finding the endpoint ===
  
If you're having trouble locating the start entity, you can use the [[Hammer_View_Menu#Go_to_Coordinates...|Go to Coordinates]] command on the '''View''' menu to find the entity and the start of the pointfile line. Simply enter the coordinates given by <code>vbsp</code> for the entity location, and the 2D and 3D views will be centered on that location. Follow the line to find your leak.
+
If you're having trouble locating the start entity, you can use the [[Hammer_View_Menu#Go_to_Coordinates...|Go to Coordinates]] command on the '''View''' menu to find the entity and the start of the pointfile line. Simply enter the coordinates given by [[VBSP]] for the entity location, and the 2D and 3D views will be centered on that location. Follow the line to find your leak.
  
 
Another method to find the source of the leak is to zoom out in one or more of the 2D views. After loading the pointfile, zoom out until you see the red line. Follow the line until you reach the entity at the one of the endpoints. Then select the entity, and choose [[Hammer_View_Menu#Center_Views_on_Selection_.3CCtrl.2BE.3E|Center 3D Views on Selection]] from the '''View''' menu. Now you can follow the pointfile line to find the leak.
 
Another method to find the source of the leak is to zoom out in one or more of the 2D views. After loading the pointfile, zoom out until you see the red line. Follow the line until you reach the entity at the one of the endpoints. Then select the entity, and choose [[Hammer_View_Menu#Center_Views_on_Selection_.3CCtrl.2BE.3E|Center 3D Views on Selection]] from the '''View''' menu. Now you can follow the pointfile line to find the leak.
Line 61: Line 59:
 
== Other causes of leaks ==
 
== Other causes of leaks ==
  
Besides gaps in outside geometry, there are other map errors that can cause [[Vbsp|vbsp]] to generate a leak error.
+
Besides gaps in outside geometry, there are other map errors that can cause [[VBSP]] to generate a leak error.
  
 
=== Entities outside the level ===
 
=== Entities outside the level ===
[[Image:hammer_leaks2.jpg||thumb|300px|right|Placing any entity in the [[Void]] will cause a leak.]]
+
[[Image:hammer_leaks2.jpg||thumb|300px|right|Placing any entity in the [[void]] will cause a leak.]]
One common mistake is the accidental placement of an entity outside the interior level space. This can happen if you place an entity outside in the void area while you're working on it, then forget to delete it when you're finished. This can also occur if you attempt to seal the map with an brush entity, such as a <code>func_door.</code> Since brush entities do not block visibility, this will create the same condition as if there were a gap in their place. All entities must be inside valid level space, or the map will generate a leak. This is because vbsp determines the inside of the level depending on where it finds entities.{{clr}}
+
All entities need to be inside the playable level space or skybox. VBSP treats all brush entities as if they are not there, so attempting to seal a map with a brush entity, such as a [[func_door]], will create the same condition as if there were a gap in their place.{{clr}}
  
 
=== Improperly constructed areaportals ===
 
=== Improperly constructed areaportals ===
 
[[Image:hammer_leaks3.jpg||thumb|300px|right|Areaportals that do not seal areas will cause leaks.]]
 
[[Image:hammer_leaks3.jpg||thumb|300px|right|Areaportals that do not seal areas will cause leaks.]]
Leak error messages can also be generated when an [[areaportal]] does not properly seal the two areas it connects. Find leaks with areaportals using the same methods as geometry gap leaks.
+
Leak error messages can also be generated when an [[areaportal]] does not properly seal the two areas it connects. Find leaks with areaportals using the same methods as geometry gap leaks.{{clr}}
 
 
See [[areaportal]] for more information on the uses of areaportals.{{clr}}
 
  
=== Non-solid geometry does not seal the world ===
+
=== Special geometry does not seal the world ===
 
[[Image:hammer_leaks4.jpg||thumb|300px|right|Seal areas behind non-solid geometry to prevent leaks.]]
 
[[Image:hammer_leaks4.jpg||thumb|300px|right|Seal areas behind non-solid geometry to prevent leaks.]]
  
One more cause of leaks is if you try to seal a map using other types of non-solid geometry, such as displacements (terrain), water, or <code>func_detail</code> brushes. None of these non-solid brush types will block visibility and seal the world. Attempting to use them in this way will generate a leak. You can fix this type of leak by adding a solid brush behind them to seal the map. Using a brush with the <code>tools/toolsnodraw</code> material will seal the map, but not add any additional rendering cost, so it's a great way to seal the map behind non-solid geometry.{{clr}}
+
[[Displacements]] and [[water]] also do not seal maps and will cause leaks. You can fix this type of leak by adding a solid brush behind them to seal the map. Using a brush with the <code>tools/toolsnodraw</code> material will seal the map, but not add any additional rendering cost, so it's a great way to seal the map behind displacements. Water should be sealed off with whatever is sealing off the area above it (probably <code>tools/toolsskybox</code> or another typical texture, such as bricks.) Do not use nodraw to seal off water, as this will cause a weird trailing effect.{{clr}}
  
 
=== Mismatched entity origins ===
 
=== Mismatched entity origins ===
Line 95: Line 91:
  
 
=== Translucent geometry ===
 
=== Translucent geometry ===
There is a particular case where your geometry could be entirely sealed and yet a leak would constantly appear, even if you have absolutely no entity around the leak. If loading the ''pointfile'' doesn't help you at all, then you might be facing this particular situation. In this case, the red line would be passing through solid geometry. The cause is pretty simple -  it is most likely that you have at least one of the brush sides textured with a translucent material. When this situation appears, the brush isn't able to seal anything anymore. In most cases, this will cause problems with areaportals that wouldn't be able to seal rooms. Remember that the sides in question could be located anywhere, even between other brushes.
+
Brushes with translucent materials, like glass, can also cause leaks if they're on the edge of a map. If your pointfile is going straight through a brush, check the textures on all sides of that brush.
  
 
=== Func_viscluster ===
 
=== Func_viscluster ===
  
[[Func_viscluster]] can also cause leaks, when they cross areaportal surfaces, or are too close to them. Disabling all func_visclusters and compiling to see if the leak is gone should be done, at least at last resort.
+
[[Func_viscluster]] can also cause leaks when they cross areaportal surfaces, or are too close to them. Disabling all func_visclusters and compiling to see if the leak is gone should be done, at least at last resort. {{Todo|How do you ''actually'' fix this?}}
  
 
== Conclusion: An ounce of prevention ==
 
== Conclusion: An ounce of prevention ==

Revision as of 21:13, 15 May 2018

Deutsch Русский

What is a leak?

BSP maps must be completely internally sealed. No part of the interior of the level, the world, should connect with the outside, the void. Even the sky must be sealed off with a brush using the tools/toolsskybox texture. When there is any kind of gap to the void, a leak is generated when the map is compiled by VBSP. When a leak occurs, VVIS cannot tell which part of the level is inside, and what part is outside, and it will not work properly.

This example shows a map with an obvious gap in the geometry, leading to the void. This will generate a leak error message when it is compiled:

A gap in geometry that leads to the void will cause leaks.

When a map like this is compiled, with a gap to the void, VBSP generates an error similar to this in the compile log:

ProcessBlock_Thread: 0...1...2...3...4...5...6...7...8...9...10 (0)
**** leaked ****
Entity light (-1607.69 -1094.12 -183.00) leaked!

With this error message, VBSP is telling you that there has been a leak in the level, and the first entity it found when attempting to get into the level from the void (in this case, a light entity). It also gives you the location of that entity, expressed in X, Y, and Z world unit coordinates.

Note:Often the mentioned entity is not the cause of the leak - it's the one that the leak trace originated from. Deleting it will simply make the report mention another entity, it won't solve the problem! There is one situation when deleting an entity does solve the leak: when it's placed outside the playable area. This is covered later in this article.
Note:If you have no point entities in your map when you compile it, VBSP may report a leak, because it has no way of deciding whether the interior or exterior of the map is the playable area.
Note: Portal 2 maps will not compile if there is a leak.
Note: In Portal 2, Counter-Strike: Global Offensive and Alien Swarm, if you have a leak and you skip VVIS, the map will not compile the skybox.

Effects of leaks

A leak in a level has a number of bad effects. VBSP will report the leak, and it will not correctly produce a portalfile (mapname.prt), if at all. The portal file is used by VVIS to perform its visibility calculations. Since there is no portal file, VVIS will not run correctly/at all. When this happens, VRAD will also work incorrectly, or only perform direct lighting - no light bounces.

Maps are usually not playable at all. VVIS may tell the engine to render the entire map at once, which is bad for framerates, or have entire areas be invisible. At worst, a leak can make VRAD render your entire map black.

Wasting time with leaks

VBSP will always report any leaks it finds, but spending hours of full compile time and game execution just to find out that your map is broken after compilation, simply isn't efficient. Make sure you've tested that your map doesn't have a leak before you even begin to worry about your map's visibility and lighting. If you notice that VBSP leaked while the compile is happening, press Ctrl+C to abort the compile.

Finding leaks

Sometimes these gaps aren't quite as obvious as the above example. They can be a fraction of a unit wide and still cause a leak. VBSP provides you with a pointfile to help you locate the leak. It draws a line from the void of the map to the entity it found during the leak check. After receiving a leak error, a mapname.lin file will be created in the same directory as your .vmf map file.

Loading a Pointfile

The pointfile can be loaded into the Hammer Editor to show you precisely where the leak is inside the level. To load a pointfile for the level, use the Load Pointfile command in the Map menu.

The Load Pointfile command shows the path to the leak in the Hammer viewports.

This image shows the pointfile loaded into the previous example. Notice that the red line appears in both the 3D and 2D views, and is traced back from the entity through the gap.

Using this visual aid, you can find the source of the leak by following the red line to the outside of the level. It's best to start at the entity specified by VBSP, and then follow the line until you find the gap in the geometry. Close the gap and recompile the level to see if you have fixed the leak.

Finding the endpoint

If you're having trouble locating the start entity, you can use the Go to Coordinates command on the View menu to find the entity and the start of the pointfile line. Simply enter the coordinates given by VBSP for the entity location, and the 2D and 3D views will be centered on that location. Follow the line to find your leak.

Another method to find the source of the leak is to zoom out in one or more of the 2D views. After loading the pointfile, zoom out until you see the red line. Follow the line until you reach the entity at the one of the endpoints. Then select the entity, and choose Center 3D Views on Selection from the View menu. Now you can follow the pointfile line to find the leak.

Other causes of leaks

Besides gaps in outside geometry, there are other map errors that can cause VBSP to generate a leak error.

Entities outside the level

Placing any entity in the void will cause a leak.
All entities need to be inside the playable level space or skybox. VBSP treats all brush entities as if they are not there, so attempting to seal a map with a brush entity, such as a func_door, will create the same condition as if there were a gap in their place.

Improperly constructed areaportals

Areaportals that do not seal areas will cause leaks.
Leak error messages can also be generated when an areaportal does not properly seal the two areas it connects. Find leaks with areaportals using the same methods as geometry gap leaks.

Special geometry does not seal the world

Seal areas behind non-solid geometry to prevent leaks.
Displacements and water also do not seal maps and will cause leaks. You can fix this type of leak by adding a solid brush behind them to seal the map. Using a brush with the tools/toolsnodraw material will seal the map, but not add any additional rendering cost, so it's a great way to seal the map behind displacements. Water should be sealed off with whatever is sealing off the area above it (probably tools/toolsskybox or another typical texture, such as bricks.) Do not use nodraw to seal off water, as this will cause a weird trailing effect.

Mismatched entity origins

An origin helper separated from its parent entity and moved outside the level will cause a leak.

A more subtle cause of leaks can be with any entities that have origin helpers, such as func_door_rotating or func_rot_button. While the entity itself may be inside the world, if the origin helper is outside the map, the entity will cause a leak. If you find a pointfile heading to a empty spot outside of the map, and there is no entity there, an origin helper is a good thing to look for.

One way to quickly tell if an entity origin is causing the leak is to:

  1. Load the pointfile.
  2. Find the endpoint(s) of the pointfile.
  3. Choose Select All from the Edit Menu.
  4. Make sure Show Helpers is checked on the View Menu.
  5. If you see an origin helper appear at the pointfile, you know that's the problem.

If you have an origin helper causing a leak, you can select the object and manually move the origin back into the world, use the Center Origins command from the Tools Menu, or simply right-click on the origin helper and select Center on entity.

Mismatched entity origins usually occur when a brush entity with one of these helpers is moved while in Solids mode. Moving a brush entity in solids mode does not move the entity's origin helper.

Translucent geometry

Brushes with translucent materials, like glass, can also cause leaks if they're on the edge of a map. If your pointfile is going straight through a brush, check the textures on all sides of that brush.

Func_viscluster

Func_viscluster can also cause leaks when they cross areaportal surfaces, or are too close to them. Disabling all func_visclusters and compiling to see if the leak is gone should be done, at least at last resort. To do: How do you actually fix this?

Conclusion: An ounce of prevention

Using the pointfile tools makes finding leaks relatively painless, but one of the most important ways to fix leaks is by preventing them in the first place. Taking your time when building, and making sure brushes are snapped properly to the grid can go a long way towards eliminating leaks before they occur. The cleaner and more organized your geometry, the more likely you are to be able to spot leaks when they occur, or even prevent them from happening in the first place. You can also help prevent lots of extra work by compiling your level as you go along, instead of building your whole level before trying to compile it. Finding one leak at a time while the map is only partially complete is a lot easier and faster than finding leaks in a complete map that is full of geometry.