Klotski-ts (Typescript)

Welcome to klotski-ts, a typescript package to programatically generate, and solve, Klotski puzzles. This package doesn't provide a visual interface, but facilitates the capability to plug your own in.

The package exports two classes, Board and Piece, and also two additional exports, which contain instantiated board and pieces classes. These can be used as they have been in the example/demo.ts file, to get your Klotski board up and running with little friction.

Contents

• Klotski-ts (Typescript)
  • Contents
  • Api
    • Board
    • Piece
    • Additional types
  • Using the initialised board
  • Creating your own board
  • Running the test suite
  • Backlog

Api

The reference for the Board and Piece objects, and other peripheral types

Board

new Board(boardSize: [number, number], completionCoords: number[][]): Board

addPiece(piece: Piece, startingPosition: Position, isEscapee?: boolean): Result<Piece>

movePiece(pieceId: string, direction: Direction, moves?: NumberOfMoves): Result<Position>

getBoardState(): BoardState

getCompletedState(): boolean

Piece

new Piece(id: string, shape: Shape): Piece

id: string

shape: Shape

Additional types

// A result type heavily influenced by Go's idiomatic error handling.
type Result<T> = {
  result: T | null;
  error: string | null;
}

type BoardState = {
  [key: string]: string | null;
}

type Shape = "1x1" | "1x2" | "2x1" | "2x2";

type Position = [number, number];

type NumberOfMoves = 1 | 2;

Using the initialised board

Install the package using yarn add klotski-ts

In your index.ts file, add the following:

import { initialisedBoard as board, piece } from 'klotski-ts

The pieces object contains a Piece object for each of the 10 pieces that are initialised in the board object. To gain file-level access of these objects, you can destructure the object like so:

const {
  smallSquare1,
  smallSquare2,
  smallSquare3,
  smallSquare4,
  pipe1,
  pipe2,
  pipe3,
  pipe4,
  line1,
  goldenCubeOfGlory
} = pieces;

Each piece has its own place on board, with the following diagram showing each piece on it's corresponding place on the board.

You can now start moving pieces on the board using the board.movePiece() method. The movePiece() method performs validation to ensure that a legal move is made:

A valid move is one where the piece: a) remains within the confides of the board. b) doesn't collide with existing pieces.

A piece can be moved in a single direction by either 1 or 2 spaces.

After moving pieces, you can display the current state of the board using the getBoardState() method. You can also check the completed state of the game using the getCompletedState() method.

The game completes when the escapee block, the goldenCubeOfGlory in this instance, reaches the designated exit point.

Creating your own board

You can create your own Klotski board to play with. Do note that this package doesn't ensure that your boards are solvable, or provide any validation aside from ensuring pieces are added to empty spaces within the board.

Start by creating a piece, like so:

const smallSquare1 = new Piece("ss1", "1x1");

The first argument denotes the key of the shape, which is used as a reference by the board object. The second argument is the shape of the piece, which is of type Shape.

Once you've added all of the required pieces for the game, you can create your board.

The traditional Klotski board is initalised through the following.

const board = new Board([6, 7], [[2, 1], [3, 1]]);

The board has a size of 6 horiztonal units, and 7 vertical units. The second argument is an array of all the coordinates that act as the exit point for the escapee.

After the board has been created, it's time to add all the pieces to their starting positions:

board.addPiece(smallSquare1, [1, 1])

Adds out small square to the bottom-left place on the board. Perform the same with each of your pieces. The addPiece method also offers an optional third argument, isEscapee: boolean.

Once the board has finished being initialised, you can start poerforming moving your pieces around. This is done in the exact same way as described in the Using the initialised board section.

Running the test suite

If you want to run the test suite, you can do so by running the following:

• git clone [email protected]:andrico1234/klotski-ts.git
• cd klotski-ts
• yarn
• yarn test

Backlog

• [ ] Better visualisation of board state
• [x] Reset the game
• [x] Expose turns