The DarkMod Wiki - User contributions [en]

Universe

2019-11-13T18:23:01Z

Springheel: Protected "Universe" ([Edit=Allow only autoconfirmed users] (indefinite) [Move=Allow only autoconfirmed users] (indefinite))

[[image:cityscape.jpg|thumb|The Dark Mod has its own setting]]
Welcome to the "official" setting of The Dark Mod. While FM authors can create stories in any world they like with our tools, they have been tailored to suit the world described below.

'''Disclaimer:''' Just to be clear, The Dark Mod does '''NOT''' take place in the same universe as the Looking Glass 'Thief' games (or the setting of the recent Thief from Eidos Montreal). There are no Keepers, no Hammerites, and no Garrett. That said, the settings of both The Dark Mod and Thief are based on a steampunk-influenced version of our own history, so there will be certain similarities.

== Overview ==
The Dark Mod world can be viewed as an alternate, low fantasy version of our own. It is a mixture of several historical periods, with architecture ranging from medieval castles to victorian mansions. In this world, steam and clockwork [[technology]] were discovered much earlier in history, allowing for odd inventions and industrial warehouses to exist side-by-side with gothic cathedrals and sword-wielding city watch. [[Magic]] is also a tangible force, though it is rare to for most people to encounter anything but subtle magical effects. Missions have established the date of the setting as around 1630 AD.

== Tone ==
The Dark Mod is set in a world that is dark, gritty and adult. It is a setting that strives to be immersive, and to feel as believable to the player as possible. Neither campy humour nor climactic battles between good and evil fit the style of The Dark Mod world.

Characters talk and act in ways that are appropriate to their upbringing and station. Most guards are rough, uneducated brutes who spend their lives drinking, gambling, and bedding whores. They certainly don't recite poetry or discuss philosophy in their spare time. Aristocrats are often just as brutish, but with a slightly more educated veneer.

With plagues, infection, and drunken brawls spilling into the streets on a regular basis, life is much cheaper in this world than ours. The heads and corpses of criminals line the roads, and public torture and hangings are one of the most popular forms of entertainment--watching criminals have their entrails cut out and burned while still alive is considered a good way to teach children moral lessons. Even the Church, the main provider of hope and beauty in this age, enthusiastically tortures and burns heretics.

== Places ==
Although much of the setting material for The Dark Mod focuses around the city of Bridgeport, that city does not exist in isolation. It is part of a larger world, with political connections, trading agreements, and hostile neighbours that could be possible plots for FM missions.
* [[The City]] of Bridgeport
* [[Builder Roads]]
* [[Other Cities and Towns]]
* [[The World at Large]]
* [[The Empire]]
* [[Choosing Place Names]]

