From fe99042daca059d4be51bf8db52e78e766ac03c9 Mon Sep 17 00:00:00 2001
From: Benjamin Winston
Date: Thu, 19 Jun 2025 22:29:03 -0400
Subject: readme

---
 README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 README.md

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/).
-- 
cgit v1.2.3