Better error management.

* "Uncooperative cards" is now a warning.
* Cards and actions get "Then" invoked before the card processor considers erroring out.
* Terminal UI: Errors and warnings from actions are displayed during the response; they're not only added to the temporary messages now.

cardsim/card.go

@@ -101,6 +101,15 @@ func (b *BasicCard[C]) Drawn(_ *Player[C]) bool {
 	return true
 }
 
+// RefundAction returns a func that can be used as an AfterOption, which returns
+// the player's action point.
+func RefundAction[C StatsCollection]() func(c Card[C], p *Player[C], option CardOption[C]) error {
+	return func(c Card[C], p *Player[C], option CardOption[C]) error {
+		p.ActionsRemaining++
+		return nil
+	}
+}
+
 // A PanelCard is a Card that takes its title and text from an InfoPanel,
 // while options, urgency, and the post-option callback are specified
 // (like a BasicCard). It never does anything in particular when drawn.

cardsim/debugging.go

@@ -0,0 +1,103 @@
+package cardsim
+
+// Named debug verbosity levels. Using the raw constants is fine too. This
+// is roughly consistent with "standard" meanings for these debug levels.
+const (
+	HideWarnings   = -1
+	NotDebugging   = 0
+	DebugWarning   = 1
+	DebugInfo      = 2
+	DebugDetail    = 3
+	DebugFine      = 4
+	DebugSuperfine = 5
+)
+
+// ActionCounterDebugCard constructs a BasicCard intended for use only as a
+// Debug Action that tinkers with the player's action counter.
+func ActionCounterDebugCard[C StatsCollection]() Card[C] {
+	return &BasicCard[C]{
+		CardTitle: MsgStr("Adjust Action Counter"),
+		CardText:  MsgStr("Change the number of actions you have available this turn."),
+		CardOptions: []CardOption[C]{
+			&BasicOption[C]{
+				Text: MsgStr("Get an extra action."),
+				Effect: func(p *Player[C]) error {
+					p.ActionsRemaining += 2 // counteract the one this costs
+					return nil
+				},
+				Output: MsgStr("Gotten."),
+			},
+			&BasicOption[C]{
+				Text: MsgStr("Waste an action."),
+				Effect: func(p *Player[C]) error {
+					return nil
+				},
+				Output: MsgStr("Wasted."),
+			},
+			&BasicOption[C]{
+				Text: MsgStr("Get a thousand actions."),
+				Effect: func(p *Player[C]) error {
+					p.ActionsRemaining = 1000
+					return nil
+				},
+				Output: MsgStr("ActionsRemaining set to 1000."),
+			},
+			&BasicOption[C]{
+				Text: MsgStr("Go to exactly 1 action remaining."),
+				Effect: func(p *Player[C]) error {
+					p.ActionsRemaining = 1
+					return nil
+				},
+				Output: MsgStr("ActionsRemaining set to 1."),
+			},
+			&BasicOption[C]{
+				Text: MsgStr("End the turn. (Set actions to 0.)"),
+				Effect: func(p *Player[C]) error {
+					p.ActionsRemaining = 0
+					return nil
+				},
+				Output: MsgStr("ActionsRemaining zeroed out."),
+			},
+		},
+	}
+}
+
+// DebugModeCard constructs a BasicCard to change the player's debug level.
+// It is intended for use only as a Debug Action.
+func DebugModeCard[C StatsCollection]() Card[C] {
+	return &BasicCard[C]{
+		CardTitle: MsgStr("Change Debug Level"),
+		CardText:  MsgStr("Adjust verbosity of output, or exit debug mode entirely (not recommended)."),
+		CardOptions: []CardOption[C]{
+			debugLevelOption[C]{1, "Enable debug mode. Show warnings."},
+			debugLevelOption[C]{2, "Enable debug mode. Show info messages."},
+			debugLevelOption[C]{3, "Enable debug mode. Show detailed messages."},
+			debugLevelOption[C]{4, "Enable debug mode. Show individual details of operations."},
+			debugLevelOption[C]{5, "Enable debug mode. Show every event in excruciating detail."},
+			debugLevelOption[C]{0, "NOT RECOMMENDED. Disable debugging (show warnings). IT CAN'T BE TURNED BACK ON."},
+			debugLevelOption[C]{-1, "NOT RECOMMENDED. Disable debugging (hide warnings). IT CAN'T BE TURNED BACK ON."},
+		},
+		AfterOption: RefundAction[C](),
+	}
+}
+
+type debugLevelOption[C StatsCollection] struct {
+	level       int
+	description string
+}
+
+// OptionText implements CardOption[C].
+func (d debugLevelOption[C]) OptionText(*Player[C]) (Message, error) {
+	return Msgf("Set debug level %d: %s", d.level, d.description), nil
+}
+
+// Enact implements CardOption[C].
+func (d debugLevelOption[C]) Enact(p *Player[C]) (Message, error) {
+	p.DebugLevel = d.level
+	return Msgf("Debug level is now %d.", d.level), nil
+}
+
+// Enabled implements CardOption[C].
+func (d debugLevelOption[C]) Enabled(p *Player[C]) bool {
+	return true
+}

