> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rollingquest.kramgames.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Basis — Orientation Coordinate System Reference

> API reference for the Basis class in RollingQuest Lua scripting. Represents a local coordinate system with face and orientation, providing direction vectors and rotation helpers.

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`](/api/enums/face), [`Orientation`](/api/enums/other-enums), [`Vector3`](/api/classes/vector3)

## Constructors

```lua theme={null}
-- 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.

```lua theme={null}
--- @param face Face
--- @return Basis
function Basis:withFace(face)
```

### withOrientation

Returns a copy of this basis with a new orientation.

```lua theme={null}
--- @param orientation Orientation
--- @return Basis
function Basis:withOrientation(orientation)
```

## Usage Example

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

```lua theme={null}
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:

```lua theme={null}
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
```