Commands Cheat Sheet

Commands

Syntax	Type	Capability	Description
noop	cmd ()		Do nothing.
wait	int -> cmd ()		Wait for a number of time steps.
selfdestruct	cmd ()	selfdestruct	Self-destruct the robot.
move	cmd ()	move	Move forward one step.
turn	dir -> cmd ()	turn	Turn in some direction.
grab	cmd string	grab	Grab an item from the current location.
harvest	cmd string	harvest	Harvest an item from the current location.
place	string -> cmd ()	place	Place an item at the current location.
give	robot -> string -> cmd ()	give	Give an item to another robot nearby.
install	robot -> string -> cmd ()	install	Install a device from inventory on a robot.
make	string -> cmd ()	make	Make an item using a recipe.
has	string -> cmd bool		Sense whether the robot has a given item in its inventory.
count	string -> cmd int	count	Get the count of a given item in a robot's inventory.
drill	dir -> cmd ()	drill	Drill through an entity.
build	∀ a. {cmd a} -> cmd robot	build	Construct a new robot.
salvage	cmd ()	salvage	Deconstruct an old robot.
reprogram	∀ a. robot -> {cmd a} -> cmd ()	reprogram	Reprogram another robot with a new command.
say	string -> cmd ()		Emit a message.
log	string -> cmd ()	log	Log the string in the robot's logger.
view	robot -> cmd ()		View the given robot.
appear	string -> cmd ()	appear	Set how the robot is displayed.
create	string -> cmd ()	god	Create an item out of thin air.
whereami	cmd (int * int)	senseloc	Get the current x and y coordinates.
blocked	cmd bool	sensefront	See if the robot can move forward.
scan	dir -> cmd (() + string)	scan	Scan a nearby location for entities.
upload	robot -> cmd ()	scan	Upload a robot's known entities and log to another robot.
ishere	string -> cmd bool	sensehere	See if a specific entity is in the current location.
whoami	cmd string	whoami	Get the robot's display name.
setname	string -> cmd ()		Set the robot's display name.
random	int -> cmd int	random	Get a uniformly random integer.
run	string -> cmd ()		Run a program loaded from a file.
return	∀ a. a -> cmd a		Make the value a result in cmd.
try	∀ a. {cmd a} -> {cmd a} -> cmd a		Execute a command, catching errors.
teleport	robot -> int * int -> cmd ()	teleport	Teleport a robot to the given location.
as	∀ a. robot -> {cmd a} -> cmd a	god	Hypothetically run a command as if you were another robot.
robotnamed	string -> cmd robot	god	Find a robot by name.
robotnumbered	int -> cmd robot	god	Find a robot by number.
knows	string -> cmd bool		Check if the robot knows about an entity.

Builtin functions

These functions are evaluated immediately once they have enough arguments.

Syntax	Type	Capability	Description
self	robot	whoami	Get a reference to the current robot.
parent	robot		Get a reference to the robot's parent.
base	robot		Get a reference to the base.
if	∀ a. bool -> {a} -> {a} -> a	cond	If-Then-Else function.
inl	∀ a b. a -> a + b		Put the value into the left component of a sum type.
inr	∀ a b. b -> a + b		Put the value into the right component of a sum type.
case	∀ a b c. a + b -> (a -> c) -> (b -> c) -> c		Evaluate one of the given functions on a value of sum type.
fst	∀ a b. a * b -> a		Get the first value of a pair.
snd	∀ a b. a * b -> b		Get the second value of a pair.
force	∀ a. {a} -> a		Force the evaluation of a delayed value.
undefined	∀ a. a		A value of any type, that is evaluated as error.
fail	∀ a. string -> a		A value of any type, that is evaluated as error with message.
not	bool -> bool		Negate the boolean value.
format	∀ a. a -> string	log	Turn an arbitrary value into a string.

Operators

Syntax	Type	Capability	Description
-	int -> int	arith	Negate the given integer value.
==	∀ a. a -> a -> bool	compare	Check that the left value is equal to the right one.
!=	∀ a. a -> a -> bool	compare	Check that the left value is not equal to the right one.
<	∀ a. a -> a -> bool	compare	Check that the left value is lesser than the right one.
>	∀ a. a -> a -> bool	compare	Check that the left value is greater than the right one.
<=	∀ a. a -> a -> bool	compare	Check that the left value is lesser or equal to the right one.
>=	∀ a. a -> a -> bool	compare	Check that the left value is greater or equal to the right one.
||	bool -> bool -> bool		Logical or (true if either value is true).
&&	bool -> bool -> bool		Logical and (true if both values are true).
+	int -> int -> int	arith	Add the given integer values.
-	int -> int -> int	arith	Subtract the given integer values.
*	int -> int -> int	arith	Multiply the given integer values.
/	int -> int -> int	arith	Divide the left integer value by the right one, rounding down.
^	int -> int -> int	arith	Raise the left integer value to the power of the right one.
++	string -> string -> string	log	Concatenate the given strings.
$	∀ a b. (a -> b) -> a -> b		Apply the function on the left to the value on the right.

