World Particle System - Revision history

SteveL: update other parts of article for func_smoke

2015-03-17T23:29:44Z

update other parts of article for func_smoke

← Older revision		Revision as of 23:29, 17 March 2015
Line 1:		Line 1:
	The world particle system allows particles to exist in the world independent of any emitter entity. It enables effects like trailing smoke where the emitted smoke rises naturally instead of moving with the emitter, as well as fine-grained control of the emission of individual particle quads.		The world particle system allows particles to exist in the world independent of any emitter entity. It enables effects like trailing smoke where the emitted smoke rises naturally instead of moving with the emitter, as well as fine-grained control of the emission of individual particle quads.

	~~In TDM 2.03, the world particle system is usable only via scripting. We plan to add more user-friendly methods for mappers in 2.04, as well as to add it to some stock entities.~~		TDM 2.03 supports 3 particle systems: weather patches, that emit particles like rain or snow from a wide surface; func_emitters, entities that emit particles from a point; and the world particle system that's controlled by func_smokes and scripts. If you want a particle effect to be emitted from a stationary spot, use a func_emitter or a weather patch. If you want a particle that should always move with its emitter, for example a lamp glare, use a func_emitter bound to the light source. World particles are for effects that once released take their own path independent of the movement of any emitter, like trailing smoke, or for effects where you need fine-grained control of the release of individual particle quads.

	TDM 2.03 supports 3 particle systems: weather patches, that emit particles like rain or snow from a wide surface; func_emitters, entities that emit particles from a point; and the world particle system that's controlled by scripts. If you want a particle effect to be emitted from a stationary spot, use a func_emitter or a weather patch. If you want a particle that should always move with its emitter, for example a lamp glare, use a func_emitter bound to the light source. World particles are for effects that once released take their own path independent of the movement of any emitter, like trailing smoke, or for effects where you need fine-grained control of the release of individual particle quads.

	==Usage==		==Usage==

SteveL: rv "not available until TDM 2.03"

2015-03-17T23:28:06Z

rv "not available until TDM 2.03"

← Older revision		Revision as of 23:28, 17 March 2015
Line 1:		Line 1:
	~~:''This article describes a feature that will become available in TDM 2.03.''~~

	The world particle system allows particles to exist in the world independent of any emitter entity. It enables effects like trailing smoke where the emitted smoke rises naturally instead of moving with the emitter, as well as fine-grained control of the emission of individual particle quads.		The world particle system allows particles to exist in the world independent of any emitter entity. It enables effects like trailing smoke where the emitted smoke rises naturally instead of moving with the emitter, as well as fine-grained control of the emission of individual particle quads.

SteveL: /* Usage */ + func_smoke

2015-03-17T23:27:20Z

Usage: + func_smoke

