ludeme/ludii

The Ludii general game system, developed as part of the ERC-funded Digital Ludeme Project.

The Ludii General Game System

Ludii is a general game system being developed as part of the ERC-funded Digital Ludeme Project (DLP). This repository hosts the publicly available source code for Ludii. A precompiled build (Ludii.JAR) can be downloaded from Ludii's downloads page.

Requirements

Working with Ludii's source code requires Java Development Kit (JDK) version 8 or higher.

Getting Started

Eclipse (recommended)

1. Clone (and optionally fork) this repository.
2. Import the whole Ludii/ folder to your workspace.
3. To start the GUI, right click on /Ludii/PlayerDesktop/src/app/StartDesktopApp and launch it as a Java Application

Eclipse should recognise each folder as a separate project and automatically apply the -parameters compiler flag.

IntelliJ IDEA

1. Clone (and optionally fork) this repository.
2. Import the whole Ludii/ folder as an Eclipse project. We recommend following the official instructions on importing Eclipse projects. Make sure to import each capitalised folder (AI/, ..., View Controller/) as a separate module.
3. In Settings | Build, Execution, Deployment | Compiler | Java Compiler, under Additional command line parameters, type -parameters.
4. To start the GUI, create a new run configuration under Run | Edit Configurations | + | Application.
   1. Set the module to PlayerDesktop and use java 1.8 or above.
   2. Set the main class to app.StartDesktopApp.
   3. Change the working directory from .../Ludii to .../Ludii/PlayerDesktop

Every time you want to run a class, edit the run configuration such that the working directory is .../Ludii/%Module%/ as opposed to .../Ludii/.

Other IDEs

1. Keep in mind that each capitalised folder is meant to be a different module/project.
2. The Core module needs to be compiled using the -parameters flag. It's also okay to compile all the modules with it.
3. When executing a main method, set the working directory to the class's module, not the Ludii folder or the file location. For example StartDesktopApp should have as working directory .../Ludii/PlayerDesktop.

Build & Run

The main method to launch Ludii from your IDE is located in /Ludii/PlayerDesktop/src/app/StartDesktopApp. At this time we do not use any more sophisticated build tools (such as Maven) in our day-to-day programming with Ludii. There are some relatively simple Ant build scripts, but we only use these -- specifically, the /Ludii/PlayerDesktop/build.xml script -- for generating the releases published on the Ludii downloads page.

Other Resources

We have various other resources available at the following links:

