CardSimEngine/cardsim/rules.go

package cardsim

import (
	"errors"
	"fmt"
	"sort"
)

// A Rule implements an operation run on every game turn.
//
// Rule[C] is a generic interface. Like any other generic type, it describes a
// family of related types: each different kind of StatsCollection that Rule
// could pertain to is the basis of a distinct type of Rule.
//
// When implementing a generic interface, you do not need to implement a
// generic type. In the case of Rule, you are likely to be writing rules for a
// specific simulation. That simulation will have some associated
// StatsCollection type. The rules you write will only need to implement the
// variation of Rule that pertains specifically to that type.
//
// For example, if your `StatsCollection` type is `KoboldMineData`, then rules
// for the simulation referring to it would implement `Rule[KoboldMineData]`
// only. So the `Enact` function you implment would take an argument of type
// `*Player[KoboldMineData]`, not some undefined type `C` that could be any
// StatsCollection. Since it takes a `*Player[KoboldMineData]` as an argument,
// you then know that the player's `Stats` field is not just any
// StatsCollection, it is KoboldMineData specifically. The compiler won't
// require you to convert from "some `StatsCollection`" to "`KoboldMineData`
// specifically" when using the `Player[KoboldMineData].Stats` field,
// because the type of that field is already `KoboldMineData`.
type Rule[C StatsCollection] interface {
	// Label is an internal name the rule can be recognized by.
	// Some things may be easier if it is unique, but it does not have to be.
	// Label must be constant for the life of the Rule, including after the
	// Rule is removed from the collection (it is called as part of the
	// removal process).
	Label() string

	// Step returns which numerical step this rule should be executed on.
	// It is somewhat arbitrary. Rules are enacted in order from lowest step
	// to highest step; ties are broken randomly every turn. Step must be
	// constant for the life of the Rule, including after the Rule is removed
	// from the collection (it is called during removal).
	Step() int

	// Enact operates the rule. Some special errors are recognized and change
	// the flow of the turn:
	//
	// * ErrHaltTurn skips all further rules (including rules on the same step)
	//   and immediately proceeds to the next turn.
	// * ErrDeleteRule removes the rule from the collection. It will not be
	//   executed on future turns unless it is reinserted into the active
	//   ruleset (by some other rule, option, etc.)
	// * ErrHaltDelete acts like both ErrHaltTurn and ErrDeleteRule.
	// * Any Warning is collected and displayed at the end of the turn.
	// * Any other error crashes the game.
	Enact(*Player[C]) error
}

var (
	ErrHaltTurn   = errors.New("turn halted")
	ErrDeleteRule = errors.New("delete this rule")
	ErrHaltDelete = fmt.Errorf("%w; %w", ErrHaltTurn, ErrDeleteRule)

	// ErrNotUnique matches errors from functions attempting to identify
	// a single rule by an identifier that is not unique.
	ErrNotUnique = errors.New("not unique")

	// ErrAlreadyRunning means you tried to run the rules engine from inside a rule.
	ErrAlreadyRunning = errors.New("cannot run a turn while running a turn")
)

// RuleFunc implements a Rule represented by a single function. It is the most
// common type of Rule. (You'll probably only want to implement a full Rule
// type if the rule needs to have fields of its own or be identifiable by
// something other than its Name.)
type RuleFunc[C StatsCollection] struct {
	Name string
	Seq  int
	F    func(*Player[C]) error
}

func (r *RuleFunc[C]) Label() string {
	return r.Name
}

func (r *RuleFunc[C]) Step() int {
	return r.Seq
}

func (r *RuleFunc[C]) Enact(p *Player[C]) error {
	return r.F(p)
}

// RuleID is a unique opaque ID for a rule inserted in a collection.
type RuleID uint64

// keyedRule attaches a unique ID to each Rule.
type keyedRule[C StatsCollection] struct {
	id RuleID
	Rule[C]
}

// RuleCollection stores, organizes, and runs all rules currently active for a Player.
type RuleCollection[C StatsCollection] struct {
	rules   map[RuleID]*keyedRule[C]
	byStep  map[int][]RuleID
	byLabel map[string][]RuleID
	nextID  RuleID
	steps   []int

	rulesRunning bool
	insertLater  []*keyedRule[C]
	deleteLater  []RuleID
}

