Ren'Py Chess Engine 2.0

Play it now on itch.io or watch a YouTube demo

About

This is a chess GUI built with the Ren'Py Visual Novel Engine, python-chess, and Stockfish (for chess AI). You can use it as a standalone playable or integrate it as a minigame into a Ren'Py visual novel project. Read the guide for integration below.

Compatibility

This chess engine supports Ren'Py SDK >= 7.4.0. It is not backward compatible with Ren'Py SDK <= 7.3.5 due to reasons described in this GitHub issue. See the renpy-7.3.5 branch for an old version that is compatible with Ren'Py SDK 7.3.5.

Gameplay Example: Fool's Mate

Differences between Ren'Py Chess 1.0 and Ren'Py Chess 2.0

Gameplay

The game supports Player vs. Player and Player vs. Computer. In PvC, player can choose to play as either Black or White.

Click on a piece and all of its available moves will be highlighted. Click on any of the legal destination squares to make a move. Press Flip board view to flip the view, with White on the bottom by default.

Feature List

• PvP and PvC
• Flip board view
• Resign
• Undo moves

Player vs. Computer (Stockfish)

Flip Board View, Undo Moves, Resign

Promotion UI

Threefold Repetition: UI for Claiming a Draw

(Also shows a similar UI choice screen if the fifty-move rule is in effect)

Guide for Integrating into a Ren'Py Project

All of the files essential to the chess engine are in game/00-chess-engine. Therefore, you only need to copy the entire 00-chess-engine into your Ren'Py game directory.

The chess game is full-screen when the screen resolution is 1280x720, but is customizable to fit any screen sizes, as described in subsequent sections.

Structure of 00-chess-engine

00-chess-engine/
    - audio                         # chess game sound effects
    - bin                           # chess AI Stockfish binaries
    - images                        # chess board and piece images
    - python-packages               # Python libraries
    - chess_displayable.rpy         # core GUI class
    - chess_subprocess.py           # core logic class

The core GUI class is a Ren'Py Creator-Defined Displayable named ChessDisplayable inside 00-chess-engine/chess_displayable.rpy. You can customize anything stylistic in chess_displayable.rpy, as described below in more details.

00-chess-engine/chess_subprocess.py is the underlying chess engine. Creating an instance of ChessDisplayable will launch chess_subprocess.py as a subprocess. You can make logical changes in chess_subprocess.py for your specific use cases if you are comfortable with subprocess programming.

In your Ren'Py script, for example, script.rpy, pass the following configuration variables for the chess engine to the chess screen defined as screen chess(fen, player_color, movetime, depth):

• fen: the Forsyth–Edwards Notation of the board
• player_color: None for PvP. For PvC, chess.WHITE or chess.BLACK.
• movetime: None for PvP. For PvC, between 0 and MAX_MOVETIME = 3000 milliseconds.
• depth: None for PvP. For PvC, between 0 and MAX_DEPTH = 20.

To call the chess displayable screen: (Also see the game/script.rpy file in this repo.)

define e = Character("Eileen")

window hide
$ quick_menu = False
# avoid rolling back and losing chess game state
$ renpy.block_rollback()

# launches an easy-level PvC where player plays as white
$ fen = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'
call screen chess(fen=fen, player_color=WHITE, movetime=2000, depth=2)

# avoid rolling back and entering the chess game again
$ renpy.block_rollback()
# restore rollback from this point on
$ renpy.checkpoint()
$ quick_menu = True
window show

if _return == DRAW:
    e "The game ended in a draw."
else: # RESIGN or CHECKMATE
    $ winner = "White" if _return == WHITE else "Black"
    e "The winner is [winner]."
    if player_color is not None: # PvC
        if _return == player_color:
            e "Congratulations, player!"
        else:
            e "Better luck next time, player."

Customizations for Different Difficulty Levels

The strength of the compuer player can be customized by setting the depth parameter between the range of 1 and 20, with a larger number indicating more strength. See Stockfish depth to ELO conversion.

Customizations for Different Screen Sizes, Colors, Styles, and Audios

Override the defaults in chess_displayable.rpy and replace the default chess piece and chess board images, or, audio files in 00-chess-engine/images and 00-chess-engine/audio.

# directory paths
# the path of the current directory within game/
define THIS_PATH = '00-chess-engine/'
define IMAGE_PATH = 'images/'
define AUDIO_PATH = 'audio/'
define BIN_PATH = 'bin/' # stockfish binaries
define CHESSPIECES_PATH = THIS_PATH + IMAGE_PATH + 'chesspieces/'

# file paths
define IMG_CHESSBOARD = THIS_PATH + IMAGE_PATH + 'chessboard.png'
define AUDIO_MOVE = THIS_PATH + AUDIO_PATH + 'move.wav'
define AUDIO_CAPTURE = THIS_PATH + AUDIO_PATH + 'capture.wav'
define AUDIO_PROMOTION = THIS_PATH + AUDIO_PATH + 'promotion.wav'
define AUDIO_CHECK = THIS_PATH + AUDIO_PATH + 'check.wav'
define AUDIO_CHECKMATE = THIS_PATH + AUDIO_PATH + 'checkmate.wav'
define AUDIO_DRAW = THIS_PATH + AUDIO_PATH + 'draw.wav' # used for resign, stalemate, threefold, fifty-move
define AUDIO_FLIP_BOARD = THIS_PATH + AUDIO_PATH + 'flip_board.wav'

# this chess game is full-screen when the game resolution is 1280x720
define CHESS_SCREEN_WIDTH = 1280
define CHESS_SCREEN_HEIGHT = 720

# use loc to mean UI square and distinguish from logical square
define LOC_LEN = 90 # length of one side of a loc

define COLOR_HOVER = '#90ee90aa' # HTML LightGreen
define COLOR_SELECTED = '#40e0d0aa' # Turquoise
define COLOR_LEGAL_DST = '#afeeeeaa' # PaleTurquoise
define COLOR_PREV_MOVE = '#6a5acdaa' # SlateBlue
define COLOR_WHITE = '#fff'

Continuous Development

The project is under active maintenance and you can view its development status on this public Trello board. Please feel free to submit a GitHub issue for bugs and feature requests. I have helped to integrate this chess engine into an in-development kinetic novel, The Wind at Dawn.

Contribution

Please feel free to submit GitHub issues and PRs. You are also more than welcome to join the Trello board if you are interested.

Asset Credits

• Chess image: Photo by Jani Kaasinen on Unsplash. Resized and cropped to fit the screen.
• Chess background: Chess - Wikipedia
• Chess pieces