Comment and reorganize Player.

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 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]
-	Rand              rand.Rand
-	Turn              int
+
+	// 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
+}