A_SpawnParticleEx
| Note: This feature is for ZScript only. |
void A_SpawnParticleEx (color color1, TextureID texture, int style = STYLE_None, int flags = 0, int lifetime = TICRATE, double size = 1, double angle = 0, double xoff = 0, double yoff = 0, double zoff = 0, double velx = 0, double vely = 0, double velz = 0, double accelx = 0, double accely = 0, double accelz = 0, double startalphaf = 0, double fadestepf = -1, double sizestep = 0, double startroll = 0, double rollvel = 0, double rollacc = 0)
| Note: There is currently a bug with the handling of textured particles, that makes them appear upside down. |
Usage
Spawns a single particle. Unlike A_SpawnParticle, this function also allows for creating textured particles, animated textured particles, shading particles, and giving them roll.
For a more flexible, struct-based version, see SpawnParticle.
Parameters
- color1: The color of the particle. Can be used with a hexadecimal value or a predefined value such as "Black". Colors can also be applied to textured particles to tint them a certain color, but this requires setting style to STYLE_Shaded (or STYLE_AddShaded, if you want them to be additive as well).
- texture: The texture to use for the particle, this requires a TextureID. Can be any graphic type, such as textures, sprites, miscellaneous graphics etc. This also supports graphics animated through ANIMDEFS.
- style: The render style to apply to the particle, these styles can be used both on textured and non-textured particles. Available render styles include:
- STYLE_None/STYLE_Normal/STYLE_Translucent: The particle is rendered normally, and can have custom alpha. All these styles have the same effect on particles. The default style is STYLE_None.
- STYLE_Add: Particle uses additive translucency.
- STYLE_Stencil: Particle is drawn ONLY with a the color defined in color1, this is only really useful for textured particles. Has no visual effect on untextured particles, since they're already colorized in a single flat color.
- STYLE_AddStencil: Same as STYLE_Stencil, but additive.
- STYLE_Shaded: Particle uses shaded renderstyle, tinted to the same color tone (but not a flat color, in contrast to Stencil). Has no visual effect on untextured particles, since they're already colorized in a single flat color.
- STYLE_AddShaded: Particle uses shaded renderstyle, tinted to the same color tone, and also uses additive translucency.
- STYLE_Fuzzy: Creates undefined behavior with textured and untextured particles.
- STYLE_Subtract: Uses inverted additive translucency, darkening the particle instead of making it lighter.
- STYLE_Shadow: Creates an effect similar to giving the particle STYLE_Stencil and giving it a startalphaf of 0.3.
- flags: Customizes the behavior of the function. Multiple flags can be combined by using the bitwise OR operator (
|) between the constant names:
- SPF_FULLBRIGHT — Makes the particle full bright.
- SPF_NOTIMEFREEZE — The spawned particle is not affected by the time freeze powerup or cheat.
- SPF_ROLL - The particle is allowed to use its' startroll, rollvel, and rollacc parameters.
- SPF_ROLLCENTER — Rolls the particle around the center of the graphic regardless of offsets, like the ROLLCENTER actor flag. (New from 4.13.0)
- SPF_REPLACE — If the the particle limit is reached, the oldest particles will be removed to make room for particles with SPF_REPLACE.
- SPF_NO_XY_BILLBOARD - The particle does not have any sort of billboarding, causing it to render similarly to normal actor sprites, instead of facing the players' view at all times.
- SPF_LOCAL_ANIM — Spawns an animated particle whose animation runs independently of the games' timer. This means the graphics can be animated at different times, and that pausing the game also stops them from running.
- SPF_NEGATIVE_FADESTEP — Forces negative fadestep to be interpreted literally, causing the particle to fade in (for example, with this flag a fadestep of -0.1 will cause the particle's alpha to increase by 0.1 every tic). Without this flag, any negative fadestep value will cause the particle to gradually fade out over its lifetime. (New from 4.13.0)
- SPF_FACECAMERA — Makes the particle graphic face the camera. Like the BILLBOARDFACECAMERA actor flag. (New from 4.13.0)
- SPF_NOFACECAMERA — Makes the particle graphic face the opposite direction the camera. Like the BILLBOARDNOFACECAMERA actor flag. (New from 4.13.0)
- SPF_STRETCHPIXELS — Rolling particle graphics will not ignore aspect ratio correction and continue to appear stretched. (New from 4.13.1)
- SPF_RELPOS — Position is relative to angle.
- SPF_RELVEL — Velocity is relative to angle.
- SPF_RELACCEL — Acceleration is relative to angle.
- SPF_RELANG — Adds the calling actor's angle to angle for relativity.
- SPF_RELATIVE — Combines the SPF_RELPOS, SPF_RELVEL, SPF_RELACCEL and SPF_RELANG flags.
- Default is 0.
- lifetime: The lifetime of the particle in tics. Default is 35.
- size: The size of the particle. Default is 1.
- angle: The angle to offset the particle by. Default is 0.
- x/yoff: The distance from the actor to spawn the particle along the X axis. Note that this is not relative. Default is 0.
- zoff: How high up to spawn the particle from the actor's Z position. Default is 0.
- velx/y/z: The velocity along the X/Y/Z axis to apply to the particle. This is in absolute direction, not relative. Default is 0.
- accelx/y/z: Defines how much to accelerate the particle by over its lifespan. Default is 0.
- startalphaf: Specifies the particle's alpha upon spawning. Default is 1.0.
- fadestepf: The amount by which the particle fades each tic. The particle is automatically removed early if it fades completely before lifetime expires. -1 indicates automatic (a complete fade-out over the length of lifetime). Default is -1.
- sizestep: The particle grows or shrinks in size by this amount per tic.
- startroll: The amount of roll the particle starts with. Default is 0. SPF_ROLL must be set for this parameter to be used.
- rollvel: The velocity at which the particle rotates. Default is 0. SPF_ROLL must be set for this parameter to be used.
- rollacc: How much the particle will accelerate its' roll over its' lifespan. Default is 0. SPF_ROLL must be set for this parameter to be used.
Examples
This actor spawns additive textured particles that use the sprites of the Imps' fireball, these particles then randomly pick if they should roll left or right, and accelerate their roll over time. The particles also increase in scale and fade out slowly.
Class TexturedParticleExample : Actor { Override Void Tick() { Bool Left = Random (True,False); A_SpawnParticleEx ( "FFFFFF", TexMan.CheckForTexture ("BAL1A0"), style: STYLE_Add, flags: SPF_FULLBRIGHT|SPF_RELATIVE|SPF_ROLL, lifetime: TICRATE * FRandom (1,4), size: 0.5, angle: 0., xoff: FRandom (64,-64), yoff: FRandom (64,-64), zoff: 0., velx: FRandom (0.5,-0.5), vely: FRandom (0.5,-0.5), velz: FRandom (0.4,3.0), accelx: 0, accely: 0, accelz: -0.001, startalphaf: 1.25, fadestepf: -0.002, sizestep: 0.25, startroll: 180/2, rollvel: Left ? 0.5 : -0.5, rollacc: Left ? 0.02 : -0.02 ); } }
Animated particles example
In addition to being able to use static graphics as particles, you can also use animated textures and graphics as particles as well. Below is an example on how the fireball particle spawner above can be animated using the Imp fireballs' original sprites.
The below TEXTURES definition creates new fireball textures using the original sprites as patches.
// Texture definitions generated by SLADE3 // on Fri Nov 11 05:41:11 2022 Texture "ANIMBAL1", 15, 15 { Patch "BAL1A0", 0, 0 } Texture "ANIMBAL2", 15, 15 { Patch "BAL1B0", 0, 0 } // End of texture definitions
Now that the original Imp fireball sprites are used to create new textures. ANIMDEFS can be used to turn the new textures into an animated texture.
Texture ANIMBAL1 Range ANIMBAL2 Tics 8
The sprites have now been turned into an animated texture. And you can change the graphic used by the texture parameter to one that is part of the animated texture. Causing the particles to turn into fully animated Imp fireballs.