Metadata-Version: 2.4
Name: gridgames
Version: 0.1.0
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering
Requires-Dist: numpy
Requires-Dist: pytest ; extra == 'test'
Provides-Extra: test
License-File: LICENSE
License-File: THIRD_PARTY.md
Summary: Grid games for experiments: write a game in two text files, play it in PsychoPy.
Keywords: psychopy,vgdl,meg,experiment,games
Author: Younes Strittmatter
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# 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

```python
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](https://github.com/botcs/reason-to-play) (MIT); see
`THIRD_PARTY.md`. gridgames itself is MIT.

