The most common problems you might encounter can be put in one of the categories below. If some category names don't make sense to you, you should begin by reading their first paragraph to know how things are organized. This page also contains links to on-line information or forums which you should use.

The map editor is the most widely used part of QuArK. When you first try to use it, you might have troubles in understanding what's going on. The basic idea is that you build polyhedrons (cubes or more complex) to make the shape of the map (walls, floors, ceilings...), and then you put entities to populate it (monsters, lights, doors...).

It is important to distinguish between what is related to QuArK's map editor and what is related to the game you are making maps for. For example, how you give complex shapes to polyhedrons or how you change the attributes of entities is related to the map editor. On the other hand, what all these entity attributes actually mean is related to the game only, and so is the list of entities and textures you can use; see 'Entities and other features that depend on the game only' below.

For the basic QuArK-related operations, you can get help from one of the available tutorials. A basic one is found in the documentation of the map editor (included in the QuArK distribution). Other ones are found on the QuArK web site.

Questions about this subject are welcome in the QuArK forum. See also the on-line docs on the web site.

Map compiling is the process of translating a map you made in the editor into something that the game can read, namely a  .BSP  file. In QuArK, this is done when you select a command in the "Quake" menu (or "Half-Life", or "Hexen II", or whatever the game is). This is what occurs in the black window with scrolling text. The map compilers are programs written by the authors of the game (e.g. id Software) and not by the QuArK developers, so our knowledge about them is limited. (These tools are found in the "Build Pack" corresponding to your game; see the download page on the web site.)

There are tons of problems that can occur at map compiling time. You will often get a cryptic error message at the bottom of the black window. This is 99% of the time not related to QuArK itself; either you made an "error" in your map, or you ran into one of the numerous bugs and limitations of the map compiler programs. Errors in the map include, for example, "holes", that is, gaps between polyhedrons that would let you see "outside" the map into the so-called void. You must always think about a map as floating in the outer space, and you can imagine you must prevent the air from escaping. Thus there must not exist any path from an entity of your map to the outer space. This error can be complex to localize, and only the map compilers can find it. QuArK can check for the other most common map errors before it starts the map compilers.

If you have strange problems in the game itself, like some walls being not displayed, this is also often related to the map compilers. One more time, it's important to understand that QuArK, like any other map editor, only lets you design a map, and with it you can put virtually any kind of polyhedron or entity in it. What the map compilers and the game itself will do with these polyhedrons and entities is no longer related to the map editor.

Map compiling is a complex subject and you can find a lot of information about it (not related to QuArK) at PlanetQuake. See also the links (right column in the current design) on the QuArK site, as well as the on-line docs. See also this page about compiling.

As explained in 'Compiling maps' above, some stuff depends on the game you are making maps for. This includes which entities you can use, which settings of these entities you can change, and what these settings really do. The list of textures you see in QuArK also depends on the game -- it's actually the list of the textures used in all the original maps of the game. Some games also have per-face attributes that let you make polyhedrons translucent or light-emitting, for example.

A typical example of this are ladders. You first make a polyhedron structure with two vertical bars and a lot of horizontal steps, but this is not enough to let the game know that the player should be able to climb there. The way you do the latter depends on the game you are using. In Quake 2, for example, you must set a flag on the polyhedron faces (there is a button "polyhedron flags" bottom left when you click on a polyhedron). But in Half-Life, you must use a special invisible entity "func_ladder" and put it around the actual ladder structure. If you want to know the exact way to do this in QuArK, see 'Using the map editor' above; but if you didn't know that you had to use a flag for Quake 2 and a "func_ladder" for Half-Life, read on.

The game-dependent features are not related to QuArK itself: All the map editors available on the Internet will provide you with a list of entities and textures and settings; what these settings actually do is programmed in the game itself. For information about this subject, you can look for general documentation at PlanetQuake. The other sources are Quake editing forums. You can use the QuArK forums (please mention explicitly which game you are using!). See also the links (right column in the current design) on the web site, as well as the on-line docs. There is also a Quake 2 - specific page on the web site.

An unexpected behavior is a QuArK bug unless it enters the category of 'Compiling maps'. A typical bug comes as an error message with a button "More>>" that will let you copy and paste a detailled bug report. Then send the bug to the QuArK-forum, including the bug report and what you were doing when the bug occurred. If the bug can be reproduced, please give a step-by-step procedure to follow to reproduce it.

In the recent versions of QuArK 5 and 6, there are some known problems; please don't report them. These include troubles with the 3D viewers on some 3DFX graphic cards. A description of these troubles and proposed solutions are discussed in the forum. Cdunde also writes news about important bug fixes and workarounds on the news page of the web site.

Here is one of the most common known bugs (please don't report it again, we're working on it!): I've heard that QuArK often has troubles with the most recent Glide drivers. Try using older drivers. Find an old driver, get its file "GLIDE2X.DLL", and put it into the QuArK directory. Doing it this way won't prevent other programs and games to use the already-installed recent drivers; only QuArK will use the old ones.

Beyond its basic features, the map editor has numerous advanced features which are not absolutely necessary but that will still help you a lot, particularily on large maps. These features include duplicators, diggers, face sharing, group masking, etc. Some features also come from plug-ins written by other people.

The main source of information for advanced map editor features are my Advanced Features pages.

For textures and prefabs, see 'Other parts of QuArK (incl. textures, prefabs and templates)' below.

