Reference · ISA version 13
All 64 instructions.
Stack effects are written ( before -- after ) with the top of stack rightmost. A ⟨t⟩ marks an instruction that consumes a template.
What each cell carries
A cell executes a fixed number of instructions per tick — sixteen by default — and each costs energy. HALT yields the rest of the budget and refunds part of its cost, which makes dormancy something a lineage can evolve into.
| Data stack | 16 × i16 | Circular. Popping an empty stack yields zero; pushing a full one overwrites the oldest entry. |
| Call stack | 8 × u16 | Circular, for the same reason. |
| Registers | 16 × i16 | Addressed modulo 16, so every index is legal. |
| Scratch RAM | 64 words | Addressed modulo 64. |
| PA, PB | u16 | Source and destination pointers, for copying genome bytes. |
| LN | unsigned | Copy-length counter. Saturates at zero rather than wrapping. |
| IP | u16 | Instruction pointer. Wraps modulo genome length. |
Templates, literals, stack and memory
0x00–0x0FThe two NOPs are not filler. They are the letters templates are written in, which is why a genome that looks like padding is usually addressing.
| Byte | Name | Stack effect | Notes |
|---|---|---|---|
| 0x00 | NOP0 | ( -- ) | template letter 0 |
| 0x01 | NOP1 | ( -- ) | template letter 1 |
| 0x02 | IMM<t> | ( -- v ) | push the template's value |
| 0x03 | ZERO | ( -- 0 ) | |
| 0x04 | ONE | ( -- 1 ) | |
| 0x05 | DUP | ( a -- a a ) | |
| 0x06 | DROP | ( a -- ) | |
| 0x07 | SWAP | ( a b -- b a ) | |
| 0x08 | OVER | ( a b -- a b a ) | |
| 0x09 | ROT | ( a b c -- b c a ) | |
| 0x0A | LOAD | ( addr -- v ) | scratch RAM |
| 0x0B | STORE | ( v addr -- ) | scratch RAM |
| 0x0C | RLOAD | ( idx -- v ) | register |
| 0x0D | RSTORE | ( v idx -- ) | register |
| 0x0E | RAND | ( -- v ) | hashed, not streamed — see determinism |
| 0x0F | SETBADGE | ( v -- ) | set own public badge, 15 bits. Inherited at division; anything touching can read it; the engine does nothing with it (ISA 4, took the reserved slot) |
Arithmetic and logic
0x10–0x1FAll saturating. Division and modulo by zero yield zero. Nothing here can fault, because nothing in the machine can fault.
| Byte | Name | Stack effect | Notes |
|---|---|---|---|
| 0x10 | ADD | ( a b -- a+b ) | |
| 0x11 | SUB | ( a b -- a−b ) | |
| 0x12 | MUL | ( a b -- a×b ) | |
| 0x13 | DIV | ( a b -- a÷b ) | 0 if b = 0 |
| 0x14 | MOD | ( a b -- a mod b ) | 0 if b = 0 |
| 0x15 | NEG | ( a -- −a ) | |
| 0x16 | ABS | ( a -- |a| ) | |
| 0x17 | MIN | ( a b -- min ) | |
| 0x18 | MAX | ( a b -- max ) | |
| 0x19 | SHL | ( a n -- a≪n ) | n is an address: reduced mod 16 |
| 0x1A | SHR | ( a n -- a≫n ) | arithmetic, sign preserved |
| 0x1B | AND | ( a b -- a∧b ) | |
| 0x1C | OR | ( a b -- a∨b ) | |
| 0x1D | XOR | ( a b -- a⊕b ) | |
| 0x1E | NOT | ( a -- ¬a ) | |
| 0x1F | CMP | ( a b -- sign ) | −1, 0 or 1 |
Control flow and replication machinery
0x20–0x2FJumps search for the complement of their template rather than an address, which is why cutting a genome in half tends to produce two working halves instead of two crashes.
| Byte | Name | Stack effect | Notes |
|---|---|---|---|
| 0x20 | JMPF<t> | ( -- ) | forward to the complement |
| 0x21 | JMPB<t> | ( -- ) | backward to the complement |
| 0x22 | JMPZ<t> | ( a -- ) | if a = 0 |
| 0x23 | JMPNZ<t> | ( a -- ) | if a ≠ 0 |
| 0x24 | CALL<t> | ( -- ) | jump and push a return offset |
| 0x25 | RET | ( -- ) | pop a return offset |
| 0x26 | GENE<t> | ( -- ) | the template is the gene's promoter |
| 0x27 | EXPRESS<t> | ( -- ) | call the nearest-matching promoter |
| 0x28 | SKIPZ | ( a -- ) | if a = 0, skip the next instruction and its template |
| 0x29 | SETPA | ( v -- ) | source pointer |
| 0x2A | SETPB | ( v -- ) | destination pointer |
| 0x2B | SETLN | ( v -- ) | copy counter; clamps at 0 |
| 0x2C | GLEN | ( -- n ) | own genome length |
| 0x2D | LOOPLN<t> | ( -- ) | jump back while LN ≠ 0 |
| 0x2E | HALT | ( -- ) | yield the rest of the tick, and get some of its cost back |
| 0x2F | RESERVED_1 | ( -- ) | no-op |
Body and world
0x30–0x3FThe stack effects here happen whether or not the world can satisfy them. A genome's stack discipline must not depend on whether the cell running it owns a chloroplast.
| Byte | Name | Stack effect | Notes |
|---|---|---|---|
| 0x30 | BUILD | ( param type slot -- ) | begin constructing an organelle |
| 0x31 | TEAR | ( slot -- ) | dismantle, recover matter |
| 0x32 | OSET | ( v idx slot -- ) | control input |
| 0x33 | OGET | ( idx slot -- v ) | read an output |
| 0x34 | OTYPE | ( slot -- type ) | |
| 0x35 | EAT | ( amount chem -- got ) | from local fluid |
| 0x36 | EMIT | ( amount chem -- sent ) | to local fluid |
| 0x37 | BUD | ( size -- ok ) | allocate a daughter buffer; sets PB = 0 |
| 0x38 | COPYB | ( -- ) | daughter[PB] = genome[PA]; PA++, PB++, LN−− |
| 0x39 | SPLIT | ( -- ) | finalise division |
| 0x3A | JOIN | ( key kind handle -- ok ) | attempt a junction |
| 0x3B | LEAVE | ( jidx -- ) | dissolve a junction |
| 0x3C | JXFER | ( amount what jidx -- moved ) | transfer over a soft junction |
| 0x3D | JLEN | ( v jidx -- ) | junction rest length — this is muscle |
| 0x3E | SETKEY | ( v -- ) | own receptor key, v & 0x7F |
| 0x3F | INJECT | ( jidx -- ok ) | write a byte into another cell's nucleus |
Versioning