Side Class — Block Face Entity Properties Reference

The Side class represents one of the six faces of a Block. Every side has its own identity, spatial vectors, and may hold an item or a decoration. Scripts attached to a side receive it as self in hooks such as OnBallRoll, and the ball’s current ground side is always available via ball.currentGroundSide. RollingQuest defines many typed sub-classes of Side — for example SideButton or SideLaser — each inheriting all base properties while adding their own.

Properties

Identity

Property	Type	Read-only	Description
`type`	`EntityType`	✅	Always `EntityType.Side` (`2`).
`id`	`integer`	✅	Unique numeric identifier of this side.
`name`	`string`	✅	Name of the side, taken from its template.
`tag`	`string`	✅	Tag used for scripted lookup and grouping.

Transform

Property	Type	Read-only	Description
`position`	`Vector3`	✅	World-space position of the side’s origin corner.
`rotation`	`Quaternion`	✅	World-space rotation of the side.
`centerPosition`	`Vector3`	✅	World-space position of the side’s centre point.
`normalVector`	`Vector3`	✅	Outward-pointing normal vector of the side.
`tangentVector`	`Vector3`	✅	Tangent vector lying in the plane of the side.
`bitangentVector`	`Vector3`	✅	Bitangent vector perpendicular to both normal and tangent.

Geometry

Property	Type	Read-only	Description
`block`	`Block`	✅	The parent block this side belongs to.
`blockSlot`	`BlockSlot`	✅	Grid slot of the parent block.
`face`	`Face`	✅	Which face of the block this side occupies.
`faceName`	`string`	✅	Human-readable name of the face (e.g. `"Up"`, `"Front"`).
`section`	`string`	✅	ID of the level section that contains this side.

Rules

Property	Type	Read-only	Description
`isIntangible`	`boolean`	✅	`true` when the side has no physical collision.
`hasJumpBan`	`boolean`	✅	`true` when jumping is prohibited while on this side.
`hasMoveBan`	`boolean`	✅	`true` when movement is prohibited while on this side.

Attachments

Property	Type	Read-only	Description
`item`	`Item`	✅	The item placed on this side, or `nil`.
`hasItem`	`boolean`	✅	`true` when an item is present on this side.
`decoration`	`Decoration`	✅	The decoration placed on this side, or `nil`.
`hasDecoration`	`boolean`	✅	`true` when a decoration is present on this side.
`properties`	`ElementPropertyPool`	✅	Custom property pool attached to the side.
`localData`	`RawLocalData`	✅	Per-instance local data store for this side.

Methods

getAssociatedBasis

Returns the Basis that corresponds to a ball standing on this side at a given orientation. Three overloads are available:

--- @param orientation Orientation
--- @return Basis
function Side:getAssociatedBasis(orientation)

--- @param orientation integer
--- @return Basis
function Side:getAssociatedBasis(orientation)

--- @return Basis
function Side:getAssociatedBasis()  -- uses default orientation

isDirectionBlocked

--- @param orientation Orientation
--- @return boolean
function Side:isDirectionBlocked(orientation)

--- @param orientation integer
--- @return boolean
function Side:isDirectionBlocked(orientation)

Returns true when the given orientation is a blocked movement direction for the ball on this side.

Type-cast helpers

Use these to narrow a generic entity reference to a concrete type. Each throws an error if the cast is invalid.

function Side:asLevel()      -- returns Level
function Side:asBlock()      -- returns Block
function Side:asSide()       -- returns Side
function Side:asItem()       -- returns Item
function Side:asEnemy()      -- returns Enemy
function Side:asBall()       -- returns Ball
function Side:asDecoration() -- returns Decoration

SideData

SideData is the raw, mutable representation used when constructing level data (e.g. in OnLevelLoad). It carries the optional template, scriptRef, scriptTag, scriptVars, and properties fields, plus references to an ItemData and a DecorationData. The boolean flags hasOwnTemplate, hasValidItem, and hasValidDecoration let you check which optional fields are populated. Key SideData methods: clearItem(), clearDecoration(), clear().

Side Subtypes

The following concrete sub-classes all inherit every property and method from Side. You receive the most-specific type automatically when accessing sides at runtime.

