aboutsummaryrefslogtreecommitdiff
path: root/bin
diff options
context:
space:
mode:
authorPaul Oliver <contact@pauloliver.dev>2024-02-29 02:29:13 +0100
committerPaul Oliver <contact@pauloliver.dev>2024-02-29 02:29:13 +0100
commitca0015ebf89baa1f8adfcefde4a91a7e22dd4ff2 (patch)
tree31eb9380dcd9e01bc287a3d2b2c2343fa5c96cd3 /bin
parent39abbc1596fde561111ce388f01e727452cdab96 (diff)
Added viewer/controller README.md file inside bin directory.
Diffstat (limited to 'bin')
-rw-r--r--bin/README.md69
1 files changed, 69 insertions, 0 deletions
diff --git a/bin/README.md b/bin/README.md
new file mode 100644
index 0000000..059439d
--- /dev/null
+++ b/bin/README.md
@@ -0,0 +1,69 @@
+## Salis.py: Viewer/Controller Interface for the Salis Simulator
+*Salis.py* is a text user interface (TUI) written in Python, designed to
+communicate with the *SALIS* library via the `ctypes` module. To run it, you
+must have Python3 installed and in your PATH, as well as the Cython package
+installed.
+
+### Running SALIS
+You may run SALIS in one of the following ways. Top example creates a new
+simulation of order 16 and gives it the name `./bin/sims/16.sim`. The second
+one attempts to load an existing save-file from the `./bin/sims` directory.
+```bash
+$ ./bin/salis.py new --order 16 --file 16.sim
+$ ./bin/salis.py load --file 16.sim
+```
+
+### Keyboard commands
+|Key |Action |
+|:---|------:|
+|Left/Right arrow |Previous/next page |
+|Up/Down arrows |Scroll page up/down if it can't fit terminal |
+|`wasd` |Scroll/pan (PROCESS and WORLD page) |
+|`S` |Scroll to top (PROCESS and WORLD page) |
+|`A` |Scroll to left (PROCESS page) |
+|`zx` |Zoom in/out (WORLD page) |
+|`op` |Select previous/next organism |
+|`g` |Toggle data/gene view (PROCESS page) |
+|`c` |Open console (pauses simulation) |
+|Space |Run/pause simulation |
+|`fl` |Select first/last organism |
+|`k` |Scroll/go to selected (PROCESS and WORLD page) |
+|`X` |Toggle hex/decimal value printing |
+|Numbers `[1..0]` |Cycle simulation `2^(n-1) % 10` steps |
+|Enter |Activate cursor (WORLD page) |
+|Escape |Save and quit simulation |
+
+### Console commands
+The console opens up when `c` is pressed. Commands, with their respective
+parameters separated by whitespace, may be written in order to modify or
+control some aspects of the simulation.
+
+|Command |Arg. 1 |Arg. 2+ |Description |
+|:-------|:------|:-------|-----------:|
+|`q \| quit` |--- |--- |Save and quit simulation |
+|`q! \| quit!` |--- |--- |Quit without saving |
+|`i \| input` |genome |addresses |Write genome into given addresses |
+|`c \| compile` |file |addresses |Compile genome on file into addresses |
+|`n \| new` |size |addresses |Initialize new organism(s) into addresses |
+|`k \| kill` |--- |--- |Kill organism on bottom of queue |
+|`e \| exec` |command |--- |Execute python string as command |
+|`s \| scroll` |value |--- |Scroll to Nth process or memory address |
+|`p \| process` |id |--- |Select process by ID |
+|`r \| rename` |name |--- |Give simulation a new name |
+|`s \| save` |--- |--- |Save simulation |
+|`a \| auto` |interval |--- |Set simulation's auto-save interval |
+
+### Color Legend
+In WORLD view, as well as in PROCESS view (when gene mode is selected), each
+cell is colored according to the following legend:
+
+|Background color |Meaning |
+|:----------------|-------:|
+|BLACK |Non-allocated cell |
+|BLUE |Allocated cell |
+|CYAN |Start of memory block |
+|WHITE |IP(s) currently at address |
+|YELLOW |Main memory block of selected organism |
+|GREEN |Child memory block of selected organism |
+|MAGENTA |SP of selected organism |
+|RED |IP of selected organism |