Programming

Imprint is a stack based language, instructions operate on the stack and add/remove one or more items from the stack.

Each stack item (and program memory item) may represent either an integer (signed) a vector or a colour between 0x000000 and 0xffffff (RGB)

Lines can be labelled with label-name: and referenced with label-name. At compile time, the memory address will be calculated and substituted in everywhere label-name is used. This means you can read and write the program instructions as it is running if you so desire by using a label as a pointer.

Compiler macros

LET foo initial-value will allocate program memory and leave foo usable as the address pointing to that memory so that you can use it with PushFrom/PopTo etc. (or Jump if you're getting advanced...)

LET foo[n] initial-value1 initial-value2 ... initial-value-n as above but allocates n pieces of contiguous data, foo points to the first of them, foo[1] points to the value at offset one and so on

CONST FOO value declares a compile time constant that you can use anywhere in the program you would use a normal datum

Basic instructions

Instruction	Pops	Pushes	Description
NoOp			Does nothing - padding
Push		datum	Pushes one piece of data onto the stack, e.g. Push 10, Push 0xff55ff or Push (10,-10)
Pop	datum		Removes one item from the top of the stack
PushFrom	address	memory contents	Pops a single memory address, and pushes the contents of that memory address onto the stack
PopTo	datum, address		Pops a memory address from the stack and then pops the next item from the stack into that location in memory
PeekTo	address		As above but doesn't remove the item from the stack
Clone	datum	datum, datum	Peeks the top item in the stack and pushes another copy onto the top of the stack
Swap	a, b	b, a	Swaps the top two items on the stack
BreakPoint			Stops execution and brings up the debugger having executed the line before breakpoint and ready to execute the line after on continuing

Jump commands

Instruction	Pops	Pushes	Description
Jump	address		Specifies the next instruction to be executed (usually referenced by way of a label:)
JumpNe	a, b, address		Jumps to address if a is not equal to b
JumpEq	a, b, address		Jumps to address if a is equal to b
JumpLt	a, b, address		Jumps to address if a is less than b
JumpGt	a, b, address		Jumps to address if a is greater than b
JumpZero	a, address		Jumps to address if a is equal to zero
JumpPos	a, address		Jumps to address if a is positive
JumpNeg	a, address		Jumps to address if a is negative

Logic commands

Instruction	Pops	Pushes	Description
Or	a, b	result	Performs a bitwise or operation
Xor	a, b	result	Performs a bitwise xor operation
And	a, b	result	Performs a bitwise and operation
Not	a	result	Performs a bitwise not operation

Integer Arithmetic

Instruction	Pops	Pushes	Description
Add	a, b	result	a + b = result
Sub	a, b	result	a - b = result
Div	a, b	result	a / b = result
Mult	a, b	result	a * b = result
Mod	a, b	result	a mod b = result
Inc	a	result	result = a + 1
Dec	a	result	result = a - 1
Max	a, b	result	Takes the top two integers from the stack and puts back the bigger of the two
Min	a, b	result	Takes the top two integers from the stack and puts back the smaller of the two
Random	max-range	result	Generates a random integer between 0 (inclusive) and max-range (exclusive)

Vector Arithmetic

Instruction	Pops	Pushes	Description
VecAdd	v1, v2	result	v1 + v2 = result
VecSub	v1, v2	result	v1 - v2 = result
VecLength	v	result	Length of the vector rounded down to the nearest integer
VecComp	x, y	v	Composes an x and y component integer into the vector (x, y)
VecDecomp	v	x, y	Decomposes a vector (x, y) into its constituent integers x and y

Bot based instructions

Instruction	Pops	Pushes	Description
GetId		int	Gives the running bot's id
GetPos		vec	Gives the running bot's position
GetColour		colour	Gives the running bot's colour
SetColour	colour		Sets the running bot's colour

Has Wheels

Instruction	Pops	Pushes	Description
MoveTo	vec		If the given location vector is passable, path finds to that location and begins moving towards it

Has Guns

Instruction	Pops	Pushes	Description
ShootAt	vec		Shoots at the given vector position if it is within range of guns (guns require ten ticks cooldown before subsequent firings so this command may not be executed immediately)

Has Radio

Instruction	Pops	Pushes	Description
MessageSetChannel	int		Just call this and set to 12 if you want to use messaging. Will be more useful later
MessageRead	addr, length	success	Reads the next message in the buffer if it exists. If there are no messages in the buffer success=0, if there is a message success=1. Will read length pieces of data into program memory starting at addr. Beware the complete lack of overflow protection...
MessageSend	addr, length		Reads the program memory ranging from addr for length pieces of data, will broadcast that as a message on the channel currently set by MessageSetChannel

Has Scanner

Instruction	Pops	Pushes	Description
ScannerSweep	address, n	observed	Writes the ids of the nearest n units in order of proximity to the given address and subsequent addresses, pushes on to the stack the number of units in range (which may be bigger than n)
ScannerLock	bot-id		Locks on to the given bot id allowing you to sense its position, colour etc using the Scan* commands below
ScannerLockNearest			Locks on to the nearest bot without requiring a separate ScannerSweep ScannerLock combination, allowing you to sense its position, colour etc using the Scan* commands below
ScanColour		colour	Gets the colour of the currently locked-on-to bot
ScanPosition		vec	Gets the position of the currently locked-on-to bot
ScanVisible		bool	Returns 1 if the locked on bot is still in sensor range, 0 otherwise

Has a factory module

Instruction	Pops	Pushes	Description
FactoryOrderParts	address, n		Read part numbers from a memory segment. See Parts for details
FactoryFlashFirmware	address, n		Flash the given chunk of memory to the RAM of the bot in production. Don't forget that you'll need a CPU containing module to be able to do this
FactoryBuild	position		Produce the unit specified by the other two commands. Note that you can only build within a limited range of yourself and this coordinate is absolute

Has resource storage capacity

Instruction	Pops	Pushes	Description
ResourceTransfer	vec		Transfer one resource to the given relative coordinate (which must be in an adjacent tile)
ResourceFull		bool	Pushes a 1 or a 0 on to the stack to indicate whether the unit's resource storage is full to capacity
ResourceEmpty		bool	Pushes a 1 or a 0 on to the stack to indicate whether the unit's resource storage is empty