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