readme

1 files changed, 49 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c272428
--- /dev/null
+++ b/README.md
@@ -0,0 +1,49 @@
+# yhtz - a yahtzee CLI game with 8 bytes of state
+
+Inspired by [The Bitwise Gamedev Challenge](https://github.com/zesterer/the-bitwise-challenge). 
+Not sure if this *technically* counts since there aren't really "frames", but 
+the spirit of the challenge is there -- the game should be able to be picked up 
+at any point using the single 8 byte state struct.
+
+## State layout
+
+### Byte 1
+
+* Roll count: 2 bits (high)
+* "Top" section flags: 6 bits, one for each number, indicating whether we've played it yet
+
+```
+	00 000000
+roll    ^^ ^^^^^^
+count---|| ||||||
+           654321
+```
+
+### Byte 2
+
+* "Top" rolling score: 7 bits (low)
+* High bit is ignored
+
+### Byte 3
+
+* "Bottom" section flags: 7 bits (low), one for each category
+* High bit is ignored
+
+### Byte 4
+
+* "Bottom" rolling score: 8 bits
+
+### Bytes 5-6
+
+* Dice: 5 total dice, each die has 3 bits, representing their current value
+* High bit is ignored
+
+```
+x 000 000 000 000 000
+  D4. D3. D2. D1. D0.
+```
+
+### Bytes 7-8
+
+* Seed: a 16-bit unsigned integer representing the seed for the random number generator.
+   Uses Dr. Lemire's [16-bit WyHash example](https://lemire.me/blog/2019/07/03/a-fast-16-bit-random-number-generator/).