Detailed descriptions

Noop

• syntax: noop
• type: cmd ()

Do nothing.

This is different than Wait in that it does not take up a time step. It is useful for commands like if, which requires you to provide both branches. Usually it is automatically inserted where needed, so you do not have to worry about it.

Wait

• syntax: wait
• type: int -> cmd ()

Wait for a number of time steps.

Selfdestruct

• syntax: selfdestruct
• type: cmd ()
• required capabilities: selfdestruct

Self-destruct the robot.

Useful to not clutter the world. This destroys the robot's inventory, so consider salvage as an alternative.

Move

• syntax: move
• type: cmd ()
• required capabilities: move

Move forward one step.

Turn

• syntax: turn
• type: dir -> cmd ()
• required capabilities: turn

Turn in some direction.

Grab

• syntax: grab
• type: cmd string
• required capabilities: grab

Grab an item from the current location.

Harvest

• syntax: harvest
• type: cmd string
• required capabilities: harvest

Harvest an item from the current location.

Leaves behind a growing seed if the harvested item is growable. Otherwise it works exactly like grab.

Place

• syntax: place
• type: string -> cmd ()
• required capabilities: place

Place an item at the current location.

The current location has to be empty for this to work.

Give

• syntax: give
• type: robot -> string -> cmd ()
• required capabilities: give

Give an item to another robot nearby.

Install

• syntax: install
• type: robot -> string -> cmd ()
• required capabilities: install

Install a device from inventory on a robot.

Make

• syntax: make
• type: string -> cmd ()
• required capabilities: make

Make an item using a recipe.

Has

• syntax: has
• type: string -> cmd bool

Sense whether the robot has a given item in its inventory.

Count

• syntax: count
• type: string -> cmd int
• required capabilities: count

Get the count of a given item in a robot's inventory.

Drill

• syntax: drill
• type: dir -> cmd ()
• required capabilities: drill

Drill through an entity.

Usually you want to drill forward when exploring to clear out obstacles. When you have found a source to drill, you can stand on it and drill down. See what recipes with drill you have available.

Build

• syntax: build
• type: ∀ a. {cmd a} -> cmd robot
• required capabilities: build

Construct a new robot.

You can specify a command for the robot to execute. If the command requires devices they will be installed from your inventory.

Salvage

• syntax: salvage
• type: cmd ()
• required capabilities: salvage

Deconstruct an old robot.

Salvaging a robot will give you its inventory, installed devices and log.

Reprogram

• syntax: reprogram
• type: ∀ a. robot -> {cmd a} -> cmd ()
• required capabilities: reprogram

Reprogram another robot with a new command.

The other robot has to be nearby and idle.

Say

• syntax: say
• type: string -> cmd ()

Emit a message.

The message will be in a global log, which you can not currently view. https://github.com/swarm-game/swarm/issues/513

Log

• syntax: log
• type: string -> cmd ()
• required capabilities: log

Log the string in the robot's logger.

View

• syntax: view
• type: robot -> cmd ()

View the given robot.

Appear

• syntax: appear
• type: string -> cmd ()
• required capabilities: appear

Set how the robot is displayed.

You can either specify one character or five (for each direction). The default is "X^>v<".

Create

• syntax: create
• type: string -> cmd ()
• required capabilities: god

Create an item out of thin air.

Only available in creative mode.

Whereami

• syntax: whereami
• type: cmd (int * int)
• required capabilities: senseloc

Get the current x and y coordinates.

Blocked

• syntax: blocked
• type: cmd bool
• required capabilities: sensefront

See if the robot can move forward.

Scan

• syntax: scan
• type: dir -> cmd (() + string)
• required capabilities: scan

Scan a nearby location for entities.

Adds the entity (not robot) to your inventory with count 0 if there is any. If you can use sum types, you can also inspect the result directly.

Upload

• syntax: upload
• type: robot -> cmd ()
• required capabilities: scan

Upload a robot's known entities and log to another robot.

Ishere

• syntax: ishere
• type: string -> cmd bool
• required capabilities: sensehere

See if a specific entity is in the current location.

Whoami

• syntax: whoami
• type: cmd string
• required capabilities: whoami

Get the robot's display name.

Setname

• syntax: setname
• type: string -> cmd ()

Set the robot's display name.

Random

