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’ll also need to have a developer install of pygambit available in your Python environment, see Building the Python extension.

The catalog module#

Although the catalog directory is located at the project root outside of src/pygambit/, it is installed and bundled as the pygambit.catalog subpackage.

This is handled by the package build configuration in pyproject.toml under [tool.setuptools]:

  • The package-dir mapping instructs setuptools to source the pygambit.catalog subpackage from the physical catalog directory.

  • The package-data configuration ensures all non-Python data files (like .efg and .nfg files) inside the catalog are correctly bundled during installation.

As a developer, this means you will need to reinstall the package (e.g., passing pip install .) for any new game files or internal catalog changes to be reflected in the pygambit module.

Add new game files#

You can add games to the catalog saved in a valid representation format. Currently supported representations are:

  • .efg for extensive form games

  • .nfg for normal form games

  1. Create the game file:

    Use either pygambit, the Gambit CLI or GUI to create 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>`_

  2. Add the game file:

    Create a new branch in the gambit repo. Add your new game file(s) inside the catalog dir and commit them.

  3. Update the catalog:

    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.

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

    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.

    Warning

    Make sure you commit all changed files e.g. run git add --all before committing and pushing.