From fa489cdbabe8138b486c06b7aee13f74327a6d66 Mon Sep 17 00:00:00 2001
From: Michael Peters <michael@styx>
Date: Sun, 4 Aug 2024 14:08:44 -0700
Subject: [PATCH] add tips and a readme

---
 src/components/snake/index.scss | 16 ++++++++++++++-
 src/components/snake/index.tsx  | 27 ++++++++++++++++++-------
 src/components/snake/readme.md  | 35 +++++++++++++++++++++++++++++++++
 3 files changed, 70 insertions(+), 8 deletions(-)
 create mode 100644 src/components/snake/readme.md

diff --git a/src/components/snake/index.scss b/src/components/snake/index.scss
index 1c79c75..614f01f 100644
--- a/src/components/snake/index.scss
+++ b/src/components/snake/index.scss
@@ -5,12 +5,14 @@
     display: flex;
     flex-flow: row nowrap;
 
-    .ui {
+    #ui {
         display: flex;
         flex-flow: row nowrap;
         align-items: flex-start;
         justify-content: flex-start;
 
+        margin-bottom: 10px;
+
         canvas#board {
             margin-right: 20px;
         }
@@ -25,4 +27,16 @@
             }
         }
     }
+
+    #tips {
+        display: flex;
+
+        :not(:last-child) {
+            margin-right: 20px;
+        }
+
+        a {
+            color: inherit;
+        }
+    }
 }
diff --git a/src/components/snake/index.tsx b/src/components/snake/index.tsx
index 313ec95..be2d1f9 100644
--- a/src/components/snake/index.tsx
+++ b/src/components/snake/index.tsx
@@ -78,13 +78,26 @@ const SnakePage: FC = () => {
 
     return (
         <div id="snake">
-            <div className="ui">
-                <canvas id="board" ref={boardRef} width={BOARD_SIZE} height={BOARD_SIZE} />
-                <div className="table-container">
-                    <table id="snaps">
-                        <thead>{tableHead('Itr', 'Avg', 'Min', '20%', '40%', '60%', '80%', '90%', '95%', 'Max')}</thead>
-                        <tbody>{labSnapsTRs}</tbody>
-                    </table>
+            <div>
+                <div id="ui">
+                    <canvas id="board" ref={boardRef} width={BOARD_SIZE} height={BOARD_SIZE} />
+                    <div className="table-container">
+                        <table id="snaps">
+                            <thead>
+                                {tableHead('Itr', 'Avg', 'Min', '20%', '40%', '60%', '80%', '90%', '95%', 'Max')}
+                            </thead>
+                            <tbody>{labSnapsTRs}</tbody>
+                        </table>
+                    </div>
+                </div>
+                <div id="tips">
+                    <div>5,000 snakes per generation</div>
+                    <div>Press Spacebar for Slow Motion</div>
+                    <div>
+                        <a href="https://git.beefslab.com/michael/webai/src/branch/master/src/components/snake">
+                            View Repo
+                        </a>
+                    </div>
                 </div>
             </div>
         </div>
diff --git a/src/components/snake/readme.md b/src/components/snake/readme.md
new file mode 100644
index 0000000..3764b25
--- /dev/null
+++ b/src/components/snake/readme.md
@@ -0,0 +1,35 @@
+# Snake Lab
+
+Allows you to create neural networks that play snake.
+
+Clone this repo, install with `npm install`, and run `make serve` to adjust the simulation.
+
+## Configurable Options:
+
+| option | description | default |
+|--------|-------------|---------|
+| SNAKES  | Number of snakes per iteration | 5,000 |
+| STARVE_STEPS | Number of steps without food before a snake dies of starvation | 120 |
+| CULL_RATIO | Ratio of snakes that are selected against every iteration | 0.8 (80%) |
+| MUTATE_RATE | Rate at which individual Perceptron weights are mutated | 0.03 (3%) |
+| MUTATE_MAG | Maximum magnitude for a Perceptron weight to change if it mutates | 5.0 |
+| hiddenLayerNodes | Number of nodes in each snake's hidden layer | 6 |
+
+## Game State Features (See also: `snake-brain.ts`)
+
+| feature | description |
+|---------|-------------|
+| Head Position (x, y) | The position of the snake's head |
+| Apple Relative to Head (x, y) | The position of the apple relative to the snake's head |
+| Distance to Tail (+/- x, +/- y) | The distance to the closest square occupied by the snake's tail in 4 directions |
+
+## Directory Structure
+
+| file | description |
+|------|-------------|
+| brain.ts | General Perceptron Neural Network |
+| game-engine.ts | Canvas Rendering Tools |
+| snake-brain.ts | Converts game states into feature vectors and decides movement direction |
+| hashset.tsx | Hash Set implementation used for detecting cycles |
+| index.tsx | UI Layer |
+| canvas.ts | Game Loop & Canvas Rendering Loop |