• syntax: random
• type: int -> cmd int
• required capabilities: random

Get a uniformly random integer.

The random integer will be chosen from the range 0 to n-1, exclusive of the argument.

Run

• syntax: run
• type: string -> cmd ()

Run a program loaded from a file.

Return

• syntax: return
• type: ∀ a. a -> cmd a

Make the value a result in cmd.

Try

• syntax: try
• type: ∀ a. {cmd a} -> {cmd a} -> cmd a

Execute a command, catching errors.

Teleport

• syntax: teleport
• type: robot -> int * int -> cmd ()
• required capabilities: teleport

Teleport a robot to the given location.

As

• syntax: as
• type: ∀ a. robot -> {cmd a} -> cmd a
• required capabilities: god

Hypothetically run a command as if you were another robot.

RobotNamed

• syntax: robotnamed
• type: string -> cmd robot
• required capabilities: god

Find a robot by name.

RobotNumbered

• syntax: robotnumbered
• type: int -> cmd robot
• required capabilities: god

Find a robot by number.

Knows

• syntax: knows
• type: string -> cmd bool

Check if the robot knows about an entity.

Self

• syntax: self
• type: robot
• required capabilities: whoami

Get a reference to the current robot.

Parent

• syntax: parent
• type: robot

Get a reference to the robot's parent.

Base

• syntax: base
• type: robot

Get a reference to the base.

If

• syntax: if
• type: ∀ a. bool -> {a} -> {a} -> a
• required capabilities: cond

If-Then-Else function.

If the bool predicate is true then evaluate the first expression, otherwise the second.

Inl

• syntax: inl
• type: ∀ a b. a -> a + b

Put the value into the left component of a sum type.

Inr

• syntax: inr
• type: ∀ a b. b -> a + b

Put the value into the right component of a sum type.

Case

• syntax: case
• type: ∀ a b c. a + b -> (a -> c) -> (b -> c) -> c

Evaluate one of the given functions on a value of sum type.

Fst

• syntax: fst
• type: ∀ a b. a * b -> a

Get the first value of a pair.

Snd

• syntax: snd
• type: ∀ a b. a * b -> b

Get the second value of a pair.

Force

• syntax: force
• type: ∀ a. {a} -> a

Force the evaluation of a delayed value.

Undefined

• syntax: undefined
• type: ∀ a. a

A value of any type, that is evaluated as error.

Fail

• syntax: fail
• type: ∀ a. string -> a

A value of any type, that is evaluated as error with message.

Not

• syntax: not
• type: bool -> bool

Negate the boolean value.

Format

• syntax: format
• type: ∀ a. a -> string
• required capabilities: log

Turn an arbitrary value into a string.

Neg

• syntax: -
• type: int -> int
• required capabilities: arith

Negate the given integer value.

Eq

• syntax: ==
• type: ∀ a. a -> a -> bool
• required capabilities: compare

Check that the left value is equal to the right one.

Neq

• syntax: !=
• type: ∀ a. a -> a -> bool
• required capabilities: compare

Check that the left value is not equal to the right one.

Lt

• syntax: <
• type: ∀ a. a -> a -> bool
• required capabilities: compare

Check that the left value is lesser than the right one.

Gt

• syntax: >
• type: ∀ a. a -> a -> bool
• required capabilities: compare

Check that the left value is greater than the right one.

Leq

• syntax: <=
• type: ∀ a. a -> a -> bool
• required capabilities: compare

Check that the left value is lesser or equal to the right one.

Geq

• syntax: >=
• type: ∀ a. a -> a -> bool
• required capabilities: compare

Check that the left value is greater or equal to the right one.

Or

• syntax: ||
• type: bool -> bool -> bool

Logical or (true if either value is true).

And

• syntax: &&
• type: bool -> bool -> bool

Logical and (true if both values are true).

Add

• syntax: +
• type: int -> int -> int
• required capabilities: arith

Add the given integer values.

Sub

• syntax: -
• type: int -> int -> int
• required capabilities: arith

Subtract the given integer values.

Mul

• syntax: *
• type: int -> int -> int
• required capabilities: arith

Multiply the given integer values.

Div

• syntax: /
• type: int -> int -> int
• required capabilities: arith

Divide the left integer value by the right one, rounding down.

Exp

• syntax: ^
• type: int -> int -> int
• required capabilities: arith

Raise the left integer value to the power of the right one.

Concat

• syntax: ++
• type: string -> string -> string
• required capabilities: log

Concatenate the given strings.

AppF

• syntax: $
• type: ∀ a b. (a -> b) -> a -> b

Apply the function on the left to the value on the right.

This operator is useful to avoid nesting parentheses. For exaple: f $ g $ h x = f (g (h x))