A_SpawnItemEx

From ZDoom Wiki
Jump to: navigation, search

bool A_SpawnItemEx (string type [, float xoffset [, float yoffset [, float zoffset [, float xvelocity [, float yvelocity [, float zvelocity [, float angle [, int flags [, int chance [, int tid ]]]]]]]]])

Usage

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

Parameters

  • type: The name of the actor to spawn.
  • x-/y-/zoffset: The offset from the calling actor at which to spawn the new actor.
    • xoffset: positive numbers move the spawn point further away in front of the calling actor; negative numbers - behind it.
    • yoffset: positive numbers move the spawn point to the right side of the actor, negative numbers - to the left side.
    • zoffset: positive numbers move the spawn point up from the bottom of the calling actor, negative numbers move it down.
  • x-/y-/zvelocity: The initial velocity to give to the spawned actor, useful for projectiles.
    • xvelocity: forward/backward velocity of the spawned actor.
    • yvelocity: right/left sideways velocity of the spawned actor.
    • zvelocity: 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 - spawn the actor at an absolute position, instead of offsetting it by the given coordinates from the calling actor's position.
    • 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 - if the calling actor is a monster ((New from 2.8.1) this restriction does not apply), 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>,<yoffset>,<zoffset>-(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. (New from 2.8.1)
    • SXF_TRANSFERALPHA - transfers the calling actor's alpha to the spawned actor. (New from 2.8.1)
    • SXF_TRANSFERRENDERSTYLE - transfers the calling actor's render style to the spawned actor. (New from 2.8.1)
    • SXF_SETTARGET - sets the calling actor to be the spawning actor's target. Can be combined with SXF_SETTRACER and SXF_SETMASTER. (New from 2.8.1)
    • SXF_SETTRACER - sets the calling actor to be the spawning actor's tracer. Can be combined with SXF_SETTARGET and SXF_SETMASTER. (New from 2.8.1)
    • 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. (New from 2.8.1)
    • 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. (New from 2.8.1)
    • 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. (New from 2.8.1)
    • SXF_TRANSFERROLL - transfers the calling actor's roll angle to the spawned actor. (New from 2.8.1)
    • SXF_ISTARGET - The spawned actor becomes the calling actor's target. (New from 2.8.1)
    • SXF_ISMASTER - The spawned actor becomes the calling actor's master. (New from 2.8.1)
    • SXF_ISTRACER - The spawned actor becomes the calling actor's tracer. (New from 2.8.1)
  • chance: 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

This function, when used inside of anonymous functions, returns a boolean based on whether the actor successfully spawned or not.
Note: An actor that does not spawn because of chance always counts as success. (development version cb65046 only)

Examples

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 zoffset 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"
	States
	{
	Death:
		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
		Stop
	}
}