Update readme with basic notes

README.md

@@ -1,3 +1,57 @@
 # CardSimEngine
 
-Basic engine for NationStates-like "make decisions on issues" simulation games. Very basic.
+Basic engine for NationStates-like "make decisions on issues" simulation games. Very incomplete.
+
+## General turn model
+
+1. Player has a hand of cards. Each card has one or more actions available.
+2. Player chooses one action on one card.
+3. Action runs.
+4. Card is removed.
+5. Every rule in the player's rule collection runs, in order from lowest "step" to highest. If multiple rules have the same step number, they are run in shuffled order.
+6. Any changes to the rule collection requested during rule evaluation (presumably, commanded _by_ a rule) are applied after rules are applied.
+7. Turn counter increments.
+8. Player draws back to their hand limit. (If the deck and hand are empty, the game ends with an "end of history" error.)
+9. Game outputs all visible stats, deferred messages, warning messages, other game status updates, etc.
+10. Next turn.
+
+
+## Abstractions
+
+### Rule
+
+An arbitrary function running on player data, with a name and a step it runs in. It can ask to remove itself after execution.
+
+### RuleCollection
+
+Bucket of rules which may be updated during the game. Responsible for running rules (in some appropriate order) for the turn.
+
+### Card
+
+An event the user can act on.
+
+### CardOption
+
+A choice the user can make in response to some event and its consequences. Actions from CardOption instances are similar to rules, although changes to the actual rule collection are applied immediately.
+
+### Player
+
+A bucket of game state.
+
+### Stat
+
+An arbitrary variable (or function, if it's calculated) tagged with some stuff to make it easier to display to the player.
+
+### StatsCollection
+
+An arbitrary struct that contains the player's stats for some set of rules. Can be thought of as "the game-specific part of the player". 
+
+### Errors and warnings
+
+Errors wrapped in the `Warning` type, including those created by `Warningf`, represent events that should be reported (with stack traces, in debug mode) but shoudl not crash the game.
+
+There are some special errors that Rules can use to "communicate with" the rule execution logic in RulesCollection. Other non-Warning errors crash.
+
+### Messages
+
+For now, strings but inconvenient. Intended to provide forwards compatibility when we eventually include some way to format text, where all the stuff written for "it's just a string" would break if not for having this extra type in the way to wrap it where we can stay compatible with "it's just a string" mode.