Added scrollbar picture support (builtin).
[divverent/nexuiz.git] / Docs / mapping.txt
1 ==============\r
2 =Mapping Help=\r
3 ==============\r
4 \r
5 While I can't help you make a map, I can help you get it listed in the menu and working in the maplist.  :p  The central object is the .mapcfg file, but there's much more available.\r
6 \r
7 Table of Contents\r
8 -----------------\r
9 I               Map Lists & Scripts\r
10                 (get your map listed and working)\r
11   i.            mapcfg\r
12   ii.           mapname.cfg\r
13 \r
14 II              Map Descriptions\r
15                 (get the picture and info to show)\r
16 \r
17 III             Domination\r
18 \r
19 IV              CTF\r
20 \r
21 V               Rune Match\r
22 \r
23 Appendix A      Advanced mapcfgs\r
24   i.            mapcfg revisited\r
25   ii.           exit cfgs\r
26 \r
27 Appendix B      Helpful extras\r
28   i.            Team Colors\r
29   ii.           Text Colors\r
30 \r
31 \r
32 ========================\r
33 =I. Map Lists & Scripts=\r
34 ========================\r
35 \r
36 \r
37 There are actually 3 script/cfg options available to you, each serving a different purpose and being executed at a different time during the map's life cycle:\r
38 1. The mapcfg\r
39 2. mapname.cfg\r
40 3. exit cfg (explained in Appendix A)\r
41 \r
42 Of these, the mapcfg is the only one that's truely required.\r
43 \r
44 -----------------\r
45 -The mapcfg file-\r
46 -----------------\r
47 \r
48 *cue scary music*\r
49 \r
50 The mapcfg file is basically what gets your map listed in the menu, and sets up the options needed to change to it.  This file is basically required in order for your map to work, though in a pinch you could say "map mymap" in the console.\r
51 The simplest mapcfg is simply a changelevel command, but you should usually add a timelimit and/or fraglimit to make sure your map will eventually change to the next map in the list.\r
52 \r
53 As an example, let's say I make a map called "wazat1.bsp".  As long as I'm fantasizing, I might as well say this map is so well done I'm actually willing to release it for friends, neighbors, fellow forum visitors and other people who like me to judge me by.\r
54 Let's also assume that I want domination, deathmatch/team deathmatch and runematch to all be playable on my map.\r
55 \r
56 This is very easy.  Let's start with domination.  I should make a file called "dom_wazat1.mapcfg" (and put it inside of the maps directory) and write the following inside of it:\r
57 \r
58         set g_domination 1              // turn on domination\r
59         set fraglimit 100               // 100 points to win\r
60         set timelimit 15                // 15 minute max round time\r
61         changelevel wazat1      // now change level\r
62 \r
63 Likewise, runematch is easy:\r
64 filename: "rune_wazat1.mapcfg"\r
65 \r
66         set g_runematch 1               // turn on rune match\r
67         set fraglimit 1000              // points to win\r
68         set timelimit 25                // round time\r
69         changelevel wazat1      // now change level\r
70 \r
71 \r
72 At this point I should say "okay, now it gets hard", but deathmatch and team deathmatch are easy (I skipped the comments in this one since they're fairly self-explanatory):\r
73 \r
74 filename: "dm_wazat1.mapcfg"\r
75 \r
76         set fraglimit 40\r
77         set timelimit 15\r
78         changelevel wazat1\r
79 \r
80 Team Deathmatch is turned on automatically if the server sets the "Force Teamplay" option and plays a deathmatch map, but you can add TDM as an option for your map too:\r
81 \r
82         set g_tdm 1                     // play team deathmatch\r
83         set fraglimit 50                // how many kills to win\r
84         //set timelimit 25              // disabled: don't bother setting a time limit\r
85         changelevel wazat1      // now change level\r
86 \r
87 \r
88 There's much more power in a mapcfg file.  See Appendix A for more details.\r
89 \r
90 -------------\r
91 -mapname.cfg-\r
92 -------------\r
93 \r
94 Unlike the mapcfg, which happens before the map loads (and is responsible for loading it), the mapname.cfg file doesn't exec until the map has mostly loaded.  This file is *usually* used to set values such as what music to play.\r
95 \r
96 Another difference from the mapcfg file is that mapname.cfg is global, meaning it doesn't matter if you're playing domination, deathmatch, or capture the flag, and it doesn't care what mapcfg was loaded.  It does the same thing every time this bsp file is loaded.  For that reason, this file should usually be used sparingly.\r
97 \r
98 To make the mapname.cfg, make a file with the same name as your map's .bsp file, except with a .cfg extension instead of .bsp.  For example, my "wazat1.bsp" map would use "wazat1.cfg".  It uses the same name as your map, thus the term mapname.cfg.\r
99 \r
100 \r
101 ======================\r
102 =II. Map Descriptions=\r
103 ======================\r
104 \r
105 \r
106 So, you've got your map listed in the menu and it plays properly, but the menu isn't showing your description and picture!  What manner of man would create such an accursed abomination?!\r
107 \r
108 Well... That sounds like something I'd do.  :D\r
109 \r
110 Luckily getting this to work is easy.  Just like you can have different mapcfgs for each map, you can have different descriptions.  In fact, those descriptions now match up with the mapcfgs, instead of the bsp files.\r
111 So, all you need to do is make a description for each mapcfg file.  Simple copy-pasting will fulfil this need, though a bit of modification between versions is prefered.\r
112 \r
113 There is one crucial difference in this map's format.  Like the old style, the first like is what appears in the title bar.  However, the second line is the map's image file.  This means you can have a separate image for each game mode your map supports, if you want: one for domination, one for ctf, one for regular dm, and so on.  Or you can use the same image for all of them.\r
114 \r
115 So how to do this?  Easy, just create a .txt file with the same name as the .mapcfg file.  For example, my wazat1.bsp has 4 mapcfgs:\r
116 dm_wazat1.mapcfg\r
117 tdm_wazat1.mapcfg\r
118 dom_wazat1.mapcfg\r
119 rune_wazat1.mapcfg\r
120 \r
121 I would then make 4 .txt files:\r
122 dm_wazat1.txt\r
123 tdm_wazat1.txt\r
124 dom_wazat1.txt\r
125 rune_wazat1.txt\r
126 \r
127 Each of these files can have the same content, but I recommend you change at least a little bit of it (such as the title bar).\r
128 Here is an example of what rune_wazat1.txt would look like (note that when you make your real file, you shouldn't tab it in):\r
129 \r
130         Wibble (rune_wazat1)\r
131         maps/rune_wazat1\r
132         \r
133         The only map I've ever\r
134         done right!\r
135         \r
136         Players: 3-8\r
137         \r
138         Weapons: Machinegun, Mortar,\r
139         Crylink, Nex, Rocket Launcher,\r
140         Hagar\r
141         \r
142         Powerups: None\r
143         \r
144         Gametype:\r
145         Rune Match\r
146         \r
147         Author:\r
148         Wazat\r
149 \r
150 \r
151 Notice the first line has the map's title (Wibble... what was I thinking?), and the filename of the mapcfg for the user to see (which from the player's point of view is essentially the map's filename).\r
152 \r
153 The second line defines where the image is that should be displayed.  This can be different for each game mode, but it doesn't have to be.  Note that you need to provide the right path (maps/), but you don't need to give an extension.\r
154 \r
155 The rest of the file is just plain text to print out as-is.\r
156 \r
157 \r
158 \r
159 =================\r
160 =III. Domination=\r
161 =================\r
162 \r
163 In order to get Domination working well in your map, you need to place dom_team and dom_controlpoint entites.  You *must* have at least 3 dom_team entities - 2 minimum teams and one blank one (empty netname and no team).  You can have up to 4 teams (5 dom_team entities).\r
164 \r
165 Dom Team\r
166 --------\r
167 classname       dom_team\r
168 netname         name of team (Red Team).  Set to "" or don't define for the required blank team.\r
169 cnt             color of the team.  See the "Helpful Extras" section for info.\r
170 model           When this team captures control points, the points turn to this model.  If this is the neutral team, points start out as this model.\r
171 noise           Sound to be played on the control point when it's captured.  Only players nearby will hear it.\r
172 noise1          Sound to be played to all players when the control point is captured.  Also good for an annoncer voice ("Red Team has captured a control point")\r
173 \r
174 Control Points\r
175 --------------\r
176 classname       dom_controlpoint\r
177 message         message to be displayed to all players when this point is captured, preceded by the team's name.  This defaults to " has captured a control point".  You can specify different names for each point, for example " has captured the Lava Room".\r
178 origin          where in the map this point is\r
179 wait            How often this point gives its controlling team frags.\r
180 frags           How many frags this point gives each wait cycle.\r
181 \r
182 \r
183 Here is an example entry in a .ent file that includes colored text and 3 teams:\r
184 \r
185 {\r
186 "classname" "dom_team"\r
187 "netname" ""\r
188 "model" "models/domination/dom_unclaimed.md3"\r
189 }\r
190 {\r
191 "classname" "dom_team"\r
192 "netname" "^4Blue Team"\r
193 "cnt" "13"\r
194 "noise" ""\r
195 "noise1" "domination/claim.wav"\r
196 "model" "models/domination/dom_blue.md3"\r
197 }\r
198 {\r
199 "classname" "dom_team"\r
200 "netname" "^1Red Team"\r
201 "cnt" "4"\r
202 "noise" ""\r
203 "noise1" "domination/claim.wav"\r
204 "model" "models/domination/dom_red.md3"\r
205 }\r
206 {\r
207 "classname" "dom_team"\r
208 "netname" "^2Green Team"\r
209 "cnt" "3"\r
210 "noise" ""\r
211 "noise1" "domination/claim.wav"\r
212 "model" "models/domination/dom_green.md3"\r
213 }\r
214 {\r
215 "classname" "dom_controlpoint"\r
216 "message" " ^3has captured the ^1Hallways"\r
217 "origin" "-206.0 -488.8 -150.0"\r
218 "frags" "3"\r
219 "wait" "5"\r
220 "scale" "1.3"\r
221 }\r
222 {\r
223 "classname" "dom_controlpoint"\r
224 "message" " ^3has captured the ^1Lavaroom"\r
225 "origin" "1457.1  19.9 -110.0"\r
226 "frags" "1"\r
227 "wait" "5"\r
228 }\r
229 {\r
230 "classname" "dom_controlpoint"\r
231 "message" " ^3controls the ^1Nex & Strength"\r
232 "origin" "-259.8 299.3  5"\r
233 "frags" "1"\r
234 "wait" "5"\r
235 }\r
236 {\r
237 "classname" "dom_controlpoint"\r
238 "message" " ^3has captured the ^1Upper Platform"\r
239 "origin" "539.7 1206.0 182.0"\r
240 "frags" "1"\r
241 "wait" "5"\r
242 }\r
243 {\r
244 "classname" "dom_controlpoint"\r
245 "message" " ^3has captured the ^1Teleport Room"\r
246 "origin" "-1000.0 636.2 -16.0"\r
247 "frags" "1"\r
248 "wait" "5"\r
249 }\r
250 \r
251 \r
252 As you can see in the example, there are 4 dom_team ents: one blank and then Red, Green & Blue.  Each control point has a different message (giving it a special name), and the one in the hallways gives 3 frags every 5 seconds instead of just one, making it more valuable.\r
253 \r
254 \r
255 \r
256 ==========\r
257 =III. CTF=\r
258 ==========\r
259 \r
260 Capture the flag needs at least 1 CTF flag per team, and can also make use of team spawnpoints.\r
261 \r
262 CTF Flags\r
263 ---------\r
264 classname       item_flag_team1 or item_flag_team2\r
265 angle           direction the flag will point\r
266 model           model of the flag (default: models/ctf/flag_red.md3 or models/ctf/flag_blue.md3)\r
267 noise           sound played when flag is stolen (default: "ctf/take.wav")\r
268 noise1          sound played when flag is returned by a teammate (default: "ctf/return.wav")\r
269 noise2          sound played when flag is captured (default: "ctf/capture.wav")\r
270 noise3          sound played when flag returns itself (default: "ctf/respawn.wav")\r
271 \r
272 Team Spawnpoints\r
273 ----------------\r
274 classname       info_player_team1 or info_player_team2\r
275 *note: These function just like info_player_deathmatch, but for one team only.  If you don't make team spawnpoints, info_player_deathmatch is used instead.\r
276 \r
277 \r
278 \r
279 ================\r
280 =III. Runematch=\r
281 ================\r
282 \r
283 Runematch needs only one type of entity to work: rune spawn points.  You will need at least one for each rune (5 minimum at the time of this writing), though you should probably have more than that in the map.  Just give the points a classname and origin.\r
284 \r
285 Rune Spawnpoints\r
286 ----------------\r
287 classname       runematch_spawn_point\r
288 \r
289 \r
290 \r
291 =================================\r
292 =Appendix A - Advanced Mapcfgs  =\r
293 =================================\r
294 \r
295 ---------------------\r
296 -i. mapcfg revisited-\r
297 ---------------------\r
298 \r
299 You now know how to make a basic, bare-bones mapcfg to set up a couple options and load your map.  However, there's much more you can do!  Consider these senarios:\r
300 \r
301 1. I want to play different music in ctf and domination\r
302 2. The laser has too high of a force for laser jumps and ruins CTF\r
303 3. I want to create fog in my map\r
304 \r
305 Each of these situations can be resolved with ease with a little work in the mapcfg file.\r
306 \r
307 You're already creating different settings between game modes with your gamecfgs, since you can choose different fraglimits.  You can also play different music.  The mapname.cfg file is global to all uses of your map, so instead of using it, we'll use the mapinfos.  You'll need to remove the music entry from the mapname.cfg file, and paste it into each of your mapname.cfg files *after* the changelevel command.\r
308 So, dom_wazat1.mapcfg would look like this:\r
309 \r
310         set g_domination 1              // turn on domination\r
311         set fraglimit 100               // 100 points to win\r
312         set timelimit 15                // 15 minute max round time\r
313         set changelevel wazat1  // now change level\r
314         cd loop "8"             // play music\r
315 \r
316 You can choose different music for each of your game modes by changing that last line.  Just make sure your map.cfg file doesn't have a cd loop command in it, or it'll overwrite what you've done.\r
317 \r
318 ---------------\r
319 -ii. exit cfgs-\r
320 ---------------\r
321 \r
322 In order to solve our laser jumping problem, we need to call upon another feature of mapcfgs -- map exit scripts or "exit cfgs".  These are called when the map is changing, before the next map's mapcfg is run.  You can use them to clean up any special changes you've made so they won't affect the next map.\r
323 \r
324 For our laser jumping example, we could do something like this:\r
325 \r
326          // set up the exit cfg so we can reset values to what they were before\r
327         set exit_cfg "maps/dom_wazat1_exit.cfg"\r
328          // make a backup\r
329         set BACKUP_g_balance_laser_force $g_balance_laser_force\r
330          // map-customized values here\r
331         set g_balance_laser_force 100\r
332          // and on with the rest of the config\r
333         set g_domination 1              // turn on domination\r
334         set fraglimit 100               // 100 points to win\r
335         set timelimit 15                // 15 minute max round time\r
336         set changelevel wazat1  // now change level\r
337         cd loop "8"             // play music\r
338 \r
339 Then we would make the exit cfg, named "dom_wazat1_exit.cfg":\r
340 \r
341          // reset laser damage\r
342         set g_balance_laser_force $BACKUP_g_balance_laser_force\r
343 \r
344 \r
345 When my wazat1 map is run in domination, the laser's force will only be 100.  However, before the map changes, it gets set back to what it was before.  This is because the original value was stored in BACKUP_g_balance_laser_force, then BACKUP_g_balance_laser_force was copied back into g_balance_laser_force when the exit cfg ran.\r
346 \r
347 \r
348 You can set all kinds of values like this, including fog and gameplay options.\r
349 \r
350 \r
351 \r
352 \r
353 ===============================\r
354 =Appendix B - Helpful Extras  =\r
355 ===============================\r
356 \r
357 ----------------\r
358 -i. Team Colors-\r
359 ----------------\r
360 When you need to set an entity's color or team, use these values:\r
361 \r
362 Red\r
363 ---\r
364 Team:   5\r
365 Color:  4\r
366 \r
367 Blue\r
368 ----\r
369 Team:   14\r
370 Color:  13\r
371 \r
372 Green\r
373 -----\r
374 Team:   4\r
375 Color:  3\r
376 \r
377 Yellow\r
378 ------\r
379 Team:   13\r
380 Color:  12\r
381 \r
382 \r
383 \r
384 ----------------\r
385 -i. Text Colors-\r
386 ----------------\r
387 Occasionally you may want to print text in color, such as team names.  Here are your options:\r
388 \r
389 1  Red\r
390 2  Green\r
391 3  Yellow\r
392 4  Blue\r
393 5  Cyan\r
394 6  Magenta\r
395 7  White\r
396 8  Gray\r
397 \r
398 \r
399 \r
400 \r
401 \r
402 \r
403 \r
404 \r
405 \r
406 \r
407 \r
408 \r
409 \r