4 Effectinfo Scripting Reference
5 ==============================
7 EffectInfo is built-in scripting language to describe particle effects in DarkPlaces, it's pretty simple and contains basic scripting functions.
9 Each effect can have several emitters which is defined in `effectinfo.txt` or `maps/mapname_effectinfo.txt`
26 // emitter for another effect
35 `r_drawparticles`: toggle drawing of all particles
37 `r_drawparticles_drawdistance`: set a maximal distance to draw particles at
39 `cl_particles_size`: this will scale a size of all particles
41 `cl_particles_quality`: multiplier of particles count spawned by emitters, better quality = more particles (1 - min, 4 - max. quality)
43 `cl_particles_reloadeffects`: reloads effectinfo.txt while in the game; that eliminates a need to quit and restart DP to see updated effects
50 Defines a new emitter with effectname is belongs to, all parms after that will be applied to that emitter.
54 Defines a new emitter with effectname is belongs to, all parms after that will be applied to that emitter.
58 How many particles to spawn at this emitter, this setting is affected by cl_particles_quality cvar
62 Defines a count of particles spawned regardless of cl_particles_quality setting
63 Total particles count = countabsolute + count * cl_particles_quality
67 Sets a generic particle type, affect appearance, blending, physics.
68 List of particle types:
70 - alphastatic : alpha-blended billboard
71 - static : additive-blended billboard
72 - spark : additive blended, stretched (based on velocity)
73 - beam : a beam particle, drawn from origin to origin + velocity
74 - rain : a rain particle, alpha-blended spart that will cause splash effect on impact
75 - raindecal: oriented rain decal, additive-blended
76 - snow: alpha blended, velocity jitters in realtime
77 - bubble: alpha-blended
78 - blood: inverse-modulated, leaves decal
79 - smoke: alpha-blended billboard
80 - decal: makes a decal on nearest surface
81 - entityparticle: alpha-blended, this particle gets removed after being drawn (used on EF_BRIGHTFIELD)
87 Generic blend is set by type, but with this parm it cound be changed after type is defined.
90 - alpha : alpha blended
91 - add: additive blended
92 - invmod: inverse modulation (used on blood and blood decals)
96 orientation <orientationtype>
98 Same as for blend, generic orientation is set by type, could be altered by this parm.
99 List of orientation types:
101 - billboard : always turned to viewer
102 - oriented : ignores viewwer, turned to velocity
103 - beam : facing viewer on 2 axises, stretched from origin to origin + velocity
104 - spark : facing viewer on 2 axises, stretched (based on velocity)
108 color <min_color> <max_color>
110 Sets a color for particles. On each particle spawn, it's color is linearly randomized betwen two given colors. Color should be defined as HEX 0xRRGGBB, like 0xFFFFFF is white, and 0xFF0000 is red.
112 tex <min_index> <max_index>
114 Sets a index of particle from particlefont. Indexes are counted from left to right, from up to down, last index is 63, first is 0. Randomized linearly on each particle spawn.
116 size <min_size> <max_size>
118 Size of particle in game units, typical value is 4, randomized.
122 This will make particle grow or diminish over time. <rate> is to how much utits to add or subtract per second. Note that while diminishing particle, engine will not check if particle will go to negative size, it will just invert it.
124 alpha <min_alpha> <max_alpha> <fade_rate>
126 Opacity of particles, 256 is opaque, 0 is transparent. Randomized. Could be more that 256 (to simulate fade delay). Fade rate is how huch alpha to throw away per second, once particle gets alpha 0 (full transparence), it gets removed.
128 time <min_time> <max_time>
130 Particle time-to-live in seconds, randomized.
134 Particle gravity modifier, 1 is full gravity, 0.5 is half etc., negative values are supported (particle go up).
138 Particle bounce-of-walls factor, 1 - bounce with full speed, 0.5 bounce with half speed. A value of -1 means particle will be removed on impact. Not that particle physics considered slow and spawning lots of bouncing particles is not recommended.
142 Particle friction while moving in air, good option for smoke emitters. A value of 0 means no friction, negative values will do acceleration.
144 liquidfriction <value>
146 Particle friction while moving in liquids.
148 originoffset <x> <y> <z>
150 Offset particle spawning origin by this values. Coordspace are world, x - forward, y - right, z - up.
152 velocityoffset <x> <y> <z>
154 Add this amount of constant velocity to particle on spawn.
156 originjitter <x> <y> <z>
158 Like originoffset but each axis is jittered between -value/+value. Hence it is defining spherical shape of particle random spawning.
160 velocityjitter <x> <y> <z>
162 Same as originjitter but for velocity.
164 velocitymultiplier <x>
166 Multiply particle starting velocity (one that set by QC or engine, whatever calls effect) by this value. Useful with trails. Negative values are supported.
170 Sets underwater flag for particles. Particles that are underwater will be removed in air. Useful for water bubbles.
174 Sets notunderwater flag for particles. Particles that are notunderwater will be removed in liquid. Useful for fire particles.
178 This parm is only useful when effect is spawned as trail, defines a game units gap between effect invocations.
182 A custom stretch factor that is used on sparks.
184 rotate <startangle_min> <startangle_max> <spin_min> <spin_max>
186 Used to rotate particle, first 2 parms is start angle, other two are spin velocity.
188 Particles leaving decals
189 ------------------------
191 Particles can leave decals once hit something. For this behavior a special set of parms should be used. This section is unfinished, futher explanation is required.
193 staincolor <min_color> <max_color>
195 A randomized color for decal particle.
197 stainalpha <min_alpha> <max_alpha>
201 stainsize <min_size> <max_size>
205 staintex <min_index> <max_index>
207 A randomized index into particlefont.
211 Disables decal spawning and returns all parms to it's default values.
216 Dynamic realtime lights could be placed in particle effects (useful for explosions) with this range of parms. These params apply just like standard ones.
220 Radius of light in game units. Typical value is 200.
222 lightradiusfade <rate>
224 Radius fade rate, how many units to add/subtract per second. Once light reaches radius of 0 it gets removed.
228 If radius fading not set, this parm can be used to define light life time.
230 lightcolor <red> <green> <blue>
232 A RGB-normalized light color, 1 1 1 is white, 0 0 1 is blue. Can exceed 1 (overbright light).
236 Cast shadows from light, value is 0 or 1.
238 lightcubemapnum <value>
240 Sets a numbered cubefilter for light, cubemap texture is cubemaps/<value>
245 Heres a list of effect names used by engine.
283 Using custom effects in QuakeC
284 ------------------------------
286 There are 3 QuakeC functions that can are used to call custom effects. They are defined `in dpextensions.qc`.
289 float(string effectname) particleeffectnum = #335;
290 void(entity ent, float effectnum, vector start, vector end) trailparticles = #336;
291 void(float effectnum, vector org, vector vel, float howmany) pointparticles = #337;
294 Effects can called by first obtaining the effectnum, then calling the appropriate particle function.
297 local float effectnum;
299 effectnum = particleeffectnum("EFFECT_NAME");
301 pointparticles(effectnum, self.origin, '0 0 0', 10);