flyplays 0.1.0__tar.gz

flyplays-0.1.0/GUIDE.md

@@ -0,0 +1,210 @@
+# Adding a new game
+
+This guide takes you from nothing to a fly brain playing your game, and filmed. There are three ways in,
+from least work to most control:
+
+| way | you write | the fly sees | good for |
+|---|---|---|---|
+| **1. Any web game by URL** | nothing (one command) | moving pixels, plus an optional target colour | trying a game in a minute |
+| **2. Your own Python game** | one class, 6 methods | exactly what you tell it | new games, experiments |
+| **3. A web game, properly** | a class plus a few lines of JavaScript | real positions read from the page | the best play on a web game |
+
+Whatever the way, the fly is the same. Things in the game drive its visual neurons, and its descending neurons
+press the keys. Nothing is trained.
+
+---
+
+## The 3 ideas
+
+**1. Time only moves when flyplays says so.** Every brain step (20 ms of fly time by default), flyplays calls
+`tick(dt)` and the game moves on by exactly `dt`. Between calls the game must stand still. The fly's thinking
+takes as long as it takes, the game still plays at its own speed, and **a seed always replays the same game**.
+
+**2. The fly sees `Thing`s, not pixels.** Each step, `sense()` returns what's around the player:
+
+```python
+Thing(bearing=-0.3, size=0.12, kind="target", key="sugar")
+```
+
+- `bearing`: radians from straight ahead, positive to the right and negative to the left. The fly sees about
+  ±165°; only straight behind is blind.
+- `size`: how big it looks, in radians. For something of radius `r` at distance `d`, that's `2*atan(r/d)`.
+  The helper `self.thing_at(dx, ahead, radius, kind, key)` computes both from screen coordinates.
+- `kind`: `"target"` is something to go to. `"creature"` is something that can come at you. `"shot"` is a
+  projectile.
+- `key`: any stable id for the same object across steps. The fly needs it to notice something **growing**
+  (looming).
+
+**3. The fly answers with a `Decision`.** It has three yes/no actions, from its own neurons:
+
+- `d.left` and `d.right` come from the steering neurons (left minus right over `threshold` Hz).
+- `d.escape` comes from the escape neurons (over `escape` Hz).
+
+You also get `d.turn_hz` (right minus left, for analog turning) and `d.escape_side` (`"L"` or `"R"`, whichever
+side scared it). You decide what each action does in your game.
+
+### What does "ahead" mean in my game?
+
+| game view | the fly faces | "left" means | bearing of an object at screen (x, y) |
+|---|---|---|---|
+| top-down (the player moves around) | the player's heading | turn left | rotate (x−px, py−y) into the heading |
+| top-down, fixed (it moves left/right) | up the screen | move left | `thing_at(x - px, py - y, r)` |
+| side-scroller | right, into the level | **up** (its left eye looks at the top of the screen) | `thing_at(y - py, x - px, r)` (below the player = its right) |
+| first person | into the screen | turn left | the angle off the view centre |
+
+For a side-scroller, "turn left" equals "up". That's how the fly plays Flappy: a gap above drives its left eye,
+and its left steering neurons flap.
+
+---
+
+## Way 1: any web game by URL
+
+```bash
+pip install "flyplays[web]"
+flyplays install-browser
+flyplays web https://example.com/game \
+    --keys left=ArrowLeft,right=ArrowRight,escape=Space \
+    --player 0.5,0.85 --facing up --seconds 30 --clip try.mp4
+```
+
+| option | meaning |
+|---|---|
+| `--keys` | which key each action presses. `escape` taps by default and `left`/`right` are held; add `:tap` or `:hold` to change that (`left=Space:tap`) |
+| `--player x,y` | where the player is, as fractions of the screen (0,0 is the top left) |
+| `--facing` | `up` for top-down games, `right` for side-scrollers |
+| `--target-color` | the colour of things to go to (coins, food), e.g. `#ffd700` |
+| `--start-keys` | keys pressed once to start the game (default `Space`) |
+| `--size w,h` | the browser window |
+
+Anything that moves on screen is a `creature`, and things in the target colour are `target`s. The page can't tell
+flyplays when you lose, so the score is the seconds played. It's slower than the other ways because it takes a
+screenshot every step; the clip still plays at real speed.
+
+Some games don't fit: ones that keep time with Web Audio, workers or a server won't freeze between steps.
+
+## Way 2: your own Python game
+
+The complete example is [`examples/03_my_first_game.py`](examples/03_my_first_game.py). Here it is step by step.
+
+```python
+import math
+import numpy as np
+from flyplays import Decision, Game, State, play
+
+class SugarRush(Game):
+    name = "sugar"                                  # shown in results
+    title = "A REAL FLY BRAIN HUNTS FOR SUGAR"      # the banner on clips
+    score_name = "sugar"
+
+    def start(self, seed):                          # 1. set up a fresh game; use the seed for all randomness
+        self.rng = np.random.default_rng(seed)
+        self.x, self.y, self.heading = 240, 240, 0.0
+        self.score, self.time_left = 0, 30.0
+        self.sugar = (100.0, 100.0)
+
+    def tick(self, dt):                             # 2. move the game on by exactly dt seconds
+        self.time_left -= dt
+        self.x += math.sin(self.heading) * 60 * dt
+        self.y -= math.cos(self.heading) * 60 * dt
+        if math.hypot(self.sugar[0] - self.x, self.sugar[1] - self.y) < 20:
+            self.score += 1
+            self.sugar = (float(self.rng.uniform(40, 440)), float(self.rng.uniform(40, 440)))
+        return State(alive=self.time_left > 0, score=self.score)
+
+    def sense(self):                                # 3. what the fly sees, from where it stands
+        dx, dy = self.sugar[0] - self.x, self.y - self.sugar[1]
+        right = dx * math.cos(self.heading) - dy * math.sin(self.heading)
+        ahead = dx * math.sin(self.heading) + dy * math.cos(self.heading)
+        return [self.thing_at(right, ahead, 10, kind="target", key="sugar")]
+
+    def act(self, d: Decision):                     # 4. the fly's decision -> your controls
+        self.heading += math.radians(2) * (d.right - d.left)
+
+    def frame(self):                                # 5. (for clips) the screen, an RGB numpy array
+        ...
+
+print(play(SugarRush(), seconds=30))
+```
+
+Run it from the command line by saving it as `sugar.py` and running `flyplays play sugar:SugarRush --clip sugar.mp4`
+from the same folder.
+
+**Tips**
+
+- Put **all** randomness on `self.rng` from the seed. Then a good game can be replayed and filmed.
+- Keep `act()` dumb. It maps actions to controls and nothing else. Don't add "if the sugar is left, go left":
+  that's your rule, not the fly's, and it makes the result meaningless.
+- `Tap(refractory)` from `flyplays` gives you one press, then a rest (a flap, a jump, a shot).
+- `frame()` can return any size. Clips scale it to fit.
+
+## Way 3: a web game, properly
+
+Subclass `WebGame` and read real positions from the page with a little JavaScript. The fly then sees the exact
+objects instead of guessing from pixels. That's how the built-in Flappy works; see
+[`src/flyplays/games/flappy.py`](src/flyplays/games/flappy.py).
+
+```python
+from flyplays.games.web import WebGame, Keys
+
+class MyWebGame(WebGame):
+    url = "https://example.com/game/"
+    viewport = {"width": 800, "height": 600}
+
+    def ready(self, seed):                    # the page has loaded: start the game
+        self.page.keyboard.press("Space")
+        self.keys = Keys(self.page, {"left": "ArrowLeft", "right": "ArrowRight", "escape": "Space"})
+        return self.read()
+
+    def read(self):                           # called every step: pull what you need out of the page
+        return self.page.evaluate("""() => ({
+            alive: !window.gameOver, score: window.score,
+            px: player.x, py: player.y,
+            enemies: enemies.map(e => ({x: e.x, y: e.y, r: e.r, id: e.id}))
+        })""")
+
+    def sense(self):
+        s = self.state                        # what read() returned this step
+        return [self.thing_at(e["x"] - s["px"], s["py"] - e["y"], e["r"], "creature", e["id"])
+                for e in s["enemies"]]
+
+    def act(self, d):
+        self.keys(d, 0.02)
+```
+
+flyplays freezes the page's time for you. Date, timers, `requestAnimationFrame` and CSS animations only move
+when the game ticks. `Math.random` is seeded, and requests to other sites (analytics, ads) are blocked.
+
+---
+
+## Tuning (honestly)
+
+The interface has a few knobs. The brain itself has none. These live in `flyplays.fly.DEFAULT`; set them per
+game with `settings = {...}` on your class, or per run with `--set threshold=8`.
+
+| setting | what it does |
+|---|---|
+| `target` | how hard a `target` drives LC10a |
+| `chase`, `chase_gain`, `loom_gain`, `threat`, `threat_max` | how a `creature` drives LC10a, LPLC2 and LC4 |
+| `shot_gain` | how a `shot` drives LPLC1 |
+| `spread` | how far off-centre one eye gets all of a thing |
+| `threshold` | steering Hz (left minus right) that counts as a press |
+| `escape` | escape-neuron Hz that counts as `escape` |
+| `rate_tau` | smoothing of the output rates |
+
+Also try `--flies 8`, where 8 flies with their own noise vote, and `--dt 0.01` for faster brain steps.
+
+**Check it's the brain.** Run your game three ways, like
+[`examples/06_is_it_really_the_brain.py`](examples/06_is_it_really_the_brain.py):
+
+- as is;
+- blind: `sense()` returns `[]`;
+- swapped: left and right crossed in `act()`.
+
+If the fly doesn't beat blind, your mapping isn't reaching it. Check the bearing signs first.
+
+## Sharing your game
+
+Add it to `src/flyplays/games/`, register it in `games/__init__.py`, and open a pull request with:
+
+- a clip;
+- the brain vs blind vs swapped numbers.

