# Redstone Computer Language Reference

This document describes the small 8-bit language used by the `redstone_computer`
blocks: the Redstone Computer and the Redstone Controller. It is written as an
implementation reference for humans and LLMs that need to generate valid
programs.

## Mental Model

The redstone computer family is made of powered, deterministic redstone
components.

- Redstone Computer: compact programmable logic component.
- Redstone Controller: orchestration variant crafted from the Computer, with
  more RAM and a larger CPU budget for bus and network-style builds.

On every server tick:

1. The block reads redstone strength from all six neighboring faces.
2. If every input face is `0`, the computer is asleep.
3. If at least one input face is greater than `0`, the program runs from the top.
4. Before the program runs, all redstone outputs and the comparator value are reset
   to `0`.
5. The program may write redstone outputs, comparator output, RAM, and item
   movement commands.
6. The result is published to the world as redstone output by face.

Important: registers and flags are temporary. They reset every tick. RAM and the
program text are persistent.

## Limits

- Maximum source length: `4096` characters.
- Maximum parsed instructions: `128`.
- Maximum executed instructions per powered tick: `96` on Computer, `256` on
  Controller.
- RAM size: `256` bytes on Computer, `1024` bytes on Controller.
- Register size: `8-bit`, values wrap with `value & 255`.
- Redstone output range: clamped to `0..15`.
- Comparator output range: clamped to `0..15`.
- Item movement per `PUSH`/`PUSHIF`/`ROUTE`/`ROUTEIF`: at most `64` items,
  limited by slot space.

## Syntax

Programs are line-based.

```asm
LABEL:
OP ARG1, ARG2
OP ARG1 ARG2
; comment
# comment
```

Rules:

- Opcodes, registers, labels, and port names are case-insensitive.
- Commas are optional separators. `LD A, NORTH` and `LD A NORTH` are equivalent.
- Comments start at `;` or `#`.
- Blank lines are ignored.
- A label is any single token followed by `:`.
- A label can be on its own line or before an instruction.
- Labels must be unique.
- Jump targets must exist at compile time.

## Execution State

### Registers

The CPU has four temporary 8-bit registers:

- `A`
- `B`
- `C`
- `D`

Aliases:

- `R2` and `C_REG` also refer to register `C`.

Registers are reset to `0` every powered tick because the CPU starts fresh each
tick.

### Flags

The CPU has two temporary flags:

- `ZERO`
- `CARRY`

Readable flag values:

- `Z` or `ZERO`: returns `15` if the zero flag is true, otherwise `0`.
- `CARRY`: returns `15` if the carry flag is true, otherwise `0`.

Do not use `C` for carry. `C` is register `C`.

### RAM

RAM is persistent and stored inside the block.

- Redstone Computer: `256` byte cells.
- Redstone Controller: `1024` byte cells.

Use bracket syntax to read or write RAM:

```asm
LD A, [0]
LD [1], A
STORE 2, A
```

RAM addresses wrap around the current block's RAM size.
RAM values are stored as `value & 255`.

## Values

An argument can be:

- a register: `A`, `B`, `C`, `D`
- a decimal number: `15`, `255`, `-1`
- a hexadecimal number: `0xFF` or `$FF`
- a binary number: `%10101010`
- a RAM reference: `[0]`, `[A]`
- a boolean literal: `ON`, `TRUE`, `OFF`, `FALSE`
- a flag: `ZERO`, `Z`, `CARRY`
- a port name: `NORTH`, `ITEMS`, `POWER`, `BUS_IN`, `BUS_OUT`
- comparator aliases: `CMP`, `COMPARE`, `COMPARATOR`

Boolean literals:

- `ON` and `TRUE` return `15`.
- `OFF` and `FALSE` return `0`.

## Redstone Ports

Input face ports read redstone strength from adjacent blocks:

- `NORTH` or `N`
- `SOUTH` or `S`
- `EAST` or `E`
- `WEST` or `W`
- `UP`, `TOP`, or `U`
- `DOWN`, `BOTTOM`, or `D`