// NewRuleCollection initializes an empty RuleCollection.
func NewRuleCollection[C StatsCollection]() *RuleCollection[C] {
	return &RuleCollection[C]{
		rules:   make(map[RuleID]*keyedRule[C]),
		byStep:  make(map[int][]RuleID),
		byLabel: make(map[string][]RuleID),
		nextID:  1,
	}
}

// Insert adds a Rule to a RuleCollection, returning the ID it assigned to the rule.
func (r *RuleCollection[C]) Insert(rule Rule[C]) RuleID {
	id := r.nextID
	r.nextID++
	k := &keyedRule[C]{id, rule}
	if r.rulesRunning {
		r.insertLater = append(r.insertLater, k)
		return id
	}
	r.performInsert(k)
	return id
}

func (r *RuleCollection[C]) performInsert(k *keyedRule[C]) {
	r.rules[k.id] = k

	s := r.byStep[k.Step()]
	if s == nil {
		r.steps = nil
	}
	s = append(s, k.id)
	r.byStep[k.Step()] = s

	lbl := r.byLabel[k.Label()]
	lbl = append(lbl, k.id)
	r.byLabel[k.Label()] = lbl
}

// RemoveID removes the rule with the given ID from the collection, if present.
// It returns whether it found and removed anything.
func (r *RuleCollection[C]) RemoveID(id RuleID) bool {
	rule := r.rules[id]
	if rule == nil {
		return false
	}
	if rule.id != id {
		panic(fmt.Errorf("rule stored in slot %d had internal ID %d", id, rule.id))
	}

	delete(r.rules, id)
	r.removeFromLabel(rule)
	r.removeFromStep(rule)

	return true
}

// removeFromStep removes a specific ID from r.byStep, if present.
// It's fine for this rule (or this entire step) to be gone already.
func (r *RuleCollection[C]) removeFromStep(rule *keyedRule[C]) {
	s := r.byStep[rule.Step()]
	for i, v := range s {
		if v == rule.id {
			// special case: only item?
			if len(s) == 1 {
				s = nil
				delete(r.byStep, rule.Step())
				r.steps = nil
				break
			}
			end := len(s) - 1
			if i != end {
				s[i], s[end] = s[end], s[i]
			}
			s = s[:end]
			break
		}
	}
	if s != nil {
		r.byStep[rule.Step()] = s
	}
}

// removeFromLabel removes a specific ID from r.byLabel, if present.
// It's fine for this rule (or this entire label) to be gone already.
func (r *RuleCollection[C]) removeFromLabel(rule *keyedRule[C]) {
	lbl := r.byLabel[rule.Label()]
	for i, v := range lbl {
		if v == rule.id {
			// special case: only item?
			if len(lbl) == 1 {
				lbl = nil
				delete(r.byLabel, rule.Label())
				break
			}
			end := len(lbl) - 1
			if i != end {
				lbl[i], lbl[end] = lbl[end], lbl[i]
			}
			lbl = lbl[:end]
			break
		}
	}
	if lbl != nil {
		r.byLabel[rule.Label()] = lbl
	}
}

// RemoveUniqueLabel removes the sole rule with a specific label. If there are
// no rules with that label, this returns false and nil. If there is exactly
// one rule with that label, it is removed and this returns true and nil.
// If there are multiple rules with this label, this returns false and
// an error like ErrNotUnique.
func (r *RuleCollection[C]) RemoveUniqueLabel(label string) (bool, error) {
	target := r.byLabel[label]
	if len(target) == 0 {
		return false, nil
	}
	if len(target) != 1 {
		return false, fmt.Errorf("%w: %q", ErrNotUnique, label)
	}
	if r.rulesRunning {
		r.deleteLater = append(r.deleteLater, target[0])
		return true, nil
	}

	id := target[0]
	rule := r.rules[id]
	delete(r.rules, id)
	delete(r.byLabel, label)

	r.removeFromStep(rule)
	return true, nil
}

// RemoveAllLabel removes every rule with a specific label. It returns how many
// rules were thus removed.
func (r *RuleCollection[C]) RemoveAllLabel(label string) int {
	target := r.byLabel[label]
	if r.rulesRunning {
		r.deleteLater = append(r.deleteLater, target...)
		return len(target)
	}
	delete(r.byLabel, label)
	for _, t := range target {
		// RemoveID works fine when the label is already completely gone; it
		// calls into removeFromLabel, which is a no-op in this case.
		r.RemoveID(t)
	}
	return len(target)
}

