The Gleam Chess Tournament

Welcome to the inaugural Unofficial Gleam Chess Tournament!

This is a friendly competition to see who can create the best chess bot in the Gleam programming language. Once submissions are closed, the tournament will be turned into a Twitch stream or YouTube video on my channel.

Submission deadline

Chess bots need to be submitted by 12pm UTC on June 8th, 2025. See the submission guidelines for more information.

Changelog

2025-04-28

• Updated submission guidelines. Submissions will now be happening through CodeCrafters. See the submission guidelines for more information.

2025-03-15

• Added a testing script to the testing_utils directory. See the section on testing for more information.

2025-03-12

• Updated Dockerfiles (#4, thanks @MoeDevelops!) to be a bit slimmer. You may still use the old Dockerfiles, which are now prefixed with pre-2025-03-11-.
• Added a new rule to limit the total number of failures a bot is allowed per game before forfeiting. This is to prevent the potential workaround outlined in #5. The limit is currently 15 failures.
• Added new prizes! Thanks CodeCrafters for the sponsorship!

2025-03-11

• Added birl, gtempo and gleam_time as allowed libraries for all targets.

How does it work?

Essentially, each entry will be a Gleam web server that responds to HTTP requests sent to a /move endpoint. The body will be a JSON object containing three fields:

{
  "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
  "turn": "white",
  "failed_moves": ["Nf3"]
}

Field	Description
fen	The FEN of the current board position.
turn	The side to move. Either "white" or "black".
failed_moves	A list of moves that your bot attempted to make for this turn, but were not legal moves.

The task of parsing the FEN and returning a move is left up to you.

Prizes

Prizes will be awarded to the top three entries. The winner will be determined by tournament.

An additional prize will be awarded to the entry with the most interesting strategy.

• 1st place: $500, a Lucy T-shirt and a Lucy mug, and CodeCrafters VIP memberships for you and your team
• 2nd place: $300 and a T-shirt OR mug, and 1 year CodeCrafters memberships for you and your team
• 3rd place: $100 and a T-shirt OR mug, and 3 month CodeCrafters memberships for you and your team
• Most interesting strategy: $50 and a T-shirt OR mug, and 1 month CodeCrafters memberships for you and your team

See the Gleam shop for more information on merch.

CodeCrafters

Thanks to CodeCrafters for sponsoring the prizes! Check them out for an awesome way to get better at coding.

Submissions

Chess bots need to be submitted by 12pm UTC on June 8th, 2025.

Submissions should be Gleam web servers and may use either the Erlang or JavaScript targets. Templates for both are provided in the erlang_template and javascript_template directories respectively.

Submissions will be pitted against each other by a client running the chess.js library for tracking and validation.

The format of the tournament is yet to be decided and will likely depend on the number of submissions.

Ssubmissions will be happening through CodeCrafters. they’ve very kindly put together two new challenges on their site to support the competition - one for bots running on the Erlang target, and another for bots running on JavaScript.

If you’ve not used CodeCrafters before, essentially, it’s an online platform for learning intermediate-to-advanced software engineering concepts by recreating popular software like SQLite, Redis and Kafka.

When you start a CodeCrafters challenge, you’ll get access to a special Git repo, and when you push code to that repo, the CodeCrafters Git server will run tests against your submission, allowing you to progress to the next stage of the challenge.

For the purposes of the chess bot tournament, the challenges test your bot against a number of boards to ensure you produce valid moves. You can submit your bot by completing stage 5 (which just requires you to fill out a markdown file with your entry details), and I’ll be given access to your bot once the tournament has ended, so you won’t need to do anything else!

You can keep pushing updates up to the deadline, of course, and I’ll test against the most recent commit pushed before the competition reaches its end.

Check out the CodeCrafters challenges here:

• Erlang
• JavaScript

If you’re not already signed up to CodeCrafters, you should be! You can get 40% off (and support me and the competition!) by clicking here.

How to participate

• Install Gleam and clone this repository.
• Create a new directory for your submission and copy the erlang-template or javascript-template directory into it.
• Ensure you can run gleam run and the webserver starts correctly on port 8000.
• Fill out the move function in src/<target>_template/chess.gleam with your bot's logic.
  • The function should return a Result(String, String) where the Ok variant is a move in SAN format. The client will validate using chess.js's permissive move parser (see here).
• Ensure your program compiles and runs correctly.
• Ensure you can build a Docker image for your submission using the Dockerfile provided in the template project.
• Write up a brief description of how your bot works in the README.md file.
• Once you're happy with your bot, submit your project here.

Rules

• You can participate alone or in a group.
• You may only submit one entry per person.
  • If you wish to update your entry before the tournament closes, please reach out to me via Bluesky or in the #chess-tournament channel in my Discord.
• You may only use a limited set of external libraries. See the libraries list. for more information.
• You may not do any IO operations to the filesystem or network.
• FFI is not allowed.
• Your bot may not use more than the following resources. These will be enforced by Docker:
  • 2 CPU cores
  • 512mb of RAM
• Each move will be timed out after 5 seconds.
• If your bot fails three times for the same turn, either by timing out or by failing to make a legal move, it will forfeit the match.
  • Your bot will also forfeit if it fails or times out 15 times total during the match. See #5 for details.
• You may not modify the provided Dockerfile.
• The bots will run on Gleam 1.9.1.
  • The JavaScript bot will run on Deno, as that's what's best supported by Glen.
• You may not modify the project names (sorry, it'll break Dockerfiles!).

Libraries

The following is a list of libraries allowed on each target. If you feel that the list is missing something, please open an issue.

You may use any dev dependencies you wish, but they must not be included in the built output.

All targets

• gleam_stdlib
• gleam_http
• gleam_json
• gleam_time
• gleam_community_maths
• flash
• iv
• glearray
• snag
• birl
• gtempo

Erlang

• gleam_erlang
• gleam_otp
• mist
• wisp

JavaScript

• gleam_javascript
• glen

Testing

The testing_utils directory contains a Deno test script that will run a suite of test moves against your bot. Feel free to use it as you see fit.

Run the tests with deno run test, assuming your bot is running on port 8000 (which it should be!).

Newsletter

To be kept up to date with the latest news and updates, rule changes and so forth, subscribe to the Gleam Chess newsletter.

Useful resources

• The Chess Programming Wiki