gridgames

Grid games for experiments. A game is two plain-text files, a rules file and a level file. gridgames loads it, steps it and gives its picture; showing it (in PsychoPy, a browser, ...) is your program's part.

Install

Install into the Python that PsychoPy uses:

• in PsychoPy: Tools → Plugins/Packages manager → Packages, search gridgames, Install;
• or in a terminal: <PsychoPy's python> -m pip install gridgames (on Windows usually "C:\Program Files\PsychoPy\python.exe").

One wheel per platform (Windows, macOS, Linux) works on every Python from 3.8 on. No compiler is needed, and the only dependency is numpy.

gridgames has no built-in games: every game is loaded from its files. Example games to try or copy are a separate, optional package:

pip install gridgames-examples        # or: pip install "gridgames[examples]"
python -m gridgames_examples copy zelda_vgfmri4 games
python -m gridgames play games/zelda_vgfmri4      # arrows, space; Esc quits

Use

from gridgames import vgdl

game = vgdl.load("games/mygame", level=2, seed=1)    # a game folder
maze = vgdl.rules("rules/maze.vgdl")                 # or rules and levels
game = maze.load("levels/hard.txt")                  # from different places
game.step("up")            # up, down, left, right, use, none
game.image(cell=8)         # numpy array (H, W, 3), uint8
game.score, game.outcome   # outcome: "win", "lose" or None

A game folder contains mygame.vgdl (the rules), mygame_lvl0.txt, mygame_lvl1.txt, ... (the levels), and optionally mygame.skin (the colours). The levels next to the rules are numbered; any other level file can be loaded with the same rules. python -m gridgames check games/mygame lists each mistake with its file and line.

gridgames has no screen, keyboard or experiment code. In PsychoPy, show game.image() (pass it as a PIL image, Image.fromarray(pixels, "RGB"), to keep its exact colours) in an ImageStim with interpolate=False, and step the game 15 times a second. python -m gridgames play (needs PsychoPy) is a window to try a game.

License

MIT. The example games in gridgames-examples carry their own notices.