Q3Radiant Editor Manual

Tools 9: Debugging Maps

The Editor's Debug Tools

The pointfile appears as a series of points, connected by red line segments, that traces a connecting path between an entity inside the hull and a point in the outside world.. Follow the pointfile through the map and note where it passes out of the enclosed space and into the void. In the case of an entity outside the world, it may just draw a line near the entity. You may need to turn off the display of clip and hint brushes, and curves to find the leaks. Adjust your solid map geometry to close up the leaks.

When you save the map (or an auto-save occurs), the pointfile disappears. You can bring the pointfile back by toggling this command.

Note: If you use a front-end program for compiling, such as Q3Build, you will need to reload the map file and select the "pointfile" command under the File menu.

Mixed faces: One or more faces on a brush has a surface parameter that conflicts with the other surface parameters. This is not a problem. Putting nodraw or clip on a brush that has a face that draws will cause this. That includes most all "flame" brushes, many water brushes, and just about every instance where alpha-channel textures are used to create see-through brush faces.

Bad point to polygon form factor: A curve patch is larger than 512 units in at least one dimension. This is not fatal, but may result in some unusual light artifacts on the curve.

Unknown surfaceparm: "nomipmaps" Some shaders contain old or incorrectly spelled parameters. This is not a problem.

Too many portals. Your map is broken into too many separate hulls by areaportal brushes. Try to keep the number of discrete portalled areas under 16.

Duplicate plane. During the course of manipulating brushes, you may have moved edges in such a manner that two adjacent sides of a brush now form a single brush side. Use Find brush to locate the problem brush. Use the old brush as a template or pattern, but build the new one with a single side in the place of the duplicate plane sides. One way to solve the problem is to use the Clipper tool cut off a corner instead of collapsing two faces into one. While this is not a serious problem for multiplayer play, it can create "solid" areas in the bot navigation (.aas) file. This makes the bots think there are walls in places where there appear to be none. You can check for solid areas with the "bot_testsolid 1" inside the game (after creating an .aas file). See the Bot Navigation appendix for more details.

******* Leaked *******. There is a hole between the contained space of your map and the outer void. Use the pointfile to locate the problem.

Couldn't load baseq3/pics/colormap.pcx trying tools/colormap.pcx...failed! This is not a compile error, but a loading error. Correct it by checking the hi-color textures setting in Preferences.

Loading base_light/light_flare...failed, using default shader. Just ignore this.

match token ("{") failed at line [line number]. You broke a shader while editing it. Go closely look at the shader you most recently edited. Chances are you'll find a bracket error in the syntax.

In-game Debug tools

give [weapon/item/ammo/health] [amount] // Give selected weapon/item/ammo/health

give all // Gives all weapons, ammo, armor, and items

god // Godmode

noclip // Pass through anything. Use in conjunction with r_fastsky 1 or r_clear 1, or you will have hall of mirror problems when you pass out of the bounds of the map.

notarget // Bots think you're a pal viewpos // Outputs player coordinate position and facing angle.

The "gl_showtris" and "r_speeds" commands allow you to see the number and location of polygons (surface triangles) in your view. The "

Show me the Triangles Showtris draws a white line around each triangle used to create the world when it is a part of a map's potential viewable set (PVS). This is especially effective tool, since it shows the triangle outlines of map areas that are being "seen" by the engine, which are not always just the ones that the player sees.

Depending on your video card, this may work well, or it may not. For some (like the Matrox cards, it comes with a huge performance hit).

The Need for (R_) Speeds This output is one of the more valuable reports you can get on a map. The numbers show you the numbers that can tell you what kind of real visual costs you are encounter. Combined with other commands that turn features like entities, curves, and multi-pass texturing on and off, you can get a realistic idea of where you're having problems.

Here's what those cryptic numbers mean. When r_speeds = 1, the numbers read as follows (where the # sign equals a number)

# / # shaders/surfs # leafs # verts # / # tris #.## mtex #.## dc

# / # shaders/surfs is the number of shaders in view, followec by the number of surfaces in view.

# leafs is how many leaf nodes are potentially visible.

# verts is how many vertexes are in view

# / # tris is the number of trangles drawn by the renderer in a single pass single pass followed by the number of triangles drawn by the renderer with all passes. These are the numbers that are most often implied when someone talks about "r_speeds." If the r_ext_multitexture variable is off, the numbers will reflect a more accurate accounting of the real triangle count (see multi-pass texturing section below).

# .## mtex #.## dc [definition under construction]