← Older revision		Revision as of 23:27, 17 March 2015
Line 8:		Line 8:

	==Usage==		==Usage==
	Script event sys.emitParticle is used for ~~all~~ world particle system emissions.
			===Func_smoke===
			Func_smoke entities use the world particle system. Use them like a func_emitter, except that the particle effect is specified by the "smoke" spawnarg instead of "model".

			Func_smokes can be triggered on and off like func_emitters. They also support the "start_off" spawnarg.

			If bound to a moving object, func_smokes will leave their particles trailing behind them. The two flasks in the video are bound to rotating gears and have the same particle attached (mcu_lilpipesmoke.prt): the left one uses a func_emitter, the right one a func_smoke.

			[https://youtu.be/B_PQ5TO3VE4 Video demo of the difference]

			===Scripting===
			Script event sys.emitParticle is used for world particle system emissions.

	From the script reference:		From the script reference:
Line 30:		Line 41:
	The script event is designed to be called every frame if you want to achieve "normal" particle emission as specified in the particle decl. It needs to be given a start time, which it uses to determine whether it should emit a quad or not right now.		The script event is designed to be called every frame if you want to achieve "normal" particle emission as specified in the particle decl. It needs to be given a start time, which it uses to determine whether it should emit a quad or not right now.

	===Single quad emission===		====Single quad emission====
	Calling emitParticle with the current time -- sys.getTime() -- as the startTime parameter will always emit a quad, the first that would be emitted by the specified particle effect. That's because particle effects always emit their first quad as soon as they start up no matter what timing is specified in the particle decl.		Calling emitParticle with the current time -- sys.getTime() -- as the startTime parameter will always emit a quad, the first that would be emitted by the specified particle effect. That's because particle effects always emit their first quad as soon as they start up no matter what timing is specified in the particle decl.

	==="Natural" timing===		===="Natural" timing====
	To make sys.emitParticle emit particle quads just like a ~~func_emitter would~~, using the timings specified in the particle decl, call it with the same "startTime" every frame. Typically your script will start with the current time, and store that time so that you can pass the same time in every frame. Your code will continue doing that until emitParticle returns false (0), meaning that all quads for the particle effect have now been released:		To make sys.emitParticle emit particle quads just like a func_smoke does, using the timings specified in the particle decl, call it with the same "startTime" every frame. Typically your script will start with the current time, and store that time so that you can pass the same time in every frame. Your code will continue doing that until emitParticle returns false (0), meaning that all quads for the particle effect have now been released:

	<tt>float starttime = sys.getTime();</tt>		<tt>float starttime = sys.getTime();</tt>
Line 47:		Line 58:
	For example, if you are using a particle effect that emits one quad every second, and you call sys.emitParticle every frame, i.e. 60 times per second, then it will emit 1 particle every 60th call. The 59 calls in between will not emit anything.		For example, if you are using a particle effect that emits one quad every second, and you call sys.emitParticle every frame, i.e. 60 times per second, then it will emit 1 particle every 60th call. The 59 calls in between will not emit anything.

	Unlike func_emitters, emitParticle does not support cycling particle effects. If you want your emissions to carry on forever, you have to repeat the above instructions for ever in your script, e.g:		Unlike func_emitters and func_smokes, emitParticle does not support cycling particle effects. If you want your emissions to carry on forever, you have to repeat the above instructions for ever in your script, e.g:

	<tt>while (1) // cycle for ever</tt>		<tt>while (1) // cycle for ever</tt>

SteveL: /* "Natural" timing */

2015-01-11T22:21:36Z

"Natural" timing

← Older revision		Revision as of 22:21, 11 January 2015
Line 45:		Line 45:
	<tt>}</tt>		<tt>}</tt>

	For example, if you are using a particle effect that emits one quad every second, and you call sys.~~EmitParticle~~ every frame, i.e. 60 times per second, then it will emit 1 particle every 60th call. The 59 calls in between will not emit anything.		For example, if you are using a particle effect that emits one quad every second, and you call sys.emitParticle every frame, i.e. 60 times per second, then it will emit 1 particle every 60th call. The 59 calls in between will not emit anything.

	Unlike func_emitters, emitParticle does not support cycling particle effects. If you want your emissions to carry on forever, you have to repeat the above instructions for ever in your script, e.g:		Unlike func_emitters, emitParticle does not support cycling particle effects. If you want your emissions to carry on forever, you have to repeat the above instructions for ever in your script, e.g:

SteveL: /* Usage */

2015-01-11T22:19:02Z

Usage

← Older revision		Revision as of 22:19, 11 January 2015
Line 8:		Line 8:

	==Usage==		==Usage==
	Script event sys.~~EmitParticle~~ is used for all world particle system emissions.		Script event sys.emitParticle is used for all world particle system emissions.

	From the script reference:		From the script reference:

SteveL: /* Performance considerations */

2015-01-11T22:04:41Z

Performance considerations

← Older revision		Revision as of 22:04, 11 January 2015
Line 88:		Line 88:
	On the other hand, world particles enjoy some performance advantages over other types of particle. Weather patches and func_emitters each generate their own individual draw call every frame that they are in view. If you have two smoking torches next to one another, that's 2 draw calls each frame for the smoke.		On the other hand, world particles enjoy some performance advantages over other types of particle. Weather patches and func_emitters each generate their own individual draw call every frame that they are in view. If you have two smoking torches next to one another, that's 2 draw calls each frame for the smoke.

	All world particles ~~that use~~ the same ~~texture~~ will be drawn in a single draw call, no matter how spread out they are in the map. So adding more world smoke emitters will increase calculations a bit, but it won't add more draw calls.		All world particles of the same kind will be drawn in a single draw call, no matter how spread out they are in the map. So adding more world smoke emitters will increase calculations a bit, but it won't add more draw calls.

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

SteveL: /* Usage */

2015-01-11T22:01:18Z

Usage

← Older revision		Revision as of 22:01, 11 January 2015
Line 24:		Line 24:
	</blockquote>		</blockquote>

	"origin" is where the quad will be released from. You can use an entity origin as reference: using $player1.getOrigin(), for example, will emit the quad from between the player's feet. Using $guard2.getEyePos() will emit it from ~~the~~ guard2's eyes.		"origin" is where the quad will be released from. You can use an entity origin as reference: using $player1.getOrigin(), for example, will emit the quad from between the player's feet. Using $guard2.getEyePos() will emit it from guard2's eyes.

	Once you have emitted a particle quad, you have no further control over it. It will go its own way according to the path specified in the [[Particle_Editor\|particle decl]].		Once you have emitted a particle quad, you have no further control over it. It will go its own way according to the path specified in the [[Particle_Editor\|particle decl]].

