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