ProcessLineOfSight: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
mNo edit summary
 
(39 intermediate revisions by 15 users not shown)
Line 1: Line 1:
{{Client function}}
{{Client function}}
__NOTOC__
__NOTOC__
This function checks if there is anything between 2 points in the world, and if there is, tells you where and what. The two positions '''must''' be within the local player's draw distance as the collision data is not loaded outside this area.
This function casts a ray between two points in the world, and tells you information about the point that was hit, if any. The two positions '''must''' be within the local player's draw distance as the collision data is not loaded outside this area, and the call will just fail as if the ray didn't hit.


This function is useful for checking for collisions and for editor-style scripts. If you wish to get an element that's positioned at a particular point on the screen, use this function combined with [[getWorldFromScreenPosition]].
This function is relatively expensive to call, so over use of this in scripts may have a detrimental effect on performance.
 
This function is useful for checking for collisions and for editor-style scripts. If you wish to find what element is positioned at a particular point on the screen, use this function combined with [[getWorldFromScreenPosition]]. If you wish to just know if something is hit, and don't care about what or where was hit, use [[isLineOfSightClear]].
 
{{Note|Due to a bug, shootThroughStuff argument does currently check for seeThroughStuff!}}
{{Note|Due to a bug, seeThroughStuff argument has no effect. It mistakenly checks for "shootThrough" surfaces and will always behave as if the argument is set to FALSE (It will never hit).}}


==Syntax==  
==Syntax==  
Return values labelled for ease of reference.
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
bool float float float element processLineOfSight ( float startX, float startY, float startZ, float endX, float endY, float endZ, [ bool checkBuildings = true, bool checkVehicles = true, bool checkPlayers = true, bool checkObjects = true, bool checkDummies = true, bool seeThroughStuff = false, bool ignoreSomeObjectsForCamera = false, bool shootThroughStuff = false, element ignoredElement = nil ] )
bool               -- hit
float float float -- hitX, hitY, hitZ
element           -- hitElement
float float float  -- normalX, normalY, normalZ
int                -- material
float              -- lighting
int                -- piece
int                -- worldModelID
float float float  -- worldModelPositionX,Y,Z
float float float  -- worldModelRotationX,Y,Z
int                -- worldLODModelID
float float        -- uvX, uvY
string            -- textureName,
string            -- frameName,
float float float  -- modelHitX, modelHitY, modelHitZ
                  processLineOfSight ( float startX, float startY, float startZ,  
                                      float endX, float endY, float endZ,  
                                      [ bool checkBuildings = true,  
                                      bool checkVehicles = true,  
                                      bool checkPlayers = true,  
                                      bool checkObjects = true,  
                                      bool checkDummies = true,  
                                      bool seeThroughStuff = false,  
                                      bool ignoreSomeObjectsForCamera = false,  
                                      bool shootThroughStuff = false,  
                                      element ignoredElement = nil,
                                      bool includeWorldModelInformation = false,
                                      bool bIncludeCarTyres = false,
                                      bool bIncludeExtraMateriaInfo = false ] )
</syntaxhighlight>  
</syntaxhighlight>  


Line 25: Line 59:
*'''checkObjects:''' Allow the line of sight to be blocked by [[Object|objects]].
*'''checkObjects:''' Allow the line of sight to be blocked by [[Object|objects]].
*'''checkDummies:''' Allow the line of sight to be blocked by GTA's internal dummies.  These are not used in the current MTA version so this argument can be set to ''false''.
*'''checkDummies:''' Allow the line of sight to be blocked by GTA's internal dummies.  These are not used in the current MTA version so this argument can be set to ''false''.
*'''seeThroughStuff:''' Allow the line of sight to be blocked by translucent game objects, e.g. glass.
*'''seeThroughStuff:''' Allow the line of sight '''pass through''' collision materials that have this flag enabled (By default material IDs 52, 55 and 66 which are some fences that you can shoot throug but still walk on them).
*'''ignoreSomeObjectsForCamera:''' Allow the line of sight to be blocked by certain objects.
*'''ignoreSomeObjectsForCamera:''' Allow the line of sight to '''pass through''' objects that have (K) property enabled in "object.dat" data file. (i.e. Most dynamic objects like boxes or barrels)
*'''shootThroughStuff:''' Allow the line of sight to be blocked by things that can be shot through
*'''shootThroughStuff:''' Allow the line of sight to '''pass through''' collision materials that have this flag enabled (By default material IDs 28, 29, 31, 32, 33, 74, 75, 76, 77, 78, 79, 96, 97, 98, 99, 100 which are exclusively sand / beach or underwater objects).
*'''ignoredElement:''' Allow the line of sight to pass through a certain specified element.  
*'''ignoredElement:''' Allow the line of sight to '''pass through''' a certain specified element. This is usually set to the object you are tracing from so it does not interfere with the results.
*'''includeWorldModelInformation :''' Include the results of hitting a world model.
*'''bIncludeCarTyres :''' Includes car tyre hits.
{{New feature/item|3.161|1.6.0|22173|
*'''bIncludeExtraMateriaInfo:''' Include the material info like UV coords, textureName, frameName and exact position hit on the model.
}}


