From ca0015ebf89baa1f8adfcefde4a91a7e22dd4ff2 Mon Sep 17 00:00:00 2001 From: Paul Oliver Date: Thu, 29 Feb 2024 02:29:13 +0100 Subject: Added viewer/controller README.md file inside bin directory. --- README.md | 2 ++ bin/README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 bin/README.md diff --git a/README.md b/README.md index b6aad80..a7c87ee 100644 --- a/README.md +++ b/README.md @@ -138,6 +138,8 @@ $ ./bin/salis.py new --order 16 --file 16.sim $ ./bin/salis.py load --file 16.sim ``` +Look at README file inside the `./bin` directory for a full list of commands. + ### New features on Salis-2.0 - Tierran templates are now used instead of keys/lock pairs - The instruction set is shorter 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 | -- cgit v1.2.1