From ZDoom Wiki
Jump to navigation Jump to search

bool, Actor A_SpawnItemEx (class<Actor> missile [, double xofs [, double yofs [, double zofs [, double xvel [, double yvel [, double zvel [, double angle [, int flags [, int failchance [, int tid]]]]]]]]]])


Spawns an actor at the specified offset away from the calling actor, facing the given angle, and with the indicated velocity.

The function does not spawn monster-based actors if the calling actor was massacred.


  • missile: The name of the actor to spawn. This can be any actor type, not just missiles.
  • x-/y-/zofs: The offset from the calling actor at which to spawn the new actor.
    • xofs: positive numbers move the spawn point further away in front of the calling actor; negative numbers - behind it.
    • yofs: positive numbers move the spawn point to the right side of the actor, negative numbers - to the left side.
    • zofs: positive numbers move the spawn point up from the bottom of the calling actor, negative numbers move it down.
  • x-/y-/zvel: The initial velocity to give to the spawned actor, useful for projectiles.
    • xvel: forward/backward velocity of the spawned actor.
    • yvel: right/left sideways velocity of the spawned actor.
    • zvel: vertical velocity of the spawned actor.
  • angle: Offsets the child actor's angle from the parent by the specified amount. Positive numbers rotate the spawned actor to the left, negative numbers turn it to the right in relation to the actor.
  • flags: The following flags can be combined by using the | character between the constant names:
    • SXF_TRANSFERTRANSLATION - the spawned actor will use the same translation as the parent.
    • SXF_ABSOLUTEPOSITION - apply the spawn offsets according to the absolute XY axes of the map, rather than relative to the direction the actor is facing.
    • SXF_ABSOLUTEANGLE - use the angle parameter as an absolute angle instead of a relative one to the calling actor's angle.
    • SXF_ABSOLUTEVELOCITY- the spawned actor will have its velocity set in absolute values instead of relative derived from the calling actor's velocities along the X, Y and Z axis.
    • SXF_SETMASTER - this places the new actor in a master/minion relationship with the parent. Master/minions will not attack each other and this allows for the use of A_KillMaster and/or A_KillChildren.
    • SXF_NOCHECKPOSITION - do not check the destination for room before spawning.
    • SXF_TELEFRAG - kills any actor that would prevent the new actor from spawning.
    • SXF_CLIENTSIDE - client-side spawning only. SkulltagIcon22.png (Skulltag only: not supported by ZDoom)
    • SXF_TRANSFERAMBUSHFLAG - if the calling actor has the AMBUSH flag set, then the spawned actor's will have it as well.
    • SXF_TRANSFERPITCH - transfers the calling actor's pitch to the spawned actor. Note that this has no effect on the spawned actor's velocities. If you want the calling actor's pitch to be taken into account for the spawned actor's trajectory, use a formula such as this one: A_SpawnItemEx (<type>,cos(pitch)*<Dist. from spawner>,<yofs>,<zofs>-(sin(pitch)*<Dist. from spawner>),cos(pitch)*<Projectile speed>,0,-sin(pitch)*<Projectile speed>,<angle>,<flags>,<chance>)
    • SXF_TRANSFERPOINTERS - transfers the calling actor's master, target, and tracer fields to the spawned actor. Note that SXF_SETMASTER has the last word for the master field.
    • SXF_USEBLOODCOLOR - uses the calling actor's BloodColor as the source of translation to be applied to the spawned actor. If no BloodColor is specifed, no translation is applied. If, both, this flag and SXF_TRANSFERTRANSLATION are used together in the same call, the latter takes precedence.
    • SXF_CLEARCALLERTID - if the actor is spawned successfully, this actor (the one that called A_SpawnItemEx) will have its TID set to 0.
    • SXF_MULTIPLYSPEED - multiply the spawned actor's velocity by its Speed property.
    • SXF_TRANSFERSCALE - transfers the current Scale factor of the spawning actor to the spawned actor.
    • SXF_TRANSFERSPECIAL - the calling actor transfers the special and the arguments of it to the spawning actor.
    • SXF_CLEARCALLERSPECIAL - if the actor is spawned successfully, the calling actor of this function will have its special and arguments removed.
    • SXF_TRANSFERSTENCILCOL - transfers the calling actor's StencilColor to the spawned actor.
    • SXF_TRANSFERALPHA - transfers the calling actor's alpha to the spawned actor.
    • SXF_TRANSFERRENDERSTYLE - transfers the calling actor's render style to the spawned actor.
    • SXF_SETTARGET - sets the calling actor to be the spawning actor's target. Can be combined with SXF_SETTRACER and SXF_SETMASTER.
    • SXF_SETTRACER - sets the calling actor to be the spawning actor's tracer. Can be combined with SXF_SETTARGET and SXF_SETMASTER.
    • SXF_NOPOINTERS - clears the spawning actor's target, master and tracer fields. This overrides SXF_TRANSFERPOINTERS, but is overridden by SXF_SETTARGET, SXF_SETMASTER and SXF_SETTRACER.
    • SXF_ORIGINATOR - Only useful for missiles. By default, when projectiles use SET pointer flags, the monster who did the spawning is the one that is the master. This flag allows said missile actors to set themselves as the master of the spawned actors instead, if SXF_SETMASTER, TARGET, or TRACER is used.
    • SXF_TRANSFERSPRITEFRAME - Transfers the calling actor's current sprite and frame letter to the spawning actor. This only works if the spawned actor's first spawn sprite (and/or frame) has the reserved special name for the sprite and frame letter.
    • SXF_TRANSFERROLL - transfers the calling actor's roll angle to the spawned actor.
    • SXF_ISTARGET - The spawned actor becomes the calling actor's target.
    • SXF_ISMASTER - The spawned actor becomes the calling actor's master.
    • SXF_ISTRACER - The spawned actor becomes the calling actor's tracer.
  • failchance: This is the chance (out of 256) that the actor has of not spawning. If this is 0 or omitted, the actor will always spawn. If it is 256, it will never spawn.
  • tid: The TID to assign to the spawned actor. If you wish it to share the same TID as the calling actor's, pass tid. In conjunction with SXF_CLEARCALLERTID, this can be used to transfer a TID from the original actor to the spawned actor.

Return value

The function returns two values:

  • A boolean based on whether the actor successfully spawned or not. An actor that does not spawn because of chance or massacre always counts as success.
  • A pointer to the spawned actor. If the actor fails to spawn due to chance or massacre, the returned value is null. When testing for space to spawn the actor in, the actor is spawned, tested and then immediately destroyed if it fails the test. The returned value in this case is still a pointer to the actor, not null.

So based on the above, it is important to check for both of these values in order to determine whether an actor has truly spawned or not.


The following actor is a variant of the Heretic explosive pod that leaves a poison cloud behind it as well. It uses A_SpawnItemEx so as to make use of the SXF_TRANSFERPOINTERS flag. This way, the monster or player responsible for blowing up the pod will be known as the source of damage created by the poison cloud. This makes sure that deathmatch frags are credited to the proper player, and allows barrel-based infighting to happen. The yofs is set to 28 so as to mimick closely the A_PoisonBagInit function which isn't accessible to pod actors.

ACTOR PoisonPod : Pod 20020
	DeathSound "PoisonPod/Puff"
		PPOD C 5 Bright A_RemovePod
		PPOD D 5 Bright A_Scream
		PPOD E 5 Bright A_Explode
		PPOD A 0 A_SpawnItemEx("PoisonCloud", 0, 0, 28, 0, 0, 0, 0, SXF_TRANSFERPOINTERS)
		PPOD F 10 Bright