diff --git a/LANGUAGE.md b/LANGUAGE.md index 7518aff..41552c5 100644 --- a/LANGUAGE.md +++ b/LANGUAGE.md @@ -134,13 +134,12 @@ An important concept in the VM is that each instruction has a specific "cycle co - **Basic Operations** (push, pop, mov, stack operations): 1 cycle - **Math Operations** (pow, sqrt, trigonometric functions): 2 cycles - **Component Operations**: - - `rotate`: 3 cycles - - `drive`: 2 cycles + - `rotate`: 2 cycles + - `drive`: 1 cycle - `fire`: 3 cycles - `scan`: 3 cycles - - `attack`: 5 cycles - **Control Flow**: - - `call` and `ret`: 3 cycles + - `call` and `ret`: 2 cycles - Jump instructions: 1 cycle This means a complex instruction like `fire` will take 3 simulation cycles to complete before the VM moves on to the next instruction. During this time, other robots will continue executing their own instructions. @@ -159,7 +158,7 @@ Example: start: ; Label mov @d0 0.0 ; Initialize @d0 to 0 (1 cycle) select 1 ; Select drive component (1 cycle) - drive MAX_SPEED ; Set drive speed using constant (2 cycles) + drive MAX_SPEED ; Set drive speed using constant (1 cycle) - max speed = 5 grid units/turn jmp start ; Jump back to start (1 cycle) ``` @@ -185,48 +184,46 @@ Registers are special storage locations that hold data values. The VM has severa ### General Purpose Data Registers These registers can be both read from and written to for general-purpose storage: -| Register | Description | Read/Write | -|----------|-------------|------------| -| `@d0` - `@d18` | General purpose data registers | Read/Write | -| `@c` | Counter register (used with `loop` instruction) | Read/Write | -| `@index` | Memory index register (used with `lod` and `sto` instructions) | Read/Write | +| Register | Description | Read/Write | +|----------------|----------------------------------------------------------------|------------| +| `@d0` - `@d18` | General purpose data registers | Read/Write | +| `@c` | Counter register (used with `loop` instruction) | Read/Write | +| `@index` | Memory index register (used with `lod` and `sto` instructions) | Read/Write | ### Status Registers These provide information about the VM state: -| Register | Description | Read/Write | -|----------|-------------|------------| -| `@result` | Result of the last `cmp` operation | Read/Write | -| `@fault` | Error code if a VM fault occurs | Read-only | -| `@turn` | Current simulation turn number | Read-only | -| `@cycle` | Current execution cycle within the turn | Read-only | -| `@rand` | Random value between 0.0 and 1.0 | Read-only | +| Register | Description | Read/Write | +|-----------|-----------------------------------------|------------| +| `@result` | Result of the last `cmp` operation | Read/Write | +| `@fault` | Error code if a VM fault occurs | Read-only | +| `@turn` | Current simulation turn number | Read-only | +| `@cycle` | Current execution cycle within the turn | Read-only | +| `@rand` | Random value between 0.0 and 1.0 | Read-only | ### Robot Status Registers These provide information about the robot's current state: -| Register | Description | Read/Write | -|----------|-------------|------------| -| `@health` | Current health points | Read-only | -| `@power` | Current energy/power level | Read-only | -| `@posx` / `@pos_x` | Robot's X coordinate | Read-only | -| `@posy` / `@pos_y` | Robot's Y coordinate | Read-only | -| `@component` | ID of currently selected component | Read-only (set only by `select`/`deselect` instructions) | +| Register | Description | Read/Write | +|--------------------|------------------------------------|----------------------------------------------------------| +| `@health` | Current health points | Read-only | +| `@power` | Current energy/power level | Read-only | +| `@posx` / `@pos_x` | Robot's X coordinate | Read-only | +| `@posy` / `@pos_y` | Robot's Y coordinate | Read-only | +| `@component` | ID of currently selected component | Read-only (set only by `select`/`deselect` instructions) | ### Component Status Registers These provide information about the currently selected component: -| Register | Description | Read/Write | -|----------|-------------|------------| -| `@drive_direction` | Direction the drive component is facing (degrees) | Read-only | -| `@drive_velocity` | Speed the drive component is moving at (units/cycle) | Read-only | -| `@turret_direction` | Direction the selected turret is facing (degrees) | Read-only | -| `@forward_distance` | Distance to obstacle in front of the drive | Read-only | -| `@backward_distance` | Distance to obstacle behind the drive | Read-only | -| `@weapon_power` | Power setting of the selected weapon | Read-only | -| `@weapon_cooldown` | Remaining cooldown cycles for the selected weapon | Read-only | -| `@target_distance` | Distance to the last detected target from the selected scanner | Read-only | -| `@target_direction` | Absolute angle to the last detected target from the selected scanner (degrees) | Read-only | +| Register | Description | Read/Write | +|----------------------|--------------------------------------------------------------------------------|------------| +| `@drive_direction` | Direction the drive component is facing (degrees) | Read-only | +| `@drive_velocity` | Speed the drive component is moving at (units/cycle) | Read-only | +| `@turret_direction` | Direction the selected turret is facing (degrees) | Read-only | +| `@forward_distance` | Distance to obstacle in front of the drive | Read-only | +| `@backward_distance` | Distance to obstacle behind the drive | Read-only | +| `@target_distance` | Distance to the last detected target from the selected scanner | Read-only | +| `@target_direction` | Absolute angle to the last detected target from the selected scanner (degrees) | Read-only | ## Instructions @@ -290,29 +287,29 @@ flowchart TD ### Stack Operations -| Instruction | Description | Operands | VM Cycle Cost | Stack/Register Effects | -|-------------|-------------|----------|---------------|------------------------| -| `push ` | Push a value onto the stack | Value or register | 1 | Stack: +1 item | -| `pop ` | Pop a value from stack into register | Register | 1 | Stack: -1 item, Register: written | -| `pop` | Pop and discard value from stack | None | 1 | Stack: -1 item | -| `dup` | Duplicate top value on stack | None | 1 | Stack: +1 item (copy of top) | -| `swap` | Swap top two values on stack | None | 1 | Stack: rearranged | +| Instruction | Description | Operands | VM Cycle Cost | Stack/Register Effects | +|------------------|--------------------------------------|-------------------|---------------|-----------------------------------| +| `push ` | Push a value onto the stack | Value or register | 1 | Stack: +1 item | +| `pop ` | Pop a value from stack into register | Register | 1 | Stack: -1 item, Register: written | +| `pop` | Pop and discard value from stack | None | 1 | Stack: -1 item | +| `dup` | Duplicate top value on stack | None | 1 | Stack: +1 item (copy of top) | +| `swap` | Swap top two values on stack | None | 1 | Stack: rearranged | ### Register Operations -| Instruction | Description | Operands | VM Cycle Cost | Stack/Register Effects | -|-------------|-------------|----------|---------------|------------------------| -| `mov ` | Copy value to register | Register, Value/Register | 1 | Register: written | -| `cmp ` | Compare values, store result | Two values/registers | 1 | `@result`: written | +| Instruction | Description | Operands | VM Cycle Cost | Stack/Register Effects | +|-----------------------------|------------------------------|--------------------------|---------------|------------------------| +| `mov ` | Copy value to register | Register, Value/Register | 1 | Register: written | +| `cmp ` | Compare values, store result | Two values/registers | 1 | `@result`: written | ### Memory Operations Memory operations allow your robot to store and retrieve values from a memory array, providing more storage beyond the limited number of registers. The VM maintains a 1024-element memory array that persists throughout program execution. -| Instruction | Description | Operands | VM Cycle Cost | Register Effects | -|-------------|-------------|----------|---------------|------------------| -| `lod ` | Load value from memory at `@index` position into register | Register | 1 | `@index`: auto-incremented, Register: written | -| `sto ` | Store value to memory at `@index` position | Value/Register | 1 | `@index`: auto-incremented | +| Instruction | Description | Operands | VM Cycle Cost | Register Effects | +|------------------|-----------------------------------------------------------|----------------|---------------|-----------------------------------------------| +| `lod ` | Load value from memory at `@index` position into register | Register | 1 | `@index`: auto-incremented, Register: written | +| `sto ` | Store value to memory at `@index` position | Value/Register | 1 | `@index`: auto-incremented | Memory access is controlled via the `@index` register, which points to the current memory location (0-1023). Both `lod` and `sto` operations automatically increment `@index` after execution, making it convenient to work with consecutive memory locations. @@ -360,37 +357,37 @@ Basic arithmetic operations (`add`, `sub`, `mul`, `div`, `mod`) also have an alt - Example: `add @d0 5` -> `@result` = value of `@d0` + 5. The stack is unchanged. - Example: `sub 10 @d1` -> `@result` = 10 - value of `@d1`. The stack is unchanged. -| Instruction | Description (Stack Form) | Operands (Stack Form) | Stack Effect (Stack Form) | Operands (Operand Form) | Effect (Operand Form) | VM Cycle Cost | -|-------------|----------------------------|-----------------------|---------------------------|-------------------------|-------------------------|---------------| -| `add` | Add top two values | None | -2, +1 items | ` ` | `@result` = op1 + op2 | 1 | -| `sub` | Subtract top from second | None | -2, +1 items | ` ` | `@result` = op1 - op2 | 1 | -| `mul` | Multiply top two values | None | -2, +1 items | ` ` | `@result` = op1 * op2 | 1 | -| `div` | Divide second by top | None | -2, +1 items | ` ` | `@result` = op1 / op2 | 1 | -| `mod` | Modulo (remainder) | None | -2, +1 items | ` ` | `@result` = op1 % op2 | 1 | -| `divmod` | Divide and return both quotient and remainder | None | 1 | -2, +2 items | N/A | N/A | 1 | -| `pow` | Exponentiation | None | -2, +1 items | ` ` | `@result` = base ^ exp | 2 | -| `sqrt` | Square root of top value | None | -1, +1 items | `` | `@result` = sqrt(value) | 2 | -| `log` | Natural logarithm | None | -1, +1 items | `` | `@result` = ln(value) | 2 | -| `sin` | Sine (degrees) | None | -1, +1 items | `` | `@result` = sin(degrees)| 2 | -| `cos` | Cosine (degrees) | None | -1, +1 items | `` | `@result` = cos(degrees)| 2 | -| `tan` | Tangent (degrees) | None | -1, +1 items | `` | `@result` = tan(degrees)| 2 | -| `asin` | Arc sine (result degrees) | None | -1, +1 items | `` | `@result` = asin(value) | 2 | -| `acos` | Arc cosine (result degrees)| None | -1, +1 items | `` | `@result` = acos(value) | 2 | -| `atan` | Arc tangent (result degrees)| None | -1, +1 items | `` | `@result` = atan(value) | 2 | -| `atan2` | Two-arg arc tan (result deg)| None | -2, +1 items | ` ` | `@result` = atan2(y, x)| 2 | -| `abs` | Absolute value | None | -1, +1 items | `` | `@result` = abs(value) | 1 | +| Instruction | Description (Stack Form) | Operands (Stack Form) | Stack Effect (Stack Form) | Operands (Operand Form) | Effect (Operand Form) | VM Cycle Cost | +|-------------|-----------------------------------------------|-----------------------|---------------------------|-------------------------|--------------------------|---------------| +| `add` | Add top two values | None | -2, +1 items | ` ` | `@result` = op1 + op2 | 1 | +| `sub` | Subtract top from second | None | -2, +1 items | ` ` | `@result` = op1 - op2 | 1 | +| `mul` | Multiply top two values | None | -2, +1 items | ` ` | `@result` = op1 * op2 | 1 | +| `div` | Divide second by top | None | -2, +1 items | ` ` | `@result` = op1 / op2 | 1 | +| `mod` | Modulo (remainder) | None | -2, +1 items | ` ` | `@result` = op1 % op2 | 1 | +| `divmod` | Divide and return both quotient and remainder | None | 1 | -2, +2 items | N/A | N/A | 1 | +| `pow` | Exponentiation | None | -2, +1 items | ` ` | `@result` = base ^ exp | 2 | +| `sqrt` | Square root of top value | None | -1, +1 items | `` | `@result` = sqrt(value) | 2 | +| `log` | Natural logarithm | None | -1, +1 items | `` | `@result` = ln(value) | 2 | +| `sin` | Sine (degrees) | None | -1, +1 items | `` | `@result` = sin(degrees) | 2 | +| `cos` | Cosine (degrees) | None | -1, +1 items | `` | `@result` = cos(degrees) | 2 | +| `tan` | Tangent (degrees) | None | -1, +1 items | `` | `@result` = tan(degrees) | 2 | +| `asin` | Arc sine (result degrees) | None | -1, +1 items | `` | `@result` = asin(value) | 2 | +| `acos` | Arc cosine (result degrees) | None | -1, +1 items | `` | `@result` = acos(value) | 2 | +| `atan` | Arc tangent (result degrees) | None | -1, +1 items | `` | `@result` = atan(value) | 2 | +| `atan2` | Two-arg arc tan (result deg) | None | -2, +1 items | ` ` | `@result` = atan2(y, x) | 2 | +| `abs` | Absolute value | None | -1, +1 items | `` | `@result` = abs(value) | 1 | ### Binary Operations These operations perform bitwise manipulations by first converting float values to 32-bit unsigned integers: -| Instruction | Description | Operands | VM Cycle Cost | Stack Effect | -|-------------|-------------|----------|---------------|--------------| -| `and` | Bitwise AND of top two values | None | 1 | -2, +1 items | -| `or` | Bitwise OR of top two values | None | 1 | -2, +1 items | -| `xor` | Bitwise XOR of top two values | None | 1 | -2, +1 items | -| `not` | Bitwise NOT of top value | None | 1 | -1, +1 items | -| `shl` | Shift left value by specified bits | None | 1 | -2, +1 items | -| `shr` | Shift right value by specified bits | None | 1 | -2, +1 items | +| Instruction | Description | Operands | VM Cycle Cost | Stack Effect | +|-------------|-------------------------------------|----------|---------------|--------------| +| `and` | Bitwise AND of top two values | None | 1 | -2, +1 items | +| `or` | Bitwise OR of top two values | None | 1 | -2, +1 items | +| `xor` | Bitwise XOR of top two values | None | 1 | -2, +1 items | +| `not` | Bitwise NOT of top value | None | 1 | -1, +1 items | +| `shl` | Shift left value by specified bits | None | 1 | -2, +1 items | +| `shr` | Shift right value by specified bits | None | 1 | -2, +1 items | For binary operations, the VM: 1. Pops the required number of values from the stack (1 for `not`, 2 for others) @@ -413,14 +410,14 @@ Binary operations also have an alternative form with operands: - Example: `and @d0 5` -> `@result` = value of `@d0` & 5 (as u32). The stack is unchanged. - Example: `shl @d0 2` -> `@result` = value of `@d0` << 2 (shifted left 2 bits). The stack is unchanged. -| Instruction | Description (Operand Form) | Operands | VM Cycle Cost | Effect | -|-------------|----------------------------|----------|---------------|--------| -| `and ` | Bitwise AND of two operands | Two values/registers | 1 | `@result` = op1 & op2 | -| `or ` | Bitwise OR of two operands | Two values/registers | 1 | `@result` = op1 \| op2 | -| `xor ` | Bitwise XOR of two operands | Two values/registers | 1 | `@result` = op1 ^ op2 | -| `not ` | Bitwise NOT of operand | Value/register | 1 | `@result` = ~op | -| `shl ` | Shift op1 left by op2 bits | Two values/registers | 1 | `@result` = op1 << op2 | -| `shr ` | Shift op1 right by op2 bits | Two values/registers | 1 | `@result` = op1 >> op2 | +| Instruction | Description (Operand Form) | Operands | VM Cycle Cost | Effect | +|-------------------|-----------------------------|----------------------|---------------|------------------------| +| `and ` | Bitwise AND of two operands | Two values/registers | 1 | `@result` = op1 & op2 | +| `or ` | Bitwise OR of two operands | Two values/registers | 1 | `@result` = op1 \| op2 | +| `xor ` | Bitwise XOR of two operands | Two values/registers | 1 | `@result` = op1 ^ op2 | +| `not ` | Bitwise NOT of operand | Value/register | 1 | `@result` = ~op | +| `shl ` | Shift op1 left by op2 bits | Two values/registers | 1 | `@result` = op1 << op2 | +| `shr ` | Shift op1 right by op2 bits | Two values/registers | 1 | `@result` = op1 >> op2 | Example using binary operations: ```asm @@ -453,18 +450,18 @@ mov @d3 @result ; Update @d3 with the shifted value ### Control Flow -| Instruction | Description | Operands | VM Cycle Cost | Effect | -|-------------|-------------|----------|---------------|--------| -| `jmp