LineTrace

From ZDoom Wiki
Jump to navigation Jump to search
Note: This feature is for ZScript only.


bool LineTrace (double angle, double distance, double pitch[, int flags[, double offsetz[, double offsetforward[, double offsetside[, out FLineTraceData data]]]]])

Usage

Draws a hitscan line at the specified angle, pitch and range (distance). The line originates from the calling actor's exact position, which means that offsetz must be used if this is intended to represent an attack like a gunshot.

Parameters

  • angle - The absolute angle of the direction to fire the line.
  • distance - The maximum range the line is allowed to travel.
  • pitch - The absolute pitch of the direction to fire the line.
  • flags - Default is 0.
  • TRF_ABSPOSITION — makes offsets absolute coordinates.
  • TRF_ABSOFFSET — makes the x (forward) and y (side) offsets independent from actor rotation.
  • TRF_THRUSPECIES — passes through all actors sharing the caller's species.
  • TRF_THRUACTORS — passes through all actors in general. Useful for when you only need map geometry.
  • TRF_THRUBLOCK — passes through all lines set to "block everything".
  • TRF_THRUHITSCAN — passes through all lines set to "block hitscan".
  • TRF_NOSKY — treats hitting a sky texture as not hitting anything at all.
  • TRF_ALLACTORS — may stop at any actor, even if it's not shootable or solid (this still excludes actors not in the blockmap e.g. projectiles).
  • TRF_SOLIDACTORS — will also stop at actors that aren't shootable but still solid.
  • TRF_BLOCKUSE — stops at lines set to "block use".
  • TRF_BLOCKSELF — stops at lines that would normally block the calling actor (e.g. if called from a player, stop at impassable or "block players" lines).
  • offsetz - Default is 0. The amount to offset the height of the line's origin from the caller's position.
  • offsetforward - Default is 0. The amount to offset the line's origin in the direction the caller is facing.
  • offsetside - Default is 0. The amount to offset the line's origin to the sides of the caller.
  • data - Default is null. Stores information about the hitscan after the check is performed.

Return value

The function's actual return is true or false, indicating whether the line hit anything.

Much more significantly, this function lets you write information to an FLineTraceData pointer that can be accessed for detailed information about what the line hit and where.

Note: These values are only relevant if the return result of the function was true. If the function returns false these values will still be set to the last thing the line hit, even if that thing was ignored. For example, Actor hits will still be recorded here even with the TRF_THRUACTORS flag set. Always check the line actually hit something before using these values.

The struct contains the following pointers:

  • Actor HitActor - The actor that got hit, if any.
  • Line HitLine - The line that got hit, if any.
  • Sector HitSector - The sector in which the impact occurred or the trace terminated.
  • F3DFloor Hit3DFloor - The 3D floor that got hit, if any.
  • TextureID HitTexture - The texture of the surface that got hit, if any.
  • Vector3 HitLocation - The absolute position in the map in which the impact occurred or the trace terminated.
  • Vector3 HitDir - A unit vector representing the direction in which the trace was traveling when it terminated.
  • double Distance - The total distance traveled by the trace, whether it hit anything or not.
  • int NumPortals - The number of portals the trace crossed while traveling.
  • int LineSide - Which side of the line the trace hit, if any. Can be one of the following constants:
  • Line.front
  • Line.back
  • int LinePart - Which part of the line the trace hit, if any. Can be one of the following constants:
  • Side.top
  • Side.mid (always if a 3D floor was hit)
  • Side.bottom
  • int SectorPlane - Whether the trace hit the ceiling or floor, if either. Can be one of the following constants:
  • Sector.floor
  • Sector.ceiling
  • int HitType - What the trace hit, if anything. Can be one of the following constants:
  • TRACE_HitNone
  • TRACE_HitFloor (includes hitting the top of a 3D floor)
  • TRACE_HitCeiling (includes hitting the bottom of a 3D floor)
  • TRACE_HitWall
  • TRACE_HitActor
  • TRACE_CrossingPortal
  • TRACE_HasHitSky (unused)

Examples

This item when used will hit any switch in front of the player within about 50 metres, provided nothing is between the player and the line.

class RemoteSwitcher : CustomInventory
{
    Default
    {
            +inventory.invbar
            inventory.icon "CELLA0"; //substitute your own graphic
    }
    States
    {
    Use:
        TNT1 A 0
        {
            FLineTraceData RemoteRay;
            bool hit = LineTrace(
               angle,
               2048,
               pitch,
               offsetz: height-12,
               data: RemoteRay
            );

            if (hit && RemoteRay.HitType == TRACE_HitWall)
            {
               RemoteRay.HitLine.Activate(self, 0, SPAC_Use);
            }
        }
        Fail;
    }
}