Effectinfo-Scripting.md

   1 Reference: https://www.quakewiki.net/darkplaces-wiki/effectinfo-scripting-reference/
   2
   3 ### [**Effectinfo Scripting Reference**](https://www.quakewiki.net/darkplaces-wiki/effectinfo-scripting-reference/ "Effectinfo Scripting Reference")
   4
   5 <div>Posted on September 30th, 2012 | Last modified on August 15th, 2014</div>
   6 <div>
   7
   8 EffectInfo is built-in scripting language to describe particle effects in DarkPlaces, it’s pretty simple and contains basic scripting functions.
   9
  10 Each effect can have several emitters which is defined in effectinfo.txt or maps/mapname_effectinfo.txt
  11
  12 <table>
  13 <tr>
  14 <td>
  15
  16 <div>
  17
  18 ## Contents
  19
  20 </div>* [1 General syntax](http://web.archive.org/web/20100729132930/http://dpwiki.slipgateconstruct.com/index.php?title=Effectinfo_Scripting_Reference#General_syntax)
  21 * [2 Console variables](http://web.archive.org/web/20100729132930/http://dpwiki.slipgateconstruct.com/index.php?title=Effectinfo_Scripting_Reference#Console_variables)
  22 * [3 Particle parameters](http://web.archive.org/web/20100729132930/http://dpwiki.slipgateconstruct.com/index.php?title=Effectinfo_Scripting_Reference#Particle_parameters)
  23 * [4 Particles leaving decals](http://web.archive.org/web/20100729132930/http://dpwiki.slipgateconstruct.com/index.php?title=Effectinfo_Scripting_Reference#Particles_leaving_decals)
  24 * [5 Dynamic lights](http://web.archive.org/web/20100729132930/http://dpwiki.slipgateconstruct.com/index.php?title=Effectinfo_Scripting_Reference#Dynamic_lights)
  25 * [6 Engine effect names](http://web.archive.org/web/20100729132930/http://dpwiki.slipgateconstruct.com/index.php?title=Effectinfo_Scripting_Reference#Engine_effect_names)
  26 * [7 Known bugs](http://web.archive.org/web/20100729132930/http://dpwiki.slipgateconstruct.com/index.php?title=Effectinfo_Scripting_Reference#Known_bugs)
  27 </td>
  28 </tr>
  29 </table>
  30
  31
  32 ## General syntax
  33
  34 <pre>
  35
  36 // emitter 1\
  37 effect EFFECT_NAME\
  38 parm value\
  39 parm2 value\
  40 ...\
  41 \
  42 // emitter 2\
  43 effect EFFECT_NAME\
  44 parm value\
  45 parm2 value\
  46 ...\
  47 \
  48 // emitter for another effect\
  49 effect ANOTHER_EFFECT\
  50 parm value\
  51 parm2 value\
  52 ...
  53
  54 </pre>
  55
  56 ## Console variables
  57
  58 `r_drawparticles` : toggle drawing of all particles
  59
  60 `r_drawparticles_drawdistance` : set a maximal distance to draw particles at
  61
  62 `cl_particles_size` : this will scale a size of all particles
  63
  64 `cl_particles_quality` : multiplier of particles count spawned by emitters, better quality = more particles (1 – min, 4 – max. quality)
  65
  66 `cl_particles_reloadeffects` : reloads effectinfo.txt while in the game; that eliminates a need to quit and restart DP to see updated effects
  67
  68 ## Particle parameters
  69
  70 **effect <name>**
  71
  72 Defines a new emitter with effectname is belongs to, all parms after that will be applied to that emitter.
  73
  74 **count <count>**
  75
  76 How many particles to spawn at this emitter, this setting is affected by cl_particles_quality cvar
  77
  78 **countabsolute <count>**
  79
  80 Defines a count of particles spawned regardless of cl_particles_quality setting
  81
  82 Total particles count = countabsolute + count \* cl_particles_quality
  83
  84 **type <type>**
  85
  86 Sets a generic particle type, affect appearance, blending, physics.
  87
  88 List of particle types:
  89
  90 <dl>
  91 <dd>alphastatic : alpha-blended billboard</dd>
  92 <dd>static : additive-blended billboard</dd>
  93 <dd>spark : additive blended, stretched (based on velocity)</dd>
  94 <dd>beam : a beam particle, drawn from origin to origin + velocity</dd>
  95 <dd>rain : a rain particle, alpha-blended spart that will cause splash effect on impact</dd>
  96 <dd>raindecal: oriented rain decal, additive-blended</dd>
  97 <dd>snow: alpha blended, velocity jitters in realtime</dd>
  98 <dd>bubble: alpha-blended</dd>
  99 <dd>blood: inverse-modulated, leaves decal</dd>
 100 <dd>smoke: alpha-blended billboard</dd>
 101 <dd>decal: makes a decal on nearest surface</dd>
 102 <dd>entityparticle: alpha-blended, this particle gets removed after being drawn (used on EF_BRIGHTFIELD)</dd>
 103 </dl>
 104
 105 **blend <blendtype>**
 106
 107 Generic blend is set by type, but with this parm it cound be changed after type is defined.
 108
 109 List of blend types:
 110
 111 <dl>
 112 <dd>alpha : alpha blended</dd>
 113 <dd>add: additive blended</dd>
 114 <dd>invmod: inverse modulation (used on blood and blood decals)</dd>
 115 </dl>
 116
 117 **orientation <orientationtype>**
 118
 119 Same as for blend, generic orientation is set by type, could be altered by this parm.
 120
 121 List of orientation types:
 122
 123 <dl>
 124 <dd>billboard : always turned to viewer</dd>
 125 </dl>
 126
 127 <dl>
 128 <dd>oriented : ignores viewwer, turned to velocity</dd>
 129 </dl>
 130
 131 <dl>
 132 <dd>beam : facing viewer on 2 axises, stretched from origin to origin + velocity</dd>
 133 </dl>
 134
 135 <dl>
 136 <dd>spark : facing viewer on 2 axises, stretched (based on velocity)</dd>
 137 </dl>
 138
 139 **color <min_color> <max_color>**
 140
 141 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.
 142
 143 **tex <min_index> <max_index>**
 144
 145 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.
 146
 147 **size <min_size> <max_size>**
 148
 149 Size of particle in game units, typical value is 4, randomized.
 150
 151 **sizeincrease <rate>**
 152
 153 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.
 154
 155 **alpha <min_alpha> <max_alpha> <fade_rate>**
 156
 157 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.
 158
 159 **time <min_time> <max_time>**
 160
 161 Particle time-to-live in seconds, randomized.
 162
 163 **gravity <value>**
 164
 165 Particle gravity modifier, 1 is full gravity, 0.5 is half etc., negative values are supported (particle go up).
 166
 167 **bounce <value>**
 168
 169 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.
 170
 171 **airfriction <value>**
 172
 173 Particle friction while moving in air, good option for smoke emitters. A value of 0 means no friction, negative values will do acceleration.
 174
 175 **liquidfriction <value>**
 176
 177 Particle friction while moving in liquids.
 178
 179 **originoffset <x> <y> <z>**
 180
 181 Offset particle spawning origin by this values. Coordspace are world, x – forward, y – right, z – up.
 182
 183 **velocityoffset <x> <y> <z>**
 184
 185 Add this amount of constant velocity to particle on spawn.
 186
 187 **originjitter <x> <y> <z>**
 188
 189 Like originoffset but each axis is jittered between -value/+value. Hence it is defining spherical shape of particle random spawning.
 190
 191 **velocityjitter <x> <y> <z>**
 192
 193 Same as originjitter but for velocity.
 194
 195 **velocitymultiplier <x>**
 196
 197 Multiply particle starting velocity (one that set by QC or engine, whatever calls effect) by this value. Useful with trails. Negative values are supported.
 198
 199 **underwater**
 200
 201 Sets underwater flag for particles. Particles that are underwater will be removed in air. Useful for water bubbles.
 202
 203 **notunderwater**
 204
 205 Sets notunderwater flag for particles. Particles that are notunderwater will be removed in liquid. Useful for fire particles.
 206
 207 **trailspacing <x>**
 208
 209 This parm is only useful when effect is spawned as trail, defines a game units gap between effect invocations.
 210
 211 **stretchfactor <x>**
 212
 213 A custom stretch factor that is used on sparks.
 214
 215 **rotate <startangle_min> <startangle_max> <spin_min> <spin_max>**
 216
 217 Used to rotate particle, first 2 parms is start angle, other two are spin velocity.
 218
 219 ## Particles leaving decals
 220
 221 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.
 222
 223 **staincolor <min_color> <max_color>**
 224
 225 A randomized color for decal particle.
 226
 227 **stainalpha <min_alpha> <max_alpha>**
 228
 229 A randomized alpha.
 230
 231 **stainsize <min_size> <max_size>**
 232
 233 A randomized size.
 234
 235 **staintex <min_index> <max_index>**
 236
 237 A randomized index into particlefont.
 238
 239 **stainless**
 240
 241 Disables decal spawning and returns all parms to it’s default values.
 242
 243 ## Dynamic lights
 244
 245 Dynamic realtime lights could be placed in particle effects (useful for explosions) with this range of parms. This parms applied just like standart ones.
 246
 247 **lightradius <radius>**
 248
 249 Radius of light in game units. Typical value is 200.
 250
 251 **lightradiusfade <rate>**
 252
 253 Radius fade rate, how many units to add/subtract per second. Once light reaches radius of 0 it gets removed.
 254
 255 **lighttime <time>**
 256
 257 If radius fading not set, this parm can be used to define light life time.
 258
 259 **lightcolor <red> <green> <blue>**
 260
 261 A RGB-normalized light color, 1 1 1 is white, 0 0 1 is blue. Can exceed 1 (overbright light).
 262
 263 **lightshadow <value>**
 264
 265 Cast shadows from light, value is 0 or 1.
 266
 267 **lightcubemapnum <value>**
 268
 269 Sets a numbered cubefilter for light, cubemap texture is cubemaps/<value>
 270
 271 ## Engine effect names
 272
 273 Heres a list of effect names used by engine.
 274
 275 ```
 276 TE_GUNSHOT
 277 TE_GUNSHOTQUAD
 278 TE_SPIKE
 279 TE_SPIKEQUAD
 280 TE_SUPERSPIKE
 281 TE_SUPERSPIKEQUAD
 282 TE_WIZSPIKE
 283 TE_KNIGHTSPIKE
 284 TE_EXPLOSION
 285 TE_EXPLOSIONQUAD
 286 TE_TAREXPLOSION
 287 TE_TELEPORT
 288 TE_LAVASPLASH
 289 TE_SMALLFLASH
 290 TE_FLAMEJET
 291 EF_FLAME
 292 TE_BLOOD
 293 TE_SPARK
 294 TE_PLASMABURN
 295 TE_TEI_G3
 296 TE_TEI_SMOKE
 297 TE_TEI_BIGEXPLOSION
 298 TE_TEI_PLASMAHIT
 299 EF_STARDUST
 300 TR_ROCKET
 301 TR_GRENADE
 302 TR_BLOOD
 303 TR_WIZSPIKE
 304 TR_SLIGHTBLOOD
 305 TR_KNIGHTSPIKE
 306 TR_VORESPIKE
 307 TR_NEHAHRASMOKE
 308 TR_NEXUIZPLASMA
 309 TR_GLOWTRAIL
 310 SVC_PARTICLE
 311 ```
 312
 313 ## Known bugs
 314
 315 ~~maps/mapname_effectinfo.txt does not add effects at the moment, but replaces the whole effects info~~\
 316 The Engine now appends mapname_effectinfo.txt to effectinfo.txt. In other words you can create additional effects for your map without changing effectinfo.txt
 317
 318 </div>