Input aliases:

- `IN_NORTH`
- `INPUT_NORTH`
- same pattern for every face

Special input ports:

- `POWER` or `PWR`: maximum input signal across all six faces.
- `ITEMS`, `INPUT`, `INPUT_ITEMS`, `IN_ITEMS`: number of items in the input slot.
- `OUTPUT`, `OUTPUT_ITEMS`, `OUT_ITEMS`: number of items in the output slot.

Output ports are written with `OUT`, `POWER`, `LD`, `MOV`, or `SET` when the
target is a face.

Output aliases:

- `OUT EAST, A`
- `OUT OUT_EAST, A`
- `OUT O_EAST, A`
- `LD EAST, A`

Face output values are clamped to redstone strength `0..15`.

Implementation note: program directions are physical world directions from the
computer's point of view. `OUT EAST, 15` powers the neighboring block east of the
computer. Internally Minecraft queries that signal with the opposite side
(`WEST`), but the language hides that vanilla detail.

### Bus Convention

Both Computers and Controllers can use a simple redstone bus convention. The
Controller is not the only block allowed to use it; it just has more RAM and CPU
budget, so it is better suited to orchestrating several modules.

Input aliases:

- `BUS`, `BUS_IN`, `DATA`, `DATA_IN`, `IN_DATA`, `RX`: read `WEST`.
- `CLOCK`, `CLK`, `CLOCK_IN`, `CLK_IN`: read `NORTH`.
- `MODE`, `MODE_IN`: read `UP`.
- `RST`, `RESET_IN`, `RST_IN`: read `DOWN`.

Output aliases:

- `BUS`, `BUS_OUT`, `DATA`, `DATA_OUT`, `OUT_DATA`, `TX`: write `EAST`.
- `READY`, `READY_OUT`, `ACK`, `ACK_OUT`, `ERROR`, `ERR`: write `SOUTH`.
- `CLOCK`, `CLK`, `CLOCK_OUT`, `CLK_OUT`: write `NORTH`.
- `MODE`, `MODE_OUT`: write `UP`.
- `RST`, `RESET`, `RESET_OUT`, `RST_OUT`: write `DOWN`.

Context matters: `LD A, BUS` reads the west input, while `OUT BUS, A` writes to
the east output.

## Inventory and Hoppers

The block has two internal item slots:

- input slot: visible to automation on all sides except `DOWN`
- output slot: visible to automation on `DOWN`

The program can inspect and move items:

- `MATCH A, minecraft:iron_ingot`
- `COUNT A`
- `COUNT A, minecraft:iron_ingot`
- `PUSH 1`
- `PUSHIF A, 1`
- `ROUTE DOWN, 1`
- `ROUTEIF A, EAST, 1`

Item identifiers:

- Use full ids like `minecraft:iron_ingot` when possible.
- If the namespace is omitted, `minecraft:` is assumed by the current
  implementation.

`PUSH` moves items from input slot to output slot. It only works if:

- the input slot is not empty;
- the output slot is empty or contains the same item with same components;
- the output slot has space.

`ROUTE` moves items from the input slot directly into an adjacent inventory on a
chosen face. For example, `ROUTE DOWN, 1` inserts one item into the container
below the computer, while `ROUTE EAST, 1` inserts into the container east of the
computer. Use this for split paths such as accepted items versus rejected items.

After `PUSH`, `PUSHIF`, `ROUTE`, or `ROUTEIF`, register `A` is overwritten with
the number of moved items. The zero flag is true if no items moved.

## Comparator

The comparator output is controlled by the program.

Valid forms:

```asm
COMPARE A
ANALOG ITEMS
COMPARATOR 15
LD COMPARE, A
```

Comparator values are clamped to `0..15`.

Because comparator output resets at the start of every tick, a program must write
the comparator value every powered tick if it should stay active.

## Instruction Reference

### No-op and Stop

