OpenArena's Mapping manual
ProloguePre-mapping stageMap gameplayChoosing an editorYour first mapBrush manipulation2D/3D clippingCurve manipulationTexturesIntroduction to EntitiesLightingAdvanced lightingWeapon/Item placementTriggers and moversDynamic featuresShadersTerrains and liquidsMapmodelsSoundsGametype supportOptimization and TroubleshootingHint brushesBot playTroubleshootingFinal touchesCompilation & packaging
Glossary of termsAdvanced featuresModelling a mapEditor differencesDefault assets (Textures/Models/Sounds) • GPL

In this page we try to help you fixing some errors and common problems you may encounter with creating, compiling and running your own maps.

In-game problems[]

Launching your WIP map[]

Map not found[]

You already compiled your map, but you get "RE_LOADWORLDMAP: MAPS/MYMAP.BSP NOT FOUND" error trying to load it in-game? Probably you forgot to set /sv_pure 0 or to correctly package the map inside a .pk3 file. By default, the game does not load stuff (such as maps, textures, shaders, etc.) which is not in .pk3 files.

Couldn't find a spawn point[]

If you get the "COULDN'T FIND A SPAWN POINT" error when trying to load your map, then check the player spawn points you placed, to be sure there are at least 8 deathmatch spawn points without gametype limitation, better if at least 16. All maps, including CTF-based maps, should contain deathmatch spawn points placed around the arena and available in any gametype, to avoid crashes when launching the map on different gametypes.

See also Mapping manual/Your first map, Mapping manual/Additional gametype support.

Requested feature was omitted at compile time[]

If you get "Requested feature was omitted at compile time" error, it could be that you used a jpg image with progressive encoding. DO NOT DO THAT. Some versions of game binaries support them, but other don't, crashing the game at map loading. Do not use progressive enconding jpg: even if they do work on your system, they could crash the game for someone else! Please re-save your image as a standard jpg.

Bot problems[]

Cannot add bots[]

  • Your map loads, but you cannot add bots to it? Scroll back your console output: under "map loading" section, you may see a red "Fatal: can't open maps/MYMAP.aas" or "Fatal: aas file maps/MYMAP.aas is out of date" message. The first case means the game cannot find the bot-navigation file for this map, the second case means it found the file, but it has been compiled for a different version of the map. So, you have to use BSPC to create the .AAS file for the current version of your map. When you package your .bsp map inside a .pk3 file, don't forget to include its .aas file, too. See Mapping manual/Compiling and packaging and Mapping manual/Bot play.
  • If you see a red "Unable to add bot. All player slots are in use." message in console when you try to add one, check your /sv_maxclients value and modify it to be sure there are enough slots for more players or bots joining the game; in case you change it, you need to restart the map.

Bots behave strangely in case of gametype-restricted brushes[]

"Gametype" and "!Gametype" keys are primarily thought for entities, not for brushes (func_static exists, but use with care, with non-solid decorations mostly). As a general rule, you cannot use them to make changes in map flow for different gametypes, as bots will always consider those brushes there, even if they are removed from the current gametype. So you may see them repeatedly falling in a pit due to a boardwalk removed from current gametype.

Bots do not use grapple[]

If you added an offhand grapple (a.k.a. hook) to your map, you may have noticed bots do not use it at all. In short, bot do not completely support it yet.
For bots to use it, you need to compile .aas with "-grapplereach" option, and also to enable a specific variable in game. But the variable is disabled by default because Q3A left grapple support unfinished and bots behave buggy when it is enabled. However, you may still want to compile your aas with -grapplereach option, to have your map compatible in case some future OA version would fix bot grapple support. See also Manual/Weapons#Offhand grapple and Manual/Weapons/Appendix.

Brief hitches happen when there are bots in the map[]

If you notice some brief hitches only when there are bots in the map (not counting when a new player or bot joins the server), you may be facing a "bot stutter" problem due to the map not being bot-optimized enough. If there are too many areas in a single bot cluster, bot logic may sometimes require too much time to decide where to go then. If that's the case, you may notice the hitches more often, if you add more bots. You may solve the issue by better bot-optimizing your map, by "clipping" it (making geometry simpler with clip, botclip, weapclip) and mostly by using "cluster portals". Please follow Mapping manual/Bot play page.