SteveL at 21:59, 11 January 2015

2015-01-11T21:59:31Z

← Older revision		Revision as of 21:59, 11 January 2015
Line 5:		Line 5:
	In TDM 2.03, the world particle system is usable only via scripting. We plan to add more user-friendly methods for mappers in 2.04, as well as to add it to some stock entities.		In TDM 2.03, the world particle system is usable only via scripting. We plan to add more user-friendly methods for mappers in 2.04, as well as to add it to some stock entities.

	TDM 2.03 supports 3 particle systems: weather patches, that emit particles like rain or snow from a wide surface; func_emitters, entities that emit particles from a point; and the world particle system that's controlled by scripts. If you want a particle effect to be emitted from a stationary spot, use a func_emitter or a weather patch. If you want a particle that should always move with its emitter, for example a lamp glare, use a func_emitter bound to the light source. World particles are for effects that once released take their own path independent of the movement of ~~the~~ emitter, like trailing smoke, or for effects where you need fine-grained control of the release of individual particle quads.		TDM 2.03 supports 3 particle systems: weather patches, that emit particles like rain or snow from a wide surface; func_emitters, entities that emit particles from a point; and the world particle system that's controlled by scripts. If you want a particle effect to be emitted from a stationary spot, use a func_emitter or a weather patch. If you want a particle that should always move with its emitter, for example a lamp glare, use a func_emitter bound to the light source. World particles are for effects that once released take their own path independent of the movement of any emitter, like trailing smoke, or for effects where you need fine-grained control of the release of individual particle quads.

	==Usage==		==Usage==

SteveL: /* Performance considerations */

2015-01-11T21:54:19Z

Performance considerations

← Older revision		Revision as of 21:54, 11 January 2015
Line 90:		Line 90:
	All world particles that use the same texture will be drawn in a single draw call, no matter how spread out they are in the map. So adding more world smoke emitters will increase calculations a bit, but it won't add more draw calls.		All world particles that use the same texture will be drawn in a single draw call, no matter how spread out they are in the map. So adding more world smoke emitters will increase calculations a bit, but it won't add more draw calls.

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

SteveL: Creating article

2015-01-11T21:53:49Z

Creating article

New page

:''This article describes a feature that will become available in TDM 2.03.''

The world particle system allows particles to exist in the world independent of any emitter entity. It enables effects like trailing smoke where the emitted smoke rises naturally instead of moving with the emitter, as well as fine-grained control of the emission of individual particle quads.

In TDM 2.03, the world particle system is usable only via scripting. We plan to add more user-friendly methods for mappers in 2.04, as well as to add it to some stock entities.

TDM 2.03 supports 3 particle systems: weather patches, that emit particles like rain or snow from a wide surface; func_emitters, entities that emit particles from a point; and the world particle system that's controlled by scripts. If you want a particle effect to be emitted from a stationary spot, use a func_emitter or a weather patch. If you want a particle that should always move with its emitter, for example a lamp glare, use a func_emitter bound to the light source. World particles are for effects that once released take their own path independent of the movement of the emitter, like trailing smoke, or for effects where you need fine-grained control of the release of individual particle quads.

==Usage==
Script event sys.EmitParticle is used for all world particle system emissions.

From the script reference:
<blockquote>
'''scriptEvent float ''emitParticle''(string particle, float startTime, float diversity, vector origin, vector angle);'''

:Start a particle effect in the world without using an entity emitter. Will emit one quad per particle stage when first called with sys.getTime() as the start time. Designed to be called once per frame with the same startTime each call to achieve a normal particle effect, or on demand with sys.getTime() as the startTime for finer grained control, 1 quad at a time. Returns True (1) if there are more particles to be emitted from the stage, False (0) if the stage has released all its quads.
::''particle'': String: name of particle effect.
::''startTime'': Game seconds since map start: use sys.getTime() for the first call unless you want to back-date the particle so that it starts part way through its cycle.
::''diversity'': Randomizer value between 0 and 1. All particles with the same diversity will have the same path and rotation. Use sys.random(1) for a random path.
::''origin'': Origin of the particle effect.
::''angle'': Axis for the particle effect. Use $<entityname>.getAngles() to align the particle to an entity. use '0 0 0' for an upright (world-aligned) particle effect.

:Spawnclasses responding to this event: ''idThread''
</blockquote>

