Basis — Orientation Coordinate System Reference

The Basis class represents a local coordinate system defined by a Face (which side of a cube is “up”) and an Orientation (compass direction). It provides direction vectors (front, back, right, left, up, down) and methods to compute rotated variants. You obtain a Basis from entity properties like block.basis, enemy.basis, ball.basis, or construct one directly.

Related types: Face, Orientation, Vector3

Constructors

-- Default basis (Face.Up, Orientation.North)
local basis = Basis.new()

-- From a specific face
local basis = Basis.new(Face.Up)

-- From a face and orientation
local basis = Basis.new(Face.Up, Orientation.North)

Properties

Property	Type	Read-only	Description
`face`	`Face`	✅	The face defining “up” for this basis.
`faceName`	`string`	✅	String name of the face.
`orientation`	`Orientation`	✅	The compass orientation.
`orientationName`	`string`	✅	String name of the orientation.

Direction Vectors

Property	Type	Read-only	Description
`front`	`Vector3`	✅	Forward direction vector.
`back`	`Vector3`	✅	Backward direction vector.
`right`	`Vector3`	✅	Right direction vector.
`left`	`Vector3`	✅	Left direction vector.
`up`	`Vector3`	✅	Up direction vector.
`down`	`Vector3`	✅	Down direction vector.

Turned Bases

Property	Type	Read-only	Description
`turnUp`	`Basis`	✅	Basis rotated to face upward.
`turnDown`	`Basis`	✅	Basis rotated to face downward.
`turnLeft`	`Basis`	✅	Basis rotated to face left.
`turnRight`	`Basis`	✅	Basis rotated to face right.
`turnBack`	`Basis`	✅	Basis rotated to face backward.

Methods

withFace

Returns a copy of this basis with a new face.

--- @param face Face
--- @return Basis
function Basis:withFace(face)

withOrientation

Returns a copy of this basis with a new orientation.

--- @param orientation Orientation
--- @return Basis
function Basis:withOrientation(orientation)

Usage Example

Get the direction vectors from a block’s basis to determine movement:

function OnBallRoll(self, rollIn, side, ball)
    -- self is a Block
    local basis = self.basis

    -- The ball rolled onto the front face
    Logger.info("Block front direction: " .. basis.front.x .. "," .. basis.front.y .. "," .. basis.front.z)

    -- Get a basis rotated to face downward
    local downBasis = basis.turnDown
    Logger.info("Down-turned front: " .. downBasis.front.x .. "," .. downBasis.front.y .. "," .. downBasis.front.z)
end

Construct a basis from a specific face and orientation:

function OnStart()
    local basis = Basis.new(Face.Up, Orientation.East)
    Logger.info("Front vector: " .. basis.front.x .. "," .. basis.front.y .. "," .. basis.front.z)
    Logger.info("Right vector: " .. basis.right.x .. "," .. basis.right.y .. "," .. basis.right.z)
end

Namespaces

Entity Classes

Level Editor

Core Types

Enums

Basis — Orientation Coordinate System Reference

Constructors

Properties

Direction Vectors

Turned Bases

Methods

withFace

withOrientation

Usage Example

​Constructors

​Properties

​Direction Vectors

​Turned Bases

​Methods

​withFace

​withOrientation

​Usage Example

Constructors

Properties

Direction Vectors

Turned Bases

Methods

withFace

withOrientation

Usage Example