gambit
API
Generated with
gambit/com.phasmidsoftware/com.phasmidsoftware.gambit/com.phasmidsoftware.gambit.game

com.phasmidsoftware.gambit.game

package com.phasmidsoftware.gambit.game

Members list

Type members

Classlikes

class AlphaBetaPlayer[P, S, M, Pl](me: Pl, depth: Int = ...)(using state: State[P, S], game: Game[S, M, Pl]) extends Player[S, M, Pl]

A generic alpha-beta pruning player. For more information, see https://en.wikipedia.org/wiki/Alpha–beta_pruning

A generic alpha-beta pruning player. For more information, see https://en.wikipedia.org/wiki/Alpha–beta_pruning

Implements minimax search with alpha-beta pruning to a configurable depth. Alpha-beta pruning eliminates branches that cannot affect the final decision, reducing the effective branching factor from b to approximately √b in the best case — effectively doubling the achievable search depth for the same computation compared to plain minimax.

== Heuristic Convention ==

State.heuristic(s) is positive when the player who just moved to reach s is doing well. This is consistent with the convention used throughout Gambit. At leaf nodes (terminal or depth limit reached), the raw heuristic is returned. The maximizing/minimizing logic correctly accounts for this convention.

== Move Ordering ==

Moves are ordered by heuristic before recursing — highest first for the maximizing player, lowest first for the minimizing player. This shallow search ordering maximises the probability of early pruning, approaching the theoretical best-case performance of alpha-beta.

== Mutable State ==

Alpha and beta bounds are tracked with mutable variables, and boundary/break is used for early termination on a prune. This is intentional: alpha-beta pruning is fundamentally about early exit based on accumulated bounds, and fighting that with purely functional constructs would sacrifice both clarity and performance. Mutable state is appropriate here for the same reason it is appropriate in high-performance sorting algorithms.

Type parameters

M

the move type.

P

the proto-state type.

Pl

the player identity type.

S

the state type.

Value parameters

depth

search depth in plies (half-moves). Default 6. Higher values give stronger play at the cost of exponentially more computation.

game

implicit Game[S, M, Pl] for move generation and application.

me

this player's identity.

state

implicit State[P, S] for goal detection and heuristic.

Attributes

Supertypes
trait Player[S, M, Pl]
class Object
trait Matchable
class Any
case class Contestant[S, M, Pl](name: String, player: Player[S, M, Pl])

A named contestant in a tournament.

A named contestant in a tournament.

Wraps a Player with a display name so the league table can identify each entry independently of the Boolean player-identity used internally by two-player GameRunner.

Type parameters

M

the move type.

Pl

the player identity type.

S

the state type.

Value parameters

name

display name for the league table.

player

the underlying player.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object GambitConfig

Loads and exposes typed configuration values for the Gambit framework.

Loads and exposes typed configuration values for the Gambit framework.

Configuration is read from application.conf on the classpath (standard Typesafe Config behaviour). All values have hard-coded fallbacks so the application runs correctly even if no config file is present.

== HOCON structure ==

gambit {
 tournament.gamesPerPairing = 6
 alphaBeta.depth1           = 4
 alphaBeta.depth2           = 6
 mcts.iterations1           = 200
 mcts.iterations2           = 500
 mcts.explorationConstant   = 1.4142135623730951
}

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
trait Game[S, M, Pl]

Typeclass: describes the rules of a game in terms of state S, move M, and player identity Pl.

Typeclass: describes the rules of a game in terms of state S, move M, and player identity Pl.

A Game instance captures everything the GameRunner needs to know about the mechanics of a specific game — how moves are applied, whose turn it is, where the game starts, and how many players are involved.

This separates game rules (Game[S, M, Pl]) from game strategy (Player[S, M, Pl]) and game execution (GameRunner[P, S, M, Pl]).

Type parameters

M

the move type.

Pl

