Commands Cheat Sheet

Note, this page is auto-generated by swarm generate cheatsheet. If you notice this page is out-of-date, instead of editing it, you can help by regenerating the tables using the most up-to-date swarm executable and pasting the result here!

Commands

Syntax	Type	Capability	Description
`noop`	`cmd unit`		Do nothing.
`wait`	`int -> cmd unit`	time	Wait for a number of time steps.
`selfdestruct`	`cmd unit`	selfdestruct	Self-destruct the robot.
`move`	`cmd unit`	move	Move forward one step.
`turn`	`dir -> cmd unit`	turn	Turn in some direction.
`grab`	`cmd text`	grab	Grab an item from the current location.
`harvest`	`cmd text`	harvest	Harvest an item from the current location.
`place`	`text -> cmd unit`	place	Place an item at the current location.
`give`	`robot -> text -> cmd unit`	give	Give an item to another robot nearby.
`install`	`robot -> text -> cmd unit`	install	Install a device from inventory on a robot.
`make`	`text -> cmd unit`	make	Make an item using a recipe.
`has`	`text -> cmd bool`		Sense whether the robot has a given item in its inventory.
`installed`	`text -> cmd bool`		Sense whether the robot has a specific device installed.
`count`	`text -> cmd int`	count	Get the count of a given item in a robot's inventory.
`drill`	`dir -> cmd unit`	drill	Drill through an entity.
`build`	`∀ a. {cmd a} -> cmd robot`	build	Construct a new robot.
`salvage`	`cmd unit`	salvage	Deconstruct an old robot.
`reprogram`	`∀ a. robot -> {cmd a} -> cmd unit`	reprogram	Reprogram another robot with a new command.
`say`	`text -> cmd unit`		Emit a message.
`listen`	`cmd text`	listen	Listen for a message from other robots.
`log`	`text -> cmd unit`	log	Log the string in the robot's logger.
`view`	`robot -> cmd unit`		View the given robot.
`appear`	`text -> cmd unit`	appear	Set how the robot is displayed.
`create`	`text -> cmd unit`	god	Create an item out of thin air.
`time`	`cmd int`	time	Get the current time.
`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 (unit + text)`	scan	Scan a nearby location for entities.
`upload`	`robot -> cmd unit`	scan	Upload a robot's known entities and log to another robot.
`ishere`	`text -> cmd bool`	sensehere	See if a specific entity is in the current location.
`whoami`	`cmd text`	whoami	Get the robot's display name.
`setname`	`text -> cmd unit`		Set the robot's display name.
`random`	`int -> cmd int`	random	Get a uniformly random integer.
`run`	`text -> cmd unit`		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`	try	Execute a command, catching errors.
`swap`	`text -> cmd text`	swap	Swap placed entity with one in inventory.
`atomic`	`∀ a. cmd a -> cmd a`	atomic	Execute a block of commands atomically.
`teleport`	`robot -> int * int -> cmd unit`	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`	`text -> cmd robot`	god	Find a robot by name.
`robotnumbered`	`int -> cmd robot`	god	Find a robot by number.
`knows`	`text -> 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`	sum	Put the value into the left component of a sum type.
`inr`	`∀ a b. b -> a + b`	sum	Put the value into the right component of a sum type.
`case`	`∀ a b c. a + b -> (a -> c) -> (b -> c) -> c`	sum	Evaluate one of the given functions on a value of sum type.
`fst`	`∀ a b. a * b -> a`	prod	Get the first value of a pair.
`snd`	`∀ a b. a * b -> b`	prod	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. text -> a`		A value of any type, that is evaluated as error with message.
`not`	`bool -> bool`	negation	Negate the boolean value.
`format`	`∀ a. a -> text`	text	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`	cond	Logical or (true if either value is true).
`&&`	`bool -> bool -> bool`	cond	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.
`++`	`text -> text -> text`	text	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 unit

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 unit
required capabilities: time

