This is an intro to the Nucleus game and the kaon language. The goal is
to write a program (quark) that will outlive every other program, in a
shared memory core.
# Installation instructions
You can install lepton (the implimentation of nucleus) using flakes or
cargo (TODO!). Using nix flakes:
`nix run git+https://time.ta.rdis.dev/el/lepton` Using cargo:
`cargo install leptonvm(!)` (TODO!)
# Tutorial
The "core" is a linear sequence of random-access memory, 4096
instructions wide. Access are 0-indexed and wrap around (Address 4096 is
the same as address 0)
Example core (4 instructions wide)
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Index</th>
<th style="text-align: left;">Instruction</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;"><p>0</p></td>
<td style="text-align: left;"><p>JUMP</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>1</p></td>
<td style="text-align: left;"><p>ADD</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>2</p></td>
<td style="text-align: left;"><p>JUMP</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>3</p></td>
<td style="text-align: left;"><p>DIE</p></td>
</tr>
</tbody>
</table>
Quarks are written in a language called kaon. Every quark must start
with an author + title line. The format for a so-called "title line" is
`@ Author name : Program Name`, such as `@ John Doe : Brutus`. Quarks
are encouraged to have unique program names to reduce confusion about
winners
After the title line, one or more instructions follow. Each instruction
takes the form of keyword, followed by one or more arguments. Arguments
are comma-separated, with one or more spaces between the arguments and
keyword.
All arguments are also addresses. There are four kinds of addresses:
literal, absolute, relative, and relative-offset. Literal addresses are
a number, used as a value in a computation. They are stored in the core
as a `DIE` instruction. Absolute addresses are prefixed with a `#`, such
as `#3`. They reference addresses from the start of the core. A relative
address is a number of instructions ahead or behind the current
instruction, like `.1` (the next instruction). Each relative instruction
is prefixed with a `.`. The last type of address, a relative-offset
address takes the form of `.x#y`. This behaves like a relative address
**except** that the value of address `y` is added to the computed
relative address. This could be written as "The address x units from
where I am plus the value of address y".
**Jumps six instructions ahead**
die 5
jump .1#-1
If the instruction at `y` is not a `DIE`, the quark will stop execution.
For example, `.1#-1` will move the value of `.-1` spaces past the next
instruction (`.1`).
Each quark has its own thread. Each cycle, the computer switches between
threads. For two threads, A & B, this looks like: ABABABABABABAB; for
three: ABCABCABCABCABC. When a program dies, it is no longer executed.
If program C dies: ABC ABC AB AB AB. Dead quarks do **not** have their
memory zeroed or otherwise removed. This means you could jump into a
dead thread and revive it (though unlikely). A winner is declared when
there is only one thread left.
# Usage of lepton
Lepton is the reference implementation of nucleus. It is available at
<https://time.ta.rdis.dev/el/lepton>. Pass each program as an argument
to the command line. Use `RUST_LOG` to enable logging. `debug` will list
the loading and unloading of quarks. `trace` will print each instruction
being executed. Passing `-p` / `--playback` will produce a dump of the
core at each cycle for debugging / inspection. Each line contains the
state from the current cycle (first line is before execution, second
line is after cycle 1). To set the number of iterations, use `-i` /
`--iterations` (The default is 4096\*8)
# Example quarks
**A simple loop**
@ Ellie : Loop
jump .0
Jumps to the current address
**A quark that moves forward**
@ Ellie : Jogger
mov .0 .1
Copy the current instruction to the next instruction (which is then
executed)
**A quark that bombs the core with DIE**
@ Ellie : Bomber
jump .2
die 0
mov .-1 .3#-1
add 1, .-2
jump .-2
This uses relative-offset addresses to make the target of the bomb move
forward (`ADD`).
# Instruction reference
<table>
<colgroup>
<col style="width: 25%" />
<col style="width: 25%" />
<col style="width: 25%" />
<col style="width: 25%" />
</colgroup>
<tbody>
<tr class="odd">
<td style="text-align: left;"><p>Instruction syntax</p></td>
<td style="text-align: left;"><p>Arguments</p></td>
<td style="text-align: left;"><p>Results</p></td>
<td style="text-align: left;"><p>Notes</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p><code>move x, y</code></p></td>
<td style="text-align: left;"><p>x: The source address; y: the
destination address</p></td>
<td style="text-align: left;"><p>Copies value x to y</p></td>
<td style="text-align: left;"><p>y should not be constant.</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p><code>cmp x, y</code></p></td>
<td style="text-align: left;"><p>x: any value; y: any value</p></td>
<td style="text-align: left;"><p>Compares x to y and sets the equality
flag if they are</p></td>
<td style="text-align: left;"><p>Only compares equality</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p><code>ptlcmp x, y</code></p></td>
<td style="text-align: left;"><p>x: any value; y: any value</p></td>
<td style="text-align: left;"><p>Compares the instruction type of a to
b. Sets the flag if they are</p></td>
<td style="text-align: left;"><p><code>jump 0</code> ==
<code>jump 1</code></p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p><code>if a</code></p></td>
<td style="text-align: left;"><p>a: any address</p></td>
<td style="text-align: left;"><p>Jumps to a if the equality flag is set
(i.e. the last <code>cmp</code> was true)</p></td>
<td style="text-align: left;"><p>A constant is treated as an absolute
address.</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p><code>jump a</code></p></td>
<td style="text-align: left;"><p>a: any address</p></td>
<td style="text-align: left;"><p>Moves execution of the current thread
to address a.</p></td>
<td style="text-align: left;"><p>A constant is treated as an absolute
address.</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p><code>add a, b</code></p></td>
<td style="text-align: left;"><p>a: any value; b: any address</p></td>
<td style="text-align: left;"><p>Adds a to b and stores the result in
b</p></td>
<td style="text-align: left;"><p>b should not be constant. If b is
constant, the program dies.</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p><code>sub a, b</code></p></td>
<td style="text-align: left;"><p>a: any value; b: any address</p></td>
<td style="text-align: left;"><p>Subtracts a from b and stores the
result in b</p></td>
<td style="text-align: left;"><p>b should not be constant. If b is
constant, the programs dies.</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p><code>mul a, b</code></p></td>
<td style="text-align: left;"><p>a: any value; b: any address</p></td>
<td style="text-align: left;"><p>Multiplies a and b and stores the
result in b</p></td>
<td style="text-align: left;"><p>b should not be constant. If b is
constant, the programs dies.</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p><code>div a, b</code></p></td>
<td style="text-align: left;"><p>a: any value; b: any address</p></td>
<td style="text-align: left;"><p>divides a by b and stores the value in
b</p></td>
<td style="text-align: left;"><p>b should not be constant. The value of
b should not b 0. If either of these is true, the program dies.</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p><code>die x</code></p></td>
<td style="text-align: left;"><p>x: any literal</p></td>
<td style="text-align: left;"><p>If this instruction is executed, the
program stops. However, it stores data for use by other
instructions.</p></td>
<td style="text-align: left;"><p>Magic death trap</p></td>
</tr>
</tbody>
</table>