Effectinfo.md

   1 DarkPlaces Wiki
   2 ===============
   3
   4 Effectinfo Scripting Reference
   5 ==============================
   6
   7 EffectInfo is built-in scripting language to describe particle effects in DarkPlaces, it's pretty simple and contains basic scripting functions.
   8
   9 Each effect can have several emitters which is defined in `effectinfo.txt` or `maps/mapname_effectinfo.txt`
  10
  11 General syntax
  12 --------------
  13
  14     // emitter 1
  15     effect EFFECT_NAME
  16     parm value
  17     parm2 value
  18     ...
  19
  20     // emitter 2
  21     effect EFFECT_NAME
  22     parm value
  23     parm2 value
  24     ...
  25
  26     // emitter for another effect
  27     effect ANOTHER_EFFECT
  28     parm value
  29     parm2 value
  30     ...
  31
  32 Console variables
  33 -----------------
  34
  35 `r_drawparticles`: toggle drawing of all particles
  36
  37 `r_drawparticles_drawdistance`: set a maximal distance to draw particles at
  38
  39 `cl_particles_size`: this will scale a size of all particles
  40
  41 `cl_particles_quality`: multiplier of particles count spawned by emitters, better quality = more particles (1 - min, 4 - max. quality)
  42
  43 `cl_particles_reloadeffects`: reloads effectinfo.txt while in the game; that eliminates a need to quit and restart DP to see updated effects
  44
  45 Particle parameters
  46 -------------------
  47
  48     effect <name>
  49
  50 Defines a new emitter with effectname is belongs to, all parms after that will be applied to that emitter.
  51
  52     effect <name>
  53
  54 Defines a new emitter with effectname is belongs to, all parms after that will be applied to that emitter.
  55
  56     count <count>
  57
  58 How many particles to spawn at this emitter, this setting is affected by cl_particles_quality cvar
  59
  60     countabsolute <count>
  61
  62 Defines a count of particles spawned regardless of cl_particles_quality setting
  63 Total particles count = countabsolute + count * cl_particles_quality
  64
  65     type <type>
  66
  67 Sets a generic particle type, affect appearance, blending, physics.
  68 List of particle types:
  69
  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)
  82
  83 </end list hack>
  84
  85     blend <blendtype>
  86
  87 Generic blend is set by type, but with this parm it cound be changed after type is defined.
  88 List of blend types:
  89
  90 -   alpha : alpha blended
  91 -   add: additive blended
  92 -   invmod: inverse modulation (used on blood and blood decals)
  93
  94 </end list hack>
  95
  96     orientation <orientationtype>
  97
  98 Same as for blend, generic orientation is set by type, could be altered by this parm.
  99 List of orientation types:
 100
 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)
 105
 106 </end list hack>
 107
 108     color <min_color> <max_color>
 109
 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.
 111
 112     tex <min_index> <max_index>
 113
 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.
 115
 116     size <min_size> <max_size>
 117
 118 Size of particle in game units, typical value is 4, randomized.
 119
 120     sizeincrease <rate>
 121
 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.
 123
 124     alpha <min_alpha> <max_alpha> <fade_rate>
 125
 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.
 127
 128     time <min_time> <max_time>
 129
 130 Particle time-to-live in seconds, randomized.
 131
 132     gravity <value>
 133
 134 Particle gravity modifier, 1 is full gravity, 0.5 is half etc., negative values are supported (particle go up).
 135
 136     bounce <value>
 137
 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.
 139
 140     airfriction <value>
 141
 142 Particle friction while moving in air, good option for smoke emitters. A value of 0 means no friction, negative values will do acceleration.
 143
 144     liquidfriction <value>
 145
 146 Particle friction while moving in liquids.
 147
 148     originoffset <x> <y> <z>
 149
 150 Offset particle spawning origin by this values. Coordspace are world, x - forward, y - right, z - up.
 151
 152     velocityoffset <x> <y> <z>
 153
 154 Add this amount of constant velocity to particle on spawn.
 155
 156     originjitter <x> <y> <z>
 157
 158 Like originoffset but each axis is jittered between -value/+value. Hence it is defining spherical shape of particle random spawning.
 159
 160     velocityjitter <x> <y> <z>
 161
 162 Same as originjitter but for velocity.
 163
 164     velocitymultiplier <x>
 165
 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.
 167
 168     underwater
 169
 170 Sets underwater flag for particles. Particles that are underwater will be removed in air. Useful for water bubbles.
 171
 172     notunderwater
 173
 174 Sets notunderwater flag for particles. Particles that are notunderwater will be removed in liquid. Useful for fire particles.
 175
 176     trailspacing <x>
 177
 178 This parm is only useful when effect is spawned as trail, defines a game units gap between effect invocations.
 179
 180     stretchfactor <x>
 181
 182 A custom stretch factor that is used on sparks.
 183
 184     rotate <startangle_min> <startangle_max> <spin_min> <spin_max>
 185
 186 Used to rotate particle, first 2 parms is start angle, other two are spin velocity.
 187
 188 Particles leaving decals
 189 ------------------------
 190
 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.
 192
 193     staincolor <min_color> <max_color>
 194
 195 A randomized color for decal particle.
 196
 197     stainalpha <min_alpha> <max_alpha>
 198
 199 A randomized alpha.
 200
 201     stainsize <min_size> <max_size>
 202
 203 A randomized size.
 204
 205     staintex <min_index> <max_index>
 206
 207 A randomized index into particlefont.
 208
 209     stainless
 210
 211 Disables decal spawning and returns all parms to it's default values.
 212
 213 Dynamic lights
 214 --------------
 215
 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.
 217
 218     lightradius <radius>
 219
 220 Radius of light in game units. Typical value is 200.
 221
 222     lightradiusfade <rate>
 223
 224 Radius fade rate, how many units to add/subtract per second. Once light reaches radius of 0 it gets removed.
 225
 226     lighttime <time>
 227
 228 If radius fading not set, this parm can be used to define light life time.
 229
 230     lightcolor <red> <green> <blue>
 231
 232 A RGB-normalized light color, 1 1 1 is white, 0 0 1 is blue. Can exceed 1 (overbright light).
 233
 234     lightshadow <value>
 235
 236 Cast shadows from light, value is 0 or 1.
 237
 238     lightcubemapnum <value>
 239
 240 Sets a numbered cubefilter for light, cubemap texture is cubemaps/<value>
 241
 242 Engine effect names
 243 -------------------
 244
 245 Heres a list of effect names used by engine.
 246
 247     TE_GUNSHOT
 248     TE_GUNSHOTQUAD
 249     TE_SPIKE
 250     TE_SPIKEQUAD
 251     TE_SUPERSPIKE
 252     TE_SUPERSPIKEQUAD
 253     TE_WIZSPIKE
 254     TE_KNIGHTSPIKE
 255     TE_EXPLOSION
 256     TE_EXPLOSIONQUAD
 257     TE_TAREXPLOSION
 258     TE_TELEPORT
 259     TE_LAVASPLASH
 260     TE_SMALLFLASH
 261     TE_FLAMEJET
 262     EF_FLAME
 263     TE_BLOOD
 264     TE_SPARK
 265     TE_PLASMABURN
 266     TE_TEI_G3
 267     TE_TEI_SMOKE
 268     TE_TEI_BIGEXPLOSION
 269     TE_TEI_PLASMAHIT
 270     EF_STARDUST
 271     TR_ROCKET
 272     TR_GRENADE
 273     TR_BLOOD
 274     TR_WIZSPIKE
 275     TR_SLIGHTBLOOD
 276     TR_KNIGHTSPIKE
 277     TR_VORESPIKE
 278     TR_NEHAHRASMOKE
 279     TR_NEXUIZPLASMA
 280     TR_GLOWTRAIL
 281     SVC_PARTICLE
 282
 283 Using custom effects in QuakeC
 284 ------------------------------
 285
 286 There are 3 QuakeC functions that can are used to call custom effects. They are defined `in dpextensions.qc`.
 287
 288 ```c
 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;
 292 ```
 293
 294 Effects can called by first obtaining the effectnum, then calling the appropriate particle function.
 295
 296 ```c
 297 local float effectnum;
 298
 299 effectnum = particleeffectnum("EFFECT_NAME");
 300
 301 pointparticles(effectnum, self.origin, '0 0 0', 10);
 302 ```