flyplays-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alextitonis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flyplays-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include GUIDE.md
+recursive-include examples *.py
+recursive-include tests *.py
+prune media

flyplays-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: flyplays
+Version: 0.1.0
+Summary: A real fruit fly brain (the complete 166,700-neuron connectome) plays games: Flappy Bird, Doom, any web game, or your own. Nothing trained.
+Author: alextitonis
+License-Expression: MIT
+Project-URL: Homepage, https://flyaiworld.com
+Project-URL: Source, https://github.com/alextitonis/fly.ai/tree/main/flyplays
+Keywords: connectome,drosophila,fruit fly,games,spiking neural network,flappy bird,doom,neuroscience
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flybrain>=0.1.0
+Requires-Dist: numpy>=2.0
+Requires-Dist: scipy>=1.13
+Requires-Dist: pillow>=10.1
+Requires-Dist: imageio-ffmpeg>=0.5
+Provides-Extra: web
+Requires-Dist: playwright>=1.45; extra == "web"
+Provides-Extra: doom
+Requires-Dist: vizdoom>=1.2; extra == "doom"
+Provides-Extra: gpu
+Requires-Dist: flybrain[gpu]; extra == "gpu"
+Provides-Extra: all
+Requires-Dist: playwright>=1.45; extra == "all"
+Requires-Dist: vizdoom>=1.2; extra == "all"
+Dynamic: license-file
+
+# flyplays: a real fruit fly brain plays games
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/alextitonis/fly.ai/main/flyplays/media/fruit.gif" width="260" alt="A fly brain plays Fruit Fall">
+  <img src="https://raw.githubusercontent.com/alextitonis/fly.ai/main/flyplays/media/doom.gif" width="260" alt="A fly brain plays Doom">
+</p>
+
+Scientists mapped every neuron and every connection in a fruit fly's brain: **166,700 neurons, 25.6 million
+connections**. `flyplays` runs that map as a spiking network and lets it play games. It plays Flappy Bird, Doom,
+a little game made for flies, any web game by its URL, or a game you write yourself.
+
+**Nothing is trained and nothing is scripted.** The game shows up on the fly's own visual neurons. The fly's own
+steering and escape neurons press the keys. Everything in between is the real wiring.
+
+```bash
+pip install flyplays
+flyplays play fruit --clip fruit.mp4
+```
+
+The first run downloads the brain (about 260 MB, once). It runs on a normal laptop CPU, faster with a CUDA GPU
+(`pip install "flyplays[gpu]"`).
+
+## Is it really the brain?
+
+Fruit Fall, 10 games of 40 seconds each (seeds 101–110):
+
+| the fly | fruit caught per game | survived the swatter |
+|---|---|---|
+| **as it is** | **6.4** | 6 / 10 |
+| blind (it sees nothing) | 1.6 | 1 / 10 |
+| left and right outputs crossed | 0.0 | 0 / 10 |
+
+When it sees, it catches four times as much fruit as when it can't. Cross its left and right wires and it catches
+nothing at all. The wiring itself is doing the work. Check it yourself: `python examples/06_is_it_really_the_brain.py`.
+
+It's not a good gamer, and that's part of the fun. It usually gets a few pipes in Flappy Bird and a few kills in
+Doom, then panics.
+
+## Games
+
+```bash
+flyplays list
+flyplays play fruit                              # Fruit Fall: catch fruit, dodge the swatter (pure Python)
+flyplays play flappy --clip flappy.mp4           # Flappy Bird, on the open-source Floppy Bird site   [web]
+flyplays play doom --opt level=e1m1              # Freedoom through ViZDoom                           [doom]
+flyplays play my_game:MyGame                     # your own game (see GUIDE.md)
+flyplays web <url> --keys left=ArrowLeft,right=ArrowRight,escape=Space --player 0.5,0.85   # any web game  [web]
+```
+
+Extras: `pip install "flyplays[web]"`, then `flyplays install-browser` once, for web games. Use
+`pip install "flyplays[doom]"` for Doom, or `"flyplays[all]"` for everything.
+
+Useful options:
+
+- `--seed 1-20` plays 20 different games. A seed always replays the same game.
+- `--clip out.mp4` films it.
+- `--flies 8` makes 8 flies vote. This is best on a GPU.
+- `--set threshold=8` changes an interface setting.
+
+## Clips
+
+`--clip` (or `play(..., clip="x.mp4")`) films a 9:16 video at 1080×1920 and 50 fps, ready for TikTok, Shorts
+or Reels. The game is on top and the fly's brain is underneath:
+
+- what each eye sees;
+- the decision neurons;
+- a live strip of spikes from 166,700 neurons.
+
+The clip always plays at the game's real speed, even when the brain thinks slower than real time.
+
+## How the fly plays
+
+```
+the game ──► Things (where, how big) ──► the fly's visual neurons ──► 166,700-neuron connectome ──► descending neurons ──► keys
+```
+
+**What goes in.** The game describes what's around the player as `Thing`s, each with a bearing and a size. Each
+one drives the fly's identified visual neurons on the side it's on. A fly sees almost all the way round.
+
+| kind | neurons | in a real fly |
+|---|---|---|
+| `target` | LC10a | what a male fly chases |
+| `creature` | LC10a, LPLC2, LC4 | chase it while it's in view, looming as it comes closer, fast looming when it's close |
+| `shot` | LPLC1 | small objects coming at you |
+
+**What comes out.** Two groups of descending neurons (brain → body) are read as firing rates:
+
+- **steering**: DNa02, DNg111 and DNae002. Left minus right gives `left` or `right`.
+- **escape**: DNp01 (the giant fiber), DNp02, DNp04 and DNp11. They give `escape`, which in a real fly is the
+  escape jump.
+
+The game turns those three actions into its keys. In Flappy, "turn left" means up, which means flap. In Doom,
+an escape burst pulls the trigger.
+
+The only knobs are the interface: how strongly things drive the eye neurons, and how many spikes count as a press
+(`flyplays.fly.DEFAULT`). The brain itself is never changed.
+
+## Your own game
+
+A game is a class with six methods: `start`, `tick`, `sense`, `act`, `frame` and `close`. See **[GUIDE.md](GUIDE.md)**
+for a step-by-step walk-through, and [`examples/`](examples) for working code:
+
+| example | what it shows |
+|---|---|
+| `01_quickstart.py` | play a game in 3 lines |
+| `02_film_a_clip.py` | play several seeds, film the best |
+| `03_my_first_game.py` | a complete new game in about 50 lines |
+| `04_any_web_game.py` | any web game, seen through its pixels |
+| `05_doom.py` | Doom |
+| `06_is_it_really_the_brain.py` | the brain vs blind vs swapped controls |
+
+```python
+from flyplays import Game, State, play
+
+class MyGame(Game):
+    def start(self, seed): ...
+    def tick(self, dt): ...      # move the game on by dt seconds -> State(alive, score)
+    def sense(self): ...         # what the fly sees -> [Thing(bearing, size, kind)]
+    def act(self, d): ...        # d.left / d.right / d.escape -> your controls
+    def frame(self): ...         # the screen as an RGB array (for clips)
+
+print(play(MyGame(), seconds=30, clip="mine.mp4"))
+```
+
+## Where the brain comes from
+
+The connectome is MaleCNS v1.0, the complete central nervous system of a male *Drosophila melanogaster*. The
+spiking network comes from [`flybrain`](https://pypi.org/project/flybrain/). It's made by
+[fly.ai](https://flyaiworld.com), where the same brain also trades from its own wallet.
+
+Web games: only automate games you're allowed to automate, and never games that post to public leaderboards.
+The built-in Flappy game plays Nebez Briefkani's open-source [Floppy Bird](https://github.com/nebez/floppybird).
+Doom is [Freedoom](https://freedoom.github.io/) through [ViZDoom](https://github.com/Farama-Foundation/ViZDoom).
+
+MIT license.

flyplays-0.1.0/README.md

@@ -0,0 +1,135 @@
+# flyplays: a real fruit fly brain plays games
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/alextitonis/fly.ai/main/flyplays/media/fruit.gif" width="260" alt="A fly brain plays Fruit Fall">
+  <img src="https://raw.githubusercontent.com/alextitonis/fly.ai/main/flyplays/media/doom.gif" width="260" alt="A fly brain plays Doom">
+</p>
+
+Scientists mapped every neuron and every connection in a fruit fly's brain: **166,700 neurons, 25.6 million
+connections**. `flyplays` runs that map as a spiking network and lets it play games. It plays Flappy Bird, Doom,
+a little game made for flies, any web game by its URL, or a game you write yourself.
+
+**Nothing is trained and nothing is scripted.** The game shows up on the fly's own visual neurons. The fly's own
+steering and escape neurons press the keys. Everything in between is the real wiring.
+
+```bash
+pip install flyplays
+flyplays play fruit --clip fruit.mp4
+```
+
+The first run downloads the brain (about 260 MB, once). It runs on a normal laptop CPU, faster with a CUDA GPU
+(`pip install "flyplays[gpu]"`).
+
+## Is it really the brain?
+
+Fruit Fall, 10 games of 40 seconds each (seeds 101–110):
+
+| the fly | fruit caught per game | survived the swatter |
+|---|---|---|
+| **as it is** | **6.4** | 6 / 10 |
+| blind (it sees nothing) | 1.6 | 1 / 10 |
+| left and right outputs crossed | 0.0 | 0 / 10 |
+
+When it sees, it catches four times as much fruit as when it can't. Cross its left and right wires and it catches
+nothing at all. The wiring itself is doing the work. Check it yourself: `python examples/06_is_it_really_the_brain.py`.
+
+It's not a good gamer, and that's part of the fun. It usually gets a few pipes in Flappy Bird and a few kills in
+Doom, then panics.
+
+## Games
+
+```bash
+flyplays list
+flyplays play fruit                              # Fruit Fall: catch fruit, dodge the swatter (pure Python)
+flyplays play flappy --clip flappy.mp4           # Flappy Bird, on the open-source Floppy Bird site   [web]
+flyplays play doom --opt level=e1m1              # Freedoom through ViZDoom                           [doom]
+flyplays play my_game:MyGame                     # your own game (see GUIDE.md)
+flyplays web <url> --keys left=ArrowLeft,right=ArrowRight,escape=Space --player 0.5,0.85   # any web game  [web]
+```
+
+Extras: `pip install "flyplays[web]"`, then `flyplays install-browser` once, for web games. Use
+`pip install "flyplays[doom]"` for Doom, or `"flyplays[all]"` for everything.
+
+Useful options:
+
+- `--seed 1-20` plays 20 different games. A seed always replays the same game.
+- `--clip out.mp4` films it.
+- `--flies 8` makes 8 flies vote. This is best on a GPU.
+- `--set threshold=8` changes an interface setting.
+
+## Clips
+
+`--clip` (or `play(..., clip="x.mp4")`) films a 9:16 video at 1080×1920 and 50 fps, ready for TikTok, Shorts
+or Reels. The game is on top and the fly's brain is underneath:
+
+- what each eye sees;
+- the decision neurons;
+- a live strip of spikes from 166,700 neurons.
+
+The clip always plays at the game's real speed, even when the brain thinks slower than real time.
+
+## How the fly plays
+
+```
+the game ──► Things (where, how big) ──► the fly's visual neurons ──► 166,700-neuron connectome ──► descending neurons ──► keys
+```
+
+**What goes in.** The game describes what's around the player as `Thing`s, each with a bearing and a size. Each
+one drives the fly's identified visual neurons on the side it's on. A fly sees almost all the way round.
+
+| kind | neurons | in a real fly |
+|---|---|---|
+| `target` | LC10a | what a male fly chases |
+| `creature` | LC10a, LPLC2, LC4 | chase it while it's in view, looming as it comes closer, fast looming when it's close |
+| `shot` | LPLC1 | small objects coming at you |
+
+**What comes out.** Two groups of descending neurons (brain → body) are read as firing rates:
+
+- **steering**: DNa02, DNg111 and DNae002. Left minus right gives `left` or `right`.
+- **escape**: DNp01 (the giant fiber), DNp02, DNp04 and DNp11. They give `escape`, which in a real fly is the
+  escape jump.
+
+The game turns those three actions into its keys. In Flappy, "turn left" means up, which means flap. In Doom,
+an escape burst pulls the trigger.
+
+The only knobs are the interface: how strongly things drive the eye neurons, and how many spikes count as a press
+(`flyplays.fly.DEFAULT`). The brain itself is never changed.
+
+## Your own game
+
+A game is a class with six methods: `start`, `tick`, `sense`, `act`, `frame` and `close`. See **[GUIDE.md](GUIDE.md)**
+for a step-by-step walk-through, and [`examples/`](examples) for working code:
+
+| example | what it shows |
+|---|---|
+| `01_quickstart.py` | play a game in 3 lines |
+| `02_film_a_clip.py` | play several seeds, film the best |
+| `03_my_first_game.py` | a complete new game in about 50 lines |
+| `04_any_web_game.py` | any web game, seen through its pixels |
+| `05_doom.py` | Doom |
+| `06_is_it_really_the_brain.py` | the brain vs blind vs swapped controls |
+
+```python
+from flyplays import Game, State, play
+
+class MyGame(Game):
+    def start(self, seed): ...
+    def tick(self, dt): ...      # move the game on by dt seconds -> State(alive, score)
+    def sense(self): ...         # what the fly sees -> [Thing(bearing, size, kind)]
+    def act(self, d): ...        # d.left / d.right / d.escape -> your controls
+    def frame(self): ...         # the screen as an RGB array (for clips)
+
+print(play(MyGame(), seconds=30, clip="mine.mp4"))
+```
+
+## Where the brain comes from
+
+The connectome is MaleCNS v1.0, the complete central nervous system of a male *Drosophila melanogaster*. The
+spiking network comes from [`flybrain`](https://pypi.org/project/flybrain/). It's made by
+[fly.ai](https://flyaiworld.com), where the same brain also trades from its own wallet.
+
+Web games: only automate games you're allowed to automate, and never games that post to public leaderboards.
+The built-in Flappy game plays Nebez Briefkani's open-source [Floppy Bird](https://github.com/nebez/floppybird).
+Doom is [Freedoom](https://freedoom.github.io/) through [ViZDoom](https://github.com/Farama-Foundation/ViZDoom).
+
+MIT license.

flyplays-0.1.0/examples/01_quickstart.py

@@ -0,0 +1,12 @@
+"""The shortest way in: a real fruit fly brain plays Fruit Fall for 30 seconds.
+
+    pip install flyplays
+    python examples/01_quickstart.py
+
+The first run downloads the brain (~260 MB, once). No browser, no GPU needed.
+"""
+from flyplays import play
+from flyplays.games.fruit import FruitFall
+
+result = play(FruitFall(), seed=1, seconds=30)
+print(result)            # fruit seed 1: score 9 in 30.0 s (still going; left ..., right ..., escape ...)

flyplays-0.1.0/examples/02_film_a_clip.py

@@ -0,0 +1,21 @@
+"""Film the fly playing: a 9:16 video (1080x1920, 50 fps) with the game on top and the fly's neurons
+underneath - the eye neurons, the decision neurons and a live strip of spikes. Ready for TikTok / Shorts.
+
+    python examples/02_film_a_clip.py
+
+Play a few seeds and keep the best one: every seed is a different game.
+"""
+from flyplays import Fly, play
+from flyplays.games.fruit import FruitFall
+
+fly = Fly()                                   # load the brain once, reuse it for every game
+best = None
+for seed in range(1, 6):
+    r = play(FruitFall(), fly, seed=seed, seconds=25)
+    print(r)
+    if best is None or r.score > best.score:
+        best = r
+
+# a seed replays the same game, so film the best one
+clip = play(FruitFall(), fly, seed=best.seed, seconds=25, clip=f"fruit-seed{best.seed}.mp4")
+print("filmed:", clip.clip)

flyplays-0.1.0/examples/03_my_first_game.py

@@ -0,0 +1,70 @@
+"""Your own game in ~50 lines: Sugar Rush. Sugar cubes appear around the fly; it has to walk to them.
+
+    python examples/03_my_first_game.py            # plays 3 games
+
+Copied to a file named sugar.py, the command line plays it too:
+
+    flyplays play sugar:SugarRush --clip sugar.mp4
+
+A game only has to: start, move time on (tick), say what the fly sees (sense), and turn the fly's decision
+into moves (act). frame() is only needed for clips. See GUIDE.md for the walk-through.
+"""
+import math
+
+import numpy as np
+
+from flyplays import Decision, Fly, Game, State, play
+
+W, H = 480, 480
+
+
+class SugarRush(Game):
+    name = "sugar"
+    title = "A REAL FLY BRAIN HUNTS FOR SUGAR"
+    score_name = "sugar"
+
+    def start(self, seed):
+        self.rng = np.random.default_rng(seed)
+        self.x, self.y, self.heading = W / 2, H / 2, 0.0      # heading: radians, 0 = up the screen
+        self.score, self.time_left = 0, 30.0
+        self.sugar = self._new_sugar()
+
+    def _new_sugar(self):
+        return (float(self.rng.uniform(40, W - 40)), float(self.rng.uniform(40, H - 40)))
+
+    def tick(self, dt):
+        self.time_left -= dt
+        self.x = float(np.clip(self.x + math.sin(self.heading) * 60 * dt, 10, W - 10))   # it always walks forward
+        self.y = float(np.clip(self.y - math.cos(self.heading) * 60 * dt, 10, H - 10))
+        if math.hypot(self.sugar[0] - self.x, self.sugar[1] - self.y) < 20:
+            self.score += 1
+            self.sugar = self._new_sugar()
+        return State(alive=self.time_left > 0, score=self.score)
+
+    def sense(self):
+        # where the sugar is, seen from the fly: rotate into the fly's own frame (its heading = "ahead")
+        dx, dy = self.sugar[0] - self.x, self.y - self.sugar[1]
+        right = dx * math.cos(self.heading) - dy * math.sin(self.heading)
+        ahead = dx * math.sin(self.heading) + dy * math.cos(self.heading)
+        return [self.thing_at(right, ahead, 10, kind="target", key="sugar")]
+
+    def act(self, d: Decision):
+        # the steering neurons turn the fly: 2 degrees per step, the way they said
+        self.heading += math.radians(2) * ((1 if d.right else 0) - (1 if d.left else 0))
+
+    def frame(self):
+        from PIL import Image, ImageDraw
+        img = Image.new("RGB", (W, H), (245, 240, 225))
+        d = ImageDraw.Draw(img)
+        sx, sy = self.sugar
+        d.rectangle([sx - 10, sy - 10, sx + 10, sy + 10], fill=(255, 255, 255), outline=(180, 170, 150), width=2)
+        hx, hy = self.x + math.sin(self.heading) * 16, self.y - math.cos(self.heading) * 16
+        d.ellipse([self.x - 10, self.y - 10, self.x + 10, self.y + 10], fill=(40, 40, 40))
+        d.ellipse([hx - 6, hy - 6, hx + 6, hy + 6], fill=(200, 30, 30))
+        return np.asarray(img)
+
+
+if __name__ == "__main__":
+    fly = Fly()
+    for seed in (1, 2, 3):
+        print(play(SugarRush(), fly, seed=seed, seconds=30))

flyplays-0.1.0/examples/04_any_web_game.py

@@ -0,0 +1,26 @@
+"""Any web game, with no code for the game itself: the fly sees only the pixels.
+
+    pip install "flyplays[web]" && flyplays install-browser
+    python examples/04_any_web_game.py
+
+Same thing from the command line:
+
+    flyplays web https://nebezb.com/floppybird/ --keys left=Space:tap --player 0.3,0.45 --facing right \
+                 --size 480,720 --seconds 20 --clip web.mp4
+
+What the fly sees: anything that moves is a "creature" (it looms as it comes closer); with target_color, things
+of that colour are "targets" to go to. Tell it where the player is (fractions of the screen) and which way it
+faces: "up" for top-down games, "right" for side-scrollers. Map the fly's three actions to the game's keys.
+
+It takes a screenshot every brain step, so it plays slower than real time - the clip still plays at real speed.
+Only use games you're allowed to automate, and never games that post to public leaderboards.
+"""
+from flyplays import play
+from flyplays.games.web import PixelGame
+
+game = PixelGame(
+    "https://nebezb.com/floppybird/",              # Floppy Bird, Nebez Briefkani's open-source Flappy remake
+    keys={"left": "Space:tap"},                    # side view: "turn left" = up = flap
+    player=(0.3, 0.45), facing="right", viewport=(480, 720),
+)
+print(play(game, seed=1, seconds=20, clip="web.mp4"))