Coordinates

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:
  1. With a single number, which will return a string.
  1. With several numbers, which will return an array of strings
  1. 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')