This guide explains how to track down and fix common issues with your Unreal 3 map.
Map issues can generally be broken down into the following categories. Be sure you’ve gone through each category and tool before distributing your map publicly.
Build Errors – errors that show up when you build your map (lighting, paths, geometry, or Build All.)
Check Map for Errors – errors that show up when you run Tools->Check Map for Errors
Gameplay Bugs – anything that detracts from the player’s gameplay experience.
Art Bugs – anything that visually detracts from the player experience
You’ve most certainly encountered errors when building your map. You’ve probably also fixed some of them on your own.
If you double-click the error, Unreal will select the offending object in the scene. (You can then select the viewport and hit “home” to center the view on the object.) Most errors deal with objects that have some sort of placement issue, and the solution is usually pretty obvious – either move or delete the object to make the error go away.
A complete listing of build errors and their solutions can be found here: http://udn.epicgames.com/Three/MapErrors.html
Here are some of the more common errors you’ll encounter, and their solutions.
Only [x] PlayerStarts in this level (need at least 16)
Place more PlayerStart nodes until there are at least 16.
Run ‘Clean BSP Materials” to clear [x] unnecessary material references
Click Tools->Clean BSP Materials.
Brush_[x] : Brush has NULL material reference(s)
A brush still has the default checkerboard material on it. Either apply a proper material if the surface is visible, or EngineMaterials.RemoveSurfaceMaterial if the surface isn’t visible (say, hidden by a static mesh, or on the underside of the playable space.) For hidden surfaces, be sure to also open up the surface properties and set the Lightmap Resolution to 65536, and uncheck the lighting flags.
StaticMeshActor_[x] in same location as StaticMeshActor_[y]
Two meshes are placed on top of each other. Usually this happens when you accidentally duplicate a mesh. Just delete one of them.
StaticMeshActor_[x] has invalid DrawScale/DrawScale3D
A mesh got scaled badly (a scale of 0 in any dimension.) Either delete the mesh or fix the scale.
No paths from PathNode / UTPickupFactory / PlayerStart / Etc
A gameplay object has no paths leading to it. There may be a couple causes:
1) Not enough pathnodes are in place to connect up the network. Place more pathnodes and make sure the object gets connected properly.
2) The object is embedded in geometry or underneath the world. Move the object to a valid location and build paths again.
3) The object is embedded in hidden collision geometry. (Same as problem 2, just harder to detect.) Go to the Show Flags menu and turn on Collision (or hit “C”) to view world collision.
Navigation point not on valid base, or too close to steep slope
Similar to the previous issue. You probably just need to update the position of the pathnode.
[Path Node] is unnecessary and should be removed
The pathnode isn’t adding anything to the navigation tree. This may be because it’s close to another pathnode, or all of the pathnodes in its vicinity already have a direct line of sight to each other. You can view your path network by going to the Show Flags menu and turning on Paths (or hit “P”). Either delete the node, or move it to a location where it creates a new, useful path.
Actor has bAcceptsLights set but only uses unlit materials
Occurs with skydomes, volumetric lights, and any other object with a material that doesn’t receive lighting.
Open up the actor’s properties, and under StaticMeshActor->Lighting, uncheck bAcceptsDynamicLights, bAcceptsLights, and CastShadow.
In most cases you’ll also want to go to the Collision submenu and change CollisionType to COLLIDE_NoCollision.
[Pickup] doesn’t have a pickup light near it
Click Tools->Add Pickup Lights. Any time you move, add, or delete a pickup you’ll need to run this tool. All pickuplights will be updated.
As stated earlier, a gameplay bug is anything that detracts from the player’s experience. Some of these bugs will be found just by building the map, but you’ll need to hunt for most of these through heavy iteration and playtesting. You can also get gameplay feedback by releasing Beta or Work in Progress versions of you map to the community.
Here are some of the more common categories of gameplay bugs. Note that some can be considered a bug (directly detracts from the player’s experience), while others can be considered an exploit (one player gains an unfair advantage, which detracts from the experience of all the other players.)
Spend some time actively looking for each of these types of bugs. You’ll stumble across most of your bugs by simple playtesting, but you’ll be surprised by how many pop up when you’re actively looking for them.
Player can get permanently stuck
Your level has a place that the player can get into, but not out of. This may be something obvious like a deep pit, or it may be an artifact of the physics system (the player slides down a ramp into a wall, but the physics system doesn’t detect it as a flat surface.)
In these situations, either move the geometry, or place blocking volumes.
Player can get temporarily stuck
Similar to the above situation. Maybe the player has to double-jump or use the translocator to get out of a space. Again, it’s frustrating to the player, so don’t let the player get stuck in the first place.
Player can escape the world
There’s a space where the player can get outside of the intended gameplay area. If this is intended, and the player falls and hits the kill plane, that’s ok. But if the player can run around an undeveloped area, that’s bad.
Either place meshes or blocking volumes to keep the player inside. And remember that the player can use translocators to travel in unexpected ways, so you may end up surrounding your entire level in blocking volumes.
Player can use translocator/vehicles/etc to get to unintended places
Can the player use the translocator to get access to an unfair sniping location? Check all of your ledges and flat surfaces in the upper reaches of your level. Either turn off collision on objects you don’t want the player to land on, or place blocking volumes.
Player gets snagged on walls/props/etc
With Unreal’s physics system, it’s easy for the player to accidentally get snagged on what looks like a small prop or outcropping. This is arguably one of the least severe types of bugs, but smooth traversal is important to the fun factor of your level.
Turn off collision on small props if they’re getting in the way, or create blocking volumes that allow the player to smoothly slide past an obstacle. (Trapezoidal blocking volumes can be commonly seen along walls, especially around pipes and pillars.)
Player gets snagged on invisible geometry
There are many causes to this kind of bug.
– A small prop or outcropping is actually what the player is getting caught on
– A blocking volume is placed incorrectly
– An archway is too low, and the player’s head is getting caught
– A step is too high to step up
– Collision geo for a mesh doesn’t match the visible geo closely (especially a problem with meshes scaled very large.)
To track down the issue, when playing in PIE, open up the console and type “show collision” – hopefully the cause of the bug should become apparent.
Player can pass through geometry
Sometimes collision geo doesn’t match the visible mesh, or a mesh doesn’t have collision turned on, and the player can pass through it. This can be the source of an exploit in a multiplayer game. Usually the cause of the problem is obvious, but you can always place a blocking volume if there’s no other good solution.
Player falls through the world
This is really the same as the above issue. Maybe the ground mesh doesn’t have collision geo, or collision is turned off. A blocking volume is an easy way to fix this problem.
Bullets hit invisible surfaces
This is usually caused when a light volume, a piece of foliage, or a similar transparent object has collision turned on. Be sure to set the proper collision flags.
This can also happen when an object’s bHidden flag is set – it doesn’t render, but its collision is still active. Either uncheck that flag, or if it was intentionally set, turn off collision too.
Player’s camera jitters when running up a staircase
When the player steps up a step, the camera instantly jumps to the new height. This isn’t normally a big deal, but when the player runs up a BSP staircase, the camera will jitter a lot, which looks bad.
Either replace the BSP staircase with a static mesh (which will probably have nice smooth collision geo built in), or place a blocking volume that creates a smooth ramp over the top of the stairs.
Lifts/Doors not working
This should be pretty obvious when it happens, but test all of your lifts and doors thoroughly. And be sure to test them over the network too – it’s possible to create kismet code that works fine on your local machine, but doesn’t pass properly between clients in a network game.
Bots experience any of the above issues
This may be obvious, but be sure to test thoroughly with bots in your level to make sure they act like they should.
Bots don’t path to certain areas
First, make sure your path network is complete.
If it is, you may still notice that sometimes bots won’t go to certain areas of your level, or won’t take certain paths. This is usually because there’s no incentive for them to take that route. The best way to get bots to fully utilize your play space is to make sure you’ve got plenty of pickups scattered throughout your level. (That’s usually better for the player too!)
Bots don’t defend spaces intelligently
Did you remember to place UTDefensePoints around the space you want the bots to defend?
Art bugs generally aren’t nearly as severe as gameplay bugs, but bad art (or broken art) can still pull the player out of the experience.
Here are some categories that art bugs generally fall into.
Object placement issues
Look for objects floating off the ground (usually by a very small amount), sinking into the ground, intersecting strangely with other objects
Z-fighting (flickering surfaces)
This happens when two surfaces are immediately on top of each other. To resolve the issue, just move one of the props by a small amount. Z-fighting tends to happen more obviously at a distance, and may not be visible at all up close.
Gaps between meshes/BSP
Look closely to make sure there aren’t any small gaps between props or BSP surfaces.
Can see outside the world
Make sure the player can never see space they weren’t intended too – especially the shimmering effect that occurs when the player can see out into infinity.
Sometimes it’s necessary to add a lightmap to a prop in order for it to bake well. If you’ve got seams between props that are placed in a line (like wall or railing segments), you may need to uncheck “bUseSubDivisions” (under AdvancedLighting).
Lighting is too dark (goes pure black)
Make sure lighting in your level never goes to pure black, and make sure every space is lit well enough to see the people you’re fighting. You may need to place a skylight, some low-intensity directional lights, or even some low-intensity pointlights to the dark area.
Be sure to test your map in High, Medium, and Low detail mode, and look for issues in each!