• Ludii Tutorials: various tutorials on aspects ranging from game design (using Ludii's game description language) to programming with Ludii as a programmatic library. The source files for these tutorials are also available on GitHub.
• Ludii Documentation: the Ludii downloads page provides links to additional documentation, such as the Ludii User Guide, Ludii Game Logic Guide, Ludii Language Reference, and DLP Database Guide.
• Ludii Example AI: an example project for implementing Java-based AIs that can play Ludii games.
• Ludii Python AI: an example project for implementing Python-based AIs that can play Ludii games.
• Ludii AI Competition: a supporting project for Ludii AI competitions.
• Ludii AI: a repository used to hold the source code of built-in Ludii AIs before the entirety of the project was open-sourced. This repository is now deprecated, since the source code is also included in this repo.

Contributing Guidelines

While we of course cannot guarantee that we will accept every suggested change or contribution, in principle we welcome contributions and are excited to see what you come up with! Please send contributions on GitHub as new Pull Requests, and provide brief descriptions of what has changed and in what ways these changes improve Ludii (or other aspects of the repo, such as documentation). Please ensure that any new or changed code follows the same code style as the rest of the repository.

Note: pull requests should be used for code or documentation contributions, but not for new games (i.e., .lud files). We prefer that new games are submitted through our forums.

Citing Information

When using Ludii's source code in any publications, please cite our paper describing Ludii: https://ecai2020.eu/papers/1248_paper.pdf

The following .bib entry may be used for citing the use of Ludii in papers:

@inproceedings{Piette2020Ludii,
        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"
}

Contact Info

The preferred method for getting help with troubleshooting, suggesting or requesting additional functionality, or asking other questions about Ludii's source code, is posting a message on the Ludii Forum. Alternatively, the following email address may be used: ludii(dot)games(at)gmail(dot)com.

Acknowledgements

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

ludii's Issues

Taikyoku shogi: Dog's move is incorrect

The Dog piece as shown on the English Wikipedia moves to either one of the three forward squares.
But it appears the Dog pieces in front of the pawns are either Left Dog or Right Dog, so they will need to be changed to a regular Dog.

Argument labels in nested symbols

This extract is from Mweiso.lud

and {
    if:(if ("SameTurn")
        (< 0 (count at:(from)))
        (< 1 (count at:(from)))
    )
    (is In (from) (sites {(mapEntry "LeftMostOuter" Mover) (mapEntry "SecondLeftInner" Mover)}))
    (is In ("NextHole" (from) "TrackCW" (count at:(from))) (sites Mover "Inner"))
    (is Occupied ("OppositePit" ("NextHole" (from) "TrackCW" (count at:(from)))))
    (is Occupied ("OppositeOuterPit" ("NextHole" (from) "TrackCW" (count at:(from)))))
}

Is the if: label intentional in if:(if ("SameTurn")? I'm struggling to grasp why a label might be in an array. The game compiles just fine without it and, as far as I can tell, plays identically.

If it was a mistake I can make a pull request to remove every occurance

Choice of Licensing

It's been a long time since I have seen code licensed as Creative Commons, much less Non-Commercial, much less No Derivatives. What was the reasoning behind the licensing? This basically means one cannot even fork Ludii, yes? The closest forum post I could find is #150, but that still doesn't answer my question.

Ludii - Analysis metric outputing conflicting numbers with swap rules

Hello, I'm currently conducting some experiments on the game Hex using the "Evaluation Dialog" and I noticed that when I allow swap rules, the Player 1 win rate and AdvantageP1 numbers do not match and Balance also doesn't reflect the reported win rates at times. Here is the console output for an experiment on 100 trials, with no timeouts and no draws, using MC-GRAVE AI agent:

Analysing Hex [Board Size/11x11, Swap Rules/On, End Rules/Standard]

Please don't touch anything until complete!
Generating trials:
....................................................................................................
Calculating metrics:
AdvantageP1
Balance
Completion
Drawishness
Timeouts
Board Coverage Default
Decisiveness Moves
Ideal Duration

Agent type: MC-GRAVE
Draw likelihood: 0%
Timeout likelihood: 0%
Average number of moves per game: 30.76
Player 1 win rate: 58%
Player 2 win rate: 42%

AdvantageP1: 0.56 (weight: 1.0)
Balance: 0.88 (weight: 1.0)
Completion: 1 (weight: 1.0)
Drawishness: 0 (weight: 1.0)
Timeouts: 0 (weight: 1.0)
Board Coverage Default: 0.25405 (weight: 1.0)
Decisiveness Moves: 0.42 (weight: 1.0)
Ideal Duration: 0.43987 (weight: 1.0)
Final Score: 3.55391

When I look into EvaluateGame function, the win rate is calculated using "RankUtils.agentUtilities(context);" where it is explicitly checked if players swapped positions, but metrics for Advantage and Balance are calculated using "trial.status().winner()" with no further checks. If the winner is wrongly attributed to a player index before the swap, this would explain this discrepancy.

I'm not that well versed in Java and maybe I overlooked something, but can you please check my findings? The problem is reproducible on Ludii-1.2.8 and a version close to the current master.

Thank you,

David

Unexpected Symbol::returnType behaviour

Grammar.grammar().symbols() does not contain the Step symbol's returnType.

For example

Symbol moveStepType = Grammar.grammar().symbolsByName("MoveStepType").get(0);
Symbol step = Grammar.grammar().symbolsByName("Step").get(2);
List<Symbol> symbols = Grammar.grammar().symbols();
System.out.println("is " + moveStepType + " in the grammar? " + symbols.contains(moveStepType));
System.out.println("is " + step.returnType() + " in the grammar? " + symbols.contains(step.returnType()));

System.out.println("disambiguation " + step.returnType().disambiguation(moveStepType));

System.out.println(moveStepType.info());
System.out.println(step.returnType().info());

Returns

is <moveStepType> in the grammar? true
is <moveStepType> in the grammar? false
disambiguation null
~~~~ <moveStepType> name=MoveStepType type=Structural (game.rules.play.moves.decision.MoveStepType) => <moveStepType>, pack=game.rules.play.moves.decision, label=moveStepType, cls=game.rules.play.moves.decision.MoveStepType, keyword=moveStepType, atomic=MoveStepType, atomic path=game.rules.play.moves.decision.MoveStepType
Exception in thread "main" java.lang.NullPointerException: Cannot invoke "main.grammar.Symbol.name()" because "this.atomicLudeme" is null
	at main.grammar.Symbol.info(Symbol.java:1085)
	at approaches.random.GeneratorNode.main(GeneratorNode.java:64)

I had expected step.returnType() to equal moveStepType. However, it instead returns a new symbol which has the same name but is not present in Grammar.grammar().symbols(). Is this intended behaviour? And is it okay that step.returnType().info() crashes?

Assuming it's all correct. What would be the best way to find the "real" symbol from the return type?