The other parts of QuArK lack documentation. The general way QuArK works -- besides the map editor -- is by displaying files in windows with trees that describe the structure of the file. This lets you easily edit e.g.  .PAK  files. The texture browser, too, has a tree at its left, and the "New Map Items" window is itself a big tree. You work with trees a bit like you do with the Windows Explorer: Use the mouse to drag and drop or copy and paste anything, and use the right button while clicking or while dragging to get a pop-up menu. There are also commands in the menus to make new folders, etc.

If you want to make changes in a tree -- e.g. make your custom textures or add new map items or prefabs -- you should first create a new "main folder" with the corresponding item in the "Folders" menu. This command will let you specify in which file this new main folder should be stored. You can then add stuff with the copy and paste, with drag and drop, or with the buttons at the top of the window, like "new sub-folder", "new texture list", "new texture", etc.

• Example 1: creating new textures.
  In the texture browser, select "Folders", "New Main Folder". Choose the option that best suits your needs, then click Ok. Then click on the new folder called "New Folder" (you can rename it if you like by single-clicking on its name, as usual). Click on the button "new texture list" at the top. This create a sub-folder where you can store textures. Use the above buttons "new texture" to create new textures. These buttons create sub-objects in the folder, that is, they create an initially black texture. You should first rename it, and then you can edit it by clicking on the button "call external editor". Note that all these buttons at the top only appear when you select the corresponding object in the tree.
• Example 2: making prefabs.
  Same procedure as above but in the New Map Items window. To organize the prefabs in sub-folders, use the command "New sub-folder" in the "Folders" menu. Use copy and paste from the map editor. Also note that map prefabs can also be drag-and-dropped directly on the panel at the left in the map editor, where there are already a cube and a light by default.
• Example 3: making & using templates.
  Templates are somewhat like prefabs but far more powerful. There is also a specific setting for selecting a Templates folder for each game that QuArK supports in the Games Configuration section of every game. For a complete understanding of templates please see its own section in Misc tools.

All your changes are saved in the file you specified in "New Main Folder". This is an "add-on" file that you can pass to your friends, if you like. Your friends must use the "Games" menu, "Add-ons", in QuArK's main window, to use your add-on.

If you want to help with QuArK's development, here is how you can do various things. You don't have to be a programmer to give some help! If you need help about these ways of helping, see the QuArK forum on the web site.

• Testing:
  QuArK's development team is rather small, and have other responsibilities to attend to, so systematic testing of new features by users can be quite helpful, and of course requires no knowledge of programming, only mapping (and is not at all a trivial thing to do, and can be quite time-consuming). In the same vein, intelligent comparisons of QuArK's features with those of other editors can be quite useful; it may or may not be easy or even possible to implement your favorite feature from Editor X, but if we know about it, we can at least think about trying.
• Support for a mod:
  If you want to write support for a game mod (e.g. a Mission Pack or any smaller mod), you have to write a small add-on file which lists the new entities available and their attributes, as well as the new textures, if any. This process is relatively easy. Try opening with any text editor one of the add-on files included in the QuArK distribution, e.g. "CTFq2.qrk" (Capture-The-Flag for Quake 2.) This is the kind of file you have to write. This is described in detail in 'Advanced customization'.
• Fixes and enhancements in the existing game data:
  If you want to enhance the existing game-specific data (e.g. the entity lists, the available entity settings, and on-line help for all this), you can do so by editing the files "DataXXX.qrk" -- "DataQ1.qrk" for Quake 1, "DataQ2.qrk" for Quake 2, etc. The format of these files is the same as for the add-ons for the support of a mod, with a single difference: For performance, these large files are not directly editable with a text editor; instead, they are stored in a binary format. You can get the original full-text files from 'The code repository at SourceForge' in the directory runtime/addons.
• A Python plug-in:
  A large part of the map editor is written in a scripting language called Python. This code is distributed with QuArK -- you already have it in the  .PY  files of the directories "quarkpy" and "plugins". If you want to program an enhancement to the map editor, you can probably do it in Python, just by modifying these files or adding a new file in "plugins". No other tool is needed. For a first project, a new plugin is best; it can be uploaded for testing to the files section of the quark or quark-python egroups, and if it is generally accepted as useful, somebody can commit it to the main code body at SourceForge. Plugins will usually work with quite a wide range of QuArK versions, so that people don't have to have the latest bleeding edge snapshot to test them, and if a plugin causes a problem, this problem can be fixed by deleting the plugin's  .PY  and  .PYC  files. More ambitious projects might involve changes to the quarkpy Python modules, or even the Delphi source code, but it's best to do a simple plugin first. For more information about Python, you can refer to the Python home page, and for Python in the context of QuArK, 'Advanced customization'.
• Direct changes in the source code:
  The source code of QuArK is freely available, by various forms of access from project QuArK on SourceForge (anonymous CVS/WinCVS is probably the most convenient, once you can get it working). The main programming language is Borland Delphi, either 5 or 6 will do. Personal Version 6 is quite adequate, and is available as a free download from Borland. If you want to program a new interface feature (such as a dialog box to hunt for things in the map having some properties, or maybe a new map layout such as perhaps something that works like the XY view in Radiant, with the vertical Z window, etc.), most or very likely all of the coding would be in Python. Reading and writing map or model formats for new games on the other hand will typically involve some Delphi coding.

As stated above, you can find more help about this subject in the QuArK forum on the web site.

The 'The Source Code' section of the infobase is gradually coming to contain more information about how the Delphi code works and how it relates to the Python.