A_SpawnParticleEx

From ZDoom Wiki
(Redirected from A SpawnParticle)
Jump to navigation Jump to search
Note: This feature is for ZScript only.


Actor

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) (ZScript only)

Older function - doesn't support roll or custom textures:
 void A_SpawnParticle (color color1, 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)

Usage

Spawns a single particle. When using A_SpawnParticleEx, the particle can optionally utilize a custom texture provided as a TextureID.

Note: in ZScript using the struct-based level.SpawnParticle instead is generally preferable as it offers more flexibility. If you decide to go with this function after all, due to a very large number of arguments, using ZScript named arguments is recommended.

Parameters

  • Color 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). Use "" to pass no color if you want to make a textured particle and not apply any tint to it.
  • TextureID texture (not supported by A_SpawnParticle)
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.
  • int style (not supported by A_SpawnParticle)
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.
  • int 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_REPLACE — If the the particle limit is reached, the oldest particles will be removed to make room for particles with SPF_REPLACE.
  • SPF_FACECAMERA — Makes the particle graphic face the camera. Like the BILLBOARDFACECAMERA actor flag.
  • SPF_NOFACECAMERA — Makes the particle graphic face the opposite direction the camera. Like the BILLBOARDNOFACECAMERA actor flag.
  • 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.
  • 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.
The following are only supported by A_SpawnParticleEx and SpawnParticle (ZScript):
  • 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.
  • 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_STRETCHPIXELS — Rolling particle graphics will not ignore aspect ratio correction and continue to appear stretched.
  • 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 (no flags).
  • int lifetime
The lifetime of the particle in tics. Default is 35.
  • double size
The size of the particle in absolute map units. If a texture is used, it'll be automatically scaled to fit this size. Default is 1.
  • double angle
The angle to offset the particle by. Default is 0.
  • double xoff
The forward/backward offset from the actor to spawn the particle at. Note that this is not relative. Default is 0.
  • double yoff
The left/right offset from the actor to spawn the particle at. Note that this is not relative. Default is 0.
  • double zoff
The vertical offset from the actor's feet to spawn the particle at. Default is 0.
  • double velx
  • double vely
  • double velz
The velocity along the X/Y/Z axis to apply to the particle. This is in absolute direction, not relative. Default is 0.
  • double accelx
  • double accely
  • double accelz
Defines how much to accelerate the particle by over its lifespan. Default is 0.
  • double startalphaf
Specifies the particle's alpha upon spawning. Default is 1.0.
  • double fadestepf
Determines how the particle's alpha changes while it exists. The values are interpreted as follows:
  • 0.0 — the particle's alpha won't change; the startalphaf value will be used throughout its lifetime.
  • Positive value — this value will be subtracted from the particle's alpha each tic, fading it out. Note, this isn't affected by its lifetime: i.e. if the value is high enough, the particle may become completely invisible before its lifetime runs out, and conversely, if it's low enough, the particle won't completely fade out before its lifetime runs out and it disappears.
  • Negative value — the particle will gradually fade out from its startalphaf to zero throughout its lifetime. (This is, essentially, the same as using a value of startalphaf / lifetime but without the need to manually precalculate it.)
  • Negative value and the SPF_NEGATIVE_FADESTEP flag is used — this value will be added to the particle's alpha each tic. This allows fading the particles in rather than out.
Default is -1, which makes the particle fade out throughout its lifetime.
  • double sizestep
The particle grows or shrinks in size by this amount per tic.
  • double startroll (not supported by A_SpawnParticle)
The amount of roll the particle starts with. Default is 0. SPF_ROLL must be set for this parameter to be used.
  • double rollvel (not supported by A_SpawnParticle)
The velocity at which the particle rotates. Default is 0. SPF_ROLL must be set for this parameter to be used.
  • double rollacc (not supported by A_SpawnParticle)
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()
	{
		int dir = randompick(-1, 1);
		A_SpawnParticleEx
		(
			"",
			TexMan.CheckForTexture ("BAL1A0"),
			style: STYLE_ADD,
			flags: SPF_FULLBRIGHT,
			lifetime: TICRATE * frandom (1,4),
			size: 0.5,
			xoff: frandom (64,-64),
			yoff: frandom (64,-64),
			velx: frandom (0.5,-0.5),
			vely: frandom (0.5,-0.5),
			velz: frandom (0.4,3.0),
			accelz: -0.001,
			startalphaf: 1.25,
			fadestepf: -0.002,
			sizestep: 0.25,
			startroll: 180/2,
			rollvel: 0.5 * dir,
			rollacc: 0.02 * dir
		);
	}
}

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 "ANIMBAL1", 15, 15
{
	Patch "BAL1A0", 0, 0
}

Texture "ANIMBAL2", 15, 15
{
	Patch "BAL1B0", 0, 0
}

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.

See also

Retrieved from "https://zdoom.org/w/index.php?title=A_SpawnParticleEx&oldid=54672"