 # 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')``````