== "Factions" ==
"Factions" are not necessarily organized groups, and should not be thought of as homogeneous. Even within factions there are plenty of disagreements and sometimes outright conflicts.
* [[Builders]]
* [[Pagans]]
* [[Inventor's Guild]]
* [[Mages]]
* [[Necromancers]]
* [[Thieves]]

== Creatures ==
While the TDM setting generally looks like our own world, there are strange and unusual creatures in existence. The stranger the beast, the further from civilization it is generally found.

* [[Giant Spiders]]
* [[Undead]]
* [[Fire Elementals]]

== Notable Characters ==
A catalogue of significant characters from the TDM setting. These include important figures as well as characters drawn from existing Fan Missions.
* [[Thief Characters]]
* [[Noble/Wealthy Characters]]
* [[Clergy/Builder Characters]]

== Daily Life ==
A few historical details can go a long way towards making a mission seem more "real".
* The kinds of [[Food]] people eat
* The importance of [[Letter Writing]]
* The running of a [[Wealthy Household]]
* Types of [[Jobs]] people might have

== Other ==
Other information about the setting.
* The invention of several unique [[arrows]]
* What kind of [[technology]] is available?
* What about [[magic]]?
* How to choose good-sounding [[Names]]
* [[Glossary of terms]]

Clergy/Builder Characters

2019-11-13T18:22:46Z

Springheel: Protected "Clergy/Builder Characters" ([Edit=Allow only autoconfirmed users] (indefinite) [Move=Allow only autoconfirmed users] (indefinite))

= Historical Figures =

== The Prophet Amos ==

The main prophet of Builder theology, who was said to communicate directly with the Master Builder himself. He was responsible for the founding of the Builder Church, in the year 0. The "Book of Amos" is the most significant part of the Builder Gospels, and establishes that each person will be judged after death according to the work they have done and the things they have built.

== Patriarch Gregory IX ==

Instituted the papal Inquisition in 1231 to bring order and legality to the process of dealing with heresy.

== Patriarch Sixtus IV ==

Granted ecclesiastical courts the right to execute heretics in 1478, giving the Inquisitors full power over the detection, judgement and punishment of heresy.

== Bernard of Clairvaux ==

Author of "The Pagan Problem", a work that describes pagans as inferior and evil. Frequently used to justify discriminatory laws against Pagans. (from "Tears of St. Lucia")

= Current Characters =

== Paschal Murnerus ==

Inquisitor General of Bridgeport (from "Tears of St. Lucia")

== Cardinal Laurenti ==

Another Inquisitor General, and a puritan. Brought the Courts of the Inquisition to Braeden. (from "Builders' Influence")
[[Category:Universe]]

Clergy/Builder Characters

2019-11-13T18:21:18Z

Springheel: Removed protection from "Clergy/Builder Characters"

Universe

2019-11-13T18:20:17Z

Springheel: Removed protection from "Universe"

Swimmable Water

2019-07-17T00:25:56Z

Springheel:

''written by angua''

== Create some walls ==

[[Image:Watertutorial1.jpg]]

In this example, I made this little rectangular pool, but you can also use differently shaped structures.

== Fill in your water ==

Draw a brush that is going to be your water volume and texture it with common/nodraw

[[Image:Watertutorial2.jpg]]

== Create the entity ==

In [[DarkRadiant]]: Select your brush, {{RMB}} -> Create Entity -> '''atdm:liquid_water'''

[[Image:Watertutorial5.jpg]]

In the Entity Inspector you can see that the classname is now '''atdm:liquid_water''', and the name '''atdm:liquid_water_1''' (or similiar). It should also have a blue outline in the orthographic view (The XZ Front in this case).

Note: If you use "func_liquid" instead of "atdm:liquid_water", your water will not function correctly. It will f.i. not extinguish flames.

== Texture the surface ==

Select the face that is going to be the surface ({{key|CTRL}} + {{key|SHIFT}} + {{LMB}}) and texture it with a nice water texture, for example '''water_source/water_clear'''.

[[Image:Watertutorial6.jpg]]

Do not assign the water texture to the whole brush, or you will see this: (You can also get rid of that z-fighting by dragging the brush into the wall so that it insersects with it.)

[[Image:Watertutorial4.jpg]]

However, if you don't want clear water then you need to choose another surface, say water_green or water_colored, include an extra overlay plus an underwater overlay. For this, see the next section.

==Coloured and Murky Water==

This is a method for providing water that is coloured or murky underwater and a surface that matches.

You can use this with different water surfaces but I recommend you first try:

''textures/water_source/water_colored.'' (this can be coloured but by default it is not so won't confuse the issue - the colour will be added by the overlay below.)

To your water entity give the property:

'''''underwater_gui'''''

Now give the property the name of one of the overlay guis. The names are fairly descriptive so you can choose which type you want suitable for a river, a cave pool, or a sewer, etc.:

guis/underwater/underwater_green_midmurk.gui
guis/underwater/underwater_green_thickmurk.gui
guis/underwater/underwater_green_thinmurk.gui

guis/underwater/underwater_blue_midmurk.gui
guis/underwater/underwater_blue_thickmurk.gui
guis/underwater/underwater_blue_thinmurk.gui

guis/underwater/underwater_bluegrey_midmurk.gui
guis/underwater/underwater_bluegrey_thickmurk.gui
guis/underwater/underwater_bluegrey_thinmurk.gui

guis/underwater/underwater_greengrey_midmurk.gui
guis/underwater/underwater_greengrey_thickmurk.gui
guis/underwater/underwater_greengrey_thinmurk.gui

Now with the water entity still selected:

* Choose Top view in Dark Radiant's orthoview
* Create a simple patch from the patch menu.
* Move this up flush with the surface of the water.
* Give it the texture that matches the gui you chose above. For example, if you chose '' guis/underwater/underwater_bluegrey_thinmurk.gui'' from the above then give the overlay the texture: ''textures/water_source/bluegrey_plain_flat_thinmurk''

Using the above method you should find the surface opacity and colour matches how it looks when the players goes underwater.

== Underwater fog ==

Your water looks much more believable if it has an underwater fog. Create a light, select as texture "fog/basicfog", give it a very dark color and resize the light so it covers the entire underwater area. This will make your water darker the deeper it is, just like in real-life!

== Test your water ==

[[Image:Watertutorial3.jpg]]

And there it is!

==Current Flow==

There is at least one flowing stream surface texture at the time of writing. If you want to create your own variations then just examine that material shader, copy and modify it. Probably it can be used with other existing surface texture images or you can create new ones.

==Flow Force==

A force field can be placed in water to apply a tangible flow, eg, to push the player and/or other objects along.

See [[Func Forcefields]]

==Wave Frequency and Direction==

You can set the frequency of the surface waves from tiny undulations to large slow ones just by changing the surface texture scale in Surface Inspector. Flowing surfaces such as stream textures can of course be rotated to get the direction you want.

A better way to influence the wave speed and wave hight is via [[List_of_shaderParm_variables|shaderParms]]. Set the following spawnargs on your water entity:

<pre>
shaderParm5 0.05
shaderParm6 0.75
</pre>

parm5 controls the wave speed, parm6 the wave height. The defaults are 0.1 and 1.5, respectively. Experiment a bit, values lower than the defaults look more believable for still waterbodies, higher values for when you have a lot of wind.

==Sound==

If the water level is less than 1, you get normal footsteps.

Between 1 and 34, you get splash sounds.

Between 34 and 77, you get wading sounds.

If 77 or more, you get swimming sounds.

==Troubleshooting Problems==

===Visible Joints Between Water Brushes===

If you place brushes of water against one another, eg, along a channel, round corners, to form a canal, etc. and you can 'see the joins' then the most likely cause of the problem is that the surface textures do not align. We are used to aligning static textures but it is not so obvious with the dynamic translucent surface of water that we might not think of it. Just copy and paste shader one of the surface textures to all the others to get the same scroll and scale alignment and it should be OK.

NOTE: If you want to use the NoDraw Solid texture, be sure NOT to use it between water entities, otherwise you won't be able to swim between them.

{{tutorial-water}}
[[Category:Mapping Tutorials]]

Objects Floating in Water

2019-07-17T00:25:21Z

Springheel:

''Written by Geep, 2019''

Entities found in the “Movables” folder will float dynamically in water if their calculated density is light enough. But there are issues.

== Adjust the “Mass”, Ignore “Density” ==

To control floating and underwater behavior (detailed below), you may wish to inspect and override the inherited “mass” spawnarg value. If a mass value is defined - and it always is if you use a standard moveable class - then the “density” spawnarg is algorithmically ignored… so you can ignore it too.

Remember that the mass of an object can affect non-water aspects of game play.

== Desired Initial Placement of an Object ==

This restates general considerations when placing a Moveable in the map, but in a water context.

''In the Water, but Above the Sea Floor.'' By “sea floor”, we just mean the first solid object encountered directly below the object. Place the movable object where you wish (below, at, or slightly above the water surface), and set its “nodrop” spawnarg to “1”. On worldspawn, it will stay where you placed it, awaiting activation by the player.

''On the Sea Floor.'' Like the above, but make sure nodrop = 0 (the usual default). On worldspawn, the movable will move immediately to the sea floor (without special effects), awaiting activation by the player.

''Far Above the Water.'' If the object is placed far above the water or any other floor, it just hangs there (awaiting player activation), no matter the nodrop value. If the player is swimming, the object will be out of reach.

== Getting the Placed Object to Activate ==

Unfortunately, the object will not rise off the sea floor, or if at the surface, begin bobbing, until after the player activates it by bumping and/or frobbing it.

Clever game design may get around this, e.g., in the case of a floating rowboat, spawning the player directly into it.

''[Is there a way to activate objects by triggers/scripting?]''

== Plausible Behaviors When First Activated ==

Objects initially placed above the water surface or higher in the water than they would normally float may trigger splash sound and visual effects, and plunge below the surface (before arising if buoyant). Similarly, initially underwater objects that are highly buoyant may pop above the surface, with effects.

As in real life, the presence and extent of such behaviors is presumably influenced by the momentum at surface penetration. But the engine likely scants object shape and orientation.

== Effect of Mass on Buoyancy and Floating Behavior ==

The mass divided by the calculated (or estimated) volume gives a calculated density, which affects how high in the water an object sits and (along with mass) how vigorous any bobbing and roll-about may be.

The following summary table gives rules of thumb, based on experiments detailed further below. For box-shaped objects it is possible for both you and the physics engine to easily calculate the volume, and from that (given the mass) the density. For other shapes, the engine likely deploys shortcut estimates (perhaps using the collision model) with ad-hoc fudge factors. Rather than attempt to mimic that (or guesstimate appropriate volumes for corpses or complex prefabs), you might use the table as follows:

# Observe the object’s floating behavior, and from that, impute its approximate density.
# Compare that to the desired behavior, and scale the mass value proportionally.
# Iterate until happy.

{|
! style="text-align:left;"| Estimated Density
! Underwater: Sink (&dArr;) or Rise (&uArr;)
! Float Behavior at Surface
|-
|1.8
|&dArr;&dArr;&dArr;
|Doesn’t float
|-
[[Category:Editing]] [[Category:Water]] [[Category:Tutorial]]

2018-07-04T21:30:25Z

Springheel:

''Written by Springheel''

When writing the newer vocal scripts, I came up with the idea of including a random sequence of questions and responses that can be used to create believable conversations between AI. The following vocal sets support this (older ones do not):

1. vocal set_commander

2. vocal set_jack

3. vocal set_cynic

4. vocal set_drunk

5. vocal set_maiden

6. vocal set_moor

The sequence goes like this:

AI 1: "convo_question" vocal, ex, "So, how did the game go last night?"

AI 2: "convo_answer/response" vocal, ex, "Could have been better."

AI 1: "convo_close" vocal, ex, "Got it."

Each "convo_question" asks for a judgement response. "How was X? What did you think of X?" etc. Each vocal set has four or five questions/answers that are chosen from randomly. The overall effect is pretty good, I think, though some question/responses combinations make more sense than others.

The sitting AI in Mission 1: A New Job use this system. Basically, you create two conversations--one with AI 1 asking the questions, and the other with AI 2. Then use a trigger of some kind to start the conversations when you want them. A trigger_entityname could be used for patrolling AI. If the AI are sitting near each other, a trigger_sequencer could be used to have multiple conversations over time.

Random Conversations

2018-07-04T21:29:55Z

Springheel:

''Written by Springheel''

When writing the newer vocal scripts, I came up with the idea of including a random sequence of questions and responses that can be used to create random conversations between AI. The following vocal sets support this (older ones do not):

1. vocal set_commander

2. vocal set_jack

3. vocal set_cynic

4. vocal set_drunk

5. vocal set_maiden

6. vocal set_moor

The sequence goes like this:

AI 1: "convo_question" vocal, ex, "So, how did the game go last night?"

AI 2: "convo_answer/response" vocal, ex, "Could have been better."

AI 1: "convo_close" vocal, ex, "Got it."

Each "convo_question" asks for a judgement response. "How was X? What did you think of X?" etc. Each vocal set has four or five questions/answers that are chosen from randomly. The overall effect is pretty good, I think, though some question/responses combinations make more sense than others.

The sitting AI in Mission 1: A New Job use this system. Basically, you create two conversations--one with AI 1 asking the questions, and the other with AI 2. Then use a trigger of some kind to start the conversations when you want them. A trigger_entityname could be used for patrolling AI. If the AI are sitting near each other, a trigger_sequencer could be used to have multiple conversations over time.

2017-08-23T19:53:58Z

Springheel:

''written by Fidcal. Visportals, Func_statics and Worldspawn Brushes added by Sotha.''

== What are visportals? ==
Visportals are a very important part of mapping. They are a kind of brush that helps separate your map into individual areas (called visleafs), which is important for both rendering and sound propagation.

Without visportals, the Doom engine would render the entire map even if the player can only see one small area. This would reduce performance and slow the game down.

Visportals are also very important for sound propagation. Without them, sounds can travel through brushwork and reach areas of the map that they shouldn't (see ''Sound Propagation'' at the bottom of the page).

[https://youtu.be/RmKjmt7IJr8 Video Introduction to Visportals.]

Visportals determine how far the engine should render from the player's position. When a visportal is in the player's view, the engine tests to see if there is a second visportal viewable from the position of the first. If yes then it tests to see if a third one can be seen from the second one. If the third is not viewable from the first then the engine won't waste time rendering the map beyond it. If it is, then the engine tests for a fourth one and so on. So for example, with a long corridor with lots of 90 degree turns in it and visportals at every bend then the engine will only render the section you are in plus any parts of the next section you can see. But as you get near to it and can see further down it to the next bend's visportal then it will render the next one too.

Anything in the visleaf that the player is currently in is rendered (if it is your field of view) regardless of whether it is behind worldspawn. But things in an adjacent visleaf will not be rendered if they are behind worldspawn. The engine still has to calculate what the player can see and what he can't, and this still uses resources, but far less than if it were in the same visleaf as the player. Any visleaf that is behind a closed portal is automatically beyond what the player can see, to the engine can skip testing it completely. This is why closed visportals are so valuable for performance.

The console command '''r_showPortals 1''' shows processed visportals as wireframe in-game for testing - even right through walls they are visible. A green wireframe is an 'open' visportal and renders everything beyond it up to the next visportal. A red wireframe is a 'closed' visportal with nothing rendered beyond it and no further visportals beyond that are even processed so are not visible at all. If a visportal does not show then it is either beyond range of processing or it is not working so check it is set up correctly.

== What is rendering? ==
Rendering might be regarded as the calculating of surface lighting, colour, texture, etc. Not all rendered surfaces are visible in-game but still have to be calculated. Others do not need rendering at all. Processing only takes place in the current portal area, that is, up to the nearest closed visportals. Surfaces are treated as divided into triangles for rendering purposes. The '''r_showTris''' console command shows those triangles as wireframes. In the console use '''r_showTris N''' where N is...

*0 - Off - normal gameplay with no wireframes shown.
*1 - Shows only triangles that are visible in-game (not hidden behind other surfaces.) These visible surfaces are only part of what is rendered.
*2 - Shows as wireframes, all triangle surfaces that would be rendered in-game. This includes those hidden behind other surfaces BUT ONLY IF they face the player, even slightly. Surfaces facing away from the player are never rendered.
*3 - Shows as wireframes, all triangle surfaces even if not rendered.

You can see that for the purpose of testing performance use 2 above which shows all that would be rendered (whether visible to the player or not.) You can use 3 to see ''all'' triangles up to the next closed visportal but remember not all of it will be rendered so will not affect performance.

You might also use '''r_useScissor 0''' to show geometry outside the visportal wireframe that Doom still sends to the video card but tells it not to render. '''r_useScissor 1''' helps performance but even sending the geometry uses processor time so if you can reduce it by adjusting visportal placement so much the better.

(Remember to return to '''r_useScissor 1''' when you are done with visportal testing.)

Here is a short video with a decent visual breakdown:

[http://www.gdcvault.com/play/1014234/Excerpt-Quake-Postmortem-Optimizing-Level Video]

Another video:

[http://youtu.be/cy4FIE7BhCQ http://img.youtube.com/vi/cy4FIE7BhCQ/1.jpg]

== How and where to create visportals ==

Visportals are just brushes with one face covered in visportal texture. That is the operative face. Only be concerned with that one surface as the rest of the brush merely carries it. So to create one you just....

* Make a thin brush like a wall. Ideally make it rectangular for best sound propagation (see ''Sound Propagation'' later.) It can extend beyond the gap so does not necessarily need to be the same shape - see ''Where to place your Visportal'' later.
* Give it '''textures > editor > visportal''' to either of the main surfaces facing towards or away from you. It does not matter which except you need to be aware which it is because the visportal will be effective at that one face. (Use {{Ctrl}} + {{Shift}} + {{LMB}} on the face in the Dark Radiant camera view to select one face.)

=== Thickness ===
The exact thickness is not important to its effectiveness as it will only be effective from its one visportal-textured face anyway but it makes sense to keep it reasonably thin so you can see it clearly in the editor. Always think of visportals as one flat face and the rest of the brush can be ignored for functional purposes.

=== Where to place your Visportal ===
It will eventually be wedged tight like a plug into gaps, doorways, etc. between areas. The edges of the visportal-textured face of visportals should be completely sealed by or in solid ''worldspawn'' brush that has no gaps. The brush '''must''' be a child of worldspawn and '''not''' an entity. This is true even if the visportal is within a door (see next section.) For the visportal to be effective it does not matter if the rest of the visportal brush sticks out into space so long as the edges of the visportal-textured face are surrounded by worldspawn brush and/or another visportal brush (see later) In practice you will probably put most fully within a corridor or doorway, a city street (yes, the sky above is solid worldspawn brush), etc. Irregular shaped gaps must still be plugged with a rectangular visportal which should then overlap into the solid worldspawn and leave no gaps. This will also make sound propagation work correctly (see ''Sound Propagation'' later.)

Each area you thus created must be totally enclosed with worldspawn brushes with no gaps of either space else an entity. So a closed building with visportals at the doors but a tiny gap under the eaves of the roof won't work! Also avoid only blocking gaps with entities whether brushes or models. For example, a two-sided window entity that completely fills the opening will not seal the area for portalling purposes. Do not put in a visportal unless the window is either transparent or can be opened (like a door.) Instead put in a worldspawn brush with nodraw texture on it so it will not be visible or collidable just in front of the window. Or if you are using two windows back to back (say a lit one outside and an unlit one inside then a thin caulk brush between them.

Generally you will place visportals on bends in the terrain around which the player cannot see from the current viewpoint. Avoid placing visportals in a line along a corridor or street for example. Since the player can see straight down through them all then they serve no purpose as they will all be open and visportals themselves create extra triangles and complexity (see downside section below.)

With a large building surrounded by a walled open area then try visportals at each corner. If it is a very large building then also add visportals midway along each side. The player standing at one corner might be able to see up two sides, part of a far side, and even a small part of the fourth side so all sides would be rendered. By having extra visportals middway along each side then at least half of each side of the furthest corner need not be rendered (consider also preventing the player reaching such a viewpoint with an obstruction!)

Subject to the above, try to find the smallest gaps where possible to place visportals. The smaller the visportal then the smaller the view aperture and so the less chance of lining up those apertures. Remember, visportals beyond the first one do not open unless they intersect all open visportals in that line of view. Even without a door, an open doorway is a better place for a visportal than a wider corridor or room beyond. Imagine trying to get a straight pole through as many of these visportal apertures as possible; the narrower and less aligned they are then the harder to get the pole very far.

Don't get too hung up on perfect placement of every last visportal. Generally if you follow this guide and use your judgement you achieve a satisfactory game performance. Examine some large maps that you know work well to get some ideas where visportals are placed using the '''r_showPortals 1''' command.

What if you put visportal texture on both main faces of the visportal brush? Only one will be effective. If the visportal brush juts out into space then visportal texture at that end will not work but the one at the other end will be the operative one. If you rotated the brush then it still works and uses whichever one is surrounded by solid. If both are in space it does not work at all. If both are surrounded by solid then only one works. Which one? Hard to tell. It seems to be determined by the local geometry. It is interesting to note that when you use r_showTris 3 to see what is rendered then the triangles are confined to either side of the visportal face. In other words, a long corridor wall rendered as two large triangles would now be split into four triangles. So a visportal might be considered to help with multiple lighting performance as you do not need to visually change the terrain with trim etc.

What if you put visportal texture on all the surfaces of the brush? Only one is effective (must be surrounded by solid brush.) To be certain of optimum performance use nodraw on all surfaces except the one face with visportal texture.

===Multiple Joined Visportals===
Because visportals are a single face, by their very nature they can only be placed on a single brush. But visportal brushes can be placed or merged together to fill more complex shaped gaps. For example, a wide rectangle might have one side clipped to slope over a roof while the rectangular part of its shape sits on top of another rectangle across the street below. But complexity affects performance so only do this if one rectangular visportal intruding into interior walls might do the same job. Remember, it does not matter if the visportal overlaps into solid so if there is an interior wall on the same plane (or indeed if the building is totally solid) then the visportal can penetrate it and still function. Do not use multiple visportals just to shape nicely around solid building trim and structure but intrude into it so long as the edge does not exit into space at any point it will be fine.

== Visportals and doors ==
A visportal in contact with a door that has an openable property is automatically closed when the door is closed and automatically becomes conventionally operative when the door opens. By 'operative' I mean it is then like a normal visportal and will be open or closed depending on the player's view. So when you first go through a door and leave it open then its visportal will be open as you look immediately back at it. But as you then proceed further through other visportals, the door visportal will eventually close (prevent rendering through it) even if the door itself is left open.

=== Doors standing in front of but not within a doorway ===
Note that the visportal only needs to be in contact with the door to be affected by it. Normally you would place the visportal within the door but it actually only needs its visportal-textured surface to touch it. This means that if you have a door that is stood in front of an opening in a wall then you cannot put the visportal inside the door because it will not be surrounded by solid brush. But you can put a visportal just inside the opening and flush with the mouth of the opening and the door immediately in front of that and in contact with the visportal. You can test this by placing the door offset well to one side but part of it still in contact with the visportal. In game you can see the opening as the door is only partially covering it. When the door is closed the visportal closes and stops rendering through the doorway. You will see this as a black panel in the doorway. As the door opens the black panel disappears and you can see through the doorway again. You might think that from the other side the black panel would obscure the door when closed but it doesn't. With the door centred in its normal position, typically you might have an entity frame around the door. If you had a solid brush frame without gaps then the visportal could be inside the door if you wanted as it would then have solid all round its edges. In many cases of course, the door frame, whether entity or brush, would be within the solid brush doorway anyway.

=== Windows, Doors with windows, bars, etc. ===
Openable doors that let you see through them such as windows, doors with windows, barred gates, etc. should not be in contact with a visportal. When the door is closed it will automatically close any visportal whose effective surface is in touch with it. The visportal will not then permit any rendering through it and will show as a black panel in the window or between the bars of a gate. Instead, move the visportal away from the door. It will still function effectively as a normal visportal just as if the door were not there. This does not of course apply to simulated windows such as a glazed textured panel on a door texture where you cannot actually see through.

All doors and windows that do not have an openable property can have a visportal in touch with them as it will not be affected by them and it will just function as a normal visportal.

{{red|Rev. 2.00:}}

Starting with Rev. 2.00, you can touch a see-through door or window with a visportal, and the portal will not close when the door/window is closed, as long as you use the following spawnarg '''on the door/window''' (not the info_portalsettings entity):

* '''transparent''' "If set to 1 (0 by default), a see-through door can touch a visportal and the visportal won't close when the door is closed."

This is useful when you want the opening or closing of the door to affect the sound loss across the portal, but not affect visibility through the door/window. Imagine a closed window that muffles a sound beyond it, and as the window opens, the sound gets louder.

==Visportal switches: func_portals==

The preceding section ''Visportals and doors'' makes clear that doors can function like switches to enable and close visportals in contact with them. ''func_portals'' can be used to enact further control over portals. You can place a ''func_portal'' entity so that it intersects with a visportal, and then trigger the func_portal to close or open the visportal. A second control method is had by using the ''portal_dist'' and ''distcheck_period'' properties on the ''func_portal''. They control the distance to the player and how frequently (in seconds) this distance should be checked, respectively, and make explicit triggering of the ''func_portal'' unnecessary. As with doors, even if enabled, the visportal will not be open even if it is in the player's view. Note, if you have a mover (door/window) in contact with the visportal, it will affect it as well, so typically a visportal controlled by func_portal is placed away from the mover, or use spawnarg "transparent" set to 1.

Another clever trick exists with regard to ''func_portal''s: you can also build a func_static over the visportal, and target it with the ''func_portal'' as normal. Now, in addition to opening and closing the portal, this will also toggle the drawing of the ''func_static''. This means you could place an appropriate texture (perhaps a low resolution image of a room's interior, drawn over a window) and have it turn on or off based on the player's distance away. From a distance, the player wouldn't be able to tell that the the entire room wasn't being rendered. This can be an effective way to create the illusion of long view distances.

Note that the func_static must touch the visportal in order to work.

''One way to make this work is to create a patch, make it a func_static. Texture the patch, and then target the func_portal at that func_static. You must then add "hide" "1" to the func_static patch. There may be other ways to make this work, but I had a lot of trouble until I took these steps. -- Springheel''

An interesting, recent discovery that needs some testing is that apparently: you can take one visportal and cut it in half, and then put different func_portals on each half in order to close them at different ranges. That has interesting implications for wide city streets. They require big visportals, but if you can split them up and independently control each part, there may be some benefits there. http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/?p=370473

== Need I design, even compromise my map to make best use of visportals? ==
You need to design your map from the start as a series of connected boxes (brushes) with the player's view, sound propogation, and visportals in mind. And yes, sometimes you might need to add a bend you don't want or obstruct a view in some way so you can put in another visportal if you are having or expecting slow down in a large and/or complex area. This is a matter of experience. If you have large complex areas and are experiencing frame lag but can see no obvious place to put a visportal then you might need to compromise your terrain and add some solid brush barriers to block certain views with visportals in the access round or through them.

Note that it is not essential that visportals be only at the actual joins between brushes; they still work even if they are half way down a corridor so long as they are wedged in tight without gaps. But you will mostly place them at joins.

For rendering considerations, the player's view is everything and every room and street in front of you even if there are walls, etc. in the way. Imagine what you would see with X-Ray vision. What is behind you or just out of range of the screen does not matter. But visportals restrict the view to what can be seen through the aperture of the visportal.

It is not necessary to put visportals at every tiny bend in the map; in fact that should be avoided in smaller areas because visportals themselves create extra triangles and complexity (see downside section below.) Try to keep in mind what will be rendered through the visportals and judge what would ''not'' cause frame lag slowdown if the player could actually see that view. Three or four bends without visportals in a restricted air duct is not going to cause any problem if the duct is correctly visportalled at the ends for example.

== Is there a downside? ==
One downside to visportals is that is extra work for the mapper! Another is that they split the geometry and create extra triangles and batches. This will not normally cause a problem unless your map has a very large number of areas. The advantages in performance of using visportals far outweigh the downsides!

==Sound Propagation==

Correct propagation of sound (both to AI and to the player) relies on visportals.

Think of vis-portals as sealing off separate "areas" in a map. A sound that occurs inside a sealed "area" will travel in a straight line to anyone inside the same area, even through walls. If you are not in the same area, however, the sound will travel in a straight line to the first visportal between you and the sound source, then to the next one, etc, until it reaches the area you are in.

If the sound happens in an area that is not sealed, it essentially considers the whole map its "area", and will go straight to the player, through walls, floors, or other brushwork. This can result in confusion for players, as they will hear AI on the other side of a massive wall as if they were standing beside each other.

In the following examples, "P" is the player and "S" is the sound source. The Visportals are red lines. The green lines show how the sound would travel.

[[image:vis.jpg]]

Without any visportals, the sound goes in a straight line to the player, even through solid walls. It will sound like the player is in the same room as the sound.

One visportal is an improvement--it will sound further away, but the sound travels straight to the visportal and then straight to the player, so it will still sound like it is coming through the wall.

Two visportals are best in this case, however. The sound will seem like it is coming from the opening to the room, which is where you would expect it to come from.

Sound ''going to the AI'' travels the shortest distance through a visportal, passing at any point on the visportal surface. Mappers should always use rectangular visportals unless you have no choice with an awkwardly shaped gap or if the gap is out of range of AI, for example along a sloping roof where AI never go. '''It also still assumes that when you do have four sides, they are perpendicular.''' If you have some non-90 degree angles between the sides, some wierdness may ensue. For example, an AI that is alerted in the dark (or facing away) by hearing a sound from the player that passes through an irregular visportal might run to the center of the visportal rather than directly to where the player made the noise. Irregular visportals large enough to make this effect noticeable are likely to be uncommon.

This will be okay for smaller irregular visportals, but the error (path difference from the minimal path) will get more noticeable the larger the visportal.

Visportals function individually even if joined together into complex shapes. So a rectangle at ground level topped by an angled visportal above it tilting out over a roof will be treated separately, not as one aperture.

The bottom line is, with any non-rectangular visportals keep the above in mind and if in doubt then consider early testing of AI's alert to player sound.

Visportals do NOT need to be closed to correctly channel sound to the player. Sometimes it is worth adding visportals even if they will not help with rendering (because they will always be open) in order to make sound travel the way it should.

To make less sound go through a visportal (through a small hole, for example):
Soundprop can use info_locationSeparator or info_portalSettings to make sound incur a certain loss when going through the portal it's touching. The key/value pair is the following:

sound_loss "Soundprop: Loss in dB incurred when a sound travels through this portal. Cumulative with door loss if a door is present."

The loss must be a positive number, and negative numbers will automatically be converted to positive.

{{red|Rev 2.00:}}

Prior to Rev 2.00, '''sound_loss''' affected the sound propagation to AI '''only'''. Sound propagation to the player was not affected.

Starting with Rev 2.00, '''sound_loss''' is also used in determining sound volume to the player. This aligns what AI hear with what the player hears. It also allows sound coming through the door to increase as the door opens, or decrease as the door closes, making for a more realistic experience.

For details study:
[[Sound Propagation: Part 1]] and
[[Sound Propagation: Part 2]]

== Trouble-shooting ==

There are two possible problems I can think of: the visportal doesn't work at all or it works yet there is too much being rendered giving poor performance and frame lag. The latter problem is a matter of experience and experimentation. Often much ingenuity is needed to place visportals to reduce the size of areas being rendered at any one time. There is probably a different solution for every situation. Ultimately you might be forced to change the terrain to help visportalling.

If a visportal doesn't work at all (eg, does not show as either red or green while you are directly in its area and looking at it and you have '''r_showPortals''' enabled) then that means there is a "leak" in that ''area''. It does not necessarily mean the visportal itself is the problem.

Try the following to track down the problem.

'''Check the visportal itself:'''

* Check which face of the visportal is facing which way. It sometimes happen one clones a visportal and rotates it the wrong way without realizing. So the wrong face is in the right place but the visportal face is not in contact with worldspawn.

* Make sure the visportal hasn't been assigned to an entity but is worldspawn.

* Search for gaps anywhere around the edges of the visportal face. Check for grid snapping not only of the visportal but the surrounding brushes. A tiny difference might not be visible in the Dark Radiant grid if you are not zoomed in sufficiently.

* Check all surrounding items to see if any are entities. Remember, the visportal '''face''' must only be surrounded by worldspawn brushes. It seems to be mostly OK if the visportal ''cuts through'' an entity so long as it meets worldspawn at its edges.

'''Check the area for internal leaks:'''

There is a way to test an individual area for leaks. It sounds more complicated than it is.

1. Filter off all entities. Make sure visportals are NOT filtered.

2. Select your entire visible map (which will now be only brushwork).

3. Copy and paste into a new blank map.

4. Put the player start into the area where you think you have an internal leak.

5. Take the visportals sealing that area and texture them with a solid texture.

6. Make sure there is only void around the map (if you have your entire map encased in a skybox brush, open a hole in a distant corner of the map).

7. Save the map as a new filename and run dmap. If you do not get a leak, then the area with the player start is properly sealed. Move the player start to a new area and repeat as needed.

8. If you do get a leak, open the pointfile in DR. Because the player entity is the only entity in the map, the red line will always start there and will show you where the gap is.

9. Go back to your original map and fix the gap. Repeat as needed.

'''Having visportals that line up in parallel with each other can cause problems, usually appearing as pieces of wall that appear black or show skybox. This can usually be fixed by moving a visportal slightly or turning one on a slight angle so they're no longer parallel.'''

'''If all else fails, try:'''

* Clone the visportal and drag one edge to one side, that is, reduce its size to say half.
* Select the original and drag its opposite edge the other way so you now have two visportals pressed together and which together fill the gap. Guess which side unless you suspect one side particularly (see later.)
* Change one of the visportals to any normal visible simple texture, stone, wood, whatever so that now the original gap is smaller and filled by just one smaller visportal. (with hindsight, I think this would probably work anyway and might even be better just leaving it as visportal so you can see which one works but I'll continue with what I did!)
* Check it in game.
* If it still does not work then reduce it further, perhaps by half as much again. In particular, go past edges of surrounding brushes (eg, if working downwards with two brushes on the left then maybe it's the top brush that is the problem so reduce the top of the visportal below its bottom edge.) Obviously as you reduce the visportal you increase the solid temporary brush you made equally to keep up so there is never a gap.
* If the visportal still does not work even when reduced to a slither then try the same for all four sides noting that the three sides against the slither of visportal are obviously first suspects.
* If eventually the visportal starts to work then you know the error is in the other section where you have the solid temporary brush. Use a process of elimination to track down exactly where the error is.
* You might even have to create a third temporary brush or even a fourth but you must eventually force the visportal to work even if you surround it with four new brushes! Once working, then reduce, remove, gradually until the error re-appears - that must be where the error lies. So by a process of elimination you should track down the source of the problem.
* The result might make not seem to make sense but at least if you locate the error you can try things to solve the problem. I had a visportal up to the sky and on its left against the top of a triangle of bricks on which rested a roof. The visportal seemed to be perfectly surrounded by worldspawn but I reduced it slightly with just a slim temporary solid test brush only one unit high above it pressing against the top of this triangle. The visportal was now working yet if I removed that slim test brush and raised the visportal to the top again then it would not work. Made no sense to me unless mathematically the very top pixel of the triangle might be regarded as infinitely thin and therefore a gap. So, I left the thin test brush and gave it sky texture so it's completely invisible and everything works.

(Note: Some mappers at Doom3world reported that cloned visportal brushes can cause problems in a map. This was reported in an earlier Doom 3 build.)

== See also ==
There are other good visportal tutorials to be found under:
http://www.iddevnet.com/doom3/visportals.php and http://www.modwiki.net/wiki/Visportal

== Visportals, Func_statics and Worldspawn Brushes ==
Sometimes a visportal (VP) looks just fine in-game, but AI's behave erratically near them: cannot walk through the portal, walk into walls near the portal, can patrol through the portal but cannot chase the player through the portal. This may be due to worldspawn brushes penetrating the visportal.

Image shows scenarios A-D of different VP placement.
[[image:visportal_scenarios.png]]

*Scenario A, when VP is snugly placed in the worldspawn corridor, it always works.
*Scenario B, where a worldspawn brush penetrates the VP has often caused problems. It will fail with very high probability if the worldspawn brush is a monsterclip brush. Never do this scenario! ''[Springheel -- I'd like more confirmation on this...I'm certain I've done this on a regular basis in uneven city streets without causing any obvious problems]''
*Scenario C is what could be used if the scene absolutely requires somethings going through the VP and scenario A or D cannot be used. Usually this must be done for big outdoors VP's as seen in Knightons Manor exterior behind the manor (it is the hedge, which goes through the VP there). Note how the worldspawn brush is cut just at the VP and it is only func_static which penetrates the VP. This has worked without issues. Note that no monsterclipping is required if the func_static segment of the VP penetrating brush is short enough. The blue worldspawn brushes could also be monsterclipped func_statics as well. If so, mapper must be certain monsterclip brushes do not penetrate the VP!
*Scenario D where the VP is penetrated by func_static detail work, has not been reported to break visportals. Usually this kind of case is used in vaulted corridors etc. Works just fine. If the FS detail work is in reach of AI, special care to monsterclipping should be paid and it must be absolutely sure the monsterclip does not penetrate the VP as this will always cause trouble. In this scenario it is recommended that each side of the visportal have their own func_statics and one func_static brush should never penetrate more than one visportal.

===Conclusion===
Mappers should favour scenario A when possible. If detailwork requires, scenario D is okay, as well as scenario C. Never, ever use scenario B.

If mapper has some issues with their AI pathfinding, they should check the portal isn't broken as in scenario B. It is really easy to forget wall trims etc which could pass through the VP. Also typical mistake is to automatically surround a model near the VP with monsterclip, which results monsterclip brush which penetrates the VP. It is recommended that the mapper tests every visportal (which an AI is likely to pass) in their map before the map is released. Firstly the mapper should check in DR and make sure visportals are correctly set. Ingame testing should be done both with non-alerted path_corner patrolling AI's and with an alerted AI chasing the player.

[[Category:Skybox]]
[[Category:Visportal]]
{{tutorial-editing}}

Visportals

2017-08-23T19:52:40Z

Springheel: /* What are visportals? */

''written by Fidcal. Visportals, Func_statics and Worldspawn Brushes added by Sotha.''

== What are visportals? ==
Visportals are a very important part of mapping. They are a kind of brush that helps separate your map into individual areas (called visleafs), which is important for both rendering and sound propagation.

Without visportals, the Doom engine would render the entire map even if the player can only see one small area. This would reduce performance and slow the game down.

Visportals are also very important for sound propagation. Without them, sounds can travel through brushwork and reach areas of the map that they shouldn't (see ''Sound Propagation'' at the bottom of the page).

<iframe width="560" height="315" src="https://www.youtube.com/embed/RmKjmt7IJr8" frameborder="0" allowfullscreen></iframe>

Visportals determine how far the engine should render from the player's position. When a visportal is in the player's view, the engine tests to see if there is a second visportal viewable from the position of the first. If yes then it tests to see if a third one can be seen from the second one. If the third is not viewable from the first then the engine won't waste time rendering the map beyond it. If it is, then the engine tests for a fourth one and so on. So for example, with a long corridor with lots of 90 degree turns in it and visportals at every bend then the engine will only render the section you are in plus any parts of the next section you can see. But as you get near to it and can see further down it to the next bend's visportal then it will render the next one too.

Anything in the visleaf that the player is currently in is rendered (if it is your field of view) regardless of whether it is behind worldspawn. But things in an adjacent visleaf will not be rendered if they are behind worldspawn. The engine still has to calculate what the player can see and what he can't, and this still uses resources, but far less than if it were in the same visleaf as the player. Any visleaf that is behind a closed portal is automatically beyond what the player can see, to the engine can skip testing it completely. This is why closed visportals are so valuable for performance.

The console command '''r_showPortals 1''' shows processed visportals as wireframe in-game for testing - even right through walls they are visible. A green wireframe is an 'open' visportal and renders everything beyond it up to the next visportal. A red wireframe is a 'closed' visportal with nothing rendered beyond it and no further visportals beyond that are even processed so are not visible at all. If a visportal does not show then it is either beyond range of processing or it is not working so check it is set up correctly.

== What is rendering? ==
Rendering might be regarded as the calculating of surface lighting, colour, texture, etc. Not all rendered surfaces are visible in-game but still have to be calculated. Others do not need rendering at all. Processing only takes place in the current portal area, that is, up to the nearest closed visportals. Surfaces are treated as divided into triangles for rendering purposes. The '''r_showTris''' console command shows those triangles as wireframes. In the console use '''r_showTris N''' where N is...

*0 - Off - normal gameplay with no wireframes shown.
*1 - Shows only triangles that are visible in-game (not hidden behind other surfaces.) These visible surfaces are only part of what is rendered.
*2 - Shows as wireframes, all triangle surfaces that would be rendered in-game. This includes those hidden behind other surfaces BUT ONLY IF they face the player, even slightly. Surfaces facing away from the player are never rendered.
*3 - Shows as wireframes, all triangle surfaces even if not rendered.

You can see that for the purpose of testing performance use 2 above which shows all that would be rendered (whether visible to the player or not.) You can use 3 to see ''all'' triangles up to the next closed visportal but remember not all of it will be rendered so will not affect performance.

You might also use '''r_useScissor 0''' to show geometry outside the visportal wireframe that Doom still sends to the video card but tells it not to render. '''r_useScissor 1''' helps performance but even sending the geometry uses processor time so if you can reduce it by adjusting visportal placement so much the better.

(Remember to return to '''r_useScissor 1''' when you are done with visportal testing.)

Here is a short video with a decent visual breakdown:

[http://www.gdcvault.com/play/1014234/Excerpt-Quake-Postmortem-Optimizing-Level Video]

Another video:

[http://youtu.be/cy4FIE7BhCQ http://img.youtube.com/vi/cy4FIE7BhCQ/1.jpg]

== How and where to create visportals ==

Visportals are just brushes with one face covered in visportal texture. That is the operative face. Only be concerned with that one surface as the rest of the brush merely carries it. So to create one you just....

* Make a thin brush like a wall. Ideally make it rectangular for best sound propagation (see ''Sound Propagation'' later.) It can extend beyond the gap so does not necessarily need to be the same shape - see ''Where to place your Visportal'' later.
* Give it '''textures > editor > visportal''' to either of the main surfaces facing towards or away from you. It does not matter which except you need to be aware which it is because the visportal will be effective at that one face. (Use {{Ctrl}} + {{Shift}} + {{LMB}} on the face in the Dark Radiant camera view to select one face.)

=== Thickness ===
The exact thickness is not important to its effectiveness as it will only be effective from its one visportal-textured face anyway but it makes sense to keep it reasonably thin so you can see it clearly in the editor. Always think of visportals as one flat face and the rest of the brush can be ignored for functional purposes.

=== Where to place your Visportal ===
It will eventually be wedged tight like a plug into gaps, doorways, etc. between areas. The edges of the visportal-textured face of visportals should be completely sealed by or in solid ''worldspawn'' brush that has no gaps. The brush '''must''' be a child of worldspawn and '''not''' an entity. This is true even if the visportal is within a door (see next section.) For the visportal to be effective it does not matter if the rest of the visportal brush sticks out into space so long as the edges of the visportal-textured face are surrounded by worldspawn brush and/or another visportal brush (see later) In practice you will probably put most fully within a corridor or doorway, a city street (yes, the sky above is solid worldspawn brush), etc. Irregular shaped gaps must still be plugged with a rectangular visportal which should then overlap into the solid worldspawn and leave no gaps. This will also make sound propagation work correctly (see ''Sound Propagation'' later.)

Each area you thus created must be totally enclosed with worldspawn brushes with no gaps of either space else an entity. So a closed building with visportals at the doors but a tiny gap under the eaves of the roof won't work! Also avoid only blocking gaps with entities whether brushes or models. For example, a two-sided window entity that completely fills the opening will not seal the area for portalling purposes. Do not put in a visportal unless the window is either transparent or can be opened (like a door.) Instead put in a worldspawn brush with nodraw texture on it so it will not be visible or collidable just in front of the window. Or if you are using two windows back to back (say a lit one outside and an unlit one inside then a thin caulk brush between them.

Generally you will place visportals on bends in the terrain around which the player cannot see from the current viewpoint. Avoid placing visportals in a line along a corridor or street for example. Since the player can see straight down through them all then they serve no purpose as they will all be open and visportals themselves create extra triangles and complexity (see downside section below.)

With a large building surrounded by a walled open area then try visportals at each corner. If it is a very large building then also add visportals midway along each side. The player standing at one corner might be able to see up two sides, part of a far side, and even a small part of the fourth side so all sides would be rendered. By having extra visportals middway along each side then at least half of each side of the furthest corner need not be rendered (consider also preventing the player reaching such a viewpoint with an obstruction!)

Subject to the above, try to find the smallest gaps where possible to place visportals. The smaller the visportal then the smaller the view aperture and so the less chance of lining up those apertures. Remember, visportals beyond the first one do not open unless they intersect all open visportals in that line of view. Even without a door, an open doorway is a better place for a visportal than a wider corridor or room beyond. Imagine trying to get a straight pole through as many of these visportal apertures as possible; the narrower and less aligned they are then the harder to get the pole very far.

Don't get too hung up on perfect placement of every last visportal. Generally if you follow this guide and use your judgement you achieve a satisfactory game performance. Examine some large maps that you know work well to get some ideas where visportals are placed using the '''r_showPortals 1''' command.

What if you put visportal texture on both main faces of the visportal brush? Only one will be effective. If the visportal brush juts out into space then visportal texture at that end will not work but the one at the other end will be the operative one. If you rotated the brush then it still works and uses whichever one is surrounded by solid. If both are in space it does not work at all. If both are surrounded by solid then only one works. Which one? Hard to tell. It seems to be determined by the local geometry. It is interesting to note that when you use r_showTris 3 to see what is rendered then the triangles are confined to either side of the visportal face. In other words, a long corridor wall rendered as two large triangles would now be split into four triangles. So a visportal might be considered to help with multiple lighting performance as you do not need to visually change the terrain with trim etc.

What if you put visportal texture on all the surfaces of the brush? Only one is effective (must be surrounded by solid brush.) To be certain of optimum performance use nodraw on all surfaces except the one face with visportal texture.

===Multiple Joined Visportals===
Because visportals are a single face, by their very nature they can only be placed on a single brush. But visportal brushes can be placed or merged together to fill more complex shaped gaps. For example, a wide rectangle might have one side clipped to slope over a roof while the rectangular part of its shape sits on top of another rectangle across the street below. But complexity affects performance so only do this if one rectangular visportal intruding into interior walls might do the same job. Remember, it does not matter if the visportal overlaps into solid so if there is an interior wall on the same plane (or indeed if the building is totally solid) then the visportal can penetrate it and still function. Do not use multiple visportals just to shape nicely around solid building trim and structure but intrude into it so long as the edge does not exit into space at any point it will be fine.

== Visportals and doors ==
A visportal in contact with a door that has an openable property is automatically closed when the door is closed and automatically becomes conventionally operative when the door opens. By 'operative' I mean it is then like a normal visportal and will be open or closed depending on the player's view. So when you first go through a door and leave it open then its visportal will be open as you look immediately back at it. But as you then proceed further through other visportals, the door visportal will eventually close (prevent rendering through it) even if the door itself is left open.

=== Doors standing in front of but not within a doorway ===
Note that the visportal only needs to be in contact with the door to be affected by it. Normally you would place the visportal within the door but it actually only needs its visportal-textured surface to touch it. This means that if you have a door that is stood in front of an opening in a wall then you cannot put the visportal inside the door because it will not be surrounded by solid brush. But you can put a visportal just inside the opening and flush with the mouth of the opening and the door immediately in front of that and in contact with the visportal. You can test this by placing the door offset well to one side but part of it still in contact with the visportal. In game you can see the opening as the door is only partially covering it. When the door is closed the visportal closes and stops rendering through the doorway. You will see this as a black panel in the doorway. As the door opens the black panel disappears and you can see through the doorway again. You might think that from the other side the black panel would obscure the door when closed but it doesn't. With the door centred in its normal position, typically you might have an entity frame around the door. If you had a solid brush frame without gaps then the visportal could be inside the door if you wanted as it would then have solid all round its edges. In many cases of course, the door frame, whether entity or brush, would be within the solid brush doorway anyway.

=== Windows, Doors with windows, bars, etc. ===
Openable doors that let you see through them such as windows, doors with windows, barred gates, etc. should not be in contact with a visportal. When the door is closed it will automatically close any visportal whose effective surface is in touch with it. The visportal will not then permit any rendering through it and will show as a black panel in the window or between the bars of a gate. Instead, move the visportal away from the door. It will still function effectively as a normal visportal just as if the door were not there. This does not of course apply to simulated windows such as a glazed textured panel on a door texture where you cannot actually see through.

All doors and windows that do not have an openable property can have a visportal in touch with them as it will not be affected by them and it will just function as a normal visportal.

{{red|Rev. 2.00:}}

Starting with Rev. 2.00, you can touch a see-through door or window with a visportal, and the portal will not close when the door/window is closed, as long as you use the following spawnarg '''on the door/window''' (not the info_portalsettings entity):

* '''transparent''' "If set to 1 (0 by default), a see-through door can touch a visportal and the visportal won't close when the door is closed."

This is useful when you want the opening or closing of the door to affect the sound loss across the portal, but not affect visibility through the door/window. Imagine a closed window that muffles a sound beyond it, and as the window opens, the sound gets louder.

==Visportal switches: func_portals==

The preceding section ''Visportals and doors'' makes clear that doors can function like switches to enable and close visportals in contact with them. ''func_portals'' can be used to enact further control over portals. You can place a ''func_portal'' entity so that it intersects with a visportal, and then trigger the func_portal to close or open the visportal. A second control method is had by using the ''portal_dist'' and ''distcheck_period'' properties on the ''func_portal''. They control the distance to the player and how frequently (in seconds) this distance should be checked, respectively, and make explicit triggering of the ''func_portal'' unnecessary. As with doors, even if enabled, the visportal will not be open even if it is in the player's view. Note, if you have a mover (door/window) in contact with the visportal, it will affect it as well, so typically a visportal controlled by func_portal is placed away from the mover, or use spawnarg "transparent" set to 1.

Another clever trick exists with regard to ''func_portal''s: you can also build a func_static over the visportal, and target it with the ''func_portal'' as normal. Now, in addition to opening and closing the portal, this will also toggle the drawing of the ''func_static''. This means you could place an appropriate texture (perhaps a low resolution image of a room's interior, drawn over a window) and have it turn on or off based on the player's distance away. From a distance, the player wouldn't be able to tell that the the entire room wasn't being rendered. This can be an effective way to create the illusion of long view distances.

Note that the func_static must touch the visportal in order to work.

''One way to make this work is to create a patch, make it a func_static. Texture the patch, and then target the func_portal at that func_static. You must then add "hide" "1" to the func_static patch. There may be other ways to make this work, but I had a lot of trouble until I took these steps. -- Springheel''

An interesting, recent discovery that needs some testing is that apparently: you can take one visportal and cut it in half, and then put different func_portals on each half in order to close them at different ranges. That has interesting implications for wide city streets. They require big visportals, but if you can split them up and independently control each part, there may be some benefits there. http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/?p=370473

== Need I design, even compromise my map to make best use of visportals? ==
You need to design your map from the start as a series of connected boxes (brushes) with the player's view, sound propogation, and visportals in mind. And yes, sometimes you might need to add a bend you don't want or obstruct a view in some way so you can put in another visportal if you are having or expecting slow down in a large and/or complex area. This is a matter of experience. If you have large complex areas and are experiencing frame lag but can see no obvious place to put a visportal then you might need to compromise your terrain and add some solid brush barriers to block certain views with visportals in the access round or through them.

Note that it is not essential that visportals be only at the actual joins between brushes; they still work even if they are half way down a corridor so long as they are wedged in tight without gaps. But you will mostly place them at joins.

For rendering considerations, the player's view is everything and every room and street in front of you even if there are walls, etc. in the way. Imagine what you would see with X-Ray vision. What is behind you or just out of range of the screen does not matter. But visportals restrict the view to what can be seen through the aperture of the visportal.

It is not necessary to put visportals at every tiny bend in the map; in fact that should be avoided in smaller areas because visportals themselves create extra triangles and complexity (see downside section below.) Try to keep in mind what will be rendered through the visportals and judge what would ''not'' cause frame lag slowdown if the player could actually see that view. Three or four bends without visportals in a restricted air duct is not going to cause any problem if the duct is correctly visportalled at the ends for example.

== Is there a downside? ==
One downside to visportals is that is extra work for the mapper! Another is that they split the geometry and create extra triangles and batches. This will not normally cause a problem unless your map has a very large number of areas. The advantages in performance of using visportals far outweigh the downsides!

==Sound Propagation==

Correct propagation of sound (both to AI and to the player) relies on visportals.

Think of vis-portals as sealing off separate "areas" in a map. A sound that occurs inside a sealed "area" will travel in a straight line to anyone inside the same area, even through walls. If you are not in the same area, however, the sound will travel in a straight line to the first visportal between you and the sound source, then to the next one, etc, until it reaches the area you are in.

If the sound happens in an area that is not sealed, it essentially considers the whole map its "area", and will go straight to the player, through walls, floors, or other brushwork. This can result in confusion for players, as they will hear AI on the other side of a massive wall as if they were standing beside each other.

In the following examples, "P" is the player and "S" is the sound source. The Visportals are red lines. The green lines show how the sound would travel.

[[image:vis.jpg]]

Without any visportals, the sound goes in a straight line to the player, even through solid walls. It will sound like the player is in the same room as the sound.

One visportal is an improvement--it will sound further away, but the sound travels straight to the visportal and then straight to the player, so it will still sound like it is coming through the wall.

Two visportals are best in this case, however. The sound will seem like it is coming from the opening to the room, which is where you would expect it to come from.

Sound ''going to the AI'' travels the shortest distance through a visportal, passing at any point on the visportal surface. Mappers should always use rectangular visportals unless you have no choice with an awkwardly shaped gap or if the gap is out of range of AI, for example along a sloping roof where AI never go. '''It also still assumes that when you do have four sides, they are perpendicular.''' If you have some non-90 degree angles between the sides, some wierdness may ensue. For example, an AI that is alerted in the dark (or facing away) by hearing a sound from the player that passes through an irregular visportal might run to the center of the visportal rather than directly to where the player made the noise. Irregular visportals large enough to make this effect noticeable are likely to be uncommon.

This will be okay for smaller irregular visportals, but the error (path difference from the minimal path) will get more noticeable the larger the visportal.

Visportals function individually even if joined together into complex shapes. So a rectangle at ground level topped by an angled visportal above it tilting out over a roof will be treated separately, not as one aperture.

The bottom line is, with any non-rectangular visportals keep the above in mind and if in doubt then consider early testing of AI's alert to player sound.

Visportals do NOT need to be closed to correctly channel sound to the player. Sometimes it is worth adding visportals even if they will not help with rendering (because they will always be open) in order to make sound travel the way it should.

To make less sound go through a visportal (through a small hole, for example):
Soundprop can use info_locationSeparator or info_portalSettings to make sound incur a certain loss when going through the portal it's touching. The key/value pair is the following:

sound_loss "Soundprop: Loss in dB incurred when a sound travels through this portal. Cumulative with door loss if a door is present."

The loss must be a positive number, and negative numbers will automatically be converted to positive.

{{red|Rev 2.00:}}

Prior to Rev 2.00, '''sound_loss''' affected the sound propagation to AI '''only'''. Sound propagation to the player was not affected.

Starting with Rev 2.00, '''sound_loss''' is also used in determining sound volume to the player. This aligns what AI hear with what the player hears. It also allows sound coming through the door to increase as the door opens, or decrease as the door closes, making for a more realistic experience.

For details study:
[[Sound Propagation: Part 1]] and
[[Sound Propagation: Part 2]]

== Trouble-shooting ==

There are two possible problems I can think of: the visportal doesn't work at all or it works yet there is too much being rendered giving poor performance and frame lag. The latter problem is a matter of experience and experimentation. Often much ingenuity is needed to place visportals to reduce the size of areas being rendered at any one time. There is probably a different solution for every situation. Ultimately you might be forced to change the terrain to help visportalling.

If a visportal doesn't work at all (eg, does not show as either red or green while you are directly in its area and looking at it and you have '''r_showPortals''' enabled) then that means there is a "leak" in that ''area''. It does not necessarily mean the visportal itself is the problem.

Try the following to track down the problem.

'''Check the visportal itself:'''

* Check which face of the visportal is facing which way. It sometimes happen one clones a visportal and rotates it the wrong way without realizing. So the wrong face is in the right place but the visportal face is not in contact with worldspawn.

* Make sure the visportal hasn't been assigned to an entity but is worldspawn.

* Search for gaps anywhere around the edges of the visportal face. Check for grid snapping not only of the visportal but the surrounding brushes. A tiny difference might not be visible in the Dark Radiant grid if you are not zoomed in sufficiently.

* Check all surrounding items to see if any are entities. Remember, the visportal '''face''' must only be surrounded by worldspawn brushes. It seems to be mostly OK if the visportal ''cuts through'' an entity so long as it meets worldspawn at its edges.

'''Check the area for internal leaks:'''

There is a way to test an individual area for leaks. It sounds more complicated than it is.

1. Filter off all entities. Make sure visportals are NOT filtered.

2. Select your entire visible map (which will now be only brushwork).

3. Copy and paste into a new blank map.

4. Put the player start into the area where you think you have an internal leak.

5. Take the visportals sealing that area and texture them with a solid texture.

6. Make sure there is only void around the map (if you have your entire map encased in a skybox brush, open a hole in a distant corner of the map).

7. Save the map as a new filename and run dmap. If you do not get a leak, then the area with the player start is properly sealed. Move the player start to a new area and repeat as needed.

8. If you do get a leak, open the pointfile in DR. Because the player entity is the only entity in the map, the red line will always start there and will show you where the gap is.

9. Go back to your original map and fix the gap. Repeat as needed.

'''Having visportals that line up in parallel with each other can cause problems, usually appearing as pieces of wall that appear black or show skybox. This can usually be fixed by moving a visportal slightly or turning one on a slight angle so they're no longer parallel.'''

'''If all else fails, try:'''

* Clone the visportal and drag one edge to one side, that is, reduce its size to say half.
* Select the original and drag its opposite edge the other way so you now have two visportals pressed together and which together fill the gap. Guess which side unless you suspect one side particularly (see later.)
* Change one of the visportals to any normal visible simple texture, stone, wood, whatever so that now the original gap is smaller and filled by just one smaller visportal. (with hindsight, I think this would probably work anyway and might even be better just leaving it as visportal so you can see which one works but I'll continue with what I did!)
* Check it in game.
* If it still does not work then reduce it further, perhaps by half as much again. In particular, go past edges of surrounding brushes (eg, if working downwards with two brushes on the left then maybe it's the top brush that is the problem so reduce the top of the visportal below its bottom edge.) Obviously as you reduce the visportal you increase the solid temporary brush you made equally to keep up so there is never a gap.
* If the visportal still does not work even when reduced to a slither then try the same for all four sides noting that the three sides against the slither of visportal are obviously first suspects.
* If eventually the visportal starts to work then you know the error is in the other section where you have the solid temporary brush. Use a process of elimination to track down exactly where the error is.
* You might even have to create a third temporary brush or even a fourth but you must eventually force the visportal to work even if you surround it with four new brushes! Once working, then reduce, remove, gradually until the error re-appears - that must be where the error lies. So by a process of elimination you should track down the source of the problem.
* The result might make not seem to make sense but at least if you locate the error you can try things to solve the problem. I had a visportal up to the sky and on its left against the top of a triangle of bricks on which rested a roof. The visportal seemed to be perfectly surrounded by worldspawn but I reduced it slightly with just a slim temporary solid test brush only one unit high above it pressing against the top of this triangle. The visportal was now working yet if I removed that slim test brush and raised the visportal to the top again then it would not work. Made no sense to me unless mathematically the very top pixel of the triangle might be regarded as infinitely thin and therefore a gap. So, I left the thin test brush and gave it sky texture so it's completely invisible and everything works.

(Note: Some mappers at Doom3world reported that cloned visportal brushes can cause problems in a map. This was reported in an earlier Doom 3 build.)

== See also ==
There are other good visportal tutorials to be found under:
http://www.iddevnet.com/doom3/visportals.php and http://www.modwiki.net/wiki/Visportal

== Visportals, Func_statics and Worldspawn Brushes ==
Sometimes a visportal (VP) looks just fine in-game, but AI's behave erratically near them: cannot walk through the portal, walk into walls near the portal, can patrol through the portal but cannot chase the player through the portal. This may be due to worldspawn brushes penetrating the visportal.

Image shows scenarios A-D of different VP placement.
[[image:visportal_scenarios.png]]

*Scenario A, when VP is snugly placed in the worldspawn corridor, it always works.
*Scenario B, where a worldspawn brush penetrates the VP has often caused problems. It will fail with very high probability if the worldspawn brush is a monsterclip brush. Never do this scenario! ''[Springheel -- I'd like more confirmation on this...I'm certain I've done this on a regular basis in uneven city streets without causing any obvious problems]''
*Scenario C is what could be used if the scene absolutely requires somethings going through the VP and scenario A or D cannot be used. Usually this must be done for big outdoors VP's as seen in Knightons Manor exterior behind the manor (it is the hedge, which goes through the VP there). Note how the worldspawn brush is cut just at the VP and it is only func_static which penetrates the VP. This has worked without issues. Note that no monsterclipping is required if the func_static segment of the VP penetrating brush is short enough. The blue worldspawn brushes could also be monsterclipped func_statics as well. If so, mapper must be certain monsterclip brushes do not penetrate the VP!
*Scenario D where the VP is penetrated by func_static detail work, has not been reported to break visportals. Usually this kind of case is used in vaulted corridors etc. Works just fine. If the FS detail work is in reach of AI, special care to monsterclipping should be paid and it must be absolutely sure the monsterclip does not penetrate the VP as this will always cause trouble. In this scenario it is recommended that each side of the visportal have their own func_statics and one func_static brush should never penetrate more than one visportal.

===Conclusion===
Mappers should favour scenario A when possible. If detailwork requires, scenario D is okay, as well as scenario C. Never, ever use scenario B.

If mapper has some issues with their AI pathfinding, they should check the portal isn't broken as in scenario B. It is really easy to forget wall trims etc which could pass through the VP. Also typical mistake is to automatically surround a model near the VP with monsterclip, which results monsterclip brush which penetrates the VP. It is recommended that the mapper tests every visportal (which an AI is likely to pass) in their map before the map is released. Firstly the mapper should check in DR and make sure visportals are correctly set. Ingame testing should be done both with non-alerted path_corner patrolling AI's and with an alerted AI chasing the player.

[[Category:Skybox]]
[[Category:Visportal]]
{{tutorial-editing}}

Path Nodes

2017-08-22T14:56:56Z

Springheel: /* path_turn */

''originally written by Springheel''

For more information on pathfinding, see [[Pathfinding]]. For more general info on getting your AI to patrol, see [[AI Patrol]].

= What are Path Nodes? =

Path entities (or path nodes) are the things that you use to make your AI move (patrol) around the map. Placing path nodes can take a little getting used to; hopefully this article will help (I'm far from an expert, but here's what I've discovered so far).

There are lots of different kinds of path nodes. It can sometimes help to think of them as "travel nodes" (nodes that AI will travel to) and "behaviour nodes" (nodes that tell AI how to behave at a certain point).

Although path nodes have a directional arrow in the editor, it has no impact on most nodes. Rotating the node does add a corresponding "angle" property to the entity (matching the direction of the arrow). Certain nodes (path_anim, path_wait, and path_turn, for example) are affected by the "angle" property, but most will ignore it.

= How to use Path Nodes =

Path nodes are placed like any other entity (RMB and select "add entity", then scroll to "paths"). They show up as a coloured box with an arrow in the editor (colour varies depending on config.)

Path nodes are useless if they are not linked to another entity (either an AI or another node). In order to link them, you use the "target" property. This tells the AI what path node they should go to (or act on) next. If you type "target" "path_corner_1" in your AI property list, then your AI will walk to "path_corner_1" when the map starts. Without a "target" property, your AI will not go anywhere. Once you add a "target" property to either your AI or another node, you should see a colored line connecting the two entities.

Behaviour nodes activate behaviour in order. In other words, if you want an AI to reach a path_corner, then turn to face a direction, then wait for a time, then play an animation, you need to link the nodes in that order.

path_corner ---> path_turn ----> path_wait ----> path_cycleanim -----> next path_corner

== Variation and Randomness ==

It is also possible to target multiple nodes (using "target1", "target2" etc. spawn args). In this case, the AI will choose one of these nodes with equal probability.
If the '''"chance"''' spawn arg (between 0 and 1) is set on a node, it defines the probability for the AI to choose this path node next when multiple path nodes are targetted. The chances at any point must not add to greater than 1, or it won't work properly. For example, if a path_corner targets two different nodes, you could set "chance" ".75" on one and "chance" ".25" on the other. This will result in AI choosing the first path 3/4 of the time.

There are now two new spawnargs, '''"alert_idle_only"''' and '''"idle_only"''' that can be set on path nodes. The nodes are then only chosen when the AI is in that state. For example, if you set a path_corner as "idle_only", then the AI will no longer go to that path node when it has been alerted. This allows the mapper to set a complete set of alternate patrols and actions for AI who have been alerted (like sending them to guard important areas). (for info on how to use Objectives to alter paths, see [[Objectives#Using_Objectives_Creatively]])

''Note that if an AI reaches a node that targets pathnodes that are unavailable (because they are idle_only, and the AI is alert, for example), the AI will stop and no longer proceed.''

Nodes that make the AI walk to a specified location (currently the only one that does this is the path_corner) can have an '''"move_to_position_tolerance"''' spawn arg, which defines how close the AI has to be to the destination point to determine the position as reached. Normally, the AI considers the position reached as soon as it is inside its bounding box (most of our humanoid AI are using aas32, so the point would need to be within 16 units from the AI's origin). This is not always accurate enough, for example when a path_corner is placed in front of a chair where the AI is supposed to sit down, making the AI place half of their back next to the chair. Smaller numbers mean the AI must get closer, larger numbers are more forgiving.

[Fidcal: I believe the accuracy spawnarg is replaced by the move_to_position_tolerance above. The following likely applies to the new spawnarg anyway.]
Setting the accuracy spawn arg will change the horizontal size of the bounding box used for checking. If the accuracy is set to negative values (default is -1), the standard bounding box will be used as before.

This spawnarg is available for all entities and can also affect AIs moving towards levers or buttons.

== Triggering ==
These path nodes will trigger their targets when AI 'use' them (as of TDM v2.02):

* path_corner - triggers targets when node is reached
* path_turn - triggers targets when turn is done
* path_wait - triggers targets when wait is over
* path_sit - triggers targets when sitting anim is done, including any final turn
* path_sleep - triggers targets when lying down anim is done
* path_anim - triggers targets when anim is done

= Kinds of Path Nodes =

== path_corner ==
Probably the most common path node, this is a "travel node". AI will walk from their current position to this node in as straight a line as possible. This node must be on the ground and in an area AI can reach. See [[Pathfinding]] for more information on how to help AI go from one node to another.

To make AI patrol an area, each path_corner node can target the next one in sequence. If AI reach a node that does not target anything, they will stop there and no longer move without player interaction. It is possible for two path_corners to target each other, which means the AI will walk from one to the other and back again endlessly.

A single entity (path node or AI) can target more than one path_corner; TDM will randomly choose between the targeted nodes. Use the following syntax:

target path_corner_1
target2 path_corner_2

In the example below, both A and B are path_corner nodes. On map start, the AI will walk to A, then turn and walk to B, then stop.

[[image:pathfinding2.jpg]]

Extra note: To make an AI run on patrol add the property/value : "run" "1" to a path_corner on the AI's patrol and the AI will run to it (then resume walking after it if the next path_corner does not have that property set.)

'''Note that an AI will continue on to their next path_corner after a failed search. If you do not have at least one path_corner, the AI will return to its original position when their search is complete.'''

'''Also note that if the AI is going to stop at a path_corner--perhaps to wait a spell--the path_corner origin should be kept at least 16 horizontal units away from monsterclip and worldspawn brushes. Otherwise, the stopping animation might not look right.'''

== path_wait ==

This is a behaviour node. It does not tell an AI to move anywhere. This node tells an AI to wait in an idle state for a given amount of time. Once that time is up, the AI will proceed to whatever the next target is (a path_wait with no target is pretty pointless).

A path_wait node appears as a small orange box. It has a directional arrow, but that has no affect on which direction the AI faces in the first place. However, you can set the angle key on the path either by rotating the entity or by setting the key directly to make the AI turn and face this direction before starting to wait. '''Important:''' If the angle is 0 make sure it is actually on the entity and not just default.

A path_wait node should have a "wait" property, with the number of seconds the AI should wait there before proceeding. It can also have a "wait_max" property which will vary the repeat time. So for example...

* wait 30
* wait_max 40

...will cause the AI to wait between 30 to 40 seconds before proceeding. If wait_max is set to 0, the AI will always wait exactly the time specified in wait before proceeding. If you set wait to 0, the AI will wait between 0 seconds and the time specified in wait_max. Default values are 2 seconds for wait, and 0 seconds for wait_max, so the AI will always wait exactly 2 seconds.

In the following example, A and B are path_corners, and the small orange box is a path_wait entity. On map start, the AI will walk to A and wait there for the required amount of time, then turn and proceeds to B.

[[image:pathfinding3.jpg]]

Note that it does not matter '''where''' the path_wait node is placed. The AI does not actually follow the orange lines (this is not really intuitive, I know). The example below would cause the exact same behaviour as the example above--in both cases the AI will walk directly from A to B.

[[image:pathfinding4.jpg]]

Another useful example for path_wait is that of the stationary guard who turns to look in different directions periodically. This can be schematically represented (arrows indicate target links) as:

AI -> path_corner1 -> path_wait1 -> path_wait2 -> path_corner1

Example properties for the path_wait are:
wait: 5 (minimum time to wait on action)
wait_max: 10 (maximum time to wait on action)
angle: 0 ('''Important''': this property is essential for proper function even if the angle is 0)

The AI walks to or stands at the path_corner. The next action is to do what is indicated by the first path_wait. In this example, it tells the AI to face a particular direction for a certain period of time. This then targets a second path_wait which has the AI face a different direction for a certain period of time. To complete the cycle, the second path_wait then targets the original path_corner. The path_corners are necessary because again, the path_wait doesn't contain pathing or location information. Without the path_corner, if the AI is caused to wander (e.g. becomes alerted), it might not return to the original standing spot, and instead will do the look angles right where it stands. The path_corner assures the AI returns to its original position.

== path_turn ==

''(edit: I'm not sure why this node is useful, since path_wait can do the same thing).''

This behaviour node tells an AI to turn in place to face a chosen direction. It does not make the AI walk anywhere. This is the one node where the directional arrow does seem to matter--the AI turns to face the same direction as the arrow. Alternately, you can use the property "angle" and the values below:

* 0 = East (X)
* 90 = North (Y)
* 180 = West (-X)
* 270 = South (-Y)
* 360 = East(X)

(Actually, to be more accurate, rotating the entity automatically adds the "angle" property to the entity. If you just leave the arrow facing the way it is when you create the entity, there will be no "angle" property, and therefore the AI will not turn.)

Adding a "wait" spawnarg to this node doesn't seem to do anything.

== path_anim ==

This is a behaviour node that makes the AI play an animation, once. When that animation is done, it proceeds to the next target (if any). This could be used to make an AI walk over to a bookshelf and play a 'reaching out' animation, for example. Other possibilities include peering through a window, picking a carrot off a table and eating it, or running to a spot and cowering.

The syntax proper syntax is:

anim [animation name]

You can see the list of animations names here: [[Animation List]]. Do not use the name of the actual animation file.

A path_anim can have only one animation, but it is possible for a single entity to target more than one path_anim. The AI will pick one of the path_anim nodes at random and play that animation.

When you first create the path_anim entity, the directional arrow is meaningless. However, if you rotate the entity, the "angle" property is added to the entity and is updated based on which direction the arrow is pointing. That property indicates the direction the AI will face while playing the animation. '''This value appears to be necessary to make the animation work.'''

Tip: Animation blending doesn't seem to do very much, so AI often "snap" into position from walking to playing the animation. For a more natural look, add a path_wait of a few seconds first, so AI transition to their idle pose before playing the animation.

== path_lookat ==

This does not stop the AI, but they will turn their head and look somewhere specific as they walk to their next target. For the next ''wait'' seconds, turn head to look at the entity given by the ''focus'' spawnarg (defaults to looking at the path_lookat entity itself). This is useful if you want to make sure an AI is looking at a specific spot (or away from a certain spot) during their patrol. Note the focus entity must not be obscured by monsterclip.

== path_sit ==

This is a behaviour node that makes the AI sit down at its current location. See [[Sitting Behaviour for AI]] for more information.

== path_waitfortrigger ==

Waits at a given place until triggered, then proceeds to the next target. This is useful if you want some control over exactly where the AI is when the players first see it.

The "path_waitfortrigger" basically operates like a wall, blocking the AI from proceeding until triggered.

Here are the steps for future reference. Let's say you want an AI to stand somewhere until a player triggers him, then you want him to walk to path_corner 1.

1. Make a "path_waitfortrigger" pathnode, and have it target "path_corner_1".

2. Have the AI target the "path_waitfortrigger" pathnode.

3. Create a trigger_once entity, and target the AI.

The AI will stand where they are at map start and behave as if there are no pathnodes set (ie, he plays idle animations and can be alerted). When the player goes through the trigger, the "path_waitfortrigger" is cleared and the AI will proceed to path_corner_1.

== path_interact ==

This lets the AI interact with an entity (for example a button) in a similar way to frobbing. This will only work for buttons etc, not for inventory items and moveables. The AI will stop and look at the entiy while interacting, but not walk to it, so a path_corner next to the entity is required. AI will use normal doors and elevators without needing a path_interact. However, this could be used to make AI turn on lightswitches, open mechanical doors, etc.

You need to add these spawnargs to the path_interact entity:

ent <name of entity to be frobbed by AI>

target <next path entity (if any)>

= How to Make AI do Random Interesting Things (RIT) =

''by Sotha''

You can use the above to make individual AI seem to do Random Interesting Things (RIT) when entering a room. Note that it will work with basic dendritic AI, so you could have multiple AI's running in several rooms doing things.

1) Build a room with RITs. A statue. A few chairs. Maybe a lit fireplace.

2) On each RIT place the necessary interaction path_nodes to make an AI interact with them: path_corner to walk over to them; path_sit on each of the chairs, path_anims for warming hands at the fireplace and standing in front of the statue and pondering, etc (A, B & C in image).

3) Place two path_waits (1 & 2 in image) on the ceiling of the room. (They could be anywhere in the room, but it is easiest to manage if they are in the ceiling.)

4) Name one of the path_waits "enter_room_decide_what_to_do." (1) From that path_wait target each of the RIT path_corners. Set the path_wait "wait 0". so AI won't stop there. The idea is to use the path_wait as a simple decision making node. Be sure that the path_wait has no angle-spawnarg. If it does, the AI will turn towards the angle each time he targets the node.

5) Name the other path_wait "exit_room_decide_what_to_do." (2) Make each RIT final path_node target this path_wait. Make the path_wait target other rooms with similar decision making path_waits.

6) Done.

[[Image:Rits.jpg]]

AI will come into the room, select A, B or C at random, and then leave. Next time they enter, they'll again pick at random.

This could be used to make servants to run around a mansion, cleaning, making food, taking sitting breaks, visit the toilet, etc. You could build room decision making network separately for different AI. Servants clean, cook and take breaks. Guards patrol, make random deviations once in a while, and of course take breaks. Controlling the RIT path_corner chance-spawnarg gives you control what RITs the AI do more likely.

Please see the dedicated RIT network article for more details. [[RIT Networks]]

= Switching from one Path network to another =

Suppose you want to have an AI patrol outside a mansion for the first part of a mission, and then change his route to patrol in another location later?

It is possible to change the "target" property on a path_corner by using ''atdm:target_changetarget.''

Target the atdm:target_changetarget entity at the pathnode you wish to alter. Use the following spawnargs:

"add" "[new path_corner]"
and/or
"remove" "[old path_corner]"

Then add a trigger that targets the atdm:target_changetarget.

When triggered, the new path_corner will be added and the old removed, sending the AI to a new path network. This no doubt has vast potential for variation and creativity that has yet to be explored. One simple example would be a "changing of the guard" moment, where some guards leave their posts and go to their barracks to sleep, while others take over for them.

'''Other ideas:'''

'''Doormen'''-- An AI (or the player) walks up to the door and knocks on it. AI inside is triggered to walk over to the door and open it, then go back to his regular duties.

'''Abandon ship!''' -- When triggered, all AI drop what they're doing and start running for the exits.

'''Lights out!''' -- At a specific time, all AI stop what they're doing and walk to their beds to go to sleep.

'''Re-use, recycle''' -- AI that are stuck back in a portion of the map the player won't be coming back to could be told to walk to a new portion of the map and assume some job there.

It''''s a trap!''' -- Player walks down a hall and hits a trigger that causes AI to quickly position themselves at the only exits.

= Flee Points =

Do NOT target the AI to a flee point; AI will automatically go to a flee point if in danger. Just make available path_flee_point entities at suitable places where you would like your AI to flee to.

On the path_flee_point entity:

"is_guarded", a fleeing AI, eg, a civilian, would give this preference (but it is up to the mapper to actually provide a guard there.)

"team", only AI on this team would use this flee point, also required for "friendly" flee points per below.

This is how the code works:
* The AI tries to determine the nearest friendly (their team specified) guarded flee point and flee to it.
* If there is no friendly guarded flee point, the AI tries to find the nearest friendly flee point (on friendly team) and run to it.
* If this also fails, the AI tries to find an AAS area far from the enemy and run there.
* If the enemy is still visible when the AI reaches his destination, he chooses the farthest friendly guarded flee point to run to,
* if this fails, the farthest friendly flee point,
* and if this also fails falls back to choosing an AAS area far from the enemy to run to.
* So neither the priority nor the target spawn arg have any function here, it is not possible to weight the flee points. The AI will choose one automatically.

A problem occurs when the AI doesn't find any appropriate flee points but also no AAS area that is far away enough from the enemy. In this case, he will just stand there. Maybe he should either cower and be afraid in this case or just run around like a mad chicken?

Whether a fleeing AI passes on info to other AI as to the source of their alert (ie so armed guard would go to investigate to the right place whereas another civilian might also flee to the farthest point.)
Yes, they do. The cry for help bark is propagated to other AI and carries information about the last alert position.

Armed AI will also flee if their health points drop to a certain level? Where is that determined?
This is determined by the health_critical spawn arg.

= Untested Nodes =

I have not personally tested the following, so I'm just going by their editor descriptions. They may or may not work as described.

== path_cycleanim ==

The AI stays in place and loops the selected animation, either for a specified amount of time (using the 'wait' property) or until triggered. Syntax needed.

== path_hide ==

Supposedly deactivates and stops rendering the AI.

Turns out this doesn't work well with TDM...makes AI invisible but they still talk and occupy space. To remove an AI from the map, try grayman's approach:

Create a [b]func_remove[/b] with this spawnarg:

"target" "<AI's name>"

At the point in his path where you want him to disappear, place a [b]trigger_once_entityname[/b] with these spawnargs:

"entityname" "<AI's name>"
"target" "<func_remove's name>"

When the AI walks through the [b]trigger_once_entityname[/b], it recognizes him, triggers the [b]func_remove[/b], and that takes the AI out of the game.

I wrapped the AI's final path corner in a trigger_once_entityname and gave the trigger the keyword pair "entityname <AI_name>". (The docs don't tell you about this key, but the game will error out if it's not there, and tell you it's missing. A classic "trial by error".)

== path_show ==

Starts rendering the AI. I would assume this one would be linked to a path_waitfortrigger, to create AI that spawn when triggered. This could be used to create the effect that an AI just came through a doorway or around a corner.

== path_attack ==

Used to script AI attacking a particular enemy, for scripted sequences I guess. AI will continue on to the next path entity if it kills the enemy.

Questions: How do you define who the AI attacks?

[Fidcal]: Just found this - "Character will attack the character specified by 'enemy' key. Character will go to next path when enemy dies or when activated." Not tested.

{{tutorial-editing}}