From 99e9e35b1db5eb58c7ea99318d9f17dabb4d1d9b Mon Sep 17 00:00:00 2001
From: Kistaro Windrider <kistaro@gmail.com>
Date: Sat, 1 Apr 2023 18:05:57 -0700
Subject: [PATCH] Card.Drawn, to give cards a chance to not show up

A card can be shuffled into the deck because of a certain condition, and then that condition could cease to apply. If the card should not be presented to the player, it gets one last chance to hide.

There is currently no direct mechanism for making a card _already in the hand_ disappear if it is not relevant, although there are various ways to implement a Rule to do this.
---
 cardsim/card.go | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/cardsim/card.go b/cardsim/card.go
index 0888aa6..cd51389 100644
--- a/cardsim/card.go
+++ b/cardsim/card.go
@@ -10,9 +10,19 @@ type Card[C StatsCollection] interface {
 	Title(p *Player[C]) (Message, error)
 
 	// Urgent reports whether the card is considered urgent. If
-	// the player hasa any
+	// the player has any urgent cards in hand, they cannot choose to act
+	// on a non-urgent card.
 	Urgent(p *Player[C]) bool
 
+	// Drawn is invoked after a card is drawn, before presenting it to the
+	// player. If Drawn returns `false`, the card is discarded without being
+	// put into the hand or shown to the player and a replacement is drawn
+	// instead. To put a card back on the bottom of the deck (or similar)
+	// use p.Deck.Insert (or a related function) to put it back explicitly
+	// in the right position. Do not put it right back on top of the deck or
+	// you'll create an infinite loop.
+	Drawn(p *Player[C]) bool
+
 	// EventText returns the text to display on the card. If it returns an
 	// error that is not a warning, the game crashes.
 	EventText(p *Player[C]) (Message, error)
@@ -44,7 +54,8 @@ type CardOption[C StatsCollection] interface {
 	Enact(p *Player[C]) (Message, error)
 }
 
-// A BasicCard is a Card with fixed title, text, options, and optional post-option callback.
+// A BasicCard is a Card with fixed title, text, options, and optional
+// post-option callback. It never does anything in particular when drawn.
 type BasicCard[C StatsCollection] struct {
 	CardTitle   Message
 	IsUrgent    bool
@@ -76,6 +87,10 @@ func (b *BasicCard[C]) Then(p *Player[C], option CardOption[C]) error {
 	return b.AfterOption(p, option)
 }
 
+func (b *BasicCard[C]) Drawn(p *Player[C]) bool {
+	return true
+}
+
 // A BasicOption is a CardOption with fixed text, effects, and output.
 type BasicOption[C StatsCollection] struct {
 	Text   Message