cardsim/messages.go

@@ -35,6 +35,19 @@ func Msgf(f string, args ...any) Message {
 	return stringMessage(fmt.Sprintf(f, args...))
 }
 
+// ErrorMessage returns a Message representing an Error.
+// This is preferred over Msgf for errors, since future versions of the library
+// may perform special message formatting for errors.
+func ErrorMessage(e error) Message {
+	if e == nil {
+		return nil
+	}
+	if IsSeriousError(e) {
+		return MultiMessage{MsgStr("SERIOUS ERROR:"), Msgf("%v", e)}
+	}
+	return MultiMessage{MsgStr("Warning:"), Msgf("%v", e)}
+}
+
 // A SpecialMessage is a specific, uniquely identifiable message.
 type SpecialMessage struct {
 	msg Message

cardsim/player.go

@@ -8,14 +8,14 @@ import (
 )
 
 var (
-	ErrUncooperativeCards = errors.New("a milion cards refused to join the hand")
 	ErrInvalidCard   = errors.New("invalid card specified")
 	ErrInvalidChoice = errors.New("invalid choice specified")
 	ErrNotUrgent     = errors.New("action not urgent when urgent card is available")
 	ErrNoActions     = errors.New("no actions remaining")
 	ErrNotDebugging  = errors.New("this is a debug-only feature and you're not in debug mode")
 
-	WarningStalemate = errors.New("no actions can be taken")
+	WarningStalemate         = &Warning{errors.New("no actions can be taken")}
+	WarningUncoperativeCards = &Warning{errors.New("a milion cards refused to join the hand")}
 )
 
 // Player stores all gameplay state for one player at a specific point in time.
@@ -178,6 +178,8 @@ func InitPlayer[C StatsCollection](stats C) *Player[C] {
 		DebugActions: []Card[C]{
 			&DeckDebugger[C]{},
 			&PanelCard[C]{Panel: RuleDumper[C]{}},
+			ActionCounterDebugCard[C](),
+			DebugModeCard[C](),
 		},
 	}
 }
@@ -270,9 +272,9 @@ func (p *Player[C]) StartNextTurn() error {
 }
 
 // Draw draws a card into the hand, informing the card that it has been drawn.
