Particle collisions and cutoff - Revision history

Stgatilov: Added section about particle models.

2020-12-09T16:46:06Z

Added section about particle models.

← Older revision		Revision as of 16:46, 9 December 2020
Line 141:		Line 141:
	=== Texture layout ===		=== Texture layout ===

	We will consider rain as an example.		This mode was the only available in TDM 2.08. We will consider rain as an example.

	Copy particle definition <tt>tdm_rain2_heavy</tt> from <tt>particles/tdm_weather2.prt</tt> file into your FM. Then add the following keywords:		Copy particle definition <tt>tdm_rain2_heavy</tt> from <tt>particles/tdm_weather2.prt</tt> file into your FM. Then add the following keywords:
Line 167:		Line 167:
	=== Linear layout ===		=== Linear layout ===

	We will consider snow as an example.		This mode was added in TDM 2.09. We will consider snow as an example.

	Copy particle definition <tt>tdm_snow_moderate</tt> from <tt>particles/tdm_weather.prt</tt> file into your FM. Then add the following keywords into every particle stage:		Copy particle definition <tt>tdm_snow_moderate</tt> from <tt>particles/tdm_weather.prt</tt> file into your FM. Then add the following keywords into every particle stage:
Line 192:		Line 192:

	Unlike texture layout, the linear layout mode is rather unstable. If you change some parameters in particle definition even slightly, the old cutoff texture won't work anymore.		Unlike texture layout, the linear layout mode is rather unstable. If you change some parameters in particle definition even slightly, the old cutoff texture won't work anymore.



			== Particle models ==

			Everything described above applies only to surface emitters, i.e. patches/brushes with a material with "particle deform" applied to it. Starting from TDM 2.09, collisions are partly supported for more popular "particle models" too. Only '''mapLayout linear''' makes sense in this case.

			However, there are many limitations for particle models (see also [https://bugs.thedarkmod.com/view.php?id=5437 #5437]):

			* Only particle models explicitly listed in .map file work. So there must be a map entity with "model" spawnarg having "XXX.prt" value. Particle models inside def_attach-ed entities are ignored.
			* Entity with several models pointing to same .prt don't work (like chandeliers).
			* If entity's diversity is randomized by some in-game code, then precomputed collisions won't match. Randomization is done at least for func_emitter-s and in light scripts.

			It is not yet clear how this area would develop in future.


Line 223:		Line 237:
	With '''mapLayout linear''', quite a lot of precomputation can be needed. Check the math above. Note that '''count''' value in particle definition defines number of emitter particle per 64x64 square, so for a large emitter total the number of particles N is much larger.		With '''mapLayout linear''', quite a lot of precomputation can be needed. Check the math above. Note that '''count''' value in particle definition defines number of emitter particle per 64x64 square, so for a large emitter total the number of particles N is much larger.
	You might want to disable collisionStatic and see how it works/looks, after that set minimum values of count, diversityPeriod, and collisionStaticTimeSteps. From there, increase them slightly as needed.		You might want to disable collisionStatic and see how it works/looks, after that set minimum values of count, diversityPeriod, and collisionStaticTimeSteps. From there, increase them slightly as needed.

			* Collisions don't work with '''mapLayout linear''', particle pass through.

			As explained in linear-layout section, this mode is quite unstable. Any difference between the situation during precomputation and during gameplay may result in cutoff texture mismatch. Make sure you have done dmap and runParticle properly, and if it does not help, ask for investigation on forums. If this is "particle model", then also read appropriate section about limitations.

	* Rain disappears under some viewing angles (old TDM).		* Rain disappears under some viewing angles (old TDM).
Line 239:		Line 257:

	* Animate to different material after cutoff, which would allow to generate splashes from rain.		* Animate to different material after cutoff, which would allow to generate splashes from rain.
			* Full support for particle models, including attachments, func_emitters, etc.


	== References ==		== References ==

	You can download a sample test map with collision-aware rain [https://thedarkmod.blob.core.windows.net/various/wiki_rain_testcollision/test_raincollision.zip here].		You can download a sample test map with collision-aware rain and snow [https://thedarkmod.blob.core.windows.net/various/wiki_rain_testcollision/test_raincollision.zip here].

	Related threads on developers-only forums:		Related threads on developers-only forums:

Stgatilov: Filled mapLayout linear section.

2020-12-09T16:29:36Z

Filled mapLayout linear section.

@@ Line 145: / Line 145: @@
 Copy particle definition <tt>tdm_rain2_heavy</tt> from <tt>particles/tdm_weather2.prt</tt> file into your FM. Then add the following keywords:
 * '''collisionStatic''': says that the particles should stop on collisions with static objects.
-* '''mapLayout texture {W} {H}''': specifies how cutoff would be applied, and resolution of the cutoff texture.
+* '''mapLayout texture {W} {H}''': specifies that cutoff is applied by texcoords, and sets resolution of the cutoff texture.
 The texture resolution affects how precise collisions would be depending on spawn location. For instance, if you apply one 1000 x 1000 rain-emitting patch over the whole map of size 3000 x 3000, then all particles emitted 3 length units from each other will stop at the same height. Such precision is more than enough for rain. If you create small patches for something more localized, better use lower resolution to avoid wasted storage and performance consequences.
@@ Line 164: / Line 165: @@
-== Linear layout ==
+=== Linear layout ===
@@ Line 192: / Line 218: @@
 This [https://forums.thedarkmod.com/index.php?/topic/20291-beta-testing-208/&do=findComment&comment=447846 happens] if the material of the water surface does not have the "water" contents/keyword.
 A surface is allowed to block particles only if it has either "solid" or "water" content flag, other materials never block particles.
 * Rain disappears under some viewing angles (old TDM).

Stgatilov: Reworking collisionStatic section and FAQ, preparing for mapLayout linear subsection.

2020-12-09T15:50:54Z

Reworking collisionStatic section and FAQ, preparing for mapLayout linear subsection.

Show changes

Stgatilov: Added linear layout section (to be filled later).

2020-12-09T14:58:27Z

Added linear layout section (to be filled later).

← Older revision		Revision as of 14:58, 9 December 2020
Line 153:		Line 153:

	Aside from that, you can add '''collisionStaticWorldOnly''' keyword to particle definition file: in this case only world geometry (brushes and patches) will be considered blockers.		Aside from that, you can add '''collisionStaticWorldOnly''' keyword to particle definition file: in this case only world geometry (brushes and patches) will be considered blockers.



			== Linear layout ==

Stgatilov: Added possible issue with water surface

2020-06-01T11:26:05Z

Added possible issue with water surface

← Older revision		Revision as of 11:26, 1 June 2020
Line 177:		Line 177:

	Check that emitting patch is facing the right direction: it should be visible in DR from the side where particles go to. Also, try <tt>r_showTris 1</tt> to be sure that they are not invisible.		Check that emitting patch is facing the right direction: it should be visible in DR from the side where particles go to. Also, try <tt>r_showTris 1</tt> to be sure that they are not invisible.

			* Rain falls through water, even with '''particle_collision_static_blocker 1'''.

			This [https://forums.thedarkmod.com/index.php?/topic/20291-beta-testing-208/&do=findComment&comment=447846 happens] if the material of the water surface does not have the "water" contents/keyword.
			A surface is allowed to block particles only if it has either "solid" or "water" content flag, other materials never block particles.

	* '''cutoffTimeMap''' does not work.		* '''cutoffTimeMap''' does not work.

Stgatilov: Added reference to test map.

2020-03-08T15:20:42Z

Added reference to test map.

← Older revision		Revision as of 15:20, 8 March 2020
Line 194:		Line 194:
	== References ==		== References ==

	sample FM:		You can download a sample test map with collision-aware rain [https://thedarkmod.blob.core.windows.net/various/wiki_rain_testcollision/test_raincollision.zip here].

	Related threads on developers-only forums:		Related threads on developers-only forums:

Stgatilov: First version

2020-03-08T15:17:53Z

First version

New page

This article describes the collision and cutoff features of particle systems, introduced in TDM 2.08.
If you want to know what various particle keywords mean, please read [[Particle Editor]] article.

== Particle lifetime cutoff ==

The whole feature relies on the idea of lifetime "cutoff".

Normally, every emitted particle lives for the duration specified by '''time''' keyword in the particle stage declaration.
Different particle are emitted at different time moments (controlled by '''bunching''' keyword), but every particle lives for the same time.
A particle can go through various transformations during its lifetime, including fading in and out, animations, shape and color changes, etc.

This feature introduces an additional event in particle lifetime called ''cutoff''. A particle is no longer rendered after the cutoff moment.
Most importantly, this cutoff moment is specified by cutoff texture and varies among particles. This flexibility allows to bake collisions with static objects into the texture.

== Overview ==

Here are all the necessary bits:

* surface used as emitter in .map
* particle-emitting material in .mtr
* particle effect definition in .prt
* cutoff texture (not needed with collisionStatic)

== Specify cutoff texture manually ==

One approach is to specify cutoff texture manually.
Note that you should never do this if you simply want particles to stop at collisions: use '''collisionStatic''' keyword instead!
However, this would serve as a good warmup before the next section.
Besides, this way can be used to set cutoff for some artistic reasons not related to collisions.

First of all, draw a particle-emitting surface in DarkRadiant. It can be either a patch or a brush with 5 nodraw sides.

In most cases the emitting surface must have [0..1] x [0..1] texture coordinates. So select the created surface (i.e. the patch or single side of the brush), open Surface Inspector, and click on Fit button on <tt>Fix Texture: 1.00 x 1.00</tt> line.

Now it remains only to apply a particle-emitting material to this surface, but we have to create it first. Please look into <tt>materials/tdm_weather2.mtr</tt> file for an example of particle-emitting material:

textures/darkmod/weather/rain2_heavy
{
deform particle tdm_rain2_heavy
qer_editorimage textures/editor/rain
nonsolid
noshadows
{ //needed to emit particles
blend filter
map _white
}
}

Copy this definition into your own material and rename to something customized to avoid confusion in future. Note that the first line references a particle definition, which we have not created yet.

'''IMPORTANT:''' Use <tt>deform particle</tt> and never <tt>deform particle2</tt>, since the latter does not ensure uniform particle distribution across the surface!

The next step is to create a particle definition.
Open <tt>particles/tdm_weather2.prt</tt> file, and copy <tt>tdm_rain2_heavy</tt> particle definition from it into some .prt file in your FM. Better rename the copied particle definition to something custom to avoid confusion.

particle tdm_rain2_heavy {
{
count 10
material textures/particles/drop2
time 0.500
cycles 0.000
bunching 1.000
distribution rect 0.000 0.000 0.000
direction cone "0.000"
orientation aimed 0.000 0.040
speed "1000.000"
size "0.500"
aspect "1.000"
randomDistribution 0.000
fadeIn 0.200
fadeOut 0.000
color 0.040 0.040 0.040 1.000
fadeColor 0.000 0.000 0.000 1.000
offset 0.000 0.000 0.000
gravity 0.000
}
}

'''IMPORTANT:''' Ensure that your particle stage has no additional randomization of spawn location, i.e. it contains the exact line: <tt>distribution rect 0.000 0.000 0.000</tt> (the aforementioned rain2 definitions are already OK). Otherwise you will have hard time understanding what happens.

In order to attach cutoff texture, you have to add two keywords to particle stage:
* '''cutoffTimeMap {path/to/texture/image.tga}''': specifies which texture to use as cutoff.
* '''mapLayout texture {W} {H}''': specifies how the texture should be applied. '''{W}''' and '''{H}''' must equal width and height of the texture.

Here is an example of added keywords:

cutoffTimeMap textures/cutoff/shapedrain.tga
mapLayout texture 256 128

Lastly, draw the cutoff texture itself. This texture would be stretched onto the particle-emitting surface, and the color at each point would define the cutoff moment for all particles emitted from it.

More precisely, the color defines which ratio of the lifetime a particle lives before cutoff. If you set full-black color, then particle will die immediately after spawning, you won't see it. If you set full-white color, then particle will live through its whole lifetime without cutoff. Middle-gray color (128 128 128) will make particles disappear after they live through half of their lifetime.

For the purpose of creating manual cutoff textures, only red channel of the texture matters. The green and blue channels are used for additional precision beyond 8 bits.

For a tutorial, you might want to start with some simple black-and-white image and check how it affects the particle system in-game, then continue to some grayscale texture.

== Auto-generate cutoff texture from collisions ==

Now that you understand how cutoff texture works, let's see how it can be auto-generated in order to stop particles on collisions. We will consider rain as an example.

Once again, copy particle definition <tt>tdm_rain2_heavy</tt> from <tt>particles/tdm_weather2.prt</tt> file into your FM. Then add the following keywords:
* '''collisionStatic''': says that the particles should stop on collisions with static objects.
* '''mapLayout texture {W} {H}''': specifies how cutoff would be applied, and resolution of the cutoff texture.

The texture resolution affects how precise collisions would be depending on spawn location. For instance, if you apply one 1000 x 1000 rain-emitting patch over the whole map of size 3000 x 3000, then all particles emitted 3 length units from each other will stop at the same height. Such precision is more than enough for rain. If you create small patches for something more localized, better use lower resolution to avoid wasted storage and performance consequences.

The '''collisionStatic''' keyword currently imposes many restrictions on the particle definition. The <tt>tdm_rain2_XXX</tt> definitions adhere to all these restrictions. Here are they for the reference:
* '''distribution rect 0 0 0''', i.e. no additional randomization of spawn location
* '''direction cone 0''' and '''gravity 0''', so that all particles travel along parallel lines
* '''speed''' must be constant (for now)
* '''worldAxis''' is forbidden

However, the '''collisionStatic''' is not enough on its own, it only marks the particle system as using collision detection. In order to compute the cutoff maps, you must run the '''runParticle''' compiler tool in the game engine. This tool is very similar to '''dmap''' in nature and usage. Here are the steps:
# '''dmap {mapname}''' --- makes sure your .proc file is correct, since runParticle uses it.
# '''runParticle {mapname}''' --- computes the cutoff maps for all '''collisionStatic''' particle systems in the map.

All the generated textures will be saved into <tt>textures/_prt_gen/</tt> directory.

'''IMPORTANT''': Never store anything important there! runParticle starts with clearing this directory every time you run it.

The texture filename is composed of the name of the model in .proc file (which is either world area or entity), the index of the surface in the model, and the index of the particle stage in the particle definition file.

If you decide to inspect these maps, better mask off green and blue channels in your image viewer, and look only at the red channel, since it contains the high bits of the cutoff ratio.

One important rule for collisionStatic is that different locations on the surface emitter must have different texture coordinates. The tool will throw error if it detects that several locations have same texture coordinates, since it cannot write two values into one texel.

On the other hand, it is perfectly normal if some parts of the cutoff texture are not used by the emitter. Given that dmap carves away some parts of the patch which are inside opaque brushes, this happens almost always. The generated texture has all-zero color at such unused locations, including zero alpha channel.

Another interesting fact is that dmap splits a patch which spans over several areas. In a typical usage scenario, mapper applies a single huge rain-emitting patch over the whole map, and this patch gets splitted into many pieces: one piece per every area it covers. A separate texture is generated for every piece.
It is worth noting that runParticle computes minimum bounding rectangle of all the used texels and does not save anything outside of it. So don't be surprised that texture resolution for those pieces is much lower than the resolution you specified: you set resolution for the whole [0..1] x [0..1] region.

The optimization mentioned above can be used to create non-rectangular surface emitters. Let's suppose that you have a map with a very tall building in the center, and outdoors area surrounding it. If you create one rain patch crossing the building, then rain would go inside building. To fix this, you can use CSG/boolean operation to subtract a rectangular region from the patch (well, I'm afraid DR cannot do this, so consider it a mind experiment). The remaining region would consist of many patches with various texcoords rectangles, but everything would work normally, and the effective cutoff texture resolution would remain the same.

The runParticle tool takes everything which looks like static (i.e. never moves or disappears) and solid (e.g. not a light flare) geometry and considers them blockers. In reality, it is quite hard to reliably distinguish static geometry. While the tool has some complicated ruled built in, in some cases it might be necessary for tweak something manually. Of course, better keep such tweaking at minimum level.

There are two entity spawnargs which override automatic decisions:
* '''particle_collision_static_blocker {0 or 1}''': consider this entity a blocker / not a blocker for particle collision computations.
* '''particle_collision_static_emitter {0 or 1}''': compute collisions for particle-emitting surfaces of this entity / don't compute them.

Aside from that, you can add '''collisionStaticWorldOnly''' keyword to particle definition file: in this case only world geometry (brushes and patches) will be considered blockers.

== Troubleshooting ==

* '''runParticle''' complains about overlapping texcoords.

Check if you really have this problem, and fix it if you have. If you are sure that there is no such problem, then it might happen due to precision issues or dmap mesh optimization glitches. Please report it on forums.

* Generated textures have missing triangles.

Such errors happened on first implementations, caused by dmap issues. They resulted in triangular zones without rain, which can be detected in-game using <tt>r_showTris 1</tt>. Also, they are easy to see in generated textures, since dropped triangles have zero color and alpha.
If you have some problems, report them on forums.

* Rain does not reach ground, i.e. stops before collision.

The '''collisionStatic''' feature allows to hide particles prematurely, but cannot extend their lifetime. If rain does not reach ground, then you have to increase '''time''' keyword in particle definition. Keep in mind that increasing lifetime in K times effectively decreases particle density in K times, so you might need increasing '''count''' too.

* Rain disappears under some viewing angles.

This is the bug in bounding box computation of particle systems. I hope to fix it soon ([https://bugs.thedarkmod.com/view.php?id=5136 #5136]). For now, you might hack around the problem by setting a large '''boundsExpansion''' value to particle definition. Estimate the maximum size of your particle system and set this value --- that should be enough to avoid particle system being wrongly culled away.

* Cannot see any particles.

Check that emitting patch is facing the right direction: it should be visible in DR from the side where particles go to. Also, try <tt>r_showTris 1</tt> to be sure that they are not invisible.

* '''cutoffTimeMap''' does not work.

It seems that '''cutoffTimeMap''' does not work yet with '''com_smp 1''' (Multi Core Enhancement). Hope to fix it in future ([https://bugs.thedarkmod.com/view.php?id=5141 #5141]). Note that collisionStatic does not suffer from this problem.

== Possible future improvements ==

The following extensions are planned for future:

* '''mapLayout linear''': different texture generation technique which would support all particles, even ones with random and curves paths.
* Animate to different material after cutoff, which would allow to generate splashes from rain.

== References ==

sample FM:

Related threads on developers-only forums:
* https://forums.thedarkmod.com/index.php?/topic/20235-proposal-for-particle-collision
* https://forums.thedarkmod.com/index.php?/topic/20244-5139-renew-particle-declarations-for-rain/

[[Category:Editing]][[Category:Tutorial]][[Category:Particles]]