procedure (sides tbg game-state) → (listof Side)

tbg : TBG

game-state : GameState

Returns the set of sides that are currently in the game. Order in the result list does not matter.

procedure (next-side tbg game-state side) → Side

tbg : TBG

game-state : GameState

side : Side

Returns the side to play once side’s turn is over. This should be called after side’s turn is over and game-state has been updated with side’s move choice.

procedure (valid-move-choice?   tbg             game-state             side             move-choice)   →   Boolean

tbg : TBG

game-state : GameState

side : Side

move-choice : MoveChoice

Determines whether the given move-choice is a valid legal move according to the rules of the game. If it is legal, valid-move-choice? returns true, otherwise it returns false.

procedure (valid-move-choices tbg game-state side)

→ (sequenceof MoveChoice)

tbg : TBG

game-state : GameState

side : Side

Returns a sequence which will enumerate all possible legal moves within the rules of the game.

NOTE: This sequence may or may not be finite, so if you’re relying on using it to iterate through all the elements, check with known-finite? first.

procedure (play-move-choice   tbg             game-state             side             move-choice)   →   GameState

tbg : TBG

game-state : GameState

side : Side

move-choice : MoveChoice

Returns the game state after side plays the given move-choice for their turn. This should not mutate the original game state, but return a new one.

procedure (winning-state? tbg game-state side) → Boolean

tbg : TBG

game-state : GameState

side : Side

Determines whether the given side has won in the given game-state according to the rules of the game.

procedure (standard-initial-state tbg) → GameState

tbg : TBGI

Produces the standard initial game state for the given turn-based game.

procedure (standard-initial-side tbg) → Side

tbg : TBGI

Produces the standard starting side for the given turn-based game, that is, the side that starts the game with their turn.

A HandlerResult is one of:
  – (continue-turn TurnState)
  – (finish-turn MoveChoice)

procedure (display-game-state   tbg             game-state             side             turn-state)   →   Image

tbg : TBGG

game-state : GameState

side : Side

turn-state : TurnState

procedure (display-end-state   tbg             game-state             side             winner)   →   Image

tbg : TBGG

game-state : GameState

side : Side

winner : (or/c #f Side)

procedure (start-turn tbg) → TurnState

tbg : TBGG

Determines the initial state that every player starts their turn with. The first mouse event or key event of a turn will use the result of this method as the starting turn-state.

procedure (handle-mouse   tbg             game-state             side             turn-state             mouse-posn             mouse-event)   →   HandlerResult

tbg : TBGG

game-state : GameState

side : Side

turn-state : TurnState

mouse-posn : Posn

mouse-event : MouseEvent

This method handles mouse events, including "move" for mouse movements, "button-down" and "button-up" for mouse clicks, "drag" for dragging movements, and "enter" and "leave" for when the mouse enters and leaves the game canvas.

Mouse scrolling motions are actually not handled as mouse events; they are handled as key events using handle-key.

When a mouse event happens, this method can either continue the turn with an updated turn-state using continue-turn, or finish the turn with a final MoveChoice, using finish-turn. If the mouse event is not relevant, it should continue the turn with the same turn-state as before.

For example, some games might require moving a piece by clicking on it and then clicking on the space to move it to. On the first click, the handle-mouse method should return (continue-turn piece-selection) where piece-selection is a TurnState representing which piece was clicked on to be moved. Then on the second click, the handle-mouse method should return (finish-turn move-choice) where move-choice is a MoveChoice representing which piece should be moved and where it should go. A rough sketch of the definition would look like this:

;; A Space represents the position of a space on the board.

;; A MoveChoice is a (move Space Space)

(struct move [from to])

;; representing moving a piece from the `from` space to the `to` space.

;; A TurnState is one of:

;;  - #false  ; beginning of turn

;;  - Space   ; the piece on this space has been selected to be moved

;; handle-mouse :

;; TBGG GameState Side TurnState Posn MouseEvent -> HandlerResult

(define (handle-mouse self game side turn-state posn mouse)

(cond

[(mouse=? "button-down" mouse)

(cond [(false? turn-state)

;; this is the first click

(if (piece-exists-at-space? game side (posn->space posn))

;; select the piece at this space to be moved

(continue-turn (posn->space posn))

;; otherwise just a stray click on an empty space

(continue-turn turn-state))]

[else

;; there is already a piece selected; this is the second click

(if (piece-can-move-here? game turn-state (posn->space posn))

;; this is a finished move choice

(finish-turn (move turn-state (posn->space posn)))

;; otherwise this would be an invalid move

....)])]

[else

;; the mouse event is not relevant

(continue-turn turn-state)]))

procedure (handle-key   tbg             game-state             side             turn-state             key-event)   →   HandlerResult

tbg : TBGG

game-state : GameState

side : Side

turn-state : TurnState

key-event : KeyEvent

This method handles key events. One-character strings like "a", "b", and "c" represent the "regular" keys like A, B, and C. This includes strings like " " for the Spacebar, "\r" for the Enter key, and "\t" for the Tab key.

Other keys are represented with multi-character strings, such as "left", "right", "up", and "down" for the arrow keys, and "shift" and "rshift" for the two shift keys.

Mouse scrolling motions are also handled as key events, with "wheel-up" representing scrolling up, "wheel-down" representing scrolling down, and "wheel-left" and "wheel-right" representing scrolling left and right.

Just like with handle-mouse, when a key event happens, this method can either continue the turn with an updated turn-state using continue-turn, or finish the turn with a final MoveChoice using finish-turn.