Updating the Games Catalog#

This page includes developer notes regarding the catalog module, and the process for contributing to and updating Gambit’s Games Catalog. To do so, you will need to have the gambit GitHub repo cloned and be able to submit pull request via GitHub; you may wish to first review the contributor guidelines.

You can add new games to the catalog, or edit existing ones that are saved in a valid representation format. Currently supported representations are:

  • .efg for extensive form games

  • .nfg for normal form games

Note

When updating the catalog, changes can be viewed by inspecting the documentation build generated by a pull request. To test changes locally, you’ll need to have a developer install of pygambit available in your Python environment, see Building the Python extension.

  1. Create or edit a game file:

    Use either pygambit, the Gambit CLI or GUI to create (or edit) and save game in a valid representation format. Make sure the game includes a description, with any citations referencing the bibliography. Use a full link to the bibliography entry, so the link can be accessed from the file directly, as well as being rendered in the docs e.g. `Rei2008 <https://gambitproject.readthedocs.io/en/latest/biblio.html#Rei2008>`_

    Important

    If no bibliography entry exists, you should add one by editing doc/biblio.rst.

  2. Commit the changes:

    Create a new branch in the gambit repo. Add your new game file(s) inside the catalog dir and commit them, or edit an existing game. If there are multiple games from a particular source, place them in an appropriately named folder.

    Important

    The name of the game file will determine it’s “slug”, used by the load function of the catalog module:

    pygambit.catalog.load("watson2013/exercise29_6")

  3. [Optional] Test your updates locally (and customise visuals):

    Reinstall the package to pick up the new game file(s) in the pygambit.catalog module. Then use the update.py script to update Gambit’s documentation & build files, as well as generating images for the new game(s). If you want, you can first edit the catalog_draw_tree_settings in build_support/catalog/update.py to change the default visualisation parameters for your game(s). Consult the DrawTree docs for the available options.

    pip install .
python build_support/catalog/update.py --build

    Note

    You can use the --regenerate-images flag when building the docs locally for a second time to force any changes to be picked up.

    Warning

    Running the script with the --build flag updates Makefile.am. If you moved games that were previously in contrib/games you’ll need to also manually remove those files from EXTRA_DIST.

  4. Submit a pull request to GitHub with all changes.

    Submit a PR according to the usual workflow. Ensure that any additions and changes to game files, build_support/catalog/update.py and Makefile.am are included.

    Important

    If you didn’t run the update script in step 3, you should manually update EXTRA_DIST in Makefile.am with any new game files.

Adding games from external libraries#

You can use the catalog update script to pull games from external libraries by providing the appropriate flags.

OpenSpiel#

python build_support/catalog/generate_openspiel.py

Important

If any games are added or changed by running this script, you’ll need to run the update.py script as per step 3 above.