===Returns===
===Returns===
If there is a collision, the function will return ''true'', the collision position and MTA element hit. If no element is hit, the element return value will be ''nil''. If there is no collision the function will return ''false''.
*'''hit:''' ''true'' if there is a collision, ''false'' otherwise
The other values are only filled if there is a collision, they contain ''nil'' otherwise
*'''hitX, hitY, hitZ:''' collision position
*'''hitElement:''' the MTA element hit if any, ''nil'' otherwise
*'''normalX, normalY, normalZ:''' the normal of the surface hit
*'''material:''' an integer representing the [[Material IDs|GTASA material ID]] of the surface hit when applicable (world, objects)
*'''lighting:''' a float between 0 (fully dark) and 1 (bright) representing the amount of light that the hit building surface will transfer to peds or vehicles that are in contact with it. The value can be affected by the game time of day, usually with a lower (darker) value being returned during the night.
*'''piece:''' an integer representing the part of the element hit if hitElement is a vehicle or a ped/player, ''0'' otherwise.
**For a ped/player, piece represents the body part hit:
{{BodyParts}}
**For vehicles, piece represents the vehicle part hit:
{{VehicleParts}}
*'''worldModelID:''' If includeWorldModelInformation was set to ''true'' and a world model was hit, this will contain the model ID.
*'''worldModelPositionX,Y,Z:''' If worldModelID is set, this will contain the world model position.
*'''worldModelRotationX,Y,Z:''' If worldModelID is set, this will contain the world model rotation.
*'''worldLODModelID:''' If worldModelID is set, this will contain the LOD model ID if applicable.
*'''uvX, uvY:''' If bIncludeExtraMateriaInfo is set, it contains the texture UV positions of the hit triangle of the hit entity.
*'''textureName:''' Same as above, but contains the texture name.
*'''frameName:''' Same as above, but contains the frame name. (This, for example in case of cars this is (but not limited to) a [[Vehicle Components]])
*'''modelHitX, modelHitY, modelHitZ:''' Same as above, but contains the exact position hit on the model itself (It is much more precise than the `hitX, hitY, hitZ` returned above, as those are only processed against the much more simpler collision mesh, while these are obtained from processing the visual mesh itself (the DFF))


==Example==  
==Examples==  
This example shows how you can tell what position and element the camera is looking at, up to 50 units away.
This example shows how you can tell what position and element the camera is looking at, up to 50 units away.
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
Line 47: Line 105:
end
end
</syntaxhighlight>
</syntaxhighlight>
This example shows how you can get the surface type a vehicle is on. This is useful if you want to do a script to dirt cars over time. Please note that this function doesn't count if the vehicle is streamed in or not, so expect this function to fail or return incorrect values on unloaded vehicles.
<syntaxhighlight lang="lua">
function getSurfaceVehicleIsOn(vehicle)
    if isElement(vehicle) and (isVehicleOnGround(vehicle) or isElementInWater(vehicle)) then -- Is an element and is touching any surface?
        local cx, cy, cz = getElementPosition(vehicle) -- Get the position of the vehicle
        local gz = getGroundPosition(cx, cy, cz) - 0.001 -- Get the Z position of the ground the vehicle is on (-0.001 because of processLineOfSight)
        local hit, _, _, _, _, _, _, _, surface = processLineOfSight(cx, cy, cz, cx, cy, gz) -- This will get the material of the thing the car is standing on
        if hit then
            return surface -- If everything is correct, stop executing this function and return the surface type
        end
    end
    return false -- If something isn't correct, return false
end
</syntaxhighlight>
==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04273|''bIncludeCarTyres'' argument added}}
{{ChangelogItem|1.3.0-9.04273|''worldModelID'' return value fixed}}
{{ChangelogItem|1.3.0-9.04405|''lighting'' return value fixed}}
{{ChangelogItem|1.6.0-9.22173|''bIncludeExtraMateriaInfo '' argument added}}


==See Also==
==See Also==
{{Client world functions}}
{{Client world functions}}

Latest revision as of 23:00, 8 June 2024

This function casts a ray between two points in the world, and tells you information about the point that was hit, if any. The two positions must be within the local player's draw distance as the collision data is not loaded outside this area, and the call will just fail as if the ray didn't hit.

This function is relatively expensive to call, so over use of this in scripts may have a detrimental effect on performance.

This function is useful for checking for collisions and for editor-style scripts. If you wish to find what element is positioned at a particular point on the screen, use this function combined with getWorldFromScreenPosition. If you wish to just know if something is hit, and don't care about what or where was hit, use isLineOfSightClear.

[[{{{image}}}|link=|]] Note: Due to a bug, shootThroughStuff argument does currently check for seeThroughStuff!
[[{{{image}}}|link=|]] Note: Due to a bug, seeThroughStuff argument has no effect. It mistakenly checks for "shootThrough" surfaces and will always behave as if the argument is set to FALSE (It will never hit).

Syntax

Return values labelled for ease of reference. 

bool               -- hit
float float float  -- hitX, hitY, hitZ
element            -- hitElement
float float float  -- normalX, normalY, normalZ
int                -- material
float              -- lighting
int                -- piece
int                -- worldModelID
float float float  -- worldModelPositionX,Y,Z
float float float  -- worldModelRotationX,Y,Z
int                -- worldLODModelID
float float        -- uvX, uvY
string             -- textureName,
string             -- frameName,
float float float  -- modelHitX, modelHitY, modelHitZ
                  processLineOfSight ( float startX, float startY, float startZ, 
                                       float endX, float endY, float endZ, 
                                       [ bool checkBuildings = true, 
                                       bool checkVehicles = true, 
                                       bool checkPlayers = true, 
                                       bool checkObjects = true, 
                                       bool checkDummies = true, 
                                       bool seeThroughStuff = false, 
                                       bool ignoreSomeObjectsForCamera = false, 
                                       bool shootThroughStuff = false, 
                                       element ignoredElement = nil,
                                       bool includeWorldModelInformation = false,
                                       bool bIncludeCarTyres = false,
                                       bool bIncludeExtraMateriaInfo = false ] )

Required Arguments

  • startX: The start x position
  • startY: The start y position
  • startZ: The start z position
  • endX: The end x position
  • endY: The end y position
  • endZ: The end z position

Optional Arguments

NOTE: When using optional arguments, you might need to supply all arguments before the one you wish to use. For more information on optional arguments, see optional arguments.

  • checkBuildings: Allow the line of sight to be blocked by GTA's internally placed buildings, i.e. the world map.
  • checkVehicles: Allow the line of sight to be blocked by vehicles.
  • checkPlayers: Allow the line of sight to be blocked by players.
  • checkObjects: Allow the line of sight to be blocked by objects.
  • checkDummies: Allow the line of sight to be blocked by GTA's internal dummies. These are not used in the current MTA version so this argument can be set to false.
  • seeThroughStuff: Allow the line of sight pass through collision materials that have this flag enabled (By default material IDs 52, 55 and 66 which are some fences that you can shoot throug but still walk on them).
  • ignoreSomeObjectsForCamera: Allow the line of sight to pass through objects that have (K) property enabled in "object.dat" data file. (i.e. Most dynamic objects like boxes or barrels)
  • shootThroughStuff: Allow the line of sight to pass through collision materials that have this flag enabled (By default material IDs 28, 29, 31, 32, 33, 74, 75, 76, 77, 78, 79, 96, 97, 98, 99, 100 which are exclusively sand / beach or underwater objects).
  • ignoredElement: Allow the line of sight to pass through a certain specified element. This is usually set to the object you are tracing from so it does not interfere with the results.
  • includeWorldModelInformation : Include the results of hitting a world model.
  • bIncludeCarTyres : Includes car tyre hits.
ADDED/UPDATED IN VERSION 1.6.0 r22173:
  • bIncludeExtraMateriaInfo: Include the material info like UV coords, textureName, frameName and exact position hit on the model.

Returns

  • hit: true if there is a collision, false otherwise

The other values are only filled if there is a collision, they contain nil otherwise

  • hitX, hitY, hitZ: collision position
  • hitElement: the MTA element hit if any, nil otherwise
  • normalX, normalY, normalZ: the normal of the surface hit
  • material: an integer representing the GTASA material ID of the surface hit when applicable (world, objects)
  • lighting: a float between 0 (fully dark) and 1 (bright) representing the amount of light that the hit building surface will transfer to peds or vehicles that are in contact with it. The value can be affected by the game time of day, usually with a lower (darker) value being returned during the night.
  • piece: an integer representing the part of the element hit if hitElement is a vehicle or a ped/player, 0 otherwise.
    • For a ped/player, piece represents the body part hit:
  • 3: Torso
  • 4: Ass
  • 5: Left Arm
  • 6: Right Arm
  • 7: Left Leg
  • 8: Right Leg
  • 9: Head
    • For vehicles, piece represents the vehicle part hit:
  • 0: Frame
  • 2: Trunk
  • 3: Hood
  • 4: Rear
  • 5: Front left door
  • 6: Front right door
  • 7: Rear left door
  • 8: Rear right door
  • 13: Front Left tyre
  • 14: Front Right tyre
  • 15: Back Left tyre
  • 16: Back Right tyre

(Other potential IDs haven't been documented yet and might depend on vehicle model)

  • worldModelID: If includeWorldModelInformation was set to true and a world model was hit, this will contain the model ID.
  • worldModelPositionX,Y,Z: If worldModelID is set, this will contain the world model position.
  • worldModelRotationX,Y,Z: If worldModelID is set, this will contain the world model rotation.
  • worldLODModelID: If worldModelID is set, this will contain the LOD model ID if applicable.
  • uvX, uvY: If bIncludeExtraMateriaInfo is set, it contains the texture UV positions of the hit triangle of the hit entity.
  • textureName: Same as above, but contains the texture name.
  • frameName: Same as above, but contains the frame name. (This, for example in case of cars this is (but not limited to) a Vehicle Components)
  • modelHitX, modelHitY, modelHitZ: Same as above, but contains the exact position hit on the model itself (It is much more precise than the `hitX, hitY, hitZ` returned above, as those are only processed against the much more simpler collision mesh, while these are obtained from processing the visual mesh itself (the DFF))

Examples

This example shows how you can tell what position and element the camera is looking at, up to 50 units away. 

local w, h = guiGetScreenSize ()
local tx, ty, tz = getWorldFromScreenPosition ( w/2, h/2, 50 )
local px, py, pz = getCameraMatrix()
hit, x, y, z, elementHit = processLineOfSight ( px, py, pz, tx, ty, tz )
if hit then
    outputChatBox ( "Looking at " .. x .. ", " .. y .. ", " ..  z )
    if elementHit then
        outputChatBox ( "Hit element " .. getElementType(elementHit) )
    end
end

This example shows how you can get the surface type a vehicle is on. This is useful if you want to do a script to dirt cars over time. Please note that this function doesn't count if the vehicle is streamed in or not, so expect this function to fail or return incorrect values on unloaded vehicles. 

function getSurfaceVehicleIsOn(vehicle)
    if isElement(vehicle) and (isVehicleOnGround(vehicle) or isElementInWater(vehicle)) then -- Is an element and is touching any surface?
        local cx, cy, cz = getElementPosition(vehicle) -- Get the position of the vehicle
        local gz = getGroundPosition(cx, cy, cz) - 0.001 -- Get the Z position of the ground the vehicle is on (-0.001 because of processLineOfSight)
        local hit, _, _, _, _, _, _, _, surface = processLineOfSight(cx, cy, cz, cx, cy, gz) -- This will get the material of the thing the car is standing on
        if hit then
            return surface -- If everything is correct, stop executing this function and return the surface type
        end
    end
    return false -- If something isn't correct, return false
end

Changelog

Version Description
1.3.0-9.04273 bIncludeCarTyres argument added
1.3.0-9.04273 worldModelID return value fixed
1.3.0-9.04405 lighting return value fixed
1.6.0-9.22173 bIncludeExtraMateriaInfo argument added

See Also



Retrieved from "https://wiki.multitheftauto.com/wiki/ProcessLineOfSight?oldid=79555"