Wait for a number of time steps.

Selfdestruct

syntax: selfdestruct
type: cmd unit
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 unit
required capabilities: move

Move forward one step.

Turn

syntax: turn
type: dir -> cmd unit
required capabilities: turn

Turn in some direction.

Grab

syntax: grab
type: cmd text
required capabilities: grab

Grab an item from the current location.

Harvest

syntax: harvest
type: cmd text
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: text -> cmd unit
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 -> text -> cmd unit
required capabilities: give

Give an item to another robot nearby.

Install

syntax: install
type: robot -> text -> cmd unit
required capabilities: install

Install a device from inventory on a robot.

Make

syntax: make
type: text -> cmd unit
required capabilities: make

Make an item using a recipe.

Has

syntax: has
type: text -> cmd bool

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

Installed

syntax: installed
type: text -> cmd bool

Sense whether the robot has a specific device installed.

Count

syntax: count
type: text -> cmd int
required capabilities: count

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

Drill

syntax: drill
type: dir -> cmd unit
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 unit
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 unit
required capabilities: reprogram

Reprogram another robot with a new command.

The other robot has to be nearby and idle.

Say

syntax: say
type: text -> cmd unit

Emit a message.

The message will be in the robots log (if it has one) and the global log. You can view the message that would be picked by listen from the global log in the messages panel, along with your own messages and logs. This means that to see messages from other robots you have to be able to listen for them, so once you have a listening device installed messages will be added to your log. In creative mode, there is of course no such limitation.

Listen

syntax: listen
type: cmd text
required capabilities: listen

Listen for a message from other robots.

It will take the first message said by the closest robot. You do not need to actively listen for the message to be logged though, that is done automatically once you have a listening device installed. Note that you can see the messages either in your logger device or the message panel.

Log

syntax: log
type: text -> cmd unit
required capabilities: log

Log the string in the robot's logger.

View

syntax: view
type: robot -> cmd unit

View the given robot.

Appear

syntax: appear
type: text -> cmd unit
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: text -> cmd unit
required capabilities: god

Create an item out of thin air.

Only available in creative mode.

Time

syntax: time
type: cmd int
required capabilities: time

Get the current time.

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 (unit + text)
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 unit
required capabilities: scan

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

Ishere

syntax: ishere
type: text -> cmd bool
required capabilities: sensehere

See if a specific entity is in the current location.

Whoami

syntax: whoami
type: cmd text
required capabilities: whoami

Get the robot's display name.

Setname

syntax: setname
type: text -> cmd unit

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: text -> cmd unit

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
required capabilities: try

Execute a command, catching errors.

Swap

syntax: swap
type: text -> cmd text
required capabilities: swap

Swap placed entity with one in inventory.

This essentially works like atomic grab and place. Use this to avoid race conditions where more robots grab, scan or place in one location.

Atomic

syntax: atomic
type: ∀ a. cmd a -> cmd a
required capabilities: atomic

Execute a block of commands atomically.

When executing atomic c, a robot will not be interrupted, that is, no other robots will execute any commands while the robot is executing @c@.

Teleport

syntax: teleport
type: robot -> int * int -> cmd unit
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: text -> 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: text -> 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
required capabilities: sum

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

Inr

syntax: inr
type: ∀ a b. b -> a + b
required capabilities: sum

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
required capabilities: sum

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

Fst

syntax: fst
type: ∀ a b. a * b -> a
required capabilities: prod

Get the first value of a pair.

Snd

syntax: snd
type: ∀ a b. a * b -> b
required capabilities: prod

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. text -> a

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

Not

syntax: not
type: bool -> bool
required capabilities: negation

Negate the boolean value.

Format

syntax: format
type: ∀ a. a -> text
required capabilities: text

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
required capabilities: cond

Logical or (true if either value is true).

And

syntax: &&
type: bool -> bool -> bool
required capabilities: cond

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: text -> text -> text
required capabilities: text

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))