cLineBlockTracer


Index:
Articles
Classes
Hooks

Quick navigation:
BannerPattern
BossBarColor
BossBarDivisionType
cArrowEntity
cBeaconEntity
cBedEntity
cBlockArea
cBlockEntity
cBlockEntityWithItems
cBlockInfo
cBoat
cBoundingBox
cBrewingstandEntity
cChatColor
cChestEntity
cChunkDesc
cClientHandle
cColor
cCommandBlockEntity
cCompositeChat
cCraftingGrid
cCraftingRecipe
cCryptoHash
cCuboid
cDispenserEntity
cDropperEntity
cDropSpenserEntity
cEnchantments
cEnderCrystal
cEntity
cEntityEffect
cExpBottleEntity
cExpOrb
cFallingBlock
cFile
cFireChargeEntity
cFireworkEntity
cFloater
cFlowerPotEntity
cFurnaceEntity
cGhastFireballEntity
cHangingEntity
cHopperEntity
cIniFile
cInventory
cItem
cItemFrame
cItemGrid
cItems
cJson
cJukeboxEntity
cLeashKnot
cLineBlockTracer
cLuaWindow
cMap
cMapManager
cMobHeadEntity
cMobSpawnerEntity
cMojangAPI
cMonster
cNetwork
cNoteEntity
cObjective
cPainting
cPawn
cPickup
cPlayer
cPlugin
cPluginLua
cPluginManager
cProjectileEntity
cRankManager
cRoot
cScoreboard
cServer
cServerHandle
cSignEntity
cSplashPotionEntity
cStringCompression
cTCPLink
cTeam
cThrownEggEntity
cThrownEnderPearlEntity
cThrownSnowballEntity
cTNTEntity
cUDPEndpoint
cUrlClient
cUrlParser
CustomStatistic
cUUID
cWebAdmin
cWindow
cWitherSkullEntity
cWorld
EffectID
HTTPFormData
HTTPRequest
HTTPTemplateRequest
ItemCategory
lxp
SmokeDirection
sqlite3
StatisticsManager
TakeDamageInfo
tolua
Vector3d
Vector3f
Vector3i
Globals

Contents


cLineBlockTracer class

This class provides an easy-to-use interface for tracing lines through individual blocks in the world. It can either be used to call the provided callbacks according to what events it encounters along the way, or there are shortcut functions used for the most popular tracing reasons - line of sight and solid hits.


Constants

The following constants are used to speficy which blocks are see-through when tracing a LineOfSight trace. Add them together to make up the Sight parameter.

NameValueNotes
losAir 1 LineOfSight tracing can 'see' through air blocks.
losLava 4 LineOfSight tracing can 'see' through lava blocks.
losWater 2 LineOfSight tracing can 'see' through water blocks.



Functions

NameParametersReturn valueNotes
FirstSolidHitTrace
WorldcWorld
StartVector3d
EndVector3d
HasHitSolidboolean
HitCoordsVector3d
HitBlockCoordsVector3i
HitBlockFaceeBlockFace
(STATIC) If the specified line hits a solid block, return true and the coordinates / face of the first such solid block hit. Returns false if there's no solid block on that line.
FirstSolidHitTrace
WorldcWorld
StartXnumber
StartYnumber
StartZnumber
EndXnumber
EndYnumber
EndZnumber
HasHitSolidboolean
HitCoordsVector3d
HitBlockCoordsVector3i
HitBlockFaceeBlockFace
(STATIC) If the specified line hits a solid block, return true and the coordinates / face of the first such solid block hit. Returns false if there's no solid block on that line.
LineOfSightTrace
WorldcWorld
StartXnumber
StartYnumber
StartZnumber
EndXnumber
EndYnumber
EndZnumber
Sightnumber
CanSeeboolean
(STATIC) Returns true if the two points specified are within line of sight of each other. The Sight parameter specifies which blocks are considered transparent for the trace, it is a combination of losXXX values added together.
LineOfSightTrace
WorldcWorld
StartVector3d
EndVector3d
Sightnumber
CanSeeboolean
(STATIC) Returns true if the two points specified are within line of sight of each other. The Sight parameter specifies which blocks are considered transparent for the trace, it is a combination of losXXX values added together.
Trace
WorldcWorld
Callbackstable
StartVector3d
EndVector3d
boolean
(STATIC) Performs the trace on the specified line. Returns true if the entire trace was processed (no callback returned true)
Trace
WorldcWorld
Callbackstable
StartXnumber
StartYnumber
StartZnumber
EndXnumber
EndYnumber
EndZnumber
boolean
(STATIC) (OBSOLETE, use the Vector3-based overload instead) Performs the trace on the specified line. Returns true if the entire trace was processed (no callback returned true)

