scrabble-game/backend/internal/engine/game.go

package engine

import (
	"fmt"

	"scrabble-solver/board"
	"scrabble-solver/rack"
	"scrabble-solver/rules"
	"scrabble-solver/scrabble"
)

// scorelessLimit is the number of consecutive scoreless turns (passes and
// exchanges) that ends a game, per docs/ARCHITECTURE.md §6.
const scorelessLimit = 6

// EndReason explains why a game finished.
type EndReason uint8

const (
	// EndNotOver marks a game still in progress.
	EndNotOver EndReason = iota
	// EndOutOfTiles fires when the bag is empty and a player empties their rack.
	EndOutOfTiles
	// EndScoreless fires after scorelessLimit consecutive passes/exchanges.
	EndScoreless
	// EndResign fires when a player resigns.
	EndResign
)

// String renders the end reason for logs and diagnostics.
func (r EndReason) String() string {
	switch r {
	case EndNotOver:
		return "not_over"
	case EndOutOfTiles:
		return "out_of_tiles"
	case EndScoreless:
		return "scoreless"
	case EndResign:
		return "resign"
	}
	return "unknown"
}

// Options configures a new game.
type Options struct {
	// Variant selects the rules and dictionary.
	Variant Variant
	// Version pins the dictionary version; empty selects the registry's latest.
	Version string
	// Players is the number of seats, 2 to 4.
	Players int
	// Seed seeds the tile bag, making the game reproducible.
	Seed int64
}

// Game is the in-memory state of a single match and the pure rules engine over
// it. It owns the board, the bag, each player's hand, the running scores, whose
// turn it is and the decoded move log, and it detects the end of the game. It
// performs no scheduling, persistence or I/O and is not safe for concurrent use.
type Game struct {
	solver  *scrabble.Solver
	rules   *rules.Ruleset
	variant Variant
	version string

	board        *board.Board
	bag          *Bag
	hands        [][]byte // per player, alphabet-index bytes with blankTile for blanks
	scores       []int
	toMove       int
	scorelessRun int
	over         bool
	reason       EndReason
	log          []MoveRecord
}

// New starts a game described by opts over a dictionary from reg. It resolves
// the solver (failing with ErrUnknownVariant/ErrUnknownVersion), builds an empty
// board and a seeded bag, and deals each player a full rack.
func New(reg *Registry, opts Options) (*Game, error) {
	if opts.Players < 2 || opts.Players > 4 {
		return nil, fmt.Errorf("engine: players must be between 2 and 4, got %d", opts.Players)
	}
	var (
		solver  *scrabble.Solver
		version = opts.Version
		err     error
	)
	if version == "" {
		version, solver, err = reg.Latest(opts.Variant)
	} else {
		solver, err = reg.Solver(opts.Variant, version)
	}
	if err != nil {
		return nil, err
	}

	rs := solver.Rules()
	g := &Game{
		solver:  solver,
		rules:   rs,
		variant: opts.Variant,
		version: version,
		board:   board.New(rs.Rows, rs.Cols),
		bag:     NewBag(rs, opts.Seed),
		hands:   make([][]byte, opts.Players),
		scores:  make([]int, opts.Players),
	}
	for i := range g.hands {
		g.hands[i] = g.bag.Draw(rs.RackSize)
	}
	return g, nil
}

// Play validates and applies the current player's placement of tiles forming a
// word in direction dir. It scores the play, refills the rack from the bag,
// advances the turn and may end the game. It returns ErrTilesNotOnRack when the
// player does not hold the tiles, ErrIllegalPlay when the solver rejects the
// play, and ErrGameOver on a finished game.
func (g *Game) Play(dir scrabble.Direction, tiles []scrabble.Placement) (MoveRecord, error) {
	if g.over {
		return MoveRecord{}, ErrGameOver
	}
	player := g.toMove
	if err := g.checkHolds(player, placementTiles(tiles)); err != nil {
		return MoveRecord{}, err
	}
	move, err := g.solver.ValidatePlay(g.board, dir, tiles)
	if err != nil {
		return MoveRecord{}, fmt.Errorf("%w: %v", ErrIllegalPlay, err)
	}

	scrabble.Apply(g.board, move)
	g.removeFromHand(player, placementTiles(tiles))
	g.scores[player] += move.Score
	g.refill(player)
	g.scorelessRun = 0

	rec := g.recordPlay(player, move)
	g.log = append(g.log, rec)

	if len(g.hands[player]) == 0 && g.bag.Len() == 0 {
		g.finish(EndOutOfTiles)
	} else {
		g.advance()
	}
	return rec, nil
}

