
# Commands

Basic index of all available commands in the console

## Console

```
print(Args...)
clear()
rand(Int min, Int max)
```

The `print()` function prints every given argument, then an end of line
character; the `clear()` function clears the console.

The `rand()` function returns an integer in the given range.

## Containers

```
size(Val val) -> Int
```

Returns the size of the given object.

```
push(List list, Val elem)
pop(List list)
```

These functions extend the list constructed with `[args...]` to operate as a
stack. The last element pushed is accessible at the end, with index `-1`.

## Positioning

```
here() -> Vec3
cubr() -> Vec3
cupl() -> Vec3
```

The `here()` function returns the coordinates of the player; the `cubr()` and
`cupl()` functions return the two coordinates associated with the cursor: the
one where the player might break a cell, and the one where the player might
place one.

## Querying

```
cell(Vec3 pos) -> Str
light(Vec3 pos) -> Int
face(Vec3 pos, Int side) -> Str
```

The `cell()` function returns the name of the cell in the given position; the
`light()` function returns the light value in the form of a regular number
where the first four bits indicate sunlight and the next four spot light; the
`face()` function returns the name of the face painted on the specified side of
the specified cell, or `null` if the face is not painted.

## Modifying

```
place(Vec3 pos, Str cell)
place(Vec3 pos, Str x, Str y, Str z)
place(Vec3 pos, Str l, Str r, Str d, Str u, Str f, Str b)
replace(Vec3 pos, Str cell)
spawn(Vec3 pos, Str mob)
paint(Vec3 pos, int face, Str cell)
paint(Vec3 pos, int face, Str l, Str r, Str u, Str d)
```

The `place()` function places a the cell whose name is given at the given
position; the original position must be empty (that is, occupied by a cell with
a collision value of `empty`). Alternate versions can be given different cell
types to be placed depending on the direction the player is facing. Option
specified `null` will be skipped in favor of the next best one; the function
returns `true` if the cell was placed or `false` if any condition prevented it
from being placed.

The `replace()` function replaces whichever cell was in the given position by
the one that was specified.

The `spawn()` function spawns a mob in the given cell.

The `paint()` function paints the given face of the given cell. The version
with additional arguments specifies cells to be used to paint the surface
depending on the direction the painter is facing relative to the normal of the
face that's being painted.


## Interaction

```
browse(Vec3 pos)
craft(Vec3 pos)
cross(Vec3 in, Vec3 out)
```

The `browse()` function opens the inventory of the cell at the given position.

The `craft()` function opens the crafting menu of the cell at the given
position.

The `cross()` function crosses the door at the first position, assuming the
player knocked at the second; the function is usually called with `cubr()` and
`cupl()` as arguments.

## Mobs

```
mob_frame(Mob mob, [Int value]) -> Int
mob_state(Mob mob, [Int value]) -> Int
mob_wait(Mob mob, Int ticks)
```

The `mob_frame()` and `mob_state()` functions are accessors that either set a
mob field to the given value, or return the current one if it's not provided.

The `mob_wait()` function is usually called from the mob updating function and
resets the number of ticks that should elapse before the update function is
called again. Note that giving this function a negative value disables updating
of the mob until something else triggers it.

## Items

```
give(Mob mob, Str item, [Int amount]) -> Bool
give(Vec3 pos, Str item, [Int amount]) -> Bool
take(Mob mob, Str item, [Int amount]) -> Int
take(Vec3 pos, Str item, [Int amount]) -> Int
has(Mob mob, Str item) -> Int
has(Vec3 pos, Str item) -> Int
```

The `give()` function adds items to the inventory of a mob or cell; it returns
`true` on success or `false` on failure, usually meaning that the inventory was
already full.

The `take()` function removes items from an inventory; it returns the actual
number of items removed, that can be less than the requested amount or even
zero if no such item is present.

The `has()` function returns the amount of items of the given type held by the
inventory associated with a cell or mob.

If `amount` is not specified, the functions assume `1`.

## Audio

```
play(Str sound) -> Bool
play(Str sound, Vec3 pos) -> Bool
play(Str sound, Mob mob) -> Bool
```

The `play()` functions play a sound from one of the loaded packs. If only the
first argument is provided, the sound is played raw, with no directional data;
if a position is provided, the sound will come from the center of the specified
cell, and if a mob is provided, the sound will come from that mob position and
may move with it.