Sub-class	Description
`SideNormal`	A plain, unremarkable side with no special behaviour.
`SideButton`	A pressable button that triggers signals when the ball rolls over it.
`SideCheckpoint`	Saves the ball’s respawn position when touched.
`SideExit`	Ends the level or transitions to the next section when reached.
`SideJumpPad`	Launches the ball into the air on contact.
`SideLaser`	Fires a laser beam that kills the ball on contact.
`SideMagnet`	Pulls or pushes the ball with a magnetic force.
`SideStaticSpikes`	Permanently extended spikes that destroy the ball.
`SideRetractableSpike`	Spikes that extend and retract on a timed cycle.
`SideSensorSpikes`	Spikes that extend when the ball is detected nearby.
`SidePatternSpike`	Spikes that follow a programmed sequence pattern.
`SideTrampoline`	Bounces the ball upward on contact.
`SideVent`	Propels the ball in a fixed direction with air pressure.
`SideIcy`	Reduces friction, causing the ball to slide.
`SideBurned`	Applies a burning effect to the ball on contact.
`SideOil`	Slows the ball and may interact with fire sides.
`SideSand`	Slows movement with a sandy surface effect.
`SidePlasma`	Applies an energy-based hazard to the ball.
`SideSawblades`	Rotating blades that destroy the ball on contact.
`SideTeslaCoil`	Periodically discharges electricity.
`SideFlamethrower`	Continuously or periodically emits flames.
`SideTimeStop`	Temporarily halts the level timer.
`SideTeleport`	Teleports the ball to a linked teleport destination.
`SidePortalExit`	The exit point of a portal pair.
`SideOneWay`	Allows movement in only one direction.
`SideMultiWay`	Allows movement in multiple specified directions.
`SideRotator`	Rotates the ball’s facing direction.
`SideSwitch`	Toggles blocks or other level elements.
`SidePressurePlate`	Activates only when the ball is resting on it.
`SideLightSensor`	Detects light conditions to trigger other elements.

Custom Events

Many Side sub-classes emit built-in custom events. Listen for them with the OnCustomEvent hook and dispatch on event.name.

Sub-class	Event	Parameters
`SideButton`	`pressed`	—
`SideSwitch`	`pressed`, `released`, `stateSwitch`	—
`SidePressurePlate`	`pressed`, `released`, `stateSwitch`	—
`SideCheckpoint`	`activated`	`firstTime: boolean`
`SideCheckpoint`	`deactivated`	—
`SideExit`	`open`, `close`	—
`SideTeleport`	`activate`, `deactivate`	—
`SideTeleport`	`teleportBall`	`ball: Ball`
`SideTeleport`	`teleportEnemy`	`enemy: Enemy`
`SideLaser`	`activate`, `deactivate`	—
`SideLaser`	`electrocuteEnemy`	`enemy: Enemy`
`SideTeslaCoil`	`activate`, `deactivate`	—
`SideTeslaCoil`	`electrocuteEnemy`	`enemy: Enemy`
`SideSensorSpikes`	`activate`, `deactivate`	—
`SideSensorSpikes`	`catchBall`	`ball: Ball`
`SideSensorSpikes`	`catchEnemy`	`enemy: Enemy`
`SideStaticSpikes`	`catchBall`	`ball: Ball`
`SideStaticSpikes`	`catchEnemy`	`enemy: Enemy`
`SideRetractableSpike`	`in`, `out`	—
`SideRetractableSpike`	`spikeEnemy`	`enemy: Enemy`
`SidePatternSpike`	`in`, `out`	—
`SidePatternSpike`	`spikeEnemy`	`enemy: Enemy`
`SideSawblades`	`activate`, `deactivate`	—
`SideSawblades`	`catchBall`	`ball: Ball`
`SideSawblades`	`catchEnemy`	`enemy: Enemy`
`SideRotator`	`rotateBall`	`ball: Ball`
`SideRotator`	`rotateEnemy`	`enemy: Enemy`
`SideMagnet`	`stateChanged`	`state: integer`
`SideMagnet`	`catchBall`	`ball: Ball`
`SideMagnet`	`catchEnemy`	`enemy: Enemy`
`SideJumpPad`	`farJump`, `highJump`	`ball: Ball`
`SideLightSensor`	`ballDetect`	`ball: Ball`
`SideLightSensor`	`enemyDetect`	`enemy: Enemy`

-- Script attached to a SideButton
---@param self Side
---@param event CustomEvent
function OnCustomEvent(self, event)
    if event.name == "pressed" then
        Log.info("Button on face " .. self.faceName .. " was pressed")
    end
end

Usage Example

The following OnBallRoll hook is attached to a side script and prints the face name every time the ball rolls onto the side:

function OnBallRoll(self, ball)
    -- self is a Side
    Log.info("Ball rolled onto face: " .. self.faceName)

    -- Grant the ball a shield when it lands on this side
    if self.tag == "safe_pad" then
        ball:enableShield(3.0)
    end

    -- Check whether the side carries an item
    if self.hasItem then
        local item = self.item
        Log.info("Side has item: " .. item.name)
    end
end

Namespaces

Entity Classes

Data & Math

Enums

Side Class — Block Face Entity Properties Reference

Properties

Identity

Transform

Geometry

Rules

Attachments

Methods

getAssociatedBasis

isDirectionBlocked

Type-cast helpers

SideData

Side Subtypes

Custom Events

Usage Example

​Properties

​Identity

​Transform

​Geometry

​Rules

​Attachments

​Methods

​getAssociatedBasis

​isDirectionBlocked

​Type-cast helpers

​SideData

​Side Subtypes

​Custom Events

​Usage Example

Properties

Identity

Transform

Geometry

Rules

Attachments

Methods

getAssociatedBasis

isDirectionBlocked

Type-cast helpers

SideData

Side Subtypes

Custom Events

Usage Example