============================================================================== ROBOTZ ============================================================================== Author : Eric Boon Date : 05 Jan 1999 Version : 0.2 Status : Very first draft Copying policy : Freeware [META: Comments in between square brackets and starting with META: must be seen separately from the document. These are mere annotations _to_ the document and help me ordering my thought about how to implement the machine and which possible problems I expect etc. - but comments on META's are of course just as welcome as comments on the document itself :-)] ------------------------------------------------------------------------------ Contents ------------------------------------------------------------------------------ 1. Introduction 1.1 Description of the game 1.2 Terminology, definitions and abbreviations 2. Robot Machine Architecture 2.1 Robot Architecture Overview 2.2 Status Registers 3. Command set 3.1 Action commands 3.2 Program flow control 3.3 Stack operations 3.4 Arithmatic operations 3.5 Logic operations ------------------------------------------------------------------------------ 1. Introduction ------------------------------------------------------------------------------ 1.1 --- [META: A short description of the game should come here] 1.2 Terminology, definitions and abbreviations ---------------------------------------------- 0 or 1, FALSE or TRUE signed or unsigned 8-bit value signed or unsigned 16-bit value, LSB-first
word in range $0000 - $3FFF (15 bit) Z, P, N, NZ, NP, NN (bitmask over flags status reg) stacktop top-most element of the stack ------------------------------------------------------------------------------ 2. Robot Machine Architecture ------------------------------------------------------------------------------ 2.1 Robot Architecture Overview A Robot consists of a virtual CPU which implements an extended stack machine. The machine has two stacks. One for calculations and parameter passing (a-stack) and one for storing return addresses for CALL instructions (c-stack). The a-stack is located in memory, the c-stack is machine-internal. [META: Do I have to explain the notion of stack machine here?] [META: I need some input here. Should there be a fixed address range for the stacks? Should the c-stack be located in memory, too? Could it be possible to intergrate the two stacks into one? I guess so, but how do I separate parameters passed on the stack from return addresses?] 2.2 Status Registers -------------------- The registers are divided into two classes: public and private. The private registers can only be accessed by the robot itself, the public registers are accessible to all other robots. All status registers are read-only. 2.2.1 Private status registers The flags register contains the results of the last arithmetic or logical operation: flags.Z - (bit) Zero/Equal flag flags.P - (bit) Positive/Greater flag flags.N - (bit) Negative/Less flag The env register array contains info on the direct environment of the robot. This register array always reflects the current situation. The robot itself is placed at env[0][0]; env[-2][-2], env[-2][2], env[2][-2] and env[2][2] will always contain blank data. env[-2..2][-2..2] - the environment register array env[][].contents - (byte) 0 = empty 1 = robot 2 = energy supply env[][].data - (byte) When the contents field indicates a robot at this position, this field contains the ID of that robot. When the contents field indicates a power supply, this field contains the size of the supply. The next fields are only filled in when a robot is present on that position. They are a copy of the public status registers of that robot. env[][].alive - (byte) env[][].action - (byte) The scan register contains the information obtained via the SCAN command. The robot will have to perform a SCAN to fill these registers. The scan register fields are updated just before the robot wakes up for the next turn so all information will then be up to date. scan.n_robots - (byte) scan.n_supplies - (byte) The energy status contains the amount of energy the robot contains. Executing an action command (SCAN, MOVE etc) will decreae the value of the energy status register. When its value becomes 0, the robot comes to a halt and the public.alive status flag will be set to FALSE. energy - (byte) energy status 2.2.2 Public status registers These registers contain info that is sent to the other robots. A part of it will land in the env registers of the others. Part of it will just be used to update them. public.id - (byte) identification (this is equal to env[0][0].data) public.alive - (bit) alive flag public.posx - (byte) position X coordinate public.posy - (byte) position Y coordinate public.action - (byte) last executed action command ------------------------------------------------------------------------------ 3. Command Set ------------------------------------------------------------------------------ 3.1 Action commands ------------------- The action commands define the actions which will cost the robot a turn. I.e. after the exeuction of one of these commands, the robots sends its public status register set and wait for its next turn. When the robot gets its turn again, the env registers are updated and the processing of the program continues at the next command. [META: Apart from the commands (mnemonics, actually), a byte code must be defined. A byte code is faster to interpret than plain ascii text] 3.1.1 SCAN Syntax: SCAN The lower 3 bits of stacktop indicate in which direction the SCAN should be performed (X = robot, + = scanned area): 0 - north + + + + + . + + + . . . X . . . . . . . . . . . . 1 - north-east . . + + + . . + + + . . X + + . . . . . . . . . . . . . . + . . . + + 2 - east . . X + + . . . + + . . . . + etc... 3.1.2 MOVE Syntax: MOVE The lower 2 bits of stacktop indicate the direction in which the robot is moved: 0 - north 1 - east 2 - south 3 - west 3.1.3 ATCK Syntax: ATCK The ATCK command makes the robot attack another robot at a neighbouring square. The lower 2 bits of stacktop indicate in which the attack is performed: 0 - north 1 - east 2 - south 3 - west 3.1.4 DROP Syntax: DROP Drops the amount of energy indicated by the stacktop from the energy supply onto the field. When the value of the stacktop is 0 or negative, no energy will be dropped. When the amount of energy dropped exceeds the amount of energy available, the robot will drop its entire energy supply - this is equal to self-destruction!! [META: I dropped the SKIP command, as the same effect can be achieved by PUSH 0 followed by DROP. Big advantage is that all action commands now have the same syntax and the same stack behaviour! And a command less further simplifies the machine, of course :-)] 3.2 Program flow control ------------------------ These commands influence the program execution flow. 3.2.1 SKIP Syntax: SKIP When condition holds, the next instruction is skipped and execution proceeds at the instruction following the next. This command is useful to produce conditional jumps. The state of the flags and stacks are left untouched. E.g jump to 'xyz' when the zero flag is set: SKIP NZ JP xyz xyz: [META: To be able to implement this properly, it would be easy if all commands have an equal length opcode, or if the length of the opcode is somewhere encoded in the opcode itself. Hm...] 3.2.2 JP Syntax: JP
Program execution continues at
. Flags and stacks are untouched. 3.2.3 CALL Syntax: CALL
The address of the next instruction is put on top of the c-stack and program execution continues at
. a-stack and flags are untouched. 3.2.4 RET Syntax: RET Program execution continues at the address indicated on top of the c-stack, and this address is removed from the c-stack. 3.3 A-Stack operations ---------------------- The machine uses the a-stack for calculations. It's a stack of words, not bytes. 3.3.1 PUSH Syntax: PUSH PUSH (
) Pushes or the word at in memory on stacktop of the a-stack. 3.3.2 POP Syntax: POP (
) Pops the word on stacktop of the a-stack and stores it in
. 3.3.3 PUSB Syntax: PUSB PUSB (
) Pushes or the byte at
in memory on top of the a-stack as word. The byte is set as low-byte of the word, the hi-byte is set to 0. [META: Would it make sense to use sign extension instead of 0 filling? Or even introduce a signed variant of PUSB?] 3.3.2 POPB Syntax: POPB (
) Pops the word on stacktop of the a-stack and stores the low-byte at
in memory. 3.4 Arithmatic operations ------------------------- The arithmatic operations take the two topmost elements of the a-stack perform the operation and push the result on the a-stack again. Flags will be set as expected. ADD SUB MUL DIV MOD CP 3.5 Bit operations ------------------ The bitwise operations take the two topmost elements of the a-stack (or only the stack top, for NOT), perform the operation and push the result on the a-stack again. Flags will be set as expected. AND OR XOR NOT 01234567890123456789012345678901234567890123456789012345678901234567890123456789