Frame Rate There is a tendency for rate of frame display to become a sort of god (or at least a "greatest good") for some players. Their quality of play, whether real or psychological, revolves around how fast their computer is flipping through screen updates. Everything else, to them, is throw away. While the design and complexity of a map can affect this, so can many features that are outside of the designer's control. For that reason, frame rate is not a particularly good way to judge the quality of your map.

The "cg_drawfps 1" command gives you instantaneous frame rate readout.

Use this command string to toggle the three at once. Include the following lines in your Debug Config script:

This command string script toggles the use of the PVS table to let you do this. It also toggles on the r_clear option, so instead of Hall of Mirrors the void beyond the world is seen in fashion doll pink.

This feature toggles between multi-pass texturing and single-pass texturing. When multi-pass texturing is enabled, the additional triangles are masked. They won't appear in the r_speeds report.

For this feature to work, the video must be restarted. That command is included in the binding. For best results, refrain from pressing the bound key again until the video has re-initialized and the map has re-loaded. Your normal setting for r_ext_multitexture should appear also. In the key binding below, it's been set to a value of 1, which is the most common. This way it will be properly set on startup, since this toggle can hose that setting.

Curves, Caulk, T-Junctions and Cracks

During the course of Quake III Arena development, a number of solutions were created to deal with the idiosyncrasies of the compiling process. None of these problems is a game killer, but the presence of these little flaws tends to reduce the professional appearance of game maps.

1. Avoid spanning more than one brush with one edge of a patch. For example, if an inverted bevel is 128 units tall, back it with 128 unit tall caulk brushes. Likewise, if the wall is made up of two vertically stacked brushes; use two vertically stacked patches of matching heights.
2. Avoid patches that extend into world brushes, unless all of the edges extend into world brushes. When adding patches, if one edge of the patch extends into the world, while the other edges line up with other brushes, there will most likely be cracking. Sometimes, particularly in the case of 'flesh' elements, it is necessary to extend parts of a patch into the world. In these cases, extend all edges into the world, or into surrounding patches.
3. Be Careful with vertices. Use Snap to Grid. Without it, your curves will create far more problems than they will otherwise might. Sometimes, especially after resizing patches, vertices can get "knocked off" the grid. Always make sure vertices are where they're supposed to be. If needed, patch vertices can always be snapped back to the grid using CTRL+ G. It's always a good idea to be completely aware of where things are in relation to the grid.
4. Caulk, caulk and more caulk. Get into the habit early of building the space behind curve patches with caulk brushes. You will eliminate Z-fighting, seal up the area behind the curves, and unless you are building a map in fashion doll pink, edges that aren't aligned with the curves have a better chance of showing up.

Here are a few examples of common elements from the maps in Quake III Arena, and how they should (and should not) be built to avoid Cracks and "Z-Fighting":

Jump Pads
Jump pads are probably the most common occurrence of T-junction cracks in Quake III Arena Maps. They usually extend upwards through at least two 'levels' (layers) of textures, so they're a perfect illustration of proper caulking. They are also a perfect illustration of 'binding' curves within structural brushes.

Flat arches
Flat Arches are another good example of 'binding' curves with structural brushes. This is a handy technique when incorporating a curve into a complex map element seamlessly.

Rounded Wall Edges (endcapped)
This is a simple example of terminating a wall in a rounded edge. The most important thing to keep in mind here is where the vertices are placed. If the patch is extended into the ceiling or floor, there will almost certainly be cracks.

Inverted Wall Bevels
Filleting a wall seems like it would be a simple thing, but there are many cases that could cause cracks. It's important to make sure heights are consistent, especially in the case of layered texturing, as is the case in this example.

\r_clear 1: This will clear the frame buffer on each frame, eliminating the Hall of Mirrors effect.

\r_fastsky 1: This will draw the sky as a single, solid color, making it easier to see the void behind curves. This makes cracks stand out. Be aware that fastsky also disables the function of portal screens and mirrors.

\r_showtris 1: This will draw white lines around all of the triangles in the world, showing exactly how the geometry in the map is affecting the patches.

NOTE: Another good way to use these commands is to set them to toggle on a key. The Debug Config below contains these commands as toggles.

Turn on r_clear, and r_fastsky, and run through the map, looking at the patches from all possible angles. If there is a crack, turn on r_showtris, and make sure that the patch does not extend into the world, unless it was intended to. Next, look at the surrounding brushes. Make sure that no splits meet the edge of the patch. If neither case is true (it happens these case… 'mystery cracks'), then try a different approach to building the area; perhaps splitting one patch into two, or rearranging the brushes surrounding the patch. When none of the above seems to work, experiment with as many different ways as possible. If something works, keep it in mind for the next time.

A Debug Config

Back | Home | Next