Flickering surfaces[]

If you see a spot on the map "flickering", it may probably be due to some overlapping brushes. Return to the editor and check that section carefully, idenfity the overlapping brushses and modify them to avoid overlapping. Usually, brushes should touch each other only with their external surfaces, one should not be inside another one.

In particular cases, you may make a sort of "decal" by using "PolygonOffset" parameter on the shader of one of the two overlapping brushses (e.g. the one depicting a partially transparent logo). That parameter causes the surface to be rendered slightly off the polygon surface, also avoiding the flickering effect in case of overlapping brushes.

Thin border shown around transparent things[]

[Note: this one should probably be rewritten with better explanation.]

Some objects (usually, lights) may show a glitch of a thin colored border where they should be transparent, showing an edge that should be invisible. That sort of "bleeding edge glitch" behavior can be avoided by following the steps described in these images (click to enlarge):

They have been originally posted by LauraNeko in this post on the forums.

Sound problems[]

Sound effect played at half speed and truncated[]

Sound files to be used with entities such as target_speaker have to be in MONO format. In case you use a stereo sound, it will be played at half speed and truncated in case of SDL audio and played at full volume (instead of fading out while you get far from its source) in case of OpenAL audio. Solution is to use a software to make your sound file mono. Does not apply to background music.

Sound effect or background music not played[]