-// If more than a million cards refuse to enter the hand, this crashes with
-// ErrUncooperativeCards. If the deck does not have enough cards, this
-// returns WarningTooFewCards.
+// If more than a million cards refuse to enter the hand, this gives up and
+// returns WarningUncooperativeCards. If the deck does not have enough cards,
+// this returns WarningTooFewCards.
 func (p *Player[C]) Draw() error {
 	for attempts := 0; attempts < 1000000; attempts++ {
 		if p.Deck.Len() == 0 {
@@ -284,13 +286,13 @@ func (p *Player[C]) Draw() error {
 			return nil
 		}
 	}
-	return ErrUncooperativeCards
+	return WarningUncoperativeCards
 }
 
 // FillHand draws up to the hand limit, informing cards that they have been
-// drawn. If more than a million cards refuse to enter the hand, this crashes
-// with ErrUncooperativeCards. If the deck does not have enough cards, this
-// returns WarningTooFewCards.
+// drawn. If more than a million cards refuse to enter the hand, this gives up
+// and returns WarningUncooperativeCards. If the deck does not have enough
+// cards, this returns WarningTooFewCards.
 func (p *Player[C]) FillHand() error {
 	var lastErr error
 	for p.Deck.Len() > 0 && len(p.Hand) < p.HandLimit {
@@ -384,17 +386,14 @@ func (p *Player[C]) EnactCardUnchecked(cardIdx, choiceIdx int) (Message, error)
 
 	ret, err := options[choiceIdx].Enact(p)
 	errs.Add(err)
-	if IsSeriousError(err) {
-		p.State = GameCrashed
-		return ret, errs.Emit()
-	}
-
 	err = card.Then(p, options[choiceIdx])
 	errs.Add(err)
+
+	err = errs.Emit()
 	if IsSeriousError(err) {
 		p.State = GameCrashed
 	}
-	return ret, errs.Emit()
+	return ret, err
 }
 
 // EnactCard executes a card choice, removes it from the hand, and decrements
@@ -468,17 +467,13 @@ func (p *Player[C]) enactActionUnchecked(actionSource []Card[C], actionIdx, choi
 
 	ret, err := chosen.Enact(p)
 	errs.Add(err)
-	if IsSeriousError(err) {
-		p.State = GameCrashed
-		return ret, errs.Emit()
-	}
-
 	err = card.Then(p, chosen)
 	errs.Add(err)
-	if IsSeriousError(err) {
+	retErr := errs.Emit()
+	if IsSeriousError(retErr) {
 		p.State = GameCrashed
 	}
-	return ret, errs.Emit()
+	return ret, retErr
 }
 
 // EnactPermanentAction executes a permanently-available card and decrements
@@ -510,15 +505,11 @@ func (p *Player[C]) ReportError(e error) {
 	if e == nil || p.DebugLevel < -1 {
 		return
 	}
-	if p.DebugLevel < 0 && !IsSeriousError(e) {
-		return
-	}
-	p.ChapterBreak()
-	severity := "[Warning]"
+	minLvl := NotDebugging
 	if IsSeriousError(e) {
-		severity = "[ERROR]"
+		minLvl = HideWarnings
 	}
-	p.TemporaryMessages = append(p.TemporaryMessages, Msgf("%s: %v", severity, e))
+	p.Debug(minLvl, ErrorMessage(e))
 }
 
 // CanAct returns whether the player has actions theoretically available.
@@ -532,6 +523,7 @@ func (p *Player[C]) Debug(minLevel int, msg Message) {
 	if p.DebugLevel < minLevel || msg == nil {
 		return
 	}
+	p.ChapterBreak()
 	p.TemporaryMessages = append(p.TemporaryMessages, msg)
 }
 

cardsim/terminalui.go

@@ -46,6 +46,10 @@ func RunSimpleTerminalUI[C StatsCollection](p *Player[C]) error {
 				}
 				continue
 			}
+			if err != nil {
+				display(ErrorMessage(err))
+				display(MsgStr(""))
+			}
 			display(msg)
 			wait()
 		}
@@ -149,19 +153,19 @@ func pickNextAction[C StatsCollection](p *Player[C]) (actionType EnactableType,
 				wait()
 			} else if i <= actionsOffset {
 				i = i - debugOffset - 1
-				option, promptErr := promptCard(p, p.DebugActions[i])
+				option, promptErr := promptCard(p, p.DebugActions[i], DebugActionEnactable)
 				if option >= 0 || IsSeriousError(promptErr) {
 					return DebugActionEnactable, i, option, promptErr
 				}
 			} else if i <= handOffset {
 				i = i - actionsOffset - 1
-				option, promptErr := promptCard(p, p.PermanentActions[i])
+				option, promptErr := promptCard(p, p.PermanentActions[i], PermanentActionEnactable)
 				if option >= 0 || IsSeriousError(promptErr) {
 					return PermanentActionEnactable, i, option, promptErr
 				}
 			} else {
 				i = i - handOffset - 1
-				option, promptErr := promptCard(p, p.Hand[i])
+				option, promptErr := promptCard(p, p.Hand[i], CardEnactable)
 				if option >= 0 || IsSeriousError(promptErr) {
 					return CardEnactable, i, option, nil
 				}
@@ -281,10 +285,10 @@ func displayNumberedTitles[C StatsCollection, T Titled[C]](p *Player[C], cards [
 
 // promptCard asks the player to take an action on a card. Returns the option
 // they chose, or -1 if there was a serious error or they cancelled selection.
-func promptCard[C StatsCollection](p *Player[C], card Card[C]) (optionIdx int, err error) {
+func promptCard[C StatsCollection](p *Player[C], card Card[C], cardType EnactableType) (optionIdx int, err error) {
 	// Iterate until the player makes a valid choice.
 	for {
-		opts, valid, err := displayCard(p, card, true)
+		opts, valid, err := displayCard(p, card, cardType, true)
 		if IsSeriousError(err) {
 			return -1, err
 		}
@@ -322,11 +326,11 @@ func promptCard[C StatsCollection](p *Player[C], card Card[C]) (optionIdx int, e
 	}
 }
 
-func displayCard[C StatsCollection](p *Player[C], card Card[C], canAct bool) ([]CardOption[C], bool, error) {
+func displayCard[C StatsCollection](p *Player[C], card Card[C], cardType EnactableType, canAct bool) ([]CardOption[C], bool, error) {
 	cls()
 	t := card.Title(p).String()
 	urgent := card.Urgent(p)
-	if urgent {
+	if urgent && cardType == CardEnactable {
 		t = "[URGENT!] " + t
 	}
 	fmt.Println(t)
@@ -342,7 +346,7 @@ func displayCard[C StatsCollection](p *Player[C], card Card[C], canAct bool) ([]
 	fmt.Println()
 	fmt.Println(SectionBreak.String())
 	fmt.Println()
-	if !urgent && p.HasUrgentCards() {
+	if !urgent && cardType != DebugActionEnactable && p.HasUrgentCards() {
 		fmt.Println("<You have more urgent matters to attend to! You cannot act on this right now.>")
 		fmt.Println()
 		canAct = false
@@ -457,13 +461,13 @@ func actionsMode[C StatsCollection](p *Player[C], canAct bool) (actionType Enact
 			} else if v <= dOff {
 				v--
 				if canAct {
-					optIdx, err := promptCard(p, p.DebugActions[v])
+					optIdx, err := promptCard(p, p.DebugActions[v], DebugActionEnactable)
 					errs.Add(err)
 					if optIdx >= 0 || IsSeriousError(err) {
 						return DebugActionEnactable, v, optIdx, errs.Emit()
 					}
 				} else {
-					_, _, err := displayCard(p, p.DebugActions[v], false)
+					_, _, err := displayCard(p, p.DebugActions[v], DebugActionEnactable, false)
 					errs.Add(err)
 					if IsSeriousError(err) {
 						return DebugActionEnactable, -1, -1, errs.Emit()
@@ -473,13 +477,13 @@ func actionsMode[C StatsCollection](p *Player[C], canAct bool) (actionType Enact
 			} else if v <= pOff {
 				v = v - dOff - 1
 				if canAct {
-					optIdx, err := promptCard(p, p.PermanentActions[v])
+					optIdx, err := promptCard(p, p.PermanentActions[v], PermanentActionEnactable)
 					errs.Add(err)
 					if optIdx >= 0 || IsSeriousError(err) {
 						return PermanentActionEnactable, v, optIdx, errs.Emit()
 					}
 				} else {
-					_, _, err := displayCard(p, p.PermanentActions[v], false)
+					_, _, err := displayCard(p, p.PermanentActions[v], PermanentActionEnactable, false)
 					errs.Add(err)
 					if IsSeriousError(err) {
 						return PermanentActionEnactable, -1, -1, errs.Emit()
@@ -489,13 +493,13 @@ func actionsMode[C StatsCollection](p *Player[C], canAct bool) (actionType Enact
 			} else {
 				v = v - pOff - 1
 				if canAct {
-					optIdx, err := promptCard(p, p.Hand[v])
+					optIdx, err := promptCard(p, p.Hand[v], CardEnactable)
 					errs.Add(err)
 					if optIdx >= 0 || IsSeriousError(err) {
 						return CardEnactable, v, optIdx, errs.Emit()
 					}
 				} else {
-					_, _, err := displayCard(p, p.Hand[v], false)
+					_, _, err := displayCard(p, p.Hand[v], CardEnactable, false)
 					errs.Add(err)
 					if IsSeriousError(err) {
 						return CardEnactable, -1, -1, errs.Emit()
@@ -552,21 +556,21 @@ func review[C StatsCollection](p *Player[C]) error {
 				displayOnePanel(p, p.InfoPanels[i-1])
 			} else if i <= actionsOffset {
 				i = i - debugOffset - 1
-				_, _, err := displayCard(p, p.DebugActions[i], false)
+				_, _, err := displayCard(p, p.DebugActions[i], DebugActionEnactable, false)
 				errs.Add(err)
 				if IsSeriousError(err) {
 					return errs.Emit()
 				}
 			} else if i <= handOffset {
 				i = i - actionsOffset - 1
-				_, _, err := displayCard(p, p.PermanentActions[i], false)
+				_, _, err := displayCard(p, p.PermanentActions[i], PermanentActionEnactable, false)
 				errs.Add(err)
 				if IsSeriousError(err) {
 					return errs.Emit()
 				}
 			} else {
 				i = i - handOffset - 1
-				_, _, err := displayCard(p, p.Hand[i], false)
+				_, _, err := displayCard(p, p.Hand[i], CardEnactable, false)
 				errs.Add(err)
 				if IsSeriousError(err) {
 					return errs.Emit()