// RemoveUniqueStep removes the sole rule on a specific step. Its semantics
// are equivalent to RemoveUniqueLabel.
func (r *RuleCollection[C]) RemoveUniqueStep(step int) (bool, error) {
	target := r.byStep[step]
	if len(target) == 0 {
		return false, nil
	}
	if len(target) != 1 {
		return false, fmt.Errorf("%w: %d", ErrNotUnique, step)
	}
	if r.rulesRunning {
		r.deleteLater = append(r.deleteLater, target[0])
		return true, nil
	}

	id := target[0]
	rule := r.rules[id]
	delete(r.rules, id)
	delete(r.byStep, step)

	r.removeFromLabel(rule)
	return true, nil
}

// RemoveAllStep removes every rule on a specific step. It returns how many
// rules were thus removed.
func (r *RuleCollection[C]) RemoveAllStep(step int) int {
	target := r.byStep[step]
	if target == nil {
		return 0
	}
	if r.rulesRunning {
		r.deleteLater = append(r.deleteLater, target...)
		return len(target)
	}
	delete(r.byStep, step)
	r.steps = nil
	for _, t := range target {
		// RemoveID works fine when the label is already completely gone; it
		// calls into removeFromLabel, which is a no-op in this case.
		r.RemoveID(t)
	}
	return len(target)
}

// Run runs all rules in the collection against the specified Player, in
// step order, with ties broken randomly.
//
// It stops early if it observes a failure other than the errors described in
// Rule.Enact as having special meaning to the rules engine.
func (r *RuleCollection[C]) Run(p *Player[C]) error {
	if r.rulesRunning {
		return ErrAlreadyRunning
	}
	r.rulesRunning = true
	defer r.applyDelayedUpdates()
	defer func() { r.rulesRunning = false }()

	steps := r.steps
	if steps == nil {
		// Step set changed, recalculate.
		steps := make([]int, 0, len(r.byStep))
		for step := range r.byStep {
			steps = append(steps, step)
		}
		sort.Ints(steps)
		r.steps = steps
	}

	p.Debug(2, Msgf("Executing steps: %v", steps))

	var errs ErrorCollector
	for _, step := range steps {
		stepRules := r.byStep[step]
		p.Debug(3, Msgf("Executing step %d; length %d", step, len(stepRules)))
		ShuffleAll(stepRules, p.Rand)
		var remove []RuleID
		halt := false
		for _, id := range stepRules {
			rule := r.rules[id]
			p.Debug(4, Msgf("Executing rule %x (labeled %q)", id, rule.Label()))
			err := rule.Enact(p)
			if err != nil {
				p.Debug(2, Msgf("Rule %x (%q): error: %v", id, rule.Label(), err))
				ignore := false
				if errors.Is(err, ErrDeleteRule) {
					remove = append(remove, id)
					ignore = true
				}
				if errors.Is(err, ErrHaltTurn) {
					halt = true
					ignore = true
				}
				if !ignore {
					errs.Add(err)
					if !errors.Is(err, AnyWarning) {
						halt = true
					}
				}
			}
			if halt {
				break
			}
		}
		// Remove rules flagged for removal. We're done iterating this set of
		// steps so removing the rule from the step collection won't mess up
		// iteration, and we're iterating off a local reference to the list of
		// steps so we also won't mess up iteration if we drop the list because
		// we removed the last rule from this step.
		for _, id := range remove {
			if !r.RemoveID(id) {
				panic(fmt.Errorf("can't find rule %d after it asked to remove itself", id))
			}
		}
		if halt {
			ret := errs.Emit()
			p.Debug(2, Msgf("Rules stopping early. Result: %v", ret))
			return ret
		}
	}
	ret := errs.Emit()
	p.Debug(2, Msgf("Rules complete. Result: %v", ret))
	return ret
}

func (r *RuleCollection[C]) applyDelayedUpdates() {
	insert := r.insertLater
	r.insertLater = nil
	remove := r.deleteLater
	r.deleteLater = nil
	for _, k := range insert {
		r.performInsert(k)
	}
	for _, id := range remove {
		r.RemoveID(id)
	}
}