Reversi.jl

A high-performance Reversi (Reversi) implementation in Julia, built on StaticArrays.jl for efficient board representation. Designed with flexibility for machine learning research and reinforcement learning applications.

Features

• Efficient Implementation: Uses StaticArrays.jl for fast, stack-allocated board representation
• Terminal Gameplay: Play interactively in the terminal
• Flexible Player System: Easy to integrate custom AI players and ML models
• Clean API: Simple, well-documented interface for programmatic control
• Extensible: Abstract player interface allows easy implementation of new strategies

Installation

using Pkg
Pkg.add(url="https://github.com/sotashimozono/Reversi.jl")
Pkg.add("Reversi")

Or in the Julia REPL package mode (press ]):

pkg> add https://github.com/sotashimozono/Reversi.jl
pkg> add Reversi

Quick Start

Play in Terminal

using Reversi

# Human vs Random AI
play_game(HumanPlayer(), RandomPlayer())

Or run the interactive script:

julia --project examples/play.jl

Programmatic Usage

using Reversi

# Create a new game
game = ReversiGame()

# Display the board
display_board(game)

# Get valid moves
moves = valid_moves(game)

# Make a move
make_move!(game, 3, 4)

# Check game status
if is_game_over(game)
    winner = get_winner(game)
end

Create Custom AI Players

using Reversi

# Define a custom player type
struct MyAIPlayer <: Player end

# Implement the get_move function
function Reversi.get_move(player::MyAIPlayer, game::ReversiGame)
    moves = valid_moves(game)
    
    if isempty(moves)
        return nothing  # Pass turn
    end
    
    # Your AI logic here
    # Return a Position(row, col)
    return moves[1]  # Example: pick first valid move
end

# Play a game
play_game(MyAIPlayer(), RandomPlayer())

API Documentation

Core Types

• ReversiGame: Main game state structure

  • board::MMatrix{8,8,Int,64}: 8x8 game board
  • current_player::Int: Current player (BLACK or WHITE)
  • pass_count::Int: Number of consecutive passes

• Position: Represents a board position

  • row::Int: Row (1-8)
  • col::Int: Column (1-8)

• Player: Abstract type for player implementations

Game Functions

• make_move!(game, row, col): Make a move at the specified position
• valid_moves(game, player): Get all valid moves for a player
• is_game_over(game): Check if the game has ended
• get_winner(game): Get the winner (BLACK, WHITE, or EMPTY for draw)
• display_board(game): Display the current board state
• play_game(player1, player2; verbose=true): Play a complete game

Built-in Players

• HumanPlayer(): Interactive terminal player
• RandomPlayer(): Makes random valid moves

Machine Learning Integration

Reversi.jl is designed to facilitate machine learning research. The flexible player system allows you to integrate:

• Reinforcement Learning agents (e.g., DQN, AlphaZero-style)
• Neural network policies
• MCTS-based players
• Any custom strategy

Example: Integrating a Neural Network Player

using Reversi
using Flux  # Or your preferred ML framework

struct NeuralPlayer <: Player
    model  # Your trained neural network
end

function Reversi.get_move(player::NeuralPlayer, game::ReversiGame)
    moves = valid_moves(game)
    
    if isempty(moves)
        return nothing
    end
    
    # Convert board to model input
    input = convert_board_to_input(game.board)
    
    # Get policy from neural network
    policy = player.model(input)
    
    # Select move based on policy
    return select_move_from_policy(policy, moves)
end

# Train your model separately, then:
trained_model = load_trained_model("model.bson")
nn_player = NeuralPlayer(trained_model)
play_game(nn_player, RandomPlayer())

Examples

See the examples/ directory for more examples:

• examples/demo.jl: Demonstrates various features
• examples/play.jl: Interactive terminal game

Game Rules

Reversi (also known as Reversi) is played on an 8x8 board:

1. Black (●) plays first
2. Players alternate placing pieces
3. A valid move must flip at least one opponent piece
4. Pieces are flipped by sandwiching them between your pieces
5. If no valid moves exist, the player must pass
6. Game ends when both players pass or the board is full
7. Winner is the player with more pieces

Future Development

• Web-based UI using Genie.jl or similar
• Opening book support
• Game replay and analysis tools
• Additional built-in AI strategies
• Tournament system for comparing players

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.