@slugbugblue/trax 1.1.0 → 1.2.0

package/src/engine.d.ts

@@ -0,0 +1,456 @@
+/** A digital representation of a Trax game. */
+export class Trax {
+  /** @readonly */
+  static readonly version: '1.2.0'
+  /**
+    @readonly
+    @type {Record<TraxVariant, string>}
+    */
+  static readonly names: Record<TraxVariant, string>
+  /** @readonly */
+  static readonly variants: Set<string>
+  /**
+    Create an x,y Point object with special functions.
+    @param {number|PointLike} x - either the x value, or an object with x,y keys
+    @param {number} [y] - if x is a number, y must be provided as well
+    @returns {Point} a new Point object
+    */
+  static point: (x: number | PointLike, y?: number) => Point
+  /**
+    Given a player number, get the color.
+    @param {number} playerNumber - the player number, 1 or 2
+    @returns {Color} the color of that player, w or b
+    */
+  static colorOf: (playerNumber: number) => Color
+  /**
+    Given a color, get the player number.
+    @param {string} color - the color, w or b
+    @returns {number} the player number, 1 or 2
+    */
+  static playerNumber: (color: string) => number
+  /**
+    Given a color, get the other color.
+    @param {string} color - the color, w or b
+    @returns {Color} the other color, b or w
+    */
+  static other: (color: string) => Color
+  /**
+    Encode a numeric column number into the Trax notation column letter.
+    @param {number} col - the column number, with 0 just to the left of the tiles
+    @returns {string} the encoded column letter
+    */
+  static encodeCol: (col: number) => string
+  /**
+    Decode a Trax notation column letter back to a number.
+    @param {string} col - the Trax column letter
+    @returns {number} the column number
+    */
+  static decodeCol: (col: string) => number
+  /**
+    Create a new Trax game
+    @param {TraxVariant} [rules='trax'] - the variant to play
+    @param {string|string[]} [moves=''] - the initial moves to pre-play
+    @param {string} [id='trax'] - an id used to differentiate tiles from multiple games
+    */
+  constructor(rules?: TraxVariant, moves?: string | string[], id?: string)
+  id: string
+  rules: TraxVariant
+  turn: number
+  over: boolean
+  left: number
+  right: number
+  top: number
+  bottom: number
+  count: number
+  /** @type {string[]} */
+  moves: string[]
+  /** @type {Map<TileId, Point>} */
+  frontier: Map<TileId, Point>
+  /** @type {Record<TileId, Tile>} */
+  tiles: Record<TileId, Tile>
+  /** @type {TileId[]} */
+  path: TileId[]
+  invalid: boolean
+  /**
+    Save the current game data to a variable.
+    @returns {SaveState} an opaque save state object
+    @see restore for restoring the state
+    */
+  save(): SaveState
+  /**
+    Restore a previously saved position.
+    @param {SaveState} saved - the previously saved state
+    @see save for saving the state
+    */
+  restore(saved: SaveState): void
+  /**
+    Lightweight checkpoint for internal rollback. Valid only for ancestor restores.
+    Callers must be in a non-over, valid game state — rewind() restores those
+    fields to those fixed values rather than saving and restoring them.
+    @returns {Checkpoint} a lightweight snapshot of mutable board dimensions
+    @typedef {{ move: number, count: number, turn: number, left: number, right: number, top: number, bottom: number }} Checkpoint
+    */
+  checkpoint(): {
+    move: number
+    count: number
+    turn: number
+    left: number
+    right: number
+    top: number
+    bottom: number
+  }
+  /**
+    Rewind to a checkpoint. Only valid for ancestor restores.
+    @param {Checkpoint} cp - the checkpoint to rewind to
+    */
+  rewind(cp: {
+    move: number
+    count: number
+    turn: number
+    left: number
+    right: number
+    top: number
+    bottom: number
+  }): void
+  /** The name of this variant. */
+  get name(): string
+  /** The move number of the last-played move. */
+  get move(): number
+  /** The color of the current player, w or b. */
+  get color(): Color
+  /** True if the game is over. */
+  get gameOver(): boolean
+  /** 1 or 2 for a win, 0 for a tie, false if the game is still in progress. */
+  get winner(): number | false
+  /**
+    Provides the tile ID for the tile at the given location.
+    @param {PointLike} loc - the location
+    @returns {TileId} a string key encoding this game's id and the location
+    */
+  tileId(loc: PointLike): TileId
+  /**
+    Add a tile to the board. Note that no validity checking is done here,
+    except that invalid tiles are not actually placed on the board, so this
+    should only be called externally.
+    @param {TileType} type - letter 'a'-'f' for valid tiles, 'x' for invalid
+    @param {Point} loc - the location
+    @returns {Tile} the tile placed on the board
+    */
+  addTile(type: TileType, loc: Point): Tile
+  /**
+    The type of tile at the given location.
+    @param {PointLike} loc - the location the tile is in
+    @returns {ValidTiles|undefined} the type of tile, or undefined if no tile
+    */
+  tileAt(loc: PointLike): ValidTiles | undefined
+  validTile(type: string, loc: Point): type is ValidTiles
+  /**
+    Get a list of possible tiles that can be played in this location.
+    @param {Point} loc - the location to check
+    @param {string | boolean} [s=false] - if provided, a direction modifier, '/', '\\', or '+'
+    @returns {TileType[]} the list of valid tile types for this location
+    */
+  possibleTiles(loc: Point, s?: string | boolean): TileType[]
+  get height(): number
+  get width(): number
+  /**
+    Determine if a location is valid to play in.
+    @param {Point} loc - the location to check
+    @returns {boolean} true if a tile can be placed here
+    */
+  validLocation(loc: Point): boolean
+  /**
+    Find all possible locations to play in. Note that these are not
+    necessarily valid locations, just empty ones that border existing tiles.
+    @returns {Point[]} all frontier locations
+    */
+  possibleLocations(): Point[]
+  /**
+    Find all possible moves as a list of notations,
+    ie: ['@1+', '@1/', '@1\\', ...]
+  
+    Note that moves are not guaranteed to be valid.
+    @returns {string[]} all valid move notations from the current position
+    */
+  possibleMoves(): string[]
+  /**
+    Called after a move was just played, to determine the forced moves.
+    @param {Point} loc - the location just played at
+    @returns {Tile[]} a list of tiles that should be added as part of the move
+    */
+  forcedMoves(loc: Point): Tile[]
+  /**
+    Determine the notation for a move. Note that this must be determined
+    BEFORE the move is placed on the board.
+    @param {ValidTiles} type - the tile placed on the board
+    @param {Point} loc - the location the tile is placed
+    @returns {string} the notation of the move
+    */
+  notate(type: ValidTiles, loc: Point): string
+  /**
+    Turn a move notation into a tile type and location.
+    @param {string} notation - a notation for a single move to be played at
+    the current board position
+    @returns {RawMove} the tile type and location of the move
+    */
+  decodeNotation(notation: string): RawMove
+  /**
+    Follow a color from one location through one or more tiles to the other
+    end of the color line.
+    @param {Color} color - the color to follow
+    @param {Point} loc - the location to start
+    @param {string} from - the edge of the tile to start from
+    @returns {LineEnd} the ending location and a list of the tile ids the path
+    takes to get there
+    */
+  follow(color: Color, loc: Point, from: string): LineEnd
+  /**
+    Given a tile and a color, follow the line for that color to each end.
+    @param {Color} color - the color of ends of interest
+    @param {Point} loc - the location of the tile of interest
+    @returns {LineEnd[]} a list of two items, each one end of the line
+    */
+  findEnds(color: Color, loc: Point): LineEnd[]
+  /**
+    Determine if a given line ends the game.
+    @param {Point} locA - one end of the line
+    @param {Point} locB - the other end of the line
+    @returns {boolean} true if this line wins the game
+    */
+  lineWin(locA: Point, locB: Point): boolean
+  /**
+    Determine if the game has ended.
+    @param {Tile[]} tiles - a list of the tiles placed during the last move
+    */
+  checkWin(tiles: Tile[]): void
+  /**
+    Play a move. Can be called either as:
+    - play(moveNumber, notation) to ensure move safety, or
+    - play(notation) for quicker access.
+    @param {number|string} moveNumber - the move number or the notation
+    @param {string} [notation] - the notation, if a move number was provided
+    @returns {{dropped: Tile[], notation: string, valid: boolean}} the result of the move
+    */
+  play(
+    moveNumber: number | string,
+    notation?: string,
+  ): {
+    dropped: Tile[]
+    notation: string
+    valid: boolean
+  }
+  /**
+    Play one or more moves.
+    @param {string|string[]} moves - the list of moves, provided either as a
+    space-separated string of notations, or as a list of notations. Move
+    numbers are optional, but if provided will be checked for accuracy.
+    */
+  playMoves(moves: string | string[]): void
+  /** The formatted notation string for the current game, wrapped at 80 columns. */
+  get notation(): string
+  /**
+    Drop a tile onto the board. This is a lower level call. Use play() if possible instead.
+    @param {string|ValidTiles} type - a special move, a tile type, or a notation
+    @param {Point} [loc] - a location if type is a tile type
+    @param {string|boolean} [tentative] - if truthy, the move will not be saved
+    @returns {TileDrop} an object representing the results of the drop
+    */
+  dropTile(
+    type: string | ValidTiles,
+    loc?: Point,
+    tentative?: string | boolean,
+  ): TileDrop
+  /**
+    Symmetry helper. Rotates a move around the board in case we are trying to
+    play a symmetrical rather than an exact move.
+    @param {string} move - the notation of the move to be rotated
+    @returns {string[]} the four rotations of this move
+    */
+  moveRotations(move: string): string[]
+  /**
+    Play a provisional move if it is valid.
+    @param {string} from - the normalized encoding of the starting position
+    @param {string} to - the normalized encoding of the ending position
+    @param {string} via - the move to be used to transition
+    @returns {false|string} if the provisional move is invalid: false; if the
+    provisional move will never be valid for any future moves:
+    'delete-provisional'; if the provisional move is valid, the correct
+    notation, which may be symmetrically adjusted as needed
+    */
+  provisionalMove(from: string, to: string, via: string): false | string
+  /**
+    Get an encoded representation of the current position, useful for drawing
+    the board without having to do much analysis.
+    @returns {string} the current position code
+    */
+  get icon(): string
+  /**
+    Get an encoded representation of the current position, with a set of
+    tiles highlighted differently, useful for showing the effects of a move.
+    @param {TileDrop} drops - the drops of the most recent play
+    @returns {string} the current position code, with drops highlighted
+    */
+  dropsIcon(drops: TileDrop): string
+  /**
+    Symmetry helper, draw the board from different angles.
+    @param {boolean} [rightToLeft] - reverse order horizontally
+    @param {boolean} [bottomToTop] - reverse order vertically
+    @param {boolean} [rotate] - rotate the tiles by 90 degrees
+    @param {TileDrop} [drops] - the drops of the most recent play, if you want
+    them highlighted
+    @returns {string} an encoding of the position
+    */
+  positionCode(
+    rightToLeft?: boolean,
+    bottomToTop?: boolean,
+    rotate?: boolean,
+    drops?: TileDrop,
+  ): string
+  /**
+    Trax has the potential for symmetry, so this gives us the ability to
+    examine horizontal, vertical, and rotational symmetry for a color.
+    @returns {string} a position code that matches all symmetrical positions
+    */
+  normalize(): string
+  /**
+    Get the normalized code for this position. All symmetrical positions will
+    result in the same normalized code.
+    @returns {string} the normalized position code
+    */
+  get normalized(): string
+}
+export type Color = 'w' | 'b'
+/**
+ * One end of a line and the tiles taken to get there.
+ */
+export type LineEnd = {
+  /**
+   * - the ending location
+   */
+  loc: Point
+  /**
+   * - tile ids from start to end
+   */
+  path: TileId[]
+}
+export type Notation = string
+/**
+ * A tile type and a location determine a raw move.
+ */
+export type RawMove = {
+  /**
+   * - the tile type
+   */
+  type: TileType
+  /**
+   * - the location
+   */
+  loc: Point
+}
+/**
+ * Treat the save state as an opaque object,
+ * produced by save() and fed into restore().
+ */
+export type SaveState = {
+  /**
+   * - game id
+   */
+  id: string
+  /**
+   * - move number
+   */
+  move: number
+  /**
+   * - current player (1 or 2)
+   */
+  turn: number
+  /**
+   * - whether the game is over
+   */
+  over: boolean
+  /**
+   * - leftmost tile column
+   */
+  left: number
+  /**
+   * - rightmost tile column
+   */
+  right: number
+  /**
+   * - topmost tile row
+   */
+  top: number
+  /**
+   * - bottommost tile row
+   */
+  bottom: number
+  /**
+   * - move notations
+   */
+  moves: string[]
+  /**
+   * - frontier locations
+   */
+  frontier: [TileId, Point][]
+  /**
+   * - serialized tiles
+   */
+  tiles: string
+  /**
+   * - serialized winning path
+   */
+  path: string
+  /**
+   * - whether an invalid tile was placed
+   */
+  invalid: boolean
+}
+export type Slash = '/' | '\\' | '+'
+/**
+ * A single tile on the board.
+ */
+export type Tile = {
+  /**
+   * - unique tile identifier
+   */
+  id: TileId
+  /**
+   * - board location
+   */
+  loc: Point
+  /**
+   * - tile type letter
+   */
+  type: TileType
+  /**
+   * - move number when placed
+   */
+  move: number
+  /**
+   * - sequence number among all tiles
+   */
+  seq: number
+}
+export type TileId = string
+/**
+ * When a tile is dropped, this object represents the results.
+ */
+export type TileDrop = {
+  /**
+   * - all tiles placed, including forced moves
+   */
+  dropped: Tile[]
+  /**
+   * - the notation of the played move
+   */
+  notation: Notation
+  /**
+   * - whether the move was legal
+   */
+  valid: boolean
+}
+export type TileType = ValidTiles | 'x'
+export type TraxVariant = 'trax' | 'traxloop' | 'trax8'
+export type ValidTiles = 'a' | 'b' | 'c' | 'd' | 'e' | 'f'
+import { Point } from '@slugbugblue/point'
+import type { PointLike } from '@slugbugblue/point'