Merge branch 'northivanastan/documentation' into 'master'
[xonotic/xonotic.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\r
6 working in the maplist. :p  The central object is the .mapinfo file, but\r
7 there's much more available.\r
8 \r
9 Table of Contents\r
10 -----------------\r
11 I        Map Settings\r
12          (get your map listed and working)\r
13 \r
14 II       Map Image\r
15 \r
16 III      Domination\r
17 \r
18 IV       CTF\r
19 \r
20 V        Race/CTS\r
21 \r
22 VI       Nexball\r
23 \r
24 Appendix A - Advanced mapinfo\r
25 \r
26 Appendix B - Helpful extras\r
27   i.     Team Colors\r
28   ii.    Text Colors\r
29 \r
30 Appendix C - Advanced Darkplaces shaders\r
31 \r
32 =================\r
33 =I. Map Settings=\r
34 =================\r
35 \r
36 All map specific settings goes in a single file:\r
37 \r
38 mapname.mapinfo\r
39 \r
40 The mapinfo file is basically what gets your map listed in the menu, and sets\r
41 up the options needed to change to it. If no mapinfo file exists, the menu\r
42 will automatically generate a rough draft for you on game startup. It will get\r
43 stored into data/data/mapname.mapinfo.\r
44 \r
45 As an example, let's say I make a map called "wazat1.bsp". As long as I'm\r
46 fantasizing, I might as well say this map is so well done I'm actually willing\r
47 to release it for friends, neighbors, fellow forum visitors and other people\r
48 who like me to judge me by. Let's also assume that I want domination,\r
49 deathmatch/team deathmatch to all be playable on my map.\r
50 \r
51 This is very easy. First, I start the game and exit it again so the game writes\r
52 data/data/wazat1.mapinfo for me. The file may look like:\r
53 \r
54     title Wazat's Great Map\r
55     description Bleh.\r
56     author Unknown\r
57     _diameter 1966.839355\r
58     _spawnpoints 5\r
59     has weapons\r
60     cdtrack 5\r
61     gametype dm // defaults: timelimit=20 pointlimit=30 leadlimit=0\r
62     gametype dom // defaults: timelimit=20 pointlimit=200 teams=2 leadlimit=0\r
63     gametype lms // defaults: timelimit=20 lives=9 leadlimit=0\r
64 \r
65 As I see, the menu autodetected that my map may be suitable for deathmatch,\r
66 domination, last man standing and keepaway. But I want the map to be played in\r
67 domination, deathmatch, team deathmatch only, and I also want different\r
68 timelimits/fraglimits, so I will change the "gametype" lines to:\r
69 \r
70     gametype dom pointlimit=100 timelimit=15\r
71     gametype dm pointlimit=40 timelimit=15\r
72     gametype tdm pointlimit=50 timelimit=0 teams=2\r
73 \r
74 Also, while I am at it, I should fix the placeholders in the map description lines:\r
75 \r
76     title Wibble\r
77     description A large multi level arena map\r
78     author Wazat\r
79 \r
80 Although not entirely necessary, I will now move the .mapinfo file from\r
81 data/data/maps/wazat1.mapinfo to data/maps/wazat1.mapinfo, so it is at the same\r
82 place as my map. Next time I start the game, my map will be shown supporting\r
83 the right game modes and with the right description in the menu.\r
84 \r
85 Also, note the "has weapons" line. If this line is not there (which happens if\r
86 the map contains no weapon entities other than the Nex), the map will run in\r
87 InstaGib only and not be shown in the menu normally. So if you look for your\r
88 map and don't find it, add "has weapons" to the mapinfo file, and make sure you\r
89 have weapon entities placed.\r
90 \r
91 There's much more power in a mapinfo file. See Appendix A for more details.\r
92 \r
93 Gametype        | Syntax                                                                                                   | Notes\r
94 ----------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------\r
95 Deathmatch      | gametype dm [timelimit=...] [pointlimit=...] [leadlimit=...]                                             |\r
96 Team Deathmatch | gametype tdm [timelimit=...] [pointlimit=...] [teams=...] [leadlimit=...]                                | 2, 3, or 4 teams\r
97 Domination      | gametype dom [timelimit=...] [pointlimit=...] [teams=...] [leadlimit=...]                                | 2, 3, or 4 teams, only if map has no dom_team ents\r
98 CTF             | gametype ctf [timelimit=...] [caplimit=...] [leadlimit=...]                                              |\r
99 LMS             | gametype lms [timelimit=...] [lives=...] [leadlimit=...]                                                 |\r
100 Key Hunt        | gametype kh [timelimit=...] [pointlimit=...] [teams=...] [leadlimit=...]                                 | 2, 3, or 4 teams\r
101 Assault         | gametype as [timelimit=...]                                                                              | never uses points\r
102 Onslaught       | gametype ons [timelimit=...]                                                                             | never uses points\r
103 Race            | gametype rc [timelimit=...] [qualifying_timelimit=...] [laplimit=...] [teamlaplimit=...] [leadlimit=...] | g_race_teams: teamlaplimit is used instead of laplimit\r
104 CTS             | gametype cts [timelimit=...] [skill=...]                                                                 | never uses points\r
105 CA              | gametype ca [timelimit=...] [pointlimit=...] [teams=...] [leadlimit=...]                                 | 2, 3, or 4 teams\r
106 Nexball         | gametype nb [timelimit=...] [pointlimit=...] [leadlimit=...]                                             |\r
107 Freeze Tag      | gametype ft [timelimit=...] [pointlimit=...] [teams=...] [leadlimit=...]                                 | 2, 3, or 4 teams\r
108 Keepaway        | gametype ka [timelimit=...] [pointlimit=...]                                                             |\r
109 \r
110 \r
111 ===============\r
112 =II. Map Image=\r
113 ===============\r
114 \r
115 So, you've got your map listed in the menu and it plays properly, but the menu\r
116 isn't showing your picture! Or the picture is scaled badly! What manner of man\r
117 would create such an accursed abomination?!\r
118 \r
119 Well... That sounds like something I'd do. :D\r
120 \r
121 And it is really easy: just make a screenshot of the map in action (preferably\r
122 with crosshair and HUD switched off), and place it next to the map as\r
123 mapname.jpg. For best rendering and file size, make the image in 4:3 aspect\r
124 ratio, but scale it to the resolution 256x256 or possibly 512x512. It will look\r
125 skewed in your image editing app, but the menu will show it right, and your\r
126 graphics card LOVES images of such dimension.\r
127 \r
128 \r
129 =================\r
130 =III. Domination=\r
131 =================\r
132 \r
133 In order to get Domination working well in your map, you need to place dom_team\r
134 and dom_controlpoint entites. You *must* have at least 3 dom_team entities - 2\r
135 minimum teams and one blank one (empty netname and no team). You can have up to\r
136 4 teams (5 dom_team entities), and remember: if you set 3 teams, the third team\r
137 must be the yellow one, according to the team order.\r
138 \r
139 Dom Team\r
140 --------\r
141 classname  dom_team\r
142 netname    name of team (Red Team). Set to "" or don't define for the required\r
143            blank team.\r
144 cnt        color of the team. See the "Helpful Extras" section for info.\r
145 model      When this team captures control points, the points turn to this\r
146            model. If this is the neutral team, points start out as this model.\r
147 noise      Sound to be played on the control point when it's captured. Only\r
148            players nearby will hear it.\r
149 noise1     Sound to be played to all players when the control point is\r
150            captured. Also good for an annoncer voice ("Red Team has captured a\r
151            control point")\r
152 \r
153 Control Points\r
154 --------------\r
155 classname  dom_controlpoint\r
156 message    message to be displayed to all players when this point is captured,\r
157            preceded by the team's name. This defaults to " has captured a control point".\r
158            You can specify different names for each point, for example " has captured the\r
159            Lava Room".\r
160 origin     where in the map this point is\r
161 wait       How often this point gives its controlling team frags.\r
162 frags      How many frags this point gives each wait cycle.\r
163 \r
164 Here is an example entry in a .ent file that includes colored text and 3 teams:\r
165 \r
166 {\r
167 "classname" "dom_team"\r
168 "netname" ""\r
169 "model" "models/domination/dom_unclaimed.md3"\r
170 }\r
171 {\r
172 "classname" "dom_team"\r
173 "netname" "^4Blue Team"\r
174 "cnt" "13"\r
175 "noise" ""\r
176 "noise1" "domination/claim.wav"\r
177 "model" "models/domination/dom_blue.md3"\r
178 }\r
179 {\r
180 "classname" "dom_team"\r
181 "netname" "^1Red Team"\r
182 "cnt" "4"\r
183 "noise" ""\r
184 "noise1" "domination/claim.wav"\r
185 "model" "models/domination/dom_red.md3"\r
186 }\r
187 {\r
188 "classname" "dom_team"\r
189 "netname" "^3Yellow Team"\r
190 "cnt" "12"\r
191 "noise" ""\r
192 "noise1" "domination/claim.wav"\r
193 "model" "models/domination/dom_yellow.md3"\r
194 }\r
195 {\r
196 "classname" "dom_team"\r
197 "netname" "^6Pink Team"\r
198 "cnt" "9"\r
199 "noise" ""\r
200 "noise1" "domination/claim.wav"\r
201 "model" "models/domination/dom_pink.md3"\r
202 }\r
203 {\r
204 "classname" "dom_controlpoint"\r
205 "message" " ^3has captured the ^1Hallways"\r
206 "origin" "-206.0 -488.8 -150.0"\r
207 "frags" "3"\r
208 "wait" "5"\r
209 "scale" "1.3"\r
210 }\r
211 {\r
212 "classname" "dom_controlpoint"\r
213 "message" " ^3has captured the ^1Lavaroom"\r
214 "origin" "1457.1  19.9 -110.0"\r
215 "frags" "1"\r
216 "wait" "5"\r
217 }\r
218 {\r
219 "classname" "dom_controlpoint"\r
220 "message" " ^3controls the ^1Nex & Strength"\r
221 "origin" "-259.8 299.3  5"\r
222 "frags" "1"\r
223 "wait" "5"\r
224 }\r
225 {\r
226 "classname" "dom_controlpoint"\r
227 "message" " ^3has captured the ^1Upper Platform"\r
228 "origin" "539.7 1206.0 182.0"\r
229 "frags" "1"\r
230 "wait" "5"\r
231 }\r
232 {\r
233 "classname" "dom_controlpoint"\r
234 "message" " ^3has captured the ^1Teleport Room"\r
235 "origin" "-1000.0 636.2 -16.0"\r
236 "frags" "1"\r
237 "wait" "5"\r
238 }\r
239 \r
240 \r
241 As you can see in the example, there are 5 dom_team ents: one blank, Red, Blue,\r
242 Yellow and Pink. Each control point has a different message (giving it a\r
243 special name), and the one in the hallways gives 3 frags every 5 seconds\r
244 instead of just one, making it more valuable.\r
245 \r
246 If your map contains the required entities for Domination, the menu will\r
247 automatically detect it for supporting Domination. To force the map to get\r
248 re-detected after you add such entities, delete the data/data/mapname.mapinfo\r
249 file - or simply edit it to add the "gametype dom" line.\r
250 \r
251 \r
252 =========\r
253 =IV. CTF=\r
254 =========\r
255 \r
256 Capture the flag needs at least 1 CTF flag per team, and can also make use of\r
257 team spawnpoints.\r
258 \r
259 CTF Flags\r
260 ---------\r
261 classname  item_flag_team1 or item_flag_team2\r
262 angle      direction the flag will point\r
263 model      model of the flag (default: models/ctf/flag_red.md3 or\r
264            models/ctf/flag_blue.md3)\r
265 noise      sound played when flag is stolen (default: "ctf/take.wav")\r
266 noise1     sound played when flag is returned by a teammate (default:\r
267            "ctf/return.wav")\r
268 noise2     sound played when flag is captured (default: "ctf/capture.wav")\r
269 noise3     sound played when flag returns itself (default: "ctf/respawn.wav")\r
270 \r
271 Team Spawnpoints\r
272 ----------------\r
273 classname  info_player_team1 or info_player_team2\r
274 *note: These function just like info_player_deathmatch, but for one team only.\r
275 If you don't make team spawnpoints, info_player_deathmatch is used instead.\r
276 \r
277 If your map contains the required entities for CTF, the menu will automatically\r
278 detect it for supporting CTF. To force the map to get re-detected after you add\r
279 such entities, delete the data/data/mapname.mapinfo file - or simply edit it to\r
280 add the "gametype ctf" line.\r
281 \r
282 =============\r
283 =V. Race/CTS=\r
284 =============\r
285 \r
286 Making a race map is not hard: you need some special spawnpoints, and some checkpoints.\r
287 \r
288 Spawnpoints\r
289 -----------\r
290 classname  info_player_race\r
291 target     targetname of the checkpoint\r
292 race_place for finish line checkpoints, the place of the point, or -1 to make it qualifying/CTS-only, or unset to let all the other players spawn\r
293 \r
294 Checkpoints\r
295 -----------\r
296 classname  trigger_race_checkpoint\r
297 targetname some name to target the checkpoint with\r
298 cnt        number of the checkpoint (or 0 for finish line)\r
299 \r
300 Note that checkpoints are brush entities, and they should be somewhat thick and\r
301 cover the full volume the player could use to get past them.\r
302 \r
303 Example of entity placement:\r
304 \r
305                          ###\r
306     ---------------------###---\r
307    /    9999  7  5  3  1>###   \\r
308   /     9999 8  6  4  2 >###    \\r
309  |     ------------------###     |\r
310 %%%%%%%%                 ###|    |\r
311 %%%%%%%%                 $$$|    |\r
312  | ^ ^ ------------------$$$     |\r
313  \                       $$$ <  /\r
314   \                      $$$ < /\r
315    ----------------------$$$---\r
316                          $$$\r
317 \r
318 ###:  classname = trigger_race_checkpoint, cnt = 0, targetname = finish\r
319 $$$:  classname = trigger_race_checkpoint, cnt = 1, targetname = cp1\r
320 %%%:  classname = trigger_race_checkpoint, cnt = 2, targetname = cp2\r
321 >:    classname = info_player_race,                 target = finish, angle = 0\r
322 1:    classname = info_player_race,                 target = finish, angle = 0, race_place = 1\r
323 2:    classname = info_player_race,                 target = finish, angle = 0, race_place = 2\r
324 ....\r
325 8:    classname = info_player_race,                 target = finish, angle = 0, race_place = 8\r
326 9:    classname = info_player_race,                 target = finish, angle = 0, race_place = 9\r
327 <:    classname = info_player_race,                 target = cp1,    angle = 180\r
328 ^:    classname = info_player_race,                 target = cp2,    angle = 90\r
329 \r
330 If your map contains the required entities for Race, the menu will automatically\r
331 detect it for supporting Race. To force the map to get re-detected after you add\r
332 such entities, delete the data/data/mapname.mapinfo file - or simply edit it to\r
333 add the "gametype rc" line.\r
334 \r
335 CTS maps do not use checkpoints with race_place set, so you can leave them out\r
336 for CTS maps.\r
337 \r
338 The skill parameter in the mapinfo entry for CTS shall be in the range from 0 (easy) to 10 (impossible).\r
339 \r
340 =============\r
341 =VI. Nexball=\r
342 =============\r
343 \r
344 There are three required entities: nexball_redgoal, nexball_bluegoal, and one of nexball_basketball\r
345 or nexball_football. There are also optional nexball_yellowgoal and nexball_pinkgoal entities (don't\r
346 add a pink goal when there is no yellow goal on the map, it will crash)\r
347 \r
348 Goals are made just like any other regular triggers. You can use multiple brushes for one trigger,\r
349 but avoid this if possible.\r
350 \r
351 There are also two other goal-like entities, nexball_fault and nexball_bound, the first taking a point\r
352 from the team that hits the trigger with the ball, the second simply returning it. You can spawn the\r
353 ball inside a goal-like trigger, this can be useful for basketball maps with separate teams and a\r
354 common ball spawn.\r
355 The different keys for the entities are documented in entities.def.\r
356 \r
357 The ball is affected by trigger_impulse, but not by trigger_push or teleporters.\r
358 \r
359 You should better avoid patches on the field, as collisions can sometimes get buggy on these.\r
360 \r
361 \r
362 ===============================\r
363 =Appendix A - Advanced mapinfo=\r
364 ===============================\r
365 \r
366 You now know how to make a basic, bare-bones mapinfo to set up a couple options\r
367 and load your map. However, there's much more you can do!  Consider these\r
368 senarios:\r
369 \r
370 1. The laser has too high of a force for laser jumps and ruins CTF\r
371 2. I don't want players to start out with the shotgun, but with the machinegun\r
372    instead\r
373 3. The map takes so much server CPU performance that the anti-wallhack can't be\r
374    made active\r
375 \r
376 Each of these situations can be resolved with ease with a little work in the\r
377 mapinfo file.\r
378 \r
379 To do this, I can add the following lines to my mapinfo file:\r
380 \r
381     settemp_for_type ctf g_balance_blaster_primary_force 200\r
382     settemp_for_type all g_balance_shotgun_weaponstart 0\r
383     settemp_for_type all g_balance_machinegun_weaponstart 1\r
384     settemp_for_type all sv_cullentities_trace 0\r
385 \r
386 These "settemp" settings are automatically removed when the map is left and\r
387 another is loaded. As you can see, it is possible to make per-mode temporary\r
388 settings, and global ones.\r
389 \r
390 Similar settings are also possible for the client:\r
391 \r
392     clientsettemp_for_type all r_shadow_glossexponent 96\r
393 \r
394 Another possibility is to specify fog settings in the mapinfo, for convenience\r
395 in case you set sv_foginterval by it too (to force the fog on the clients):\r
396 \r
397     fog 0.2 0.25 0.3 0.3 1 1500\r
398     settemp_for_type all sv_foginterval 5\r
399 \r
400 \r
401 =============================\r
402 =Appendix B - Helpful Extras=\r
403 =============================\r
404 \r
405 ----------------\r
406 -i. Team Colors-\r
407 ----------------\r
408 When you need to set an entity's color or team, use these values:\r
409 \r
410 Red\r
411 ---\r
412 Team:      5\r
413 Color:     4\r
414 \r
415 Blue\r
416 ----\r
417 Team:      14\r
418 Color:     13\r
419 \r
420 Yellow\r
421 ------\r
422 Team:      13\r
423 Color:     12\r
424 \r
425 Pink\r
426 -----\r
427 Team:      10\r
428 Color:     9\r
429 \r
430 \r
431 ----------------\r
432 -i. Text Colors-\r
433 ----------------\r
434 Occasionally you may want to print text in color, such as team names. Here are your options:\r
435 \r
436 1  Red\r
437 2  Green\r
438 3  Yellow\r
439 4  Blue\r
440 5  Cyan\r
441 6  Magenta\r
442 7  White\r
443 8  Grey (transparent)\r
444 9  Grey (solid)\r
445 0  Black\r
446 \r
447 ==========================================\r
448 =Appendix C - Advanced Darkplaces shaders=\r
449 ==========================================\r
450 \r
451 Shader parameters for DP's own features:\r
452 - dp_reflect <distort> <r> <g> <b> <a>\r
453   Makes surfaces of this shader reflective with r_water. The reflection is\r
454   alpha blended on the texture with the given alpha, and modulated by the given\r
455   color. distort is used in conjunction with the normalmap to simulate a\r
456   nonplanar water surface.\r
457 - dp_refract <distort> <r> <g> <b>\r
458   Makes surfaces of this shader refractive with r_water. The refraction\r
459   replaces the transparency of the texture. distort is used in conjunction with\r
460   the normalmap to simulate a nonplanar water surface.\r
461 - dp_water <reflectmin> <reflectmax> <refractdistort> <reflectdistort> <refractr> <refractg> <refractb> <reflectr> <reflectg> <reflectb> <alpha>\r
462   This combines the effects of dp_reflect and dp_refract to simulate a water\r
463   surface. However, the refraction and the reflection are mixed using a Fresnel\r
464   equation that makes the amount of reflection slide from reflectmin when\r
465   looking parallel to the water to reflectmax when looking directly into the\r
466   water. The result of this reflection/refraction mix is then layered BELOW the\r
467   texture of the shader, so basically, it "fills up" the alpha values of the\r
468   water. The alpha value is a multiplicator for the alpha value on the texture\r
469   - set this to a small value like 0.1 to emphasize the reflection and make\r
470   the water transparent; but if r_water is 0, alpha isn't used, so the water can\r
471   be very visible then too.\r
472 \r