Skip to main content
The Block class represents a single block in the RollingQuest game world — the fundamental building unit that the ball rolls across. Scripts attached to a block receive it as self in hooks such as OnBallRoll and OnBallLand. From a Block reference you can inspect every side and neighboring block, read movement state, toggle tangibility, and mark the block as visited.
Related types: Each side of a block is a Side instance. The block’s grid position is described by a BlockSlot. The raw data representation used at level-build time is BlockData.

​
Identity

PropertyTypeRead-onlyDescription
typeEntityType✅Always EntityType.Block (1).
idinteger✅Unique numeric identifier of the block.
namestring✅Name of the block (set in the editor).
tagstring✅Tag used for grouping and scripted lookup.

​
Transform

PropertyTypeRead-onlyDescription
positionVector3✅World-space position of the block’s centre.
rotationQuaternion✅World-space rotation of the block.
slotBlockSlot✅Grid position (x, y, z) of the block within its section.

​
Sides

Each face of the block is exposed as a direct property and also via getSide.
PropertyTypeRead-onlyDescription
upSideSide✅The upward-facing side.
downSideSide✅The downward-facing side.
leftSideSide✅The left-facing side.
rightSideSide✅The right-facing side.
frontSideSide✅The front-facing side.
backSideSide✅The back-facing side.
sidesSide[]✅Array of all six sides.

​
Neighbors

PropertyTypeRead-onlyDescription
neighborsBlock[]✅All touching blocks (sharing a full face).
adjacentBlock[]✅All adjacent blocks (including diagonal adjacency).
upNeighborBlock✅Block directly above.
downNeighborBlock✅Block directly below.
leftNeighborBlock✅Block to the left.
rightNeighborBlock✅Block to the right.
frontNeighborBlock✅Block in front.
backNeighborBlock✅Block behind.

​
State

PropertyTypeRead-onlyDescription
sectionstring✅ID of the level section that contains this block.
isVisitedboolean✅true once the ball has rolled onto this block.
isMovingboolean✅true while the block is in motion (e.g. elevator).
movingSpeednumber✅Speed of the block while it is moving.
movingDirectionVector3✅Normalised direction the block is moving toward.
isInMovingRestboolean✅true when a moving block has reached a rest waypoint.
intangibleboolean❌Set to true to make the block passable; false to restore solidity.
propertiesElementPropertyPool✅Custom property pool attached to the block.
localDataRawLocalData✅Per-instance local data store for this block.

​
Methods

​
getSide

--- @param face Face
--- @return Side
function Block:getSide(face)
Returns the Side corresponding to the given Face enum value. Useful when the face is determined at runtime.

​
markAsVisited

function Block:markAsVisited()
Programmatically marks the block as visited without requiring the ball to roll over it.

​
enable / disable

function Block:enable()
function Block:disable()
Enable or disable the block entirely. A disabled block is removed from play until re-enabled.

​
Type-cast helpers

Call these to narrow a generic entity reference to a specific type. Each throws an error if the cast is invalid. 
function Block:asLevel()      -- returns Level
function Block:asBlock()      -- returns Block
function Block:asSide()       -- returns Side
function Block:asItem()       -- returns Item
function Block:asEnemy()      -- returns Enemy
function Block:asBall()       -- returns Ball
function Block:asDecoration() -- returns Decoration

​
BlockData

BlockData is the raw, mutable representation of a block used when building or modifying level data (e.g. in OnLevelLoad). It holds the grid coordinates x, y, z, a SideData for each of the six faces (up, down, left, right, front, back), and the scripting fields template, scriptRef, scriptTag, scriptVars, and properties. Key BlockData methods:
  • getSides() — returns a table of all six SideData values in order: Up, Down, Left, Right, Front, Back.
  • getSidesIterator() — returns an iterator-compatible version of the same sequence.
  • clear() — resets the block data to empty defaults.

​
BlockSlot

BlockSlot identifies a block’s integer grid coordinate (x, y, z) within a section. You can obtain the world-space Vector3 from slot.position. Use BlockSlot.new(x, y, z) to construct a slot, and slot:translate(dx, dy, dz) or slot:translateFromBasis(basis, dx, dy, dz) to compute offsets.

​
Usage Example

The OnBallRoll hook fires each time the ball moves onto a new side. The example below disables a block when it has been visited three times by incrementing a counter stored in localData: 
function OnBallRoll(self, ball)
    -- self is a Block
    local data = self.localData
    local count = (data:get("rollCount") or 0) + 1
    data:set("rollCount", count)

    if count >= 3 then
        self:disable()
    end

    -- Log the block's grid position
    local slot = self.slot
    Log.info("Ball rolled on block at " .. slot.x .. "," .. slot.y .. "," .. slot.z)
end