```asm
NOP
HALT
END
STOP
```

- `NOP`: does nothing.
- `HALT`, `END`, `STOP`: stop execution for the current tick.

### Load and Store

```asm
LD target, value
LOAD target, value
RECV target, value
MOV target, value
SET target, value
STORE address, value
```

Targets can be registers, RAM cells, comparator aliases, or output faces.
`RECV` is an alias for `LD` intended for bus programs.

Examples:

```asm
LD A, NORTH
LD [0], A
LD EAST, A
STORE 1, A
MOV COMPARE, A
```

### Redstone Output

```asm
OUT face, value
POWER face, value
SEND face, value
```

Examples:

```asm
OUT EAST, 15
POWER SOUTH, A
```

`POWER` is an alias for `OUT` when used as an instruction.
`POWER` is also a readable port when used as a value.
`SEND` is an alias for `OUT` intended for bus programs.

### Comparator Output

```asm
ANALOG value
COMPARE value
COMPARATOR value
```

All three instructions write the comparator output.

### Arithmetic and Bitwise

```asm
ADD register, value
SUB register, value
AND register, value
OR register, value
XOR register, value
MIN register, value
MAX register, value
SHL register, value
SHR register, value
```

The first argument must be a register.
The result is stored back in that register.

Carry behavior:

- `ADD`: carry is true if `left + right > 255`.
- `SUB`: carry is true if `left < right`.
- `SHL`, `SHR`, `AND`, `OR`, `XOR`, `MIN`, `MAX` do not currently update carry
  except where the previous carry value remains unchanged.

Zero behavior:

- zero is true if the resulting register value is `0`.

Shift amounts are clamped to `0..7`.

### Unary Register Operations

```asm
NOT register
BOOL register
INC register
DEC register
```

- `NOT`: bitwise invert, then keep low 8 bits.
- `BOOL`: turns any non-zero value into `15`, keeps zero as `0`.
- `INC`: add 1.
- `DEC`: subtract 1.

### Comparisons

```asm
EQ register, value
NE register, value
GT register, value
LT register, value
GE register, value
LE register, value
```

The first argument must be a register.
The register becomes:

- `15` if the comparison is true;
- `0` if false.

Flags:

- zero is true when the comparison is false;
- carry is true when `left < right`.

### Flag-Only Compare

```asm
CMP value, value
TEST value, value
```

These do not write a register.

Flags:

- zero is true if the two values are equal.
- carry is true if the first value is less than the second.

### Jumps

```asm
JMP label
JZ label
JNZ label
JC label
JNC label
```

- `JMP`: unconditional jump.
- `JZ`: jump if zero flag is true.
- `JNZ`: jump if zero flag is false.
- `JC`: jump if carry flag is true.
- `JNC`: jump if carry flag is false.

Jump targets must be labels.
Infinite loops are stopped by the 96-instruction budget.
On a Controller, the loop budget is 256 instructions per powered tick.

### Item Instructions

```asm
MATCH register, item_id
COUNT register
COUNT register, item_id
PUSH
PUSH amount
PUSHIF condition
PUSHIF condition, amount
ROUTE face
ROUTE face, amount
ROUTEIF condition, face
ROUTEIF condition, face, amount
```

- `MATCH`: sets register to `15` if the input slot item matches `item_id`,
  otherwise `0`.
- `COUNT`: sets register to the input item count, optionally filtered by item id.
- `PUSH`: moves items from input slot to output slot. Default amount is `1`.
- `PUSHIF`: pushes only if `condition > 0`.
- `ROUTE`: moves items from the input slot into the neighboring inventory on
  `face`. Default amount is `1`.
- `ROUTEIF`: routes only if `condition > 0`.
- `EJECT` and `PUSHTO` are aliases for `ROUTE`.
- `EJECTIF` and `PUSHTOIF` are aliases for `ROUTEIF`.

### Reset

```asm
RESET
```

