Metadata-Version: 2.4
Name: gridgames
Version: 0.5.1
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: gridgames-examples ; extra == 'examples'
Requires-Dist: pytest ; extra == 'test'
Provides-Extra: examples
Provides-Extra: test
License-File: LICENSE
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 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

```python
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.

## Puzzles

A puzzle (ARC-style) is a hidden rule, examples of it, and questions about
it: one text file, `mirror.arc`. Nobody writes the rule down; the file
holds grids (digits are ARC's ten colours) and the right answers:

```
example
    100
    120
    ->
    001
    021

judge follows
    300
    ->
    003

judge breaks
    300
    ->
    300
```

```python
from gridgames import arc

puzzle = arc.load("puzzles/mirror.arc")
puzzle.actions                  # ("continue",), then ("follows", "breaks")
puzzle.step("continue")         # returns what happened
for panel in puzzle.screen(aspect=16 / 9).panels:   # the grids, and where they go
    panel.image(cell=12)        # numpy array (H, W, 3), uint8
```

```
python -m gridgames check puzzles                # every .arc file in the folder
python -m gridgames play puzzles                 # space, then number keys; Esc quits
python -m gridgames convert task.json puzzles    # ARC's JSON -> .arc
```

