Coordinates

Introduction

In Sandstone, coordinates are expressed as strings:

Relative coordinates: '~ ~1 ~',

Locale coordinates: '^ ^ ^1'

Absolute coordinates: '0 0 0'

Mix of relative & absolute coordinates: '~ 128 ~'

For example,

// Compiles to /setblock ~ ~10 ~ dirt
setblock('~ ~10 ~', 'dirt')

// Compiles to /setblock 0 5 0 dirt
setblock('0 5 0', 'dirt')

However, this is hard to use with variables. Therefore, Sandstone provides three helper functions to allow you to use numerical values as absolute, relative or local coordinates.

Syntax

In order to create coordinates from numbers, you can use one of the following functions:

absolute or abs for absolute coordinates

relative or rel for relative coordinates, using the tilde ~ notation

local or loc for local coordinates, using the caret ^ notation

You can use them in three ways:

With a single number, which will return a string.

With several numbers, which will return an array of strings

With nothing, which is like calling them with (0, 0, 0)

import { abs, rel, loc } from 'sandstone'

// A single number
abs(5) ➨ '5'
rel(5) ➨ '~5'
loc(5) ➨ '^5'

// Several numbers
abs(0, 10, 0) ➨ '0 10 0'
rel(0, 10, 0) ➨ '~ ~10 ~'
loc(0, 10, 0) ➨ '^ ^10 ^'

// No arguments
abs() ➨ '0 0 0'
rel() ➨ '~ ~ ~'
loc() ➨ '^ ^ ^'

If you want to mix different kind of coordinates in the same command, you should use single numbers. If all your coordinates are of the same kind, multiple numbers are better.

// Compiles to /setblock 0 0 0 dirt
setblock(rel(0, 0, 0), 'dirt')

// Compiles to /setblock ^ ^ ^1 dirt
setblock(loc(0, 0, 1), 'dirt')

// Compiles to /setblock ~ 0 ~ bedrock
setblock([rel(0), abs(0), rel(0)], 'dirt')

Type safety

String coordinates (’~ ~ ~’) are type-safe: you cannot use any string as coordinates.

// ✅ Compiles!
setblock('~ ~10 ~', 'dirt')

// ❌ TypeError: '~ foo ~' is not assignable to type Coordinates.
setblock('~ foo ~', 'dirt')