gridgames

Grid games for experiments. A game is two plain-text files, a rules file and a level file. gridgames plays it in PsychoPy, for example in an MEG session.

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.

Check the install:

python -m gridgames games                     # lists the built-in games
python -m gridgames play zelda_vgfmri4        # arrows, space; Esc quits

Use

from gridgames import vgdl

game = vgdl.load("zelda_vgfmri4", level=0, seed=1)   # built-in game
game = vgdl.load("games/mygame", level=2)            # your own folder
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). python -m gridgames check games/mygame lists each mistake with its file and line.

In PsychoPy, gridgames.psychopy.Player draws a game in your own frame loop. It counts game time in frames and reports each frame's event (block start, win, lose, restart, block end) and a Gray-coded sync counter, so your script can send its own triggers. The package has no hardware code.

Credits

The built-in study games (Bait, Zelda, Lemmings, _vgfmri4) are translations of the games in botcs/reason-to-play (MIT); see THIRD_PARTY.md. gridgames itself is MIT.