// Pass forfeits the current player's turn. It extends the scoreless run, which
// may end the game (EndScoreless), and otherwise advances the turn.
func (g *Game) Pass() (MoveRecord, error) {
	if g.over {
		return MoveRecord{}, ErrGameOver
	}
	player := g.toMove
	g.scorelessRun++
	rec := MoveRecord{Player: player, Action: ActionPass, Total: g.scores[player]}
	g.log = append(g.log, rec)
	g.endTurnAfterScoreless()
	return rec, nil
}

// Exchange swaps the current player's tiles (alphabet-index bytes, blankTile for
// blanks) for fresh ones. It is legal only while the bag holds at least a full
// rack. The fresh tiles are drawn before the swapped ones return, so a player
// cannot draw back their own tiles. It extends the scoreless run, which may end
// the game (EndScoreless).
func (g *Game) Exchange(tiles []byte) (MoveRecord, error) {
	if g.over {
		return MoveRecord{}, ErrGameOver
	}
	if len(tiles) == 0 {
		return MoveRecord{}, ErrNothingToExchange
	}
	if g.bag.Len() < g.rules.RackSize {
		return MoveRecord{}, ErrNotEnoughTilesToExchange
	}
	player := g.toMove
	if err := g.checkHolds(player, tiles); err != nil {
		return MoveRecord{}, err
	}

	g.removeFromHand(player, tiles)
	g.hands[player] = append(g.hands[player], g.bag.Draw(len(tiles))...)
	g.bag.Return(tiles)
	g.scorelessRun++

	rec := MoveRecord{Player: player, Action: ActionExchange, Count: len(tiles), Total: g.scores[player]}
	g.log = append(g.log, rec)
	g.endTurnAfterScoreless()
	return rec, nil
}

// Resign ends the game on the current player's turn (EndReason EndResign). In a
// two-player match this is the only resignation case; richer multi-player
// handling belongs to the game domain in a later stage.
func (g *Game) Resign() (MoveRecord, error) {
	if g.over {
		return MoveRecord{}, ErrGameOver
	}
	player := g.toMove
	rec := MoveRecord{Player: player, Action: ActionResign, Total: g.scores[player]}
	g.log = append(g.log, rec)
	g.finish(EndResign)
	return rec, nil
}

// GenerateMoves returns every legal play for the current player's rack, ranked
// by descending score. It is empty when the player has no legal play.
func (g *Game) GenerateMoves() []scrabble.Move {
	return g.solver.GenerateMoves(g.board, g.rackOf(g.toMove), scrabble.Both)
}

// Hint returns the highest-scoring legal play for the current player and true,
// or the zero move and false when there is none. It is the top-1 move the
// one-per-game hint reveals.
func (g *Game) Hint() (scrabble.Move, bool) {
	moves := g.GenerateMoves()
	if len(moves) == 0 {
		return scrabble.Move{}, false
	}
	return moves[0], true
}

// Variant returns the variant the game is played under.
func (g *Game) Variant() Variant { return g.variant }

// Version returns the pinned dictionary version.
func (g *Game) Version() string { return g.version }

// Players returns the number of seats in the game.
func (g *Game) Players() int { return len(g.hands) }

// ToMove returns the index of the player whose turn it is. On a finished game it
// is the player who made the final move.
func (g *Game) ToMove() int { return g.toMove }

// Over reports whether the game has finished.
func (g *Game) Over() bool { return g.over }

// Reason returns why the game finished, or EndNotOver while it is in progress.
func (g *Game) Reason() EndReason { return g.reason }

// Score returns the current score of the player at index player.
func (g *Game) Score(player int) int { return g.scores[player] }

// BagLen returns the number of tiles left in the bag.
func (g *Game) BagLen() int { return g.bag.Len() }

// BoardClone returns a deep copy of the board, safe for the caller to read or
// mutate without affecting the game.
func (g *Game) BoardClone() *board.Board { return g.board.Clone() }

// Log returns a copy of the dictionary-independent move log.
func (g *Game) Log() []MoveRecord {
	out := make([]MoveRecord, len(g.log))
	copy(out, g.log)
	return out
}

