Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


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


Let AI play against AI

aimole is a platform for game playing AI to play against other game playing AI. It is initially developed to support the online course taught by Dr. Wong Tsz Yeung at CUHK, see the course here.

Besides this AI competing platform, there is also an online judge for programming assignments. See codeSubmit.


aimole is modularized to two parts, platform and games. Currently have two games developed and available.






You are recommended to deploy on ubuntu because the prepared scripts are written for environment of ubuntu machines.

On the ubuntu machine, run shellscripts/npm/ to install all the required packages. These includes docker and node.js. And then run npm install to npm dependencies.

aimole persists data on MongoDB and queues jobs on RabbitMQ. To spin them up, you can run shellscripts/docker/mongodb/ and shellscripts/docker/rabbitmq/

And then, configure aimole by modifying configs/

After configuring, build the static html files by running grunt html.

To spin up aimole web server, run shellscripts/docker/production/

To spin up aimole worker, run shellscripts/docker/production/

For deploying more instances on multiple machines, run the corresponding [web, worker] script with an extra argument of master ip. E.g. shellscripts/docker/production/ to spin up a worker with databases connecting to Same for web server.

To install games, run npm run installGame with corresponding arguments to retrieve the game repository on github.


(This is for aimole platform, for aimole games, see Game Development section.) To spin up all the stuffs for development, run shellscripts/docker/aimole/ This will spin up a MongoDB, RabbitMQ, an aimole web server and an aimole worker. It will also watch for file changes to restart all both web and worker instances.

Game Development

See Othello and 2048 above for references.

There are 3 main components for an aimole game: view, verdict, default ai. And a configuration file aimole.json.

View is the beautiful, animated view of the game board, which will be included by the aimole platform through embedding an iframe. You may find this tool useful for your development, it can also be found on the aimole-example repository.

Verdict is a piece of code that keeps checking on wether players are making valid moves during the game. It communicates with the players by sending messages to players' stdin and receiving messages from players' stdout. However, these messages are not passing to verdict directly, aimole platform wraps the players' stdin and stdout with extra information, such as player id, time used or even error messages. These wrapped message is passing by stringified JSON through verdict's stdin, and expecting verdict to pass back a stringified JSON through verdict's stdout. You can see the structure of the JSON here. Command is the JSON structure passing to verdict by aimole platform. Action is the JSON structure passing to aimole platform by verdict.


All the user submitted code are running inside sandbox environment. For each code execution, codeSubmit will spawn docker instances to run the compilation and execution process. This isolates each submission as well as providing security to the host.

This sandbox is a sub-project of Dr. Wong Tsz Yeung's students' final year project. You can find its docker hub repository here.


This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see