Callbacks

The Callbacks in the Trace() function is a table that contains named functions. Cuberite will call individual functions from that table for the events that occur on the line - hitting a block, going out of valid world data etc. The following table lists all the available callbacks. If the callback function is not defined, Cuberite skips it. Each function can return a bool value, if it returns true, the tracing is aborted and Trace() returns false.
Note: The folowing can only be used when using the Vector3-based Trace() function. When using the number-based overload, the callbacks receive number-based coordinates (see Deprecated Callbacks below).

NameParametersNotes
OnNextBlockBlockPos, BlockType, BlockMeta, EntryFace Called when the ray hits a new valid block. The block type and meta is given. EntryFace is one of the BLOCK_FACE_ constants indicating which "side" of the block got hit by the ray.
OnNextBlockNoDataBlockPos, EntryFace Called when the ray hits a new block, but the block is in an unloaded chunk - no valid data is available. Only the coords and the entry face are given.
OnOutOfWorldBlockPos Called when the ray goes outside of the world (Y-wise); the coords specify the exact exit point. Note that for other paths than lines (considered for future implementations) the path may leave the world and go back in again later, in such a case this callback is followed by OnIntoWorld() and further OnNextBlock() calls.
OnIntoWorldBlockPos Called when the ray enters the world (Y-wise); the coords specify the exact entry point.
OnNoMoreHits  Called when the path is sure not to hit any more blocks. This is the final callback, no more callbacks are called after this function. Unlike the other callbacks, this function doesn't have a return value.
OnNoChunk  Called when the ray enters a chunk that is not loaded. This usually means that the tracing is aborted. Unlike the other callbacks, this function doesn't have a return value.

Deprecated Callbacks

When using the deprecated number-based Trace function, Cuberite will instead assume the following signatures for the callbacks:

NameParametersNotes
OnNextBlockBlockX, BlockY, BlockZ, BlockType, BlockMeta, EntryFace Called when the ray hits a new valid block. The block type and meta is given. EntryFace is one of the BLOCK_FACE_ constants indicating which "side" of the block got hit by the ray.
OnNextBlockNoDataBlockX, BlockY, BlockZ, EntryFace Called when the ray hits a new block, but the block is in an unloaded chunk - no valid data is available. Only the coords and the entry face are given.
OnOutOfWorldX, Y, Z Called when the ray goes outside of the world (Y-wise); the coords specify the exact exit point. Note that for other paths than lines (considered for future implementations) the path may leave the world and go back in again later, in such a case this callback is followed by OnIntoWorld() and further OnNextBlock() calls.
OnIntoWorldX, Y, Z Called when the ray enters the world (Y-wise); the coords specify the exact entry point.

Example

The following example is taken from the Debuggers plugin. It is a command handler function for the "/spidey" command that creates a line of cobweb blocks from the player's eyes up to 50 blocks away in the direction they're looking, but only through the air.

function HandleSpideyCmd(a_Split, a_Player)
	local World = a_Player:GetWorld();

	local Callbacks = {
		OnNextBlock = function(a_BlockPos, a_BlockType, a_BlockMeta)
			if (a_BlockType ~= E_BLOCK_AIR) then
				-- abort the trace
				return true;
			end
			World:SetBlock(a_BlockPos, E_BLOCK_COBWEB, 0);
		end
	};

	local EyePos = a_Player:GetEyePosition();
	local LookVector = a_Player:GetLookVector();
	LookVector:Normalize();  -- Make the vector 1 m long

	-- Start cca 2 blocks away from the eyes
	local Start = EyePos + LookVector + LookVector;
	local End = EyePos + LookVector * 50;

	cLineBlockTracer.Trace(World, Callbacks, Start, End);

	return true;
end

Generated by APIDump on 2022-10-28 17:00:47, Build ID Unknown, Commit approx: 21ec3ebe26bff24b5fc6d96f86a441c9c9628247