"origin" is where the quad will be released from. You can use an entity origin as reference: using $player1.getOrigin(), for example, will emit the quad from between the player's feet. Using $guard2.getEyePos() will emit it from the guard2's eyes.

Once you have emitted a particle quad, you have no further control over it. It will go its own way according to the path specified in the [[Particle_Editor|particle decl]].

The script event is designed to be called every frame if you want to achieve "normal" particle emission as specified in the particle decl. It needs to be given a start time, which it uses to determine whether it should emit a quad or not right now.

===Single quad emission===
Calling emitParticle with the current time -- sys.getTime() -- as the startTime parameter will always emit a quad, the first that would be emitted by the specified particle effect. That's because particle effects always emit their first quad as soon as they start up no matter what timing is specified in the particle decl.

==="Natural" timing===
To make sys.emitParticle emit particle quads just like a func_emitter would, using the timings specified in the particle decl, call it with the same "startTime" every frame. Typically your script will start with the current time, and store that time so that you can pass the same time in every frame. Your code will continue doing that until emitParticle returns false (0), meaning that all quads for the particle effect have now been released:

<tt>float starttime = sys.getTime();</tt>
<tt>float more_to_come = 1;</tt>
<tt><br /></tt>
<tt>while ( more_to_come )</tt>
<tt>{</tt>
<tt> more_to_come = sys.emitParticle("tdm_smoke_candleout", starttime, sys.random(1), smoke_origin, '0 0 0');</tt>
<tt> sys.waitFrame();</tt>
<tt>}</tt>

For example, if you are using a particle effect that emits one quad every second, and you call sys.EmitParticle every frame, i.e. 60 times per second, then it will emit 1 particle every 60th call. The 59 calls in between will not emit anything.

Unlike func_emitters, emitParticle does not support cycling particle effects. If you want your emissions to carry on forever, you have to repeat the above instructions for ever in your script, e.g:

<tt>while (1) // cycle for ever</tt>
<tt>{</tt>
<tt> float starttime = sys.getTime();</tt>
<tt> float more_to_come = 1;</tt>
<tt> </tt>
<tt> while ( more_to_come )</tt>
<tt> {</tt>
<tt> more_to_come = sys.emitParticle("tdm_smoke_candleout", starttime, sys.random(1), smoke_origin, '0 0 0');</tt>
<tt> sys.waitFrame();</tt>
<tt> }</tt>
<tt>}</tt>

== Example ==
The following script emits a trailing smoke particle effect from an extinguished candle using the "natural" timing method and without cycling.

This is an exaggerated version of the standard 2.03 candle smoke effect, where the particle decl has been tweaked to increase the number, size, and duration of the particle quads.

The script runs through the particle effect once without cycling. The only change from the script given above is that it calculates the origin of the candle top every frame from the origin of the candle base and its current orientation, so if the player is moving the candle during the effect, the smoke comes out of the right place.

<tt>float candle_height = 17; // height of wick above candle holder </tt>
<tt> </tt>
<tt>float starttime = sys.getTime();</tt>
<tt>float more_to_come = 1;</tt>
<tt>while ( more_to_come )</tt>
<tt>{</tt>
<tt> vector candle_top = sys.angToUp( $candle_holder.getAngles() ) * candle_height;</tt>
<tt> vector smoke_origin = $candle_holder.getOrigin() + candle_top;</tt>
<tt> more_to_come = sys.emitParticle("tdm_smoke_candleout", starttime, sys.random(1), smoke_origin, '0 0 0');</tt>
<tt> sys.waitFrame();</tt>
<tt>}</tt>

=== Video of the result ===
[http://youtu.be/OdctCfJjv8g YouTube video]

==Performance considerations==
Particles emitted by weather patches and func_emitters are rendered only if the particle effect might appear in some area of the map that the player can see. Particle effects on the far side of the map will be "turned off". World particles are different: they are rendered every frame no matter whether the player has any chance of seeing them or not. They won't actually be drawn if not in view -- i.e. converted to screen pixels and coloured in -- but their positions will be calculated and passed to the graphics card every frame. If you have a thousand trailing particle emitters in your map, using a variety of different particle effects, you are likely to see an impact on FPS.

On the other hand, world particles enjoy some performance advantages over other types of particle. Weather patches and func_emitters each generate their own individual draw call every frame that they are in view. If you have two smoking torches next to one another, that's 2 draw calls each frame for the smoke.

All world particles that use the same texture will be drawn in a single draw call, no matter how spread out they are in the map. So adding more world smoke emitters will increase calculations a bit, but it won't add more draw calls.

[[Category:Particles]]