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

Important

When updating the catalog, changes can be viewed by inspecting the documentation build generated by a pull request. You can also test changes locally. It can be helpful when doing so to perform an editable install of pygambit available in your Python environment. Note that for general edits to the codebase non-editable developer install is better to pick up changes in the C++ code as well as Python.

pip install -e ".[doc]"

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. Add the game(s) to the repo:

   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")
   

   Note

   For extensive form games, you may optionally commit a curated .ef file alongside the .efg (e.g. catalog/source/game.ef). When present, update.py will use this file directly as input to DrawTree instead of auto-generating the layout from the .efg, preserving any hand-tuned layout. Consult the DrawTree docs for the .ef format.

   Layout variants: To display multiple layout variants on the catalog page (rendered as clickable tabs), commit additional .ef files using the {slug}__{label}.ef naming convention (double underscore separator), e.g.:

   catalog/example/game.ef          # primary (tab label "Default")
   catalog/example/game__wide.ef    # additional (tab label "Wide")
   

   The label shown on each tab is derived automatically from the filename suffix: underscores are replaced by spaces and the result is title-cased (e.g. __very_wide → “Very Wide”).

3. Update the build files:

   Ensure you have installed the package in editable mode to automatically pick up the new game file(s) in the pygambit.catalog module without reinstalling each time. 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 to customise the visualisation parameters for your game(s), edit build_support/catalog/draw_tree_settings.yaml. Add an entry under overrides keyed by your game’s exact slug, or by a shared prefix (e.g. the author-year folder name) to apply settings to all games from that source. More specific entries (longer keys) take precedence over shorter ones. Consult the DrawTree docs for available settings.

   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

   • If haven’t done an editable install of pygambit in your python environment, you’ll need to re-install it before running the update script to include new games in the catalog module.

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

4. [Optional] Test your updates to the documentation locally:

   The previous step will (re)build your local copy of the Gambit Catalog RST page used by the documentation. You should then build the docs in the usual way. Open the catalog page at doc/_build/html/catalog.html to view your changes. Iterate steps 2-4 as required.

5. 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/draw_tree_settings.yaml, build_support/catalog/update.py and build_support/catalog/catalog.am are included.

   Important

   Even if you already checked the local docs build, ensure the Catalog page on the ReadTheDocs preview build on the pull request looks right.