Ludii Example AI

This project contains instructions and examples for the implementation of third-party AI algorithms / agents for the Ludii general game system. After developing your own agent, you can load it locally through the GUI of the Ludii application, and watch it play any game supported by Ludii!

Agents implemented according to the instructions on this page will also be suitable for submission to any future agent-based playing competitions organised using the Ludii system.

Most of the documentation found in this repository may also be found in the Ludii User Guide, accessible from the Ludii webpage.

Table of Contents

• Requirements
• Getting Started
• Example Agents
• Citing Information
• Background Info
• Contact Info
• Changelog
• Acknowledgements

Requirements

As of this time, only the development of agents in Java is supported. The minimum version of Java required is Java 8. Development of agents in other programming languages may be supported in the future, but there is no concrete timeline for when this will be supported.

Getting Started

AI Development

1. Download Ludii's JAR file. This is the JAR file that can also be used to launch the Ludii application.
2. Create a new Java project using your favourite IDE. You can also create a fork of this github repository to get started with some example implementations of basic agents.
3. Make sure to add the Ludii's JAR file downloaded in step 1 as a library for your project.
4. Any agent that you'd like to implement will have to extend the abstract class util.AI. This contains three methods that may be overridden:
   1. public Move selectAction(final Game game, final Context context, final double maxSeconds, final int maxIterations, final int maxDepth). It takes a reference to the game being played, and the current context (which contains, among other data, the current game state) as arguments, and should return the next Move to be played by the agent. The final three arguments can be used to restrict the agent's processing (its search time, or its maximum iteration count or search depth for example).
   2. public void initAI(final Game game, final int playerID). This method can be used to perform any initialisation of the AI when the game to be played has been determined, but before the initial game state has been generated.
   3. public boolean supportsGame(final Game game). This method has a default implementation to return true for any game, but may be overridden to return false for games that your agent cannot play. For example, it may be unable to play simultaneous-move games, and then be implemented to always return false for those. Ludii will then know not to try to make your AI play such a game. For a simple example class that extends this abstract class, see the Example Random AI.
5. Export your project to a new JAR file.

Loading AI in the Ludii Application

In the Ludii application, the dialog in which agent types can be assigned to players can be opened by clicking one of the player names in the GUI, or by selecting Ludii > Preferences... in the menubar. In addition to a number of built-in agents, the drop-down menus contain a From JAR option.

To load your own custom AI implementation into Ludii, select the From JAR option, and then select the JAR file containing your custom AI's .class file. A dialog will appear with all the different classes in the selected JAR file that extend Ludii's util.AI abstract class, and you will be required to choose one of them. Note that this means that it is fine if you have a single JAR file containing many different, custom AI implementations; they can all be loaded.

Ludii will attempt to instantiate an agent of the selected class by calling a zero-arguments constructor of that class. This will only work correctly if your class does indeed provide a zero-args constructor, and it will have to be public as well!. After loading it as instructed here, the custom AI can be used to play any games in the Ludii application, just like any other built-in AI.

Note: while the Ludii application is running, it will only load all the .class files of any selected JAR file once. If you have already selected a JAR file once, and then re-build your custom JAR file without changing its filepath, you will have to close and re-open the Ludii application if you wish to try loading agents from the modified JAR file.

Example Agents

• Random AI.
• Example UCT (only supports deterministic, alternating-move games).
• Example Decoupled UCT (only supporst deterministic, simultaneous-move games).

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:

@misc{Piette2019Ludii,
	Author = {{\'E}ric Piette and Dennis J. N. J. Soemers and Matthew Stephenson and Chiara F. Sironi and Mark H. M. Winands and Cameron Browne},
	Title = {Ludii - The Ludemic General Game System},
	Year = {2019},
	Eprint = {arXiv:1905.05013},
	url = {https://arxiv.org/abs/1905.05013}
}

Background Info

This repository contains information and examples for the development of third- party AI implementations which can be loaded into the Ludii General Game System. Note that this repository does not contain the full Ludii system, or its built-in AI options.

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:

• http://www.ludeme.eu/
• http://ludii.games/

Contact Info

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

Changelog

• 13 December, 2019: Updated repository for compatibility with new version 0.5.0 of Ludii.
• 27 November, 2019: Updated repository for compatibility with new version 0.4.1 of Ludii.
• 6 September, 2019: Updated repository for compatibility with new version 0.3.0 of Ludii.
• 13 August, 2019: Initial release.

Acknowledgements

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 Data Science and Knowledge Engineering.