In case of sound effect or background music not played, please check:

  • What are your /s_volume and /s_musicvolume CVARs values? "1.0" means full volume, "0.0" means mute.
  • Is the sound in the right folder? Is it packaged in a .pk3, or are you testing with /sv_pure 0?
  • Did you specify the extension for the sound file in the entity? It is advisable to do NOT specify the .wav or .ogg extension, so the engine will automatically search for both. In case you specify an extension, in OA 0.8.8 it works this way (differs in case of sound effect or background music):
    • If it's a sound effect from a target_speaker entity, specifying "sound/mymap/sound1" or "sound/mymap/sound1.wav", in both cases will search for "sound/mymap/sound1.wav" and "sound/mymap/sound1.ogg". Specifying "sound/mymap/sound1.ogg", instead, would search for "sound/mymap/sound1.ogg.wav" and "sound/mymap/sound1.ogg.ogg", and probably you don't want that.
    • If it's a background music specified in worldspawn entity, specifying "music/music1" will search for "music/music1.wav" and "music/music1.ogg". Specifying "music/music1.wav" will search for "music/music1.wav" only and "music/music1.ogg" will search for "music/music1.ogg" only.
  • 32 bit PCM wav files are not supported (and would have very little sense to be used in a game).
  • Do you hear any other sound from your speakers, from OpenArena of from any other program in your Oprating System? Maybe volume may be turned off in your OS, or your speakers may be off or disconnected.
  • Did you try turning on or off OpenAL sound system (/snd_restart might be required)? Maybe you have some problem with one of the two sound modes.
    • OpenAL has got a problem at least with "always on" target_speaker entities: it considers VIS optimization (which is meant for rendering graphics) so you might hear the sound abruptly start/stop when you move or look around. Workaround for this include (player-side) disabling OpenAL and (mapper-side) either skipping VIS optimization phase while compiling the map (which probably isn't a good idea) or trying to workaround the problem by placing multiple target_speaker entities (probably at lower volume) around, to better cover the area trying to avoid the abrupt sound start-stop from being too noticeable (potentially requiring a lot of trial-and-error); a midground could be making the brushes which cause the sound to stop as "detail" instead of "structural" (those brushes would not cause VIS optimization, but the rest of the map still would).
      Some more info here and here.

WARNING: music file music/XXXX is not 22k stereo[]

Do you see "WARNING: music file music/XXXX is not 22k stereo" in console?
This yellow warning message is just a leftover, from Quake3 expecting 22Khz music files. You can just ignore it and use your 22/44k mono/stereo file for map background music as you wish. The warning is NOT displayed in case the user has got /s_useopenAL 1 with OpenAL library installed.
However DO NOT use 32 bit PCM wav files, as they are not supported (and would have very little sense to be used in a game).


Some items do not appear in the map[]

If some items you placed do not appear in the map, you can check the following:

  • Maybe you placed them too near to a solid brush (e.g. floor, wall), and they do not have enough room for spawning. Scroll back console output, searching for "<item> in solid/startsolid at (X, Y, Z)" (under "---- Map Loading ----" section and below "AAS initialized"). This is a check you should always do before publishing your "finished" map: you may have "lost" some items "in solid" even if you didn't notice. In that case, move a bit your entities (horizontally or vertically) so they have some more space around them.
  • Maybe you used "gametype" or "!gametype" key on those entities, and you forgot about it, or mistyped gametype name. See Mapping manual/Additional gametype support#The "gametype" and "!gametype" keys.
    • Also check if you set "notfree", "notteam", "notsingle" keys (which are not used often, but check anyway).
  • Don't forget that powerups (quad damage, etc.) do not appear immediately at match start, but after some time. If you loaded your map in "devmap" mode, you can set an higher "timescale" value (default is 1.0) to make time pass faster, and check the item actually spawns.
  • Runes are only shown if /g_runes is set to 1 (default value is 0).
  • Are you using a mod? Items do not appear in mods which do not support them. Nailgun, Chaingun, Proximity mines and their ammo boxes; Invulnerability, Kamikaze and the four Runes (ammo regen, doubler, guard, scout) are not supported by most old mods.
  • Items could be set in "team" with other items. In that case, they do spawn alternately (and in random sequence) with the other items with the same "team" key. If this is the case, the item you are searching for should appear after you grab the other teamed ones a few times.
  • Are you sure you didn't set Disabling and replacing items features, right?

Area portals, cluster portals[]

Doors disappear while inside an area portal brush[]

In case you see all areaportal doors disappear while you walk through one areaportal brush, try making that brush common/areaportal on one side only, and make its other faces as common/nodraw.

Shader problems[]

Cannot find shaders in-editor, or shaders not working as expected in-game[]

  • In case you can't find any or some shaders in the editor, or in case they don't work as expected in-game:
    • First please check your editor has the option to show shaders enabled and use "flush & reload shaders" (very useful if you just modified a .shader file).
    • Then check your shaderlist.txt file (should be your baseoa/scripts folder under your OA installation path), to be sure the .shader file including the shaders you need is listed. Shaderlist.txt file is read by map editor and not by the game itself (you have not to include it into .pk3 files), but it's important it's correct when you compile the map.
    • Also, consider that after you modify a .shader file, some changes (mostly those in "stages") do not require to recompile the map, but others (most of general parameters) do require recompiling. So you may want to reload shaders in editor, save and compile the map again.
    • Then, check for errors in the shader code itself. Consider that sometimes even changing the order of the parameters gives different results.
    • Don't forget the general rule that the game does not load shaders (and their images) unless you set /sv_pure 0 or package them into .pk3 files.

Shader image missing[]

  • In case of YOUR shaders appearing as "shader image missing" in the editor: check your .shader file to be sure you correctly used qer_editorimage parameter to specify the image. Sometimes you may want to create small support images just to be used as shader icons (e.g. waves with an arrow to quickly recognize the scrolling direction of a flowing water shader).
  • In case STOCK OpenArena shaders appearing as "shader image missing" in the editor: it's not a good idea to modify stock OpenArena files. However, if you really want to see those images in the editor, you may copy the shaders you need (e.g. common/areaportal) to a new .shader file of yours, add that file to your shaderlist.txt, and give the shader a different path and name (e.g. myshaders/myareaportal). This way, you could make any kind of change to the shader without affecting original shader. Don't forget to include your new .shader file in the .pk3 of your map.
  • Shader shown as "missing texture" in-game (black and white squares) may have various causes... for example you may check:
    • That the right version of your .shader file is correctly packaged in a .pk3 file OR that you loaded the map with /sv_pure 0 (to load stuff outside from pk3 files). Same goes for all the image files loaded (e.g. by map, clampmap, animmap parameters) by the shader.
    • Check correct usage of shader properties and shader stages options. Mostly, that image path in "map/clampmap/animmap" is correct, but also usage of "farbox" for the sky, and blend options in general.
    • In some cases, taking a look to command console output may give some hint about problems.

Compiling errors[]

Compiling maps[]

Compiling AAS files[]

External links[]

See also[]

<< Previous (Bot play) Mapping manual (The final touches) Next >>