From a6b2c92f86bbded5c5ac0e6ea01af527bfd6fa03 Mon Sep 17 00:00:00 2001
From: Kistaro Windrider <kistaro@gmail.com>
Date: Sat, 1 Apr 2023 20:04:20 -0700
Subject: [PATCH] Comment and reorganize Player.

---
 cardsim/player.go | 94 ++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 81 insertions(+), 13 deletions(-)

diff --git a/cardsim/player.go b/cardsim/player.go
index 562394f..1f0da89 100644
--- a/cardsim/player.go
+++ b/cardsim/player.go
@@ -52,21 +52,89 @@ import "math/rand"
 // the specific kind of interface that works with your game. There's more detail
 // on this in the comment on `Rule[C]`.
 type Player[C StatsCollection] struct {
-	Stats             C
-	Name              string
-	Deck              *Deck[C]
-	Hand              []Card[C]
-	HandLimit         int
-	ActionsPerTurn    int
-	ActionsRemaining  int
-	PermanentActions  []Card[C]
-	InfoPanels        []InfoPanel[C]
-	Prompt            InfoPanel[C]
-	Rules             *RuleCollection[C]
-	Rand              rand.Rand
-	Turn              int
+	// Stats stores simulation-specific state.
+	Stats C
+
+	// Name stores the player's name.
+	Name string
+
+	// Rand is a source of randomness that other components can use.
+	Rand rand.Rand
+
+	Deck       *Deck[C]
+	Hand       []Card[C]
+	TurnNumber int
+	State      GameState
+
+	// HandLimit is number of cards to draw to at the start of each turn.
+	// If the player has more cards than this already, none will be drawn,
+	// but the player will keep them all.
+	//
+	// If this is 0 or less and the player has no cards in hand, no permanent
+	// actions available, and must take an action, the game ends in stalemate.
+	HandLimit int
+
+	// ActionsPerTurn is what ActionsRemaining resets to at the start of each
+	// turn. If this is 0 or less at the start of a turn, the game ends in
+	// stalemate. Activating a card or permanent action spends an action, but
+	// the card or action itself can counter this by changing the player's
+	// ActionsRemaining by giving the action back -- or force the turn to
+	// progress immediately to simulation by setting it to 0.
+	ActionsPerTurn   int
+	ActionsRemaining int
+
+	// PermanentActions are an "extra hand" of cards that are not discarded when used.
+	PermanentActions []Card[C]
+
+	// InfoPanels lists informational views available to the player. The Prompt
+	// is the InfoPanel shown before the main action menu.
+	InfoPanels []InfoPanel[C]
+	Prompt     InfoPanel[C]
+
+	// Rules are the simulation rules executed every turn after the player has
+	// run out of remaining actions. See `RuleCollection`'s documentation for
+	// more information about how rule execution works.
+	Rules *RuleCollection[C]
+
+	// Temporary messages are shown *before* the Prompt. They're cleared just
+	// before executing rules for the turn, so rules adding to TemporaryMessages
+	// are creating messages that will show up for the next turn. Temporary
+	// panels are cleared out at the same time as temporary messages; when
+	// available, they are listed separately from standard panels (before them).
 	TemporaryMessages []Message
 	TemporaryPanels   []InfoPanel[C]
 
+	// DebugLevel stores how verbose the game should be about errors. If this
+	// is greater than 0, invisible stats will usually be shown to the player
+	// (this is up to individual info panels, though). If this is -1 or lower,
+	// warning messages will not be displayed.
 	DebugLevel int
 }
+
+// GameState represents various states a player's Game can be in.
+type GameState int
+
+const (
+	// The game has not started.
+	GameUninitialized = GameState(iota)
+
+	// The game is ready to play.
+	GameActive
+
+	// The game is over and the player has lost.
+	GameLost
+
+	// The game is over and the player has won.
+	GameWon
+
+	// The game is over because of an error.
+	GameCrashed
+
+	// The game is over because the player cannot take any actions.
+	GameStalled
+)
+
+// Over returns whether this state represents a game that is over.
+func (g GameState) Over() bool {
+	return g == GameLost || g == GameWon || g == GameCrashed || g == GameStalled
+}