// Result is the outcome of a finished game.
type Result struct {
	Over   bool
	Reason EndReason
	Scores []int
	// Winner is the index of the single highest score, or -1 on a tie or while
	// the game is unfinished.
	Winner int
}

// Result reports the current outcome. Final scores already include the standard
// end-game rack adjustment applied when the game finished.
func (g *Game) Result() Result {
	scores := make([]int, len(g.scores))
	copy(scores, g.scores)
	return Result{Over: g.over, Reason: g.reason, Scores: scores, Winner: g.winner()}
}

// finish marks the game over with reason and applies the end-game rack
// adjustment to the scores.
func (g *Game) finish(reason EndReason) {
	g.over = true
	g.reason = reason
	g.applyEndAdjustment(reason)
}

// applyEndAdjustment settles the unplayed racks. When a player goes out (bag
// empty, rack empty) they gain the sum of every opponent's rack value and each
// opponent loses their own; otherwise (scoreless stalemate or resignation) each
// player simply forfeits their own rack value.
func (g *Game) applyEndAdjustment(reason EndReason) {
	if reason == EndOutOfTiles {
		out := g.toMove
		var bonus int
		for i := range g.hands {
			if i == out {
				continue
			}
			v := g.rackValue(i)
			g.scores[i] -= v
			bonus += v
		}
		g.scores[out] += bonus
		return
	}
	for i := range g.hands {
		g.scores[i] -= g.rackValue(i)
	}
}

// endTurnAfterScoreless ends the game when the scoreless run reaches the limit,
// otherwise advances the turn. Used by Pass and Exchange.
func (g *Game) endTurnAfterScoreless() {
	if g.scorelessRun >= scorelessLimit {
		g.finish(EndScoreless)
		return
	}
	g.advance()
}

// advance moves play to the next seat.
func (g *Game) advance() { g.toMove = (g.toMove + 1) % len(g.hands) }

// winner returns the index of the single highest-scoring player, or -1 on a tie
// for the lead or while the game is unfinished.
func (g *Game) winner() int {
	if !g.over {
		return -1
	}
	best, tie := 0, false
	for i := 1; i < len(g.scores); i++ {
		switch {
		case g.scores[i] > g.scores[best]:
			best, tie = i, false
		case g.scores[i] == g.scores[best]:
			tie = true
		}
	}
	if tie {
		return -1
	}
	return best
}

// rackOf builds a generation rack from player's hand.
func (g *Game) rackOf(player int) rack.Rack {
	r := rack.New(g.rules.Size())
	for _, t := range g.hands[player] {
		if t == blankTile {
			r.AddBlank()
		} else {
			r.Add(t)
		}
	}
	return r
}

// rackValue sums the tile values left on player's hand; blanks count zero.
func (g *Game) rackValue(player int) int {
	var v int
	for _, t := range g.hands[player] {
		if t != blankTile {
			v += g.rules.Values[t]
		}
	}
	return v
}

// checkHolds reports ErrTilesNotOnRack unless player holds every tile in want.
func (g *Game) checkHolds(player int, want []byte) error {
	avail := tileCounts(g.hands[player])
	for tile, n := range tileCounts(want) {
		if avail[tile] < n {
			return ErrTilesNotOnRack
		}
	}
	return nil
}

// removeFromHand takes one tile per entry of used off player's hand.
func (g *Game) removeFromHand(player int, used []byte) {
	hand := g.hands[player]
	for _, t := range used {
		for i, h := range hand {
			if h == t {
				hand = append(hand[:i], hand[i+1:]...)
				break
			}
		}
	}
	g.hands[player] = hand
}

// refill draws from the bag until player's hand is full or the bag is empty.
func (g *Game) refill(player int) {
	if need := g.rules.RackSize - len(g.hands[player]); need > 0 {
		g.hands[player] = append(g.hands[player], g.bag.Draw(need)...)
	}
}

// placementTiles maps placements to the tiles they consume (blankTile for blanks).
func placementTiles(tiles []scrabble.Placement) []byte {
	out := make([]byte, len(tiles))
	for i, p := range tiles {
		if p.Blank {
			out[i] = blankTile
		} else {
			out[i] = p.Letter
		}
	}
	return out
}

// tileCounts tallies a multiset of tiles by value.
func tileCounts(tiles []byte) map[byte]int {
	m := make(map[byte]int, len(tiles))
	for _, t := range tiles {
		m[t]++
	}
	return m
}