Resets redstone outputs, comparator output, registers, zero flag, and carry flag
for the current tick. It does not clear RAM or item slots.

## Examples

### Analog AND Gate

For redstone strengths, analog AND is represented by the minimum of two inputs.

```asm
LD A, NORTH
MIN A, WEST
OUT EAST, A
COMPARE A
HALT
```

### Digital AND Gate

Only output 15 when both inputs are non-zero.

```asm
LD A, NORTH
BOOL A
LD B, WEST
BOOL B
AND A, B
OUT EAST, A
COMPARE A
HALT
```

### OR Gate

```asm
LD A, NORTH
MAX A, WEST
OUT EAST, A
COMPARE A
HALT
```

### XOR Gate for Digital Signals

```asm
LD A, NORTH
BOOL A
LD B, WEST
BOOL B
XOR A, B
OUT EAST, A
COMPARE A
HALT
```

### Rising Counter While Powered

This counter persists in RAM. It increments once per powered tick.

```asm
LD A, [0]
INC A
LD [0], A
LD B, A
AND B, 15
OUT EAST, B
COMPARE B
HALT
```

### Serial Bus Relay

Read bus data from `WEST`, mirror it to `EAST`, and expose a ready signal on
`SOUTH` when the clock input on `NORTH` is active.

```asm
RECV A, BUS_IN
RECV B, CLOCK
SEND BUS_OUT, A
BOOL B
SEND READY, B
COMPARE A
HALT
```

### Controller Memory Latch

Use a Controller as a tiny bus memory: when `CLOCK` is on, save `BUS_IN` into
RAM, then continuously output the stored value on `BUS_OUT`.

```asm
RECV A, BUS_IN
RECV B, CLOCK
BOOL B
JZ read
LD [0], A
read:
LD C, [0]
SEND BUS_OUT, C
COMPARE C
HALT
```

### Two-output Item Filter

Route iron ingots into the container below the computer and reject every other
item into the container east of the computer. `OUT SOUTH, B` can drive a lamp
when a rejected item is present.

```asm
COUNT C
BOOL C
MATCH B, minecraft:iron_ingot
ROUTEIF B, DOWN, 1
EQ B, 0
AND B, C
ROUTEIF B, EAST, 1
OUT SOUTH, B
COMPARE ITEMS
HALT
```

### Item Counter Alarm

Output redstone if there are at least 16 input items.

```asm
COUNT A
GE A, 16
OUT EAST, A
COMPARE ITEMS
HALT
```

## LLM Generation Guidelines

When generating programs:

1. End simple programs with `HALT`.
2. Use `COMPARE value` every tick if comparator output matters.
3. Use `OUT face, value` every tick if redstone output should remain active.
4. Use `BOOL` before bitwise gates when the desired behavior is digital.
5. Use `MIN` for analog AND-like behavior.
6. Use `MAX` for analog OR-like behavior.
7. Store persistent state in RAM, not registers.
8. Avoid loops unless necessary; the VM only runs 96 instructions per powered
   tick.
9. Use full item ids like `minecraft:iron_ingot`.
10. Use `ROUTE`/`ROUTEIF` for item filters with multiple physical outputs.
11. Use `RECV`/`SEND` and the bus aliases when generating serial Computer or
    Controller programs.
12. Prefer Controller for orchestration programs that need more RAM or a longer
    loop budget.
13. Remember that the computer does nothing unless at least one face receives
    redstone power.

## Common Mistakes

- Using `C` as carry. Use `CARRY`; `C` is a register.
- Forgetting that registers reset every tick.
- Forgetting that outputs reset every tick.
- Writing `OUT ITEMS, A`; `ITEMS` is an input count, not an output face.
- Writing to an unknown face name.
- Assuming `PUSHIF` or `ROUTEIF` preserves `A`; item movement instructions
  overwrite `A` with the moved item count.
- Using `ROUTE` without a neighboring inventory on that face; the move count will
  be `0`.
- Creating an unconditional loop without a clear reason.