the player identity type (e.g., Boolean for two-player, an enum for bridge's four seats).

S

the state type.

Attributes

Supertypes
class Object
trait Matchable
class Any
object GameResult

Companion for GameResult providing factory methods.

Companion for GameResult providing factory methods.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
GameResult.type
class GameRunner[P, S, M, Pl](playerMap: Map[Pl, Player[S, M, Pl]], random: Random = ...)(using state: State[P, S], game: Game[S, M, Pl])

A generic game runner that plays a sequence of games between any number of players, for any game representable as a State[P, S] and Game[S, M, Pl].

A generic game runner that plays a sequence of games between any number of players, for any game representable as a State[P, S] and Game[S, M, Pl].

Type parameters: P — proto-state type (used by State.construct) S — state type M — move type Pl — player identity type (e.g., Boolean for two-player, Seat for bridge)

Value parameters

game

implicit Game[S, M, Pl] for game mechanics.

playerMap

a map from player identity to Player instance.

random

a Random instance for reproducibility.

state

implicit State[P, S] for goal detection.

Attributes

Supertypes
class Object
trait Matchable
class Any
class MCTSNode[S, M, Pl](val state: S, val move: Option[M], val movedBy: Option[Pl], var visits: Int, var wins: Double, val children: ListBuffer[MCTSNode[S, M, Pl]], var untriedMoves: List[M])

A node in the MCTS search tree.

A node in the MCTS search tree.

Mutable: visits and wins are updated in-place during backpropagation. Children are added during expansion. untriedMoves shrinks as children are expanded.

No parent reference -- backpropagation uses an explicit path stack accumulated during selection, avoiding circular references and the GC/equality issues that back-references cause in tree structures.

Type parameters

M

the move type.

Pl

the player identity type.

S

the state type.

Value parameters

children

expanded child nodes.

move

the move that led to this state (None for root).

movedBy

the player who made move (None for root).

state

the game state at this node.

untriedMoves

moves not yet expanded into children.

visits

number of times this node has been visited.

wins

cumulative score from simulations through this node, from the perspective of movedBy.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
object MCTSNode

Companion object for MCTSNode, providing factory methods.

Companion object for MCTSNode, providing factory methods.

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
MCTSNode.type
class MCTSPlayer[P, S, M, Pl](me: Pl, iterations: Int = ..., explorationConstant: Double = ...)(using state: State[P, S], game: Game[S, M, Pl]) extends Player[S, M, Pl]

A generic Monte Carlo Tree Search player. For more information about MCTS, see https://en.wikipedia.org/wiki/Monte_Carlo_tree_search

A generic Monte Carlo Tree Search player. For more information about MCTS, see https://en.wikipedia.org/wiki/Monte_Carlo_tree_search

Implements the standard four-phase MCTS loop:

  1. Selection -- walk the tree by UCB1 (Upper Confidence Bound) until an unexpanded node is found.
  2. Expansion -- add one new child for an untried move.
  3. Simulation -- play randomly to a terminal state (rollout).
  4. Backprop -- update visit/win counts along the path to root.

The search tree is retained between calls to chooseMove. After each move the subtree rooted at the chosen child becomes the new root, carrying forward all accumulated visit and win counts. If the opponent plays an unexplored line the retained tree cannot be advanced and a fresh root is created instead.

Tree matching uses == on the state type S; callers must ensure S has meaningful equality (satisfied by case class and case object).

== Future upgrades ==

  • Actor-based parallelism: move the mutable tree into an Akka/Pekko actor. Multiple rollout worker actors could then submit simulation results to the tree actor concurrently (root parallelization), giving a near-linear speedup with the number of cores.

  • Heuristic rollouts: replace pure random simulation with a heuristic-guided playout for stronger play.

Type parameters

M

the move type.

P

the proto-state type.

Pl

the player identity type.

S

the state type.

Value parameters

explorationConstant

UCB1 exploration parameter C (default sqrt(2)).

game

implicit Game[S, M, Pl] for move application.

iterations

number of MCTS iterations per move (default 1000).

me

this player's identity.

state

implicit State[P, S] for goal detection.

Attributes

Supertypes
trait Player[S, M, Pl]
class Object
trait Matchable
class Any
case class MatchResult[Pl](results: Seq[GameResult[Pl]])

A MatchResult aggregates GameResults over a series of games. Provides win/loss/draw counts and total games for a given player.

A MatchResult aggregates GameResults over a series of games. Provides win/loss/draw counts and total games for a given player.

Type parameters

Pl

the player identity type.

Value parameters

results

the sequence of individual game results.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
case class Move[P, S](f: S => P, desc: String) extends Transition[P, S]

A case class that implements Transition[S].

A case class that implements Transition[S].

Type parameters

P

a proto-state, from which a state S can be constructed.

S

the type of the input parameter and of the result.

Value parameters

desc

the human-legible description of f.

f

a function S => P.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait Transition[P, S]
trait S => (P, S)
class Object
trait Matchable
class Any
Show all
trait Player[S, M, Pl]

A Player in a game of type S, making moves of type M, identified as player Pl.

A Player in a game of type S, making moves of type M, identified as player Pl.

Type parameters

M

the move type.

Pl

the player identity type.

S

the state type.

Attributes

Supertypes
class Object
trait Matchable
class Any
Known subtypes
class RandomPlayer
class MenacePlayer
class RandomPlayer
class AlphaBetaPlayer[P, S, M, Pl]
class MCTSPlayer[P, S, M, Pl]
Show all
trait State[P, S] extends Ordering[S]

Type class for a State. A State is a position in a game or other situation which requires heuristically-directed tree search. For example, a State might describe a board position in Tic-tac-toe or Chess.

Type class for a State. A State is a position in a game or other situation which requires heuristically-directed tree search. For example, a State might describe a board position in Tic-tac-toe or Chess.

NOTE that State depends on Transition. CONSIDER eliminating Transition such that all logic is defined by State.

Type parameters

P

a proto-state, that's to say a type such that a P, S tuple can be converted into a new S.

S

the underlying type on which the state is based.

Attributes

Supertypes
trait Ordering[S]
trait PartialOrdering[S]
trait Equiv[S]
trait Serializable
trait Comparator[S]
class Object
trait Matchable
class Any
Show all
Known subtypes
object Connect4State
class Tournament[P, S, M, Pl](contestants: Seq[Contestant[S, M, Pl]], gamesPerPairing: Int = ..., random: Random = ...)(using state: State[P, S], game: Game[S, M, Pl])

A round-robin tournament for two-player zero-sum games.

A round-robin tournament for two-player zero-sum games.

Every pair of contestants plays gamesPerPairing games with each contestant taking the first-player role in half the games, so neither side has a systematic first-move advantage in the overall standings.

== Scoring == Standard football (soccer) 3-1-0 scoring: Win = 3 points Draw = 1 point Loss = 0 points

Ties in the table are broken by goal difference (wins minus losses), then by total wins.

== Usage ==

 val t = Tournament(contestants, gamesPerPairing = 10, random = new Random(42L))
 println(t.leagueTable)

Type parameters

M

the move type.

P

the proto-state type.

Pl

the player identity type.

S

the state type.

Value parameters

contestants

the players to enter in the tournament.

game

implicit Game[S, M, Pl].

gamesPerPairing

number of games each ordered pair plays (A-as-first vs B-as-second). Each unordered pair therefore plays 2 * gamesPerPairing games in total.

random

random source passed to each GameRunner.

state

implicit State[P, S].

Attributes

Supertypes
class Object
trait Matchable
class Any
trait Transition[P, S] extends S => (P, S)

A function that transitions from a state S to a prototype state.

A function that transitions from a state S to a prototype state.

Type parameters

P

a proto-state, from which a state S can be constructed.

S

the type of the input.

Attributes

Supertypes
trait S => (P, S)
class Object
trait Matchable
class Any
Known subtypes
class Move[P, S]

Types

type GameResult[Pl] = Map[Pl, Int]

A GameResult captures the outcome of one complete game for all players. Each player maps to a score, typically -1 (loss), 0 (draw), or +1 (win) for two-player zero-sum games. For trick-taking games like bridge, the scores might represent tricks won per side.

A GameResult captures the outcome of one complete game for all players. Each player maps to a score, typically -1 (loss), 0 (draw), or +1 (win) for two-player zero-sum games. For trick-taking games like bridge, the scores might represent tricks won per side.

A GameResult is typically a subset of a MatchResult and is a Map of Pl -> Int.

Attributes

Generated with