12 The BSPC tool is used to create AAS files from BSP files.
\r
13 An AAS file is a file with areas used by the Quake III Arena bot in order
\r
14 to navigate and understand a map. The Quake III Arena maps are stored in
\r
21 bspc [-<switch> [-<switch> ...]]
\r
23 Example 1: bspc -bsp2aas d:\quake3\baseq3\maps\mymap?.bsp
\r
24 Example 2: bspc -bsp2aas d:\quake3\baseq3\pak0.pk3\maps/q3dm*.bsp
\r
27 bsp2aas <[pakfilter/]filter.bsp> = convert BSP to AAS
\r
28 reach <filter.bsp> = compute reachability & clusters
\r
29 cluster <filter.aas> = compute clusters
\r
30 aasopt <filter.aas> = optimize aas file
\r
31 output <output path> = set output path
\r
32 threads <X> = set number of threads to X
\r
33 cfg <filename> = use this cfg file
\r
34 optimize = enable optimization
\r
35 noverbose = disable verbose output
\r
36 breadthfirst = breadth first bsp building
\r
37 nobrushmerge = don't merge brushes
\r
38 freetree = free the bsp tree
\r
39 nocsg = disables brush chopping
\r
40 forcesidesvisible = force all sides to be visible
\r
41 grapplereach = calculate grapple reachabilities
\r
44 Several metacharacter may be used in the filter and pakfilter.
\r
46 * match any string of zero or more characters
\r
47 ? match any single character
\r
48 [abc...] match any of the enclosed characters; a hyphen can
\r
49 be used to specify a range (e.g. a-z, A-Z, 0-9)
\r
51 .pk3 files are accessed as if they are normal folders. For instance
\r
52 use "d:\quake3\baseq3\pak0.pk3\maps/q3dm1.bsp" to access the
\r
53 map q3dm1.bsp from the pak0.pk3 file.
\r
55 Multiple files may be listed after the switches bsp2map, bsp2aas, reach,
\r
58 If a BSP file is being converted to an AAS file and no output path
\r
59 is entered on the command-line then the AAS file will automatically
\r
60 be stored in the same folder as the BSP file. However if the BSP file
\r
61 was stored in a .pk3 file then the AAS file will be stored in a folder
\r
62 with the name 'maps' outside the .pk3 file.
\r
65 Updating entity lump
\r
66 --------------------
\r
68 If an AAS file is already available for a BSP file and you ONLY change
\r
69 the entities inside this BSP file then you only have to recalculate the
\r
70 reachabilities. This way you can move items, platforms etc. around
\r
71 without the need to recalculate the whole AAS file which can save quite
\r
72 some compile time. You can recalculate the reachabilities as follows:
\r
74 bspc -reach mymap.bsp
\r
76 Where mymap.bsp is the BSP file. The mymap.aas file has to be in the
\r
77 same folder as mymap.bsp or should be in the output folder specified
\r
78 with the -output option.
\r
80 Keep in mind that as soon as ANY geometry in the map changes the whole
\r
81 AAS file HAS to be recalculated in order to play with bots.
\r
83 NOTE: -reach does not work on optimized .AAS files!
\r
84 NOTE: don't use -reach when moving the position of doors.
\r
90 Just like there can be vis leaks in a map there can also be clipping
\r
91 leaks. Two things can be wrong when the BSPC tool outputs that a map
\r
94 1. There are no entities in the map at all, or all entities that are
\r
95 actually in the map are placed in solid. In this case the BSPC tool
\r
96 outputs "WARNING: no entities inside". (At least a player start entity
\r
97 is needed to load a map.)
\r
99 2. There is a spot in the map where players can go outside the map
\r
100 into the void. This is bad, players should never be able to fall out
\r
101 of a level. In this case the BSPC tool outputs "WARNING: entity
\r
102 reached from outside". The BSPC tool also writes a mymap.lin file
\r
103 that can be loaded in the Q3Radiant editor to show lines that go
\r
104 through the actual leak.
\r
106 Make sure the .lin file is stored in the same folder as where q3radiant
\r
107 stores the .bsp file. Load the map in q3radiant and use the
\r
108 menu -> File -> Pointfile... to load the .lin file. A thick red line
\r
109 will be shown in the map. Follow this line to find the leak.
\r
115 Currently a map should be within the bounds (-65536, -65536, -65536) -
\r
116 (65536, 65536, 65536) for the bspc tool to compile. These are the same
\r
117 limits the q3map tool has.
\r
123 The player bounding box is a 30 units by 30 units square with a height
\r
124 of 56 units. If we assume 1.75 meters being the average height of a human
\r
125 and a player in Quake III Arena being 56 units high we get 32 units = 1 meter.
\r
127 Maximum step height of a player is 18 units (just keep steps 16 units or
\r
130 The maximum water jump height for bots has been set to 18 units. (height
\r
131 difference between water surface and the floor jumping onto). If the
\r
132 waterjump height is made higher human players will have a hard time getting
\r
135 With normal gravity and without the quad the maximum rocket jump height is
\r
136 around 280 units (you can sometimes jump a few units higher but this is a
\r
137 safe value for reference).
\r
139 The maximum height for barriers the bots will jump on is 32 units.
\r
141 Some math to calculate some other values of interest:
\r
144 jump velocity = 270;
\r
145 max vertical rocketjump velocity = 670;
\r
146 max run velocity = 320;
\r
147 max step height = 18;
\r
149 max jump height = 0.5 * gravity * (jumpvelocity/gravity)*(jumpvelocity/gravity);
\r
150 max jump height = 45 units;
\r
151 NOTE: even though this is the mathematical maximum jump height always keep
\r
152 the the 32 units maximum barrier height for bots in mind when building maps.
\r
154 maximum horizontal jump distance over a gap from one spot to another both
\r
155 at the same height:
\r
157 t = sqrt((maxjumpheight + maxstep) / (0.5 * gravity));
\r
158 t = 0.3986 seconds;
\r
159 dist = maxrunvelocity * (t + jumpvelocity / gravity);
\r
161 Because players use a bounding box we can jump a full bounding box width
\r
162 furter in the ideal case. (15 units at the jump start and 15 at the
\r
164 235 + 15 + 15 = 265 units.
\r
165 Again this is the mathematical maximum which players can only reach under
\r
166 ideal circumstances.
\r
169 Optimizing a map for bspc
\r
170 -------------------------
\r
172 Hint brushes have no effect on the bspc tool. Only solid, clip, liquid,
\r
173 cluster portal and do not enter brushes are used by the bspc tool.
\r
175 The bspc tool outputs how many areas are created for a map. Less areas
\r
176 is better. Often the number of areas can be reduced by adding additional
\r
177 clip brushes. By adding these additional clip brushes the complexity
\r
178 of the geometry used for collision can be reduced. Do not add clip
\r
179 brushes in front of the complex geometry but get the complex shaped
\r
180 geometry contained within these clip brushes. Things that should be
\r
181 contained within clip brushes are small or complex shaped (often detail)
\r
182 brushes and complex and twisted curves, but also more regular curves
\r
183 can be placed within a clip brush. When containing a curve within a
\r
184 clip brush it's preferred to place the whole curve within the clip
\r
185 brush (not just part of the curve).
\r
186 Note: you can make brushes or curves non-solid when they are contained
\r
187 within *full* clip or *weap* clip brushes to speed up bspc calculations.
\r
189 Always try to align your geometry to the grids. Always use the largest
\r
190 grid possible for alignment of your geometry. Also try to align the
\r
191 back sides of brushes which may not be visible. The more brush sides
\r
192 are aligned the better. This will also speed up bspc calculations.
\r
194 Align adjacent brushes as much as possible. Make sure no tiny faces are
\r
195 created due to badly aligned brushes.
\r
197 Quite often there are places in a map that are visible to players
\r
198 but that players can never get to. Players would be able to walk around there
\r
199 but since players can never reach such places they will never actually
\r
200 move around there. If players are never able to get to such places
\r
201 it's better to put a large clip brush which encloses that whole space.
\r
202 This will also speed up bspc calculations and reduce the number of areas
\r
203 created by the bspc tool.
\r
205 Note: the number of areas relative to the map size tells something about
\r
206 the navigation complexity for players in general (also human players).
\r
207 Reducing the collision complexity for bots also makes the map easier to
\r
208 navigate for human players
\r
211 func_plat and func_bobbing
\r
212 --------------------------
\r
214 When func_plat or func_bobbing entities are placed in a map the bots will
\r
215 use them if possible. The bots assume they can stand on top of the bounding
\r
216 box of the model used for the func_plat or func_bobbing entity. As a result
\r
217 creating complex shaped func_plat or func_bobbing models is mostly a bad
\r
218 idea. You have to make sure the bots (and players) can actually stand
\r
219 everywhere ontop of the bounding box of the model.
\r
225 A map is divided into areas. Several of these areas can be grouped together
\r
226 to create a cluster. The clusters are seperated by cluster portals which are
\r
227 areas themselves. One of the things the bot uses these clusters for is a
\r
228 multi-level routing algorithm. When a map is efficiently divided up into
\r
229 clusters bot calculations will be faster.
\r
231 several things to take into account:
\r
233 - The BSPC tool tries to create cluster portals automatically but additional
\r
234 cluster portals can be created by placing "clusterportal" brushes.
\r
235 - Cluster portals are manually created by placing "clusterportal" brushes
\r
237 - Cluster portal brushes are a tool to optimize a map for CPU usage by the
\r
238 bots. They are not needed for the bots to operate correctly.
\r
239 - The "clusterportal" brushes should not be used outside the world hull.
\r
240 - The cluster portals do not have any effect on vis.
\r
241 - If a door is already sealed with an areaportal brush, a clusterportal is
\r
242 not necessary there. (area portals are also used as cluster portals).
\r
243 - Just like the area portals, the cluster portals must seal a space off
\r
244 entirely from other areas.
\r
245 - The cluster portal areas should seal off a cluster in a way that the only
\r
246 path towards another cluster is through a cluster portal area.
\r
247 - Only create cluster portals where people can walk or swim through.
\r
248 - Don't create cluster portals in gaps in the floor. (people would fall through)
\r
249 - If you have two sealed off clusters and you add a teleporter between them
\r
250 then the two clusters will be merged again because of the teleporter.
\r
251 - Cluster portals must seperate no more and no less than two (2) clusters.
\r
252 - Try to create clusters with all the same number of 'reachability' areas.
\r
253 for instance if the map has 5400 areas try to create 10 clusters with 540
\r
254 areas each, or 12 clusters with 450 areas each, etc. The BSPC tool lists
\r
255 the number of reachability areas in each cluster.
\r
256 With Q3A version 1.25 and up you can use /set bot_testclusters 1 on the
\r
257 console and the area number and cluster number you're in will be printed
\r
258 on the screen. These cluster number correspond to the cluster numbers
\r
259 the BSPC tool prints.
\r
260 - Minimize the number of clusters with only a few (less than 10) areas.
\r
261 - When adding "cluster portal" brushes try to place them in places with
\r
262 minimal geometric complexity. For instance place them inside convex door
\r
263 openings or small hallways (not infront of door openings). Ideally the shape
\r
264 of the face through which a player walks or swims into the cluster portal
\r
265 is the same as the shape of the face through which a player leaves the
\r
266 cluster portal. Also ideally the open space inside the cluster portal
\r
268 - Make cluster portals about 16 or 32 units thick or align them with
\r
269 adjacent geometry. Don't make them too thick though.
\r
270 - Minimize the total number of cluster portal areas at all times. The more
\r
271 cluster portal areas you have the more CPU the bots need.
\r
272 - Items have no effect at all on the creation of areas or clusters.
\r
273 The same goes for item_botroam.
\r
279 When bot navigation problems show up or you want to make sure a bot never tries
\r
280 to go to a certain place "do not enter" brushes can be used.
\r
282 several things to take into account:
\r
284 - The "do not enter" brushes should not be used outside the world hull.
\r
285 - The "do not enter" brush is Not a clip brush for the bot.
\r
286 - The "do not enter" brush is a tool of last resort. Do not use it unless
\r
287 there are serious navigation problems.
\r
288 - The number of "do not enter" brushes should be minimized because these
\r
289 brushes create additional areas for the bots.
\r
290 - The "do not enter" brush will create a New area that the bot will try to
\r
291 avoid. However if the bot somehow ends up in a "do not enter" area or there
\r
292 is a valid goal inside the "do not enter" area then the bot is allowed to
\r
293 go into and out of that area. So if the bot somehow gets in a "do not enter"
\r
294 area the bot will be able to get out.
\r
300 The item_botroam entity can be used when a bot does not roam the whole level
\r
301 or prefers to go to only specific areas. This (invisible) item can be placed
\r
302 in a map just like regular items. Nobody can actually pick up the item it's
\r
303 only used to attract bots to certain places of the map. The item_botroam has
\r
304 a key "origin". The value is set by Q3Radiant automatically. The item_botroam
\r
305 also has a key "weight". The value is the weight of the roam item and is
\r
306 relative to the weight of other items in the map. The bot character specific
\r
307 item weights are stored with the bot characters in the botfiles/bots/ sub-folder
\r
308 in the .pk3 file. The value of the weight is a non-zero floating point value,
\r
309 most often in the range 0 to 400. (Higher values are allowed but keep in mind
\r
310 that the bot should also still go for normal items, so don't make the
\r
311 item_botroam weight to high.)
\r
313 When a bot should never go for a specific item the key "notbot" with value "1"
\r
314 can be used for that item. This key with value can be used for every available
\r
315 item in Quake III Arena.
\r
317 The suspended flag can be used on all items (item_botroam included).
\r
318 However keep in mind that when a suspended item is not anywhere near the
\r
319 ground the bot will ONLY try to go for this suspended item using jump pads.
\r
322 Team based entities
\r
323 -------------------
\r
325 You can use the "bot_notteam" entity key with value "1" or "2" on teleporters
\r
326 (trigger_teleport or trigger_multiple pointing at a target_teleporter),
\r
327 elevators (func_plat), cyclic movers (func_bobbing), jumppads (trigger_push)
\r
328 and areas that hurt the player (trigger_hurt).
\r
329 When "notteam" is set to "1" only bots using the travel flag TFL_NOTTEAM1 will
\r
330 use the entity or move through the area. When "bot_notteam" is set to "2" only
\r
331 bots using the travel flag TFL_NOTTEAM2 will use the entity or move through the
\r
332 area. These travel flags can be used in the game source code. Using this entity
\r
333 key also only has effect if the mod the map is being made for supports team based
\r
334 navigation for bots.
\r
340 One of the easiest ways to test the AAS file is to load the map in
\r
341 Quake3 in teamplay mode (type /set g_gametype 3 on the console before
\r
342 loading the map). Enter a team and add a bot to your team. Use the
\r
343 team order menu (by default bound to the key F3) to command the bot
\r
344 to follow you. Walk around the map and see if the bot is able to
\r
345 follow you everywhere.
\r
347 Map bugs can sometimes cause certain places in the map to show up
\r
348 'solid' in the AAS file. The bots cannot travel through these 'solid'
\r
349 areas. To test for these 'solid' places set the cvar bot_testsolid
\r
350 to 1 on the console. (type /set bot_testsolid 1) The map has to be
\r
351 started with devmap instead of map before the cvar bot_testsolid can
\r
352 be set. When the cvar is set to 1 then either "empty area" or
\r
353 "SOLID area" will be printed on the screen while traveling through a map.
\r
354 Several map bugs can cause these 'solid' places in the AAS file.
\r
355 - Sometimes microscopic brushes are left over after a brush CSG. Search
\r
356 for such brushes in the problem area and delete them.
\r
357 - Tiny brush faces (not curves) can also cause problems. Due to vertex
\r
358 snapping in the q3map tool those tiny brush faces can be snapped out
\r
359 of existence. Such faces will not show up in Quake3 and you'll see
\r
360 tiny peek holes or slits where you can view through the geometry.
\r
361 Allign vertexes of and edges of adjacent brushes to remove and avoid
\r
362 such tiny faces. Placing a clip brush in front of the face that is
\r
363 snapped out of existence will also remove the 'solid' area but ofcourse
\r
364 it's much better to remove the peek holes and slits.
\r
365 - Another cause could be a brush with a collapsed side. Check how many
\r
366 sides a brush has and how many sides actually have a surface. Rebuild
\r
367 brushes with collapsed sides.
\r
368 - All faces contained within liquid brushes using a shader without
\r
369 "surfaceparm trans" set will be removed. Those contained surfaces will
\r
370 not be visible and can cause the liquid to appear "solid" in the AAS file.
\r
372 If you insist creating an AAS file for a map with bugs then the option
\r
373 -forcesidesvisible can be used. This should fix all the problems with areas
\r
374 showing up solid in the AAS file. However creating an AAS file with this
\r
375 option takes a lot longer (often more than twice the normal compile time).
\r
377 Clusters can be tested with the cvar bot_testclusters.
\r
378 (type "/set bot_testclusters 1" on the console)
\r
380 Jumppads can also be tested. Type the following on the Quake3 console
\r
381 before loading your map:
\r
383 /set bot_maxdebugpolys 1024
\r
384 /set bot_visualizejumppads 1
\r
385 /set bot_forcereachability 1
\r
387 Now load the map. A counter will be shown and goes from 0% to 100%.
\r
388 When the counter has reached 100% type /set bot_debug 1 and
\r
389 /set r_debugSurface 2 on the console. For every jumppad the
\r
390 default arch of travel (without using air control) will be visualized.
\r
391 This only works if your .aas file is not optimized.
\r
397 Level designers should not worry too much about the following messages and/or warnings. The things reported are non fatal and won't cause any major problems. Some of the messages are just debug left overs.
\r
399 "AAS_CheckArea: area %d face %d is flipped\n"
\r
400 "AAS_CheckArea: area %d center is %f %f %f\n"
\r
401 "AAS_CheckFaceWindingPlane: face %d winding plane unequal to face plane\r\n"
\r
402 "AAS_CheckFaceWindingPlane: face %d winding reversed\r\n"
\r
403 "area %d face %d flipped: front area %d, back area %d\n"
\r
404 "area %d face %d is tiny\r\n"
\r
405 "face %d and %d, same front and back area but flipped planes\r\n"
\r
406 "AAS_SplitFace: tiny back face\r\n"
\r
407 "AAS_SplitFace: tiny back face\r\n"
\r
408 "AAS_SplitArea: front area without faces\n"
\r
409 "AAS_SplitArea: back area without faces\n"
\r
410 "gsubdiv: area %d has a tiny winding\r\n"
\r
411 "AAS_TestSplitPlane: tried face plane as splitter\n"
\r
412 "found %d epsilon faces trying to split area %d\r\n"
\r
413 "AAS_SplitArea: front area without faces\n"
\r
414 "AAS_GetFace: face %d had degenerate edge %d-%d\r\n"
\r
415 "AAS_GetFace: face %d was tiny\r\n"
\r
416 "WARNING: huge winding\n"
\r
417 "bogus brush after clip"
\r
418 "split removed brush"
\r
419 "split not on both sides"
\r
420 "two tiny brushes\r\n"
\r
421 "possible portal: %d\r\n"
\r
422 "portal %d: area %d\r\n"
\r
423 "WARNING: CM_GridPlane unresolvable\n"
\r
424 "WARNING: CM_AddFacetBevels... invalid bevel\n"
\r
425 "WARNING: CM_SetBorderInward: mixed plane sides\n"
\r
426 "WARNING: bevel plane already used\n"
\r
427 "trigger_multiple model = \"%s\"\n"
\r
428 "trigger_teleport model = \"%s\"\n"
\r
429 "found a trigger_push with velocity %f %f %f\n"
\r
430 "AAS_TraceBoundingBox: stack overflow\n"
\r
431 "AAS_TraceAreas: stack overflow\n"
\r
432 "AAS_LinkEntity: stack overflow\n"
\r
433 "MergeWindings: degenerate edge on winding %f %f %f\n"
\r
434 "Warning: MergeWindings: front to back found twice\n"
\r
435 "FindPlaneSeperatingWindings: winding1 non-convex\r\n"
\r
436 "FindPlaneSeperatingWindings: winding2 non-convex\r\n"
\r
439 When one of the following messages, errors or warnings is found then there is often something to be fixed.
\r
441 "WARNING! HashVec: point %f %f %f outside valid range\n"
\r
442 "This should never happen!\n"
\r
443 While storing the AAS file some vertex was found outside the valid map bounds. When this happens some part of the map is likely to have badly aligned brushes or weird shaped curves. Clipping off or rebuilding complex shapes often helps.
\r
444 "trigger_push start solid\n"
\r
445 The trigger_push start point is in solid. Try making the trigger_push brush a bit larger or move it around a bit.
\r
446 "trigger_push without target entity %s\n"
\r
447 Could not find the target entity of the trigger_push with the target field %s.
\r
448 "trigger_push without time\n"
\r
449 trigger_push entity found without "time" field.
\r
450 "trigger_multiple not in any jump pad area\n"
\r
451 "trigger_push not in any jump pad area\n"
\r
452 A trigger_push entity was found not to be in any valid jumppad area. (the message states trigger_multiple but it should have been trigger_push) Try making the trigger_push brush a bit larger or move it around a bit.
\r
453 "trigger_multiple at %1.0f %1.0f %1.0f without target\n"
\r
454 A trigger multiple was found at the given coordinates without a "target" field.
\r
455 "target_teleporter without target\n"
\r
456 A target_teleporter entity was found without target field.
\r
457 "trigger_teleport at %1.0f %1.0f %1.0f without target\n"
\r
458 A trigger_teleport entity was found at the given coordinates without "target" field.
\r
459 "teleporter without misc_teleporter_dest (%s)\n"
\r
460 The destination of a teleporter with target field %s could not be found.
\r
461 "teleporter destination (%s) without origin\n"
\r
462 A teleporter destination with the target name %s was found without origin field.
\r
463 "teleporter destination (%s) in solid\n"
\r
464 A teleporter destination with the targetname %s was found to be in solid.
\r
465 "teleported into slime or lava at dest %s\n"
\r
466 A player would be pushed into slime or lave at the teleporter destination with the targetname %s.
\r
467 "trigger_multiple not in any area\n"
\r
468 A teleporter trigger was found not to be in any valid area. Try moving the trigger around a bit.
\r
469 "func_plat without model\n"
\r
470 A func_plat entity was found without model field.
\r
471 "func_plat with invalid model number\n"
\r
472 A func_plat entity was found with the model field set to some invalid number.
\r
473 "func_bobbing without model\n"
\r
474 A func_bobbing entity was found without model field.
\r
475 "func_bobbing with invalid model number\n"
\r
476 A func_bobbing entity was found with the model field set to some invalid number.
\r
477 "%s in solid at (%1.1f %1.1f %1.1f)\n"
\r
478 An item with classname %s was found to be in solid at the given coordinates.
\r
479 "empty aas link heap\n"
\r
480 Some part of the map has some rather complex clipping. Reduce the geometric complexity or use clip brushes to reduce the clipping complexity.
\r
481 "too many entities in BSP file\n"
\r
482 There are too many entities in the bsp file.
\r
483 "error opening %s\n"
\r
484 Could not create a new AAS file. Hard disk might be full.
\r
485 "error writing lump %s\n"
\r
486 Could not write an AAS lump to file. Hard disk might be full.
\r
499 - added bot_notteam support on trigger_hurt entities
\r
504 - added some AAS statistics
\r
505 - don't flood through faces when creating clusters
\r
510 - fix map size limitation
\r
515 - renamed "notteam" to "bot_notteam"
\r
520 - added fs_maxfallheight
\r
521 - compiled with larger map size bounds
\r
526 - fixed cfg file loading
\r
531 - added model numbers for AREACONTENTS_MOVER
\r
532 - added team based func_plat, func_bobbing, trigger_teleport and trigger_push reachabilities
\r
537 - fixed swim reachabilities
\r
538 - fixed some reachabilities through cluster portals
\r
539 - fixed jump reachabilities
\r
540 - changed some start travel times
\r
541 - added travel time settings to cfg
\r
546 - fixed func_bobbing entities with origin brush
\r
551 - fixed trigger_teleport bug.
\r
552 - increased max map bounds to (-8192, -8192, -8192)-(8192, 8192, 8192)
\r
553 - increased max points on winding
\r
554 - made "HashVec: point x y z outside valid range" non-fatal
\r
555 - fixed rocket jump reachabilities
\r
556 - added force sides visible option
\r
557 - increased simulated stack size for area traces
\r
562 - fixed ducked bounding box size
\r
563 - fixed sv_maxsteepness being zero in aas configuration
\r
564 - AAS files are now automatically stored in BSP file folder
\r
565 - fixed crash bug caused by overflow of a simulated stack
\r
projects / xonotic / netradiant.git / blob