Raycast

A global API which provides functions for raycasting

warning

This page is a WIP. It contains all the information in Figura's documentation but we're working on adding more helpful descriptions.

---

aabb()

Raycasts based on a start position, an end position, and an array of Axis Aligned Bounding Boxes defined by the player.

AABBs are encoded as a table with indicies 1 and 2 being a Vector3.

{vec(0,0,0),vec(1,0.5,1)} is a valid AABB, with { {vec(0,0,0),vec(1,0.5,1)}, {vec(0,0.5,0.5),vec(1,1,1)} } being a valid AABB array.

This function returns the AABB table that was hit, the exact position hit as a Vector3, the side of the AABB hit as a string or nil if inside an AABB, and the index of the AABB that was hit in the array

Overload 1

aabb(startpos, endpos, aabbs)

Parameters:

Name	Type	Description	Default
start	Vector3	-	-
end	Vector3	-	-
aabbs	Table	-	-

Returns:

Type	Description
Table	Hit AABB
Vector3	Hit pos
String	Hit side or nil if inside the AABB
Integer	Integer of hit AABB

Overload 2

aabb(startX, startY, startZ, endpos, aabbs)

Parameters:

Name	Type	Description	Default
startX	Number	-	-
startY	Number	-	-
startZ	Number	-	-
end	Vector3	-	-
aabbs	Table	-	-

Returns:

Type	Description
Table	Hit AABB
Vector3	Hit pos
String	Hit side or nil if inside the AABB
Integer	Integer of hit AABB

Overload 3

aabb(startpos, endX, endY, endZ, aabbs)

Parameters:

Name	Type	Description	Default
start	Vector3	-	-
endX	Number	-	-
endY	Number	-	-
endZ	Number	-	-
aabbs	Table	-	-

Returns:

Type	Description
Table	Hit AABB
Vector3	Hit pos
String	Hit side or nil if inside the AABB
Integer	Integer of hit AABB

Overload 4

aabb(startX, startY, startZ, endX, endY, endZ, aabbs)

Parameters:

Name	Type	Description	Default
startX	Number	-	-
startY	Number	-	-
startZ	Number	-	-
endX	Number	-	-
endY	Number	-	-
endZ	Number	-	-
aabbs	Table	-	-

Returns:

Type	Description
Table	Hit AABB
Vector3	Hit pos
String	Hit side or nil if inside the AABB
Integer	Integer of hit AABB

Example:

local eyePos = player:getPos() + vec(0, player:getEyeHeight(), 0)
local eyeEnd = eyePos + (player:getLookDir() * 20)
local hitLocation = { { vec(0, 0, 0), vec(1, 1, 1) } } -- this is the block location of 0,0,0 in the world
local aabb, hitPos, side, aabbHitIndex = raycast:aabb(eyePos, eyeEnd, hitLocation)

---

block()

Raycasts a Block in the world.

If successful, returns the BlockState hit, the exact world position hit as a Vector3, and the side of the block that was hit.

When unsuccessful, returns nil.

blockCastType and fluidCastType determine how the raycast handles block shapes and fluids.

Will default to "COLLIDER" and "NONE" when nil

Overload 1

block(startpos, endpos, blockCastType, fluidCastType)

Parameters:

Name	Type	Description	Default
start	Vector3	-	-
end	Vector3	-	-
blockCastType	String	-	-
fluidCastType	String	-	-

Returns:

Type	Description
BlockState	Hit block
Vector3	Hit position
String	Hit block face

Overload 2

block(startX, startY, startZ, endpos, blockCastType, fluidCastType)

Parameters:

Name	Type	Description	Default
startX	Number	-	-
startY	Number	-	-
startZ	Number	-	-
end	Vector3	-	-
blockCastType	String	-	-
fluidCastType	String	-	-

Returns:

Type	Description
BlockState	Hit block
Vector3	Hit position
String	Hit block face

Overload 3

block(startpos, endX, endY, endZ, blockCastType, fluidCastType)

Parameters:

Name	Type	Description	Default
start	Vector3	-	-
endX	Number	-	-
endY	Number	-	-
endZ	Number	-	-
blockCastType	String	-	-
fluidCastType	String	-	-

Returns:

Type	Description
BlockState	Hit block
Vector3	Hit position
String	Hit block face

Overload 4

block(startX, startY, startZ, endX, endY, endZ, blockCastType, fluidCastType)

Parameters:

Name	Type	Description	Default
startX	Number	-	-
startY	Number	-	-
startZ	Number	-	-
endX	Number	-	-
endY	Number	-	-
endZ	Number	-	-
blockCastType	String	-	-
fluidCastType	String	-	-

Returns:

Type	Description
BlockState	Hit block
Vector3	Hit position
String	Hit block face

Example:

local eyePos = player:getPos() + vec(0, player:getEyeHeight(), 0)
local eyeEnd = eyePos + (player:getLookDir() * 20)
local block, hitPos, side = raycast:block(eyePos, eyeEnd)

---

entity()

Raycasts an Entity in the world

If successful, returns the EntityAPI hit and the exact world position hit as a Vector3.

When unsuccessful, returns nil.

predicate is a function that prevents specific entities from being raycasted.

Takes in a single EntityAPI object. Return true for valid entities, false for invalid.

Marks all entities as valid when nil

Overload 1

entity(startpos, endpos, predicate)

Parameters:

Name	Type	Description	Default
start	Vector3	-	-
end	Vector3	-	-
predicate	Function	-	-

Returns:

Type	Description
Entity	Hit entity
Vector3	Hit position

Overload 2

entity(startX, startY, startZ, endpos, predicate)

Parameters:

Name	Type	Description	Default
startX	Number	-	-
startY	Number	-	-
startZ	Number	-	-
end	Vector3	-	-
predicate	Function	-	-

Returns:

Type	Description
Entity	Hit entity
Vector3	Hit position

Overload 3

entity(startpos, endX, endY, endZ, predicate)

Parameters:

Name	Type	Description	Default
start	Vector3	-	-
endX	Number	-	-
endY	Number	-	-
endZ	Number	-	-
predicate	Function	-	-

Returns:

Type	Description
Entity	Hit entity
Vector3	Hit position

Overload 4

entity(startX, startY, startZ, endX, endY, endZ, predicate)

Parameters:

Name	Type	Description	Default
startX	Number	-	-
startY	Number	-	-
startZ	Number	-	-
endX	Number	-	-
endY	Number	-	-
endZ	Number	-	-
predicate	Function	-	-

Returns:

Type	Description
Entity	Hit entity
Vector3	Hit position

Example:

local eyePos = player:getPos() + vec(0, player:getEyeHeight(), 0)
local eyeEnd = eyePos + (player:getLookDir() * 20)
local entity, hitPos = raycast:entity(eyePos, eyeEnd,function(x) -- x is the entity hit by the raycast
    if x == player then -- if the entity hit is the player
        return false -- don't include the player in the results
    else 
        return true 
    end 
end)

---