Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Ludii Python AI

license Maintenance twitter

This repository contains information and examples for implementing general-game-playing AIs in Python, with a Java wrapper around them, such that they can subsequently be used in the Java-based Ludii General Game System.


  • Java version 8 or higher (including JDK)
  • Python 3 (probably 3.6 or higher)

Getting Started

The example in this repository consists of two parts:

  1. A simple AI algorithm (UCT) implemented in Python.

  2. A Java-based wrapper for your AI; this one is implemented following the standard Ludii Example AI instructions, such that it can be packaged in a JAR file, and loaded and used through the GUI of Ludii. In the case of this repo, the Java code does not actually implement any AI algorithms, but only contains code that, using the jpy bridge, calls the Python-based AI code.

Installing jpy

The code in this repository requires jpy to provide communication between Java and Python, but jpy itself is not included and must instead be manually downloaded and built by the end user. To do this, we refer to the jpy repository.

After following the instructions for building jpy, you should find the built library's files somewhere under /jpy/build/. The exact files and location can be different for different OSes. Generally, they will be *.so files for Unix, or *.pyd files for Windows. These files, alongside the and jpy's JAR files created by jpy's build process, should be copied over into /LudiiPythonAI/libs/. This is the directory where the Java code as we've implemented it will search for these files, though you could modify that yourself if you prefer. The file as you copied it into this directory may also need to be manually modified (in any text editor) to ensure that it still points to the correct locations for the jpy library files.

Setting up Java project

Set up a Java project in your favourite IDE for Java, using the source code from this repository to start with. The JAR file from jpy should be added to the build path. Additionally, Ludii's own JAR file (downloaded from should also be added to the build path (it may be convenient to also copy this file into /LudiiPythonAI/libs/).

Our provides an example implementation that redirects calls from the Ludii GUI to the Python-based UCT implementation. The build.xml Ant script can be used to package this Java code in a JAR file that can subsequently be loaded in Ludii's GUI using the standard instructions for loading third-party AIs.

Note that this JAR file will not actually include the Python code or the jpy library files. For this reason, the JAR file should be kept exactly where it is created and directly loaded from that location, such that our Java implementation can correctly find these files. Alternatively, you may modify that Java code to change how it locates these files.

Citing Information

When using Ludii in any publications (for example for running experiments, or for visual inspections of your agent's behaviour during development, etc.), please cite our paper on the Ludii system. This can be done using the following BibTeX entry:

        author      = "{\'E}. Piette and D. J. N. J. Soemers and M. Stephenson and C. F. Sironi and M. H. M. Winands and C. Browne",
        booktitle   = "Proceedings of the 24th European Conference on Artificial Intelligence (ECAI 2020)",
        title       = "Ludii -- The Ludemic General Game System",
        pages       = "411-418",
        year        = "2020",
        editor      = "G. De Giacomo and A. Catala and B. Dilkina and M. Milano and S. Barro and A. Bugarín and J. Lang",
        series      = "Frontiers in Artificial Intelligence and Applications",
        volume      = "325",
		publisher	= "IOS Press"

Background Info

This repository contains information and examples for the development of Python-based AI implementations, with a Java wrapper such that they can subsequently be loaded into the Java-based Ludii General Game System.

This work, as well as the full Ludii system itself, are developed for the Digital Ludeme Project. More info on the project and the system can be found on:

Contact Info

The preferred method for getting help with troubleshooting, suggesting or requesting additional is creating new Issues on the github repository. Alternatively, the following email address may be used: ludii(dot)games(at)gmail(dot)com.


This repository is part of the European Research Council-funded Digital Ludeme Project (ERC Consolidator Grant #771292), being run by Cameron Browne at Maastricht University's Department of Advanced Computing Sciences.

European Research Council Logo


Example repo for running Python-based AIs in Ludii







No releases published


No packages published