🎲 Learning Ludii

Learning the Ludii General Game System language.

Fabio Barbero published on

9 min, 1700 words

Categories: Guide

Tags: Challenge Ludii

Introduction

What is Ludii?

Ludii is a "general game system designed to play, evaluate and design a wide range of games, including board games, card games, dice games, mathematical games, and so on." (taken from Ludii's website).

Ludii games (in .lud file format) are usually loaded in the Ludii Player, which compiles the game with Java and gives an interface to play with, with also AIs to play against. This won't stop to amaze me: from a short game description you can immediately get a fully functioning environment to play in, against an AI that has never seen the game before but might still beat you.

You can install the Ludii player on Linux by running "curl https://fabiobarbero.eu/scripts/ludii.sh | sh" in a shell terminal. 1

I am lucky enough to have Cameron Browne, the creator of Ludii, as a supervisor for my bachelor thesis. His recent talk at the XXIII board game studies colloquium made me realize how truly revolutionary the Ludii language is: a "game" in Ludii is described uniquely by "ludemes", giving hence a solid mathematical definition of a Ludeme.

What is a ludeme?

Much like a meme, a ludeme is something that spreads by means of imitation from person to person within a culture and often carries symbolic meaning (from Merriam-webster dictionary). Ludemes apply to games in general: this can be rules such as hopping over a piece to capture it, reaching the opposite side of the board to win, or moving forward.

Cameron Browne describes a ludeme as:

  • a discrete unit of information (atomic or compound)
  • can be transferred between games
  • changes the function of a game

In ludii, everything is a ludeme.

Learning Ludii

As of when I'm writing this blog the only documentation that can be found for learning the Ludii language is:

I am proud to say that I have read almost all of these three documents, and hope to be able to save some of your time by writing this guide. If you would like to read the original documentation, I recommend doing it in the order listed above.

What does Ludii look like?

The "hello world" of board games is often considered to be the game Tic-Tac-Toe, which I am assuming everyone is familiar with. Here is what Tic-Tac-Toe looks like in Ludii:

(game "Tic-Tac-Toe"  
    (players 2)  
    (equipment { 
        (board (square 3)) 
        (piece "Disc" P1) 
        (piece "Cross" P2) 
    })  
    (rules 
        (play (move Add (to (sites Empty))))
        (end (if (is Line 3) (result Mover Win)))
    )
)

If you're familiar with Lisp, then this should be fairly easy to read. Ludemes are encapsulated in parentheses. If you're not, don't worry. I also had very little experience with Lisp when I started learning Ludii, knowing mainly Java and Python. Intuitively, the first word in the parentheses is the function, and the remaining terms are arguments. A list of all functions can be found in the Ludii Language Reference.

So the above code can be read as following: we define a game called "Tic-Tac-Toe". In this game, there are 2 players, and the equipment is: a 3x3 square board, Disc pieces for Player 1 and Cross pieces for Player 2. The rules of the game are: keep adding pieces to empty sites, until a line of 3 in any direction is made, which results in the Mover winning.

How to learn ludii

In this post I won't go through every single ludeme describing how they work in practice. You can find that in the Ludii Language Reference. I would just like to give a few tips on how to learn it, based on my own experience.

Read, read, read

The first thing I did to get familiar with the syntax is to read a lot of implementations of games I was already familiar with. A full list of games can be found in the Ludii Player or on the ludii library.

Here's a list of games you might be familiar with:

Don't worry if you sometimes don't understand what is going on. This is just to get used to the syntax and getting used to reading Ludii code - useful for debugging. You can also ignore the (define) commands and start reading from game.

Get a clear structure of how ludii works

The Ludii Game Logic Guide is in my opinion the best document to get a clear idea of how the language works.

The main components of a ludii games are:

  • players
  • equipment
  • rules
    • start (optional)
    • play
    • end

Practice bit by bit

Unfortunately for you, Stack Overflow does not have anything for ludii yet. This means that you'll have to learn the hard way, by debugging every single error you get.

Board generation

It is important to start experimenting with each of the different components listed above. For example, you might first want to get familiar with the board generation. In order for the game to compile, you also require the rest of the rules. I usually use these "dummy" rules to check the board generation

(game "test"
    (players 2)
    (equipment {
        // your code here
    })
    (rules
        (play (forEach Piece))
        (end (if (no Moves Next) (result Mover Win)))
    )
)

Exercise! Try to generate the following boards. You can click on the image to reveal the solution

Ludii Adugo board 
(board
    (merge 
        (shift 0 2 (square 5 diagonals:Alternating)) 
        (wedge 3)
    ) 
use:Vertex)
Adugo
Ludii Asalto board 
(board
    (merge
        (shift 0 2 (rectangle 3 7 diagonals:Alternating))
        (shift 2 0 (rectangle 7 3 diagonals:Alternating))
    )
    use:Vertex
)
Asalto
Ludii Kaooa board 
(board 
    (splitCrossings (regular Star 5))
    use:Vertex
)
Kaooa

Piece placement

Once you're comfortable with board generation, you can start playing around with the initial placement of the pieces.

Exercise! Try to generate the following piece placements. You can click on the image to reveal the solution

Ludii Three Musketeers board 
(start {
    (place "Musketeer1" {"A1" "C3" "E5"})
    (place "Enemy2" (difference 
        (sites Board) 
        (sites {"A1" "C3" "E5"})
    ))
})
Three Musketeers

Rules and end condition

I might add an interactive section here in the future, but I suggest looking at the Ludii Language Reference for a full list of moves.

Copy!

Try to write as many games as possible, by copying from games that already exist in Ludii. Before writing the game, think of similar games and look at how they have been implemented. It often gives great help and is a valuable learning experience. It is also how game designers often (subconsciously) design new games! Some great games to start learning:

Create!

Ludii has a list of games that have not yet been implemented.

Ask in the Ludii forum!

If you're really stuck on something and cannot find anything in the guides, you can always ask the Ludii forum!

Sometimes, what you're trying to do just isn't possible in the current version of Ludii! The ludii team is very friendly and competent and has always helped me with useful advice.

Here is my profile on the Ludii Forum, if you would like to see what posts I made.

Conclusion

Learning Ludii has been a fun and valuable to me. I hope that I have given you a few resources and tips to learn ludii by yourself. The key message is to try to copy/replicate as much as possible from existing games.

I'd like to end this post with a quote from Cameron (during one of our meetings):

Writing/creating a game can be a game by itself

1

It is generally NOT a good idea to pipe the content of a website into bash, so you should ideally first download the script locally, check what it does, and then run it. If you do not understand some of the code you can use https://explainshell.com/.