flyplays 0.1.0__py3-none-any.whl

flyplays/__init__.py

@@ -0,0 +1,19 @@
+"""flyplays: a real fruit fly brain plays games.
+
+The complete fruit fly connectome (166,700 neurons, from the `flybrain` package) sees the game and presses the
+keys. Nothing is trained and nothing is scripted.
+
+    from flyplays import play
+    from flyplays.games.fruit import FruitFall
+    print(play(FruitFall(), seed=1, seconds=30, clip="fruit.mp4"))
+
+Command line: `flyplays list`, `flyplays play fruit --clip fruit.mp4`, `flyplays web <url> --keys ...`.
+Write your own game: see GUIDE.md (a game is a class with six methods).
+"""
+from .fly import DEFAULT, Decision, Fly, Thing
+from .game import Game, State, Tap
+from .runner import Result, play
+
+__version__ = "0.1.0"
+
+__all__ = ["DEFAULT", "Decision", "Fly", "Thing", "Game", "State", "Tap", "Result", "play"]

flyplays/__main__.py

@@ -0,0 +1,109 @@
+"""flyplays command line.
+
+    flyplays list
+    flyplays play fruit [--seed 3] [--seconds 60] [--clip fruit.mp4]
+    flyplays play flappy --flies 8 --dt 0.01 --clip flappy.mp4
+    flyplays play doom --opt level=e1m1
+    flyplays play my_game:MyGame                      # your own game class
+    flyplays web https://example.com/game --keys left=ArrowLeft,right=ArrowRight,escape=Space \\
+                 --player 0.5,0.85 --facing up [--target-color "#ff3030"] [--clip web.mp4]
+    flyplays install-browser                          # once, for web games
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+
+
+def seeds(text: str) -> list[int]:
+    out = []
+    for part in str(text).split(","):
+        a, _, b = part.partition("-")
+        out += list(range(int(a), int(b or a) + 1))
+    return out
+
+
+def pairs(items, cast=float) -> dict:
+    out = {}
+    for kv in items or []:
+        for one in kv.split(","):
+            k, _, v = one.partition("=")
+            out[k.strip()] = cast(v) if cast else v
+    return out
+
+
+def value(v: str):
+    for f in (int, float):
+        try:
+            return f(v)
+        except ValueError:
+            pass
+    return {"true": True, "false": False}.get(v.lower(), v)
+
+
+def common(ap):
+    ap.add_argument("--seed", default="1", help="a seed, or a range like 1-10")
+    ap.add_argument("--seconds", type=float, default=60.0, help="stop after this much game time")
+    ap.add_argument("--until", type=float, help="stop shortly after reaching this score")
+    ap.add_argument("--clip", help="film to this .mp4 (9:16); with several seeds, {seed} is replaced")
+    ap.add_argument("--flies", type=int, default=1, help="flies voting (a brain batch; best on a GPU)")
+    ap.add_argument("--device", default="auto", help="auto | cpu | cuda")
+    ap.add_argument("--dt", type=float, help="brain step in seconds (default 0.02)")
+    ap.add_argument("--set", nargs="*", help="interface settings, e.g. threshold=8 escape=60 (see flyplays.fly.DEFAULT)")
+
+
+def run(game_factory, a, game_dt=None) -> None:
+    from .fly import Fly
+    from .runner import play
+    fly = Fly(flies=a.flies, device=a.device, dt=a.dt or game_dt)
+    for sd in seeds(a.seed):
+        clip = a.clip.replace("{seed}", str(sd)) if a.clip else None
+        r = play(game_factory(), fly, seed=sd, seconds=a.seconds, clip=clip, until=a.until, settings=pairs(a.set))
+        print(r, f"-> {r.clip}" if r.clip else "", flush=True)
+
+
+def main(argv=None) -> None:
+    ap = argparse.ArgumentParser(prog="flyplays", description="A real fruit fly brain plays games.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("list", help="the built-in games")
+    p = sub.add_parser("play", help="play a built-in game or your own (module:Class)")
+    p.add_argument("game")
+    p.add_argument("--opt", nargs="*", help="game options, e.g. level=e1m1 easy=true")
+    common(p)
+    w = sub.add_parser("web", help="play any web game, seen through its pixels")
+    w.add_argument("url")
+    w.add_argument("--keys", required=True, help="action=key pairs: left=ArrowLeft,right=ArrowRight,escape=Space "
+                                                 "(add :tap or :hold; escape taps, left/right hold by default)")
+    w.add_argument("--player", default="0.5,0.5", help="where the player is, as x,y fractions of the screen")
+    w.add_argument("--facing", default="up", choices=["up", "right"], help="up = top-down, right = side-scroller")
+    w.add_argument("--target-color", help="colour of things to go to, e.g. #ff3030")
+    w.add_argument("--start-keys", default="Space", help="keys pressed once to start the game (comma-separated)")
+    w.add_argument("--size", default="640,480", help="browser window, width,height")
+    common(w)
+    sub.add_parser("install-browser", help="download Chromium for web games (once)")
+    a = ap.parse_args(argv)
+
+    if a.cmd == "list":
+        from .games import GAMES
+        for name, (_, about) in GAMES.items():
+            print(f"  {name:8} {about}")
+        print("  web      any web game by URL: flyplays web <url> --keys ...")
+    elif a.cmd == "install-browser":
+        sys.exit(subprocess.call([sys.executable, "-m", "playwright", "install", "chromium"]))
+    elif a.cmd == "play":
+        from .games import load
+        cls = load(a.game)
+        opts = {k: value(v) for k, v in pairs(a.opt, cast=None).items()}
+        run(lambda: cls(**opts), a, getattr(cls, "dt", None))
+    elif a.cmd == "web":
+        from .games.web import PixelGame
+        px, py = (float(x) for x in a.player.split(","))
+        size = tuple(int(x) for x in a.size.split(","))
+        keys = pairs([a.keys], cast=None)
+        run(lambda: PixelGame(a.url, keys, (px, py), a.facing, a.target_color,
+                              tuple(k for k in a.start_keys.split(",") if k), size), a)
+
+
+if __name__ == "__main__":
+    main()

flyplays/fly.py

@@ -0,0 +1,185 @@
+"""The fly: what goes into the brain and what comes out.
+
+Everything between IN and OUT is the real fruit fly connectome (MaleCNS v1.0, 166,700 neurons) from
+`flybrain`, run as a spiking network. Nothing is trained and nothing is scripted: the only knobs are how
+strongly the game's objects drive the eye neurons and how many spikes count as a key press.
+
+IN - a game describes what is around the player as `Thing`s (where it is, how big it looks). Each one drives
+the fly's own identified visual neurons on the side it is on (a fly sees almost all the way round):
+
+    target    LC10a          the neurons a male fly uses to chase a target
+    creature  LC10a          chase it while it's in view...
+              LPLC2          ...looming neurons when it grows (it's coming at you)
+              LC4            ...fast-looming neurons when it's big (close)
+    shot      LPLC1          small objects coming at you
+
+OUT - two groups of descending neurons (brain -> body), read as firing rates:
+
+    steering  DNa02, DNg111, DNae002   left minus right turns the fly (LC10a drives them on its own side)
+    escape    DNp01 (the giant fiber), DNp02, DNp04, DNp11   the escape jump (LPLC2/LC4 drive them)
+
+A `Decision` says which of left / right / escape is over its threshold this step; the game turns that into keys.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+
+import numpy as np
+
+SEE = {"chase": ["LC10a"], "loom": ["LPLC2"], "threat": ["LC4"], "shot": ["LPLC1"]}
+STEER = ["DNa02", "DNg111", "DNae002"]
+ESCAPE = ["DNp01", "DNp02", "DNp04", "DNp11"]
+
+# Interface settings: how the game reaches the eye neurons and how spikes become keys. The brain itself is
+# never changed. A game can ship its own values (Game.settings) and you can override any of them.
+DEFAULT = {
+    "target": 1.0,      # LC10a volts for a `target` dead ahead (split between the eyes by bearing)
+    "chase": 0.6,       # LC10a volts while a `creature` is in view...
+    "chase_gain": 0.8,  # ...plus this much per radian of its size
+    "loom_gain": 25.0,  # LPLC2 volts per radian a `creature` grew since the last step
+    "threat": 0.25,     # radians: a `creature` this big (close) drives LC4 fully...
+    "threat_max": 0.8,  # ...with this many volts
+    "shot_gain": 25.0,  # LPLC1 volts per radian a `shot` grew since the last step
+    "cap": 0.8,         # most volts any input adds per step (a `target` may go up to `target`)
+    "spread": 0.35,     # radians off dead ahead at which one eye gets all of a thing
+    "rate_tau": 0.05,   # seconds: smoothing of the output firing rates
+    "threshold": 6.0,   # Hz of left-minus-right steering that counts as "left" (or right-minus-left: "right")
+    "escape": 90.0,     # Hz on the escape neurons (either side) that counts as "escape"
+}
+
+
+@dataclass
+class Thing:
+    """Something the fly can see, relative to the player.
+
+    bearing: radians from straight ahead, + = to the right, - = to the left. A fly sees about +-165 degrees.
+    size:    how big it looks, in radians (for an object of radius r at distance d: 2 * atan(r / d)).
+    kind:    "target" (something to go to), "creature" (something that can come at you) or "shot".
+    key:     a stable id across steps (any hashable), so the fly can tell it is growing (looming).
+    """
+    bearing: float
+    size: float = 0.1
+    kind: str = "creature"
+    key: object = None
+
+
+@dataclass
+class Decision:
+    """What the fly's descending neurons said this step."""
+    left: bool = False
+    right: bool = False
+    escape: bool = False
+    steer_hz: tuple = (0.0, 0.0)    # smoothed steering rates, left and right
+    escape_hz: tuple = (0.0, 0.0)   # smoothed escape rates, left and right
+
+    @property
+    def turn_hz(self) -> float:
+        """Right-minus-left steering rate: + turns right. For games with analog turning."""
+        return self.steer_hz[1] - self.steer_hz[0]
+
+    @property
+    def escape_side(self) -> str:
+        """The side whose escape neurons fire more ("L"/"R"): a real fly jumps away from that side."""
+        return "L" if self.escape_hz[0] >= self.escape_hz[1] else "R"
+
+    @property
+    def actions(self) -> set[str]:
+        return {a for a in ("left", "right", "escape") if getattr(self, a)}
+
+
+@dataclass
+class Fly:
+    """A fly brain that plays. `brain` is a flybrain.FlyBrain (made for you when left out).
+
+        fly = Fly()                       # CPU or GPU, picked for you
+        fly = Fly(flies=8, device="cuda") # 8 flies see the same screen and vote
+        d = fly.step([Thing(bearing=-0.2, size=0.1, kind="target")])
+    """
+    brain: object = None
+    settings: dict = field(default_factory=dict)
+    flies: int = 1
+    device: str = "auto"
+    dt: float | None = None
+
+    def __post_init__(self):
+        if self.brain is None:
+            from flybrain import FlyBrain
+            kw = {"device": self.device, "batch": self.flies}
+            if self.dt:
+                kw["dt"] = self.dt
+            self.brain = FlyBrain(**kw)
+        unknown = set(self.settings) - set(DEFAULT)
+        if unknown:
+            raise ValueError(f"unknown settings {sorted(unknown)}; known: {', '.join(DEFAULT)}")
+        self.p = {**DEFAULT, **self.settings}
+        b = self.brain
+        self.see = {ch: {s: b.cells(t, s) for s in "LR"} for ch, t in SEE.items()}
+        self.steer = {s: b.cells(STEER, s) for s in "LR"}
+        self.escape_cells = {s: b.cells(ESCAPE, s) for s in "LR"}
+        self.dt = float(b.dt)
+        self.reset()
+
+    def reset(self, seed: int | None = None, settle: float = 0.5) -> None:
+        """Fresh voltages, then `settle` seconds with nothing to see so the network is calm at the start."""
+        self.brain.reset(seed)
+        for _ in range(int(round(settle / self.dt))):
+            self.brain.step()
+        self.L = self.R = self.EL = self.ER = 0.0
+        self.prev_size: dict = {}
+        self.drive = {f"{ch}{s}": 0.0 for ch in SEE for s in "LR"}
+        self.fired = np.empty(0, np.int64)
+        self.last = Decision()
+
+    def configure(self, **settings) -> None:
+        unknown = set(settings) - set(DEFAULT)
+        if unknown:
+            raise ValueError(f"unknown settings {sorted(unknown)}; known: {', '.join(DEFAULT)}")
+        self.p.update(settings)
+
+    def inputs(self, things) -> list:
+        """The volts each eye-neuron group gets from what's in view (and remembers sizes for looming)."""
+        p = self.p
+        d = {k: 0.0 for k in self.drive}
+        seen = {}
+        for i, t in enumerate(things):
+            key = t.key if t.key is not None else ("_", i)
+            left = min(1.0, max(0.0, 0.5 - t.bearing / p["spread"]))      # share going to the left eye
+            growth = max(0.0, t.size - self.prev_size.get(key, t.size))
+            seen[key] = t.size
+            for s, share in (("L", left), ("R", 1.0 - left)):
+                if share <= 0:
+                    continue
+                if t.kind == "target":
+                    d[f"chase{s}"] = max(d[f"chase{s}"], share * p["target"])
+                elif t.kind == "shot":
+                    d[f"shot{s}"] = max(d[f"shot{s}"], min(p["cap"], share * growth * p["shot_gain"]))
+                else:
+                    d[f"chase{s}"] = max(d[f"chase{s}"], min(p["cap"], share * (p["chase"] + p["chase_gain"] * t.size)))
+                    d[f"loom{s}"] = max(d[f"loom{s}"], min(p["cap"], share * growth * p["loom_gain"]))
+                    d[f"threat{s}"] = max(d[f"threat{s}"],
+                                          min(p["cap"], share * p["threat_max"] * min(1.0, t.size / p["threat"]) ** 3))
+        self.prev_size = seen
+        self.drive = d
+        return [(self.see[k[:-1]][k[-1]], v) for k, v in d.items() if v > 0]
+
+    def step(self, things=()) -> Decision:
+        """One brain step (dt seconds of fly time) with these things in view."""
+        p = self.p
+        fired = self.brain.step(inject=self.inputs(things))
+        flies = fired if isinstance(fired, list) else [fired]   # several flies vote by averaging their spikes
+        self.fired = flies[0]
+
+        def count(cells):
+            return sum(int(np.isin(f, cells).sum()) for f in flies) / len(flies)
+
+        a = math.exp(-self.dt / p["rate_tau"])
+        rate = lambda old, n: a * old + (1 - a) * n / self.dt     # noqa: E731
+        self.L, self.R = rate(self.L, count(self.steer["L"])), rate(self.R, count(self.steer["R"]))
+        self.EL = rate(self.EL, count(self.escape_cells["L"]))
+        self.ER = rate(self.ER, count(self.escape_cells["R"]))
+        diff = self.L - self.R
+        self.last = Decision(left=diff > p["threshold"], right=-diff > p["threshold"],
+                             escape=max(self.EL, self.ER) > p["escape"],
+                             steer_hz=(self.L, self.R), escape_hz=(self.EL, self.ER))
+        return self.last

flyplays/game.py

@@ -0,0 +1,83 @@
+"""What a game has to do so a fly can play it. See GUIDE.md for a walk-through.
+
+A game is a class with six methods. flyplays calls them in this loop, once per brain step (20 ms by default):
+
+    game.start(seed)
+    while alive:
+        state = game.tick(dt)          # move the game on by dt seconds
+        things = game.sense()          # what is around the player, as Things
+        decision = fly.step(things)    # one step of the real connectome
+        game.act(decision)             # turn left / right / escape into keys
+        frame = game.frame()           # (only when filming) the screen, an RGB numpy array
+    game.close()
+
+The game must not run on its own between calls: time only moves in tick(). That's how a fly brain that thinks
+slower than real time still plays at the game's real speed, and why a seed replays the same game.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from .fly import Decision, Thing
+
+
+@dataclass
+class State:
+    alive: bool = True
+    score: float = 0.0
+
+
+class Game:
+    """Base class. Override what you need; see games/fruit.py for a complete small example."""
+
+    name = "game"
+    title = "A REAL FLY BRAIN PLAYS"          # the banner on clips
+    score_name = "score"
+    settings: dict = {}                       # interface settings tuned for this game (see fly.DEFAULT)
+    dt: float | None = None                   # brain step this game plays best at (None = the brain's 20 ms)
+    labels = {"left": "LEFT", "right": "RIGHT", "escape": "ESCAPE"}   # what each action shows on clips
+
+    def start(self, seed: int) -> None:
+        raise NotImplementedError
+
+    def tick(self, seconds: float) -> State:
+        raise NotImplementedError
+
+    def sense(self) -> list[Thing]:
+        return []
+
+    def act(self, decision: Decision) -> None:
+        pass
+
+    def frame(self) -> np.ndarray | None:
+        return None
+
+    def close(self) -> None:
+        pass
+
+    # ---- helpers for games -------------------------------------------------------------------------------
+
+    @staticmethod
+    def thing_at(dx: float, ahead: float, radius: float, kind: str = "creature", key=None) -> Thing:
+        """A Thing from screen geometry: `dx` to the player's right, `ahead` in front of it, both in the same
+        units as `radius`. For a game seen from above where the player faces up, ahead = player_y - y."""
+        dist = max(1e-6, float(np.hypot(dx, ahead)))
+        return Thing(bearing=float(np.arctan2(dx, ahead)), size=2 * float(np.arctan(radius / dist)),
+                     kind=kind, key=key)
+
+
+class Tap:
+    """A key that is pressed once per decision, then rests for `refractory` seconds (a flap, a jump, a shot)."""
+
+    def __init__(self, refractory: float = 0.25):
+        self.refractory = refractory
+        self.since = 1e9
+
+    def __call__(self, want: bool, dt: float) -> bool:
+        self.since += dt
+        if want and self.since >= self.refractory:
+            self.since = 0.0
+            return True
+        return False

flyplays/games/__init__.py

@@ -0,0 +1,23 @@
+"""Built-in games, by name. Your own game can be played by its import path: `flyplays play my_module:MyGame`."""
+from __future__ import annotations
+
+import importlib
+
+GAMES = {
+    "fruit": ("flyplays.games.fruit:FruitFall", "Fruit Fall: catch fruit, dodge the swatter (pure Python, no browser)"),
+    "flappy": ("flyplays.games.flappy:Flappy", "Flappy Bird, on the open-source Floppy Bird site (needs [web])"),
+    "doom": ("flyplays.games.doom:Doom", "Freedoom through ViZDoom; options: level=center|corridor|map01|e1m1 (needs [doom])"),
+}
+
+
+def load(name: str):
+    """A game class from a built-in name or "package.module:ClassName"."""
+    path = GAMES[name][0] if name in GAMES else name
+    if ":" not in path:
+        raise SystemExit(f"unknown game {name!r}: one of {', '.join(GAMES)}, or module:Class")
+    mod, _, cls = path.partition(":")
+    import os
+    import sys
+    if os.getcwd() not in sys.path:          # so `flyplays play my_game:MyGame` finds my_game.py in this folder
+        sys.path.insert(0, os.getcwd())
+    return getattr(importlib.import_module(mod), cls)

flyplays/games/doom.py

@@ -0,0 +1,137 @@
+"""Doom: the fly plays Freedoom (the free Doom-engine game) through ViZDoom, headless and silent.
+Needs `pip install "flyplays[doom]"` (ViZDoom ships Freedoom, nothing else to download).
+
+The fly sees nearly all the way round: every monster that isn't in the blind spot straight behind is a
+`creature` on its side (LC10a while in view, LPLC2 as it comes closer, LC4 when it's close), fireballs are
+`shot`s (LPLC1). Out: left-minus-right steering turns the player; a burst on the escape neurons - in a real fly,
+the escape jump - pulls the trigger and backs away from that side. Every shot is the fly trying to get away.
+
+Levels: "center" (ViZDoom's arena: monsters come from all sides, turn and shoot), "corridor",
+"map01" (Freedoom: Phase 2), "e1m1" (Freedoom: Phase 1).
+"""
+from __future__ import annotations
+
+import os
+
+import numpy as np
+
+from ..fly import Decision, Thing
+from ..game import Game, State
+
+MONSTERS = {"Zombieman", "ShotgunGuy", "ChaingunGuy", "DoomImp", "Demon", "Spectre", "LostSoul", "Cacodemon",
+            "HellKnight", "BaronOfHell", "Arachnotron", "PainElemental", "Revenant", "Fatso", "Archvile",
+            "Cyberdemon", "SpiderMastermind", "WolfensteinSS", "MarineChainsawVzd", "ZombieMan"}
+SHOTS = {"DoomImpBall", "CacodemonBall", "BaronBall", "FatShot", "RevenantTracer", "ArachnotronPlasma",
+         "Rocket", "PlasmaBall"}
+TIC = 1 / 35
+
+
+class Doom(Game):
+    name = "doom"
+    title = "A REAL FLY BRAIN PLAYS DOOM"
+    score_name = "kills"
+    labels = {"left": "", "right": "", "escape": "BANG!"}
+    settings = {"chase": 0.6, "chase_gain": 0.8, "loom_gain": 25.0, "threat": 0.25, "threat_max": 0.8,
+                "shot_gain": 25.0, "rate_tau": 0.08, "escape": 90.0}
+    dt = 1 / 70      # two brain steps per Doom tic
+    TURN = 0.35      # degrees per tic per Hz of right-minus-left steering
+    BACK = 6.0       # units per tic backed away while the escape neurons fire (levels you can walk)
+
+    def __init__(self, level: str = "center", skill: int = 3):
+        try:
+            import vizdoom as vzd
+        except ImportError as e:
+            raise SystemExit('Doom needs ViZDoom: pip install "flyplays[doom]"') from e
+        self.vzd, self.level, self.skill = vzd, level, skill
+
+    def start(self, seed: int) -> None:
+        vzd = self.vzd
+        vz = os.path.dirname(vzd.__file__)
+        scen = os.path.join(vz, "scenarios")
+        maps = {"center": (os.path.join(scen, "defend_the_center.wad"), "map01", False, "defend_the_center.cfg"),
+                "corridor": (os.path.join(scen, "deadly_corridor.wad"), "map01", True, "deadly_corridor.cfg"),
+                "map01": (os.path.join(vz, "freedoom2.wad"), "map01", True, None),
+                "e1m1": (os.path.join(vz, "freedoom1.wad"), "e1m1", True, None)}
+        if self.level not in maps:
+            raise SystemExit(f"unknown level {self.level}; one of {', '.join(maps)}")
+        wad, mp, self.can_walk, cfg = maps[self.level]
+        g = vzd.DoomGame()
+        if cfg:
+            g.load_config(os.path.join(scen, cfg))
+        (g.set_doom_game_path if "freedoom" in wad else g.set_doom_scenario_path)(wad)
+        g.set_doom_map(mp)
+        g.set_doom_skill(self.skill)
+        g.set_screen_resolution(vzd.ScreenResolution.RES_320X240)
+        g.set_screen_format(vzd.ScreenFormat.RGB24)
+        g.set_labels_buffer_enabled(True)
+        g.set_objects_info_enabled(True)
+        g.set_render_hud(True)
+        g.set_render_messages(False)
+        g.set_window_visible(False)
+        g.set_sound_enabled(False)
+        g.set_mode(vzd.Mode.PLAYER)
+        g.set_episode_timeout(0)
+        g.set_seed(seed)
+        g.set_available_buttons([vzd.Button.TURN_LEFT_RIGHT_DELTA, vzd.Button.MOVE_FORWARD_BACKWARD_DELTA,
+                                 vzd.Button.MOVE_LEFT_RIGHT_DELTA, vzd.Button.ATTACK])
+        g.set_available_game_variables([vzd.GameVariable.HEALTH, vzd.GameVariable.KILLCOUNT, vzd.GameVariable.DEAD,
+                                        vzd.GameVariable.POSITION_X, vzd.GameVariable.POSITION_Y,
+                                        vzd.GameVariable.ANGLE])
+        g.init()
+        g.new_episode()
+        self.g = g
+        self.img = np.zeros((240, 320, 3), np.uint8)
+        self.things: list[Thing] = []
+        self.kills, self.dead, self.clock = 0, False, 0.0
+        self.action = [0.0, 0.0, 0.0, 0.0]
+        self._read()
+
+    def _read(self) -> None:
+        s = self.g.get_state()
+        if s is None:
+            return
+        self.img = s.screen_buffer
+        hp, k, dead, px, py, ang = s.game_variables
+        self.kills, self.dead = int(k), bool(dead)
+        things = []
+        for o in s.objects:
+            shot = o.name in SHOTS
+            if o.name not in MONSTERS and not shot:
+                continue
+            dx, dy = o.position_x - px, o.position_y - py
+            dist = max(16.0, float(np.hypot(dx, dy)))
+            rel = -((np.degrees(np.arctan2(dy, dx)) - ang + 180) % 360 - 180)   # + = to the player's right
+            if abs(rel) > 165:                                                  # the fly's blind spot
+                continue
+            height = 16.0 if shot else 56.0
+            things.append(Thing(float(np.radians(rel)), 2 * float(np.arctan(height / 2 / dist)),
+                                "shot" if shot else "creature", int(o.id)))
+        self.things = things
+
+    def tick(self, seconds: float) -> State:
+        self.clock += seconds
+        while self.clock >= TIC and not self.dead:
+            self.clock -= TIC
+            self.g.make_action(self.action, 1)
+            if self.g.is_episode_finished():
+                self.dead = True
+                break
+            self._read()
+        return State(not self.dead, self.kills)
+
+    def sense(self):
+        return self.things
+
+    def act(self, d: Decision) -> None:
+        back = self.BACK if (d.escape and self.can_walk) else 0.0
+        away = (1.0 if d.escape_side == "L" else -1.0) * back          # scared on the left -> step right
+        self.action = [self.TURN * d.turn_hz, -back, away, float(d.escape)]
+
+    def frame(self) -> np.ndarray:
+        return self.img
+
+    def close(self) -> None:
+        try:
+            self.g.close()
+        except Exception:
+            pass

flyplays/games/flappy.py

@@ -0,0 +1,78 @@
+"""Flappy Bird: the fly plays Floppy Bird (https://nebezb.com/floppybird/, Nebez Briefkani's open-source remake)
+on its own site, in headless Chrome. The game isn't changed. Needs `pip install "flyplays[web]"`.
+
+The fly rides the bird, looking right at the pipes. The opening ahead (the gap in the next pipe) is a `target`:
+looking right across the screen, the fly's left eye covers the top of the screen and its right eye the bottom,
+so a gap above drives LC10a on the left. "Turn left" = up = flap: when the left steering neurons out-fire the
+right ones by `threshold` Hz, we press Space. Nothing says "flap when you're under the gap".
+
+Best results: 8 flies voting on a GPU (`--flies 8 --dt 0.01`). One fly on a CPU usually gets a pipe or two.
+"""
+from __future__ import annotations
+
+import math
+
+from ..fly import Decision, Thing
+from ..game import Tap
+from .web import WebGame
+
+READ_JS = """
+() => {
+  const r = (el) => el.getBoundingClientRect();
+  const bird = r(document.getElementById('player'));
+  const fly = r(document.getElementById('flyarea'));
+  const bx = bird.left + bird.width / 2, by = bird.top + bird.height / 2;
+  let gap = null;
+  for (const p of document.querySelectorAll('.pipe')) {
+    const u = r(p.querySelector('.pipe_upper')), l = r(p.querySelector('.pipe_lower'));
+    if (u.right < bird.left || u.left > fly.right) continue;
+    if (!gap || u.left < gap.x) gap = { x: u.left, top: u.bottom, bottom: l.top };
+  }
+  const ceil = r(document.getElementById('ceiling')).bottom, land = r(document.getElementById('land')).top;
+  const top = gap ? gap.top : ceil, bottom = gap ? gap.bottom : land;
+  return { bx, by, gy: (top + bottom) / 2, gdx: gap ? gap.x - bird.right : 200,
+           alive: window.currentstate !== 2, score: window.score || 0 };
+}
+"""
+
+
+class Flappy(WebGame):
+    name = "flappy"
+    title = "A REAL FLY BRAIN PLAYS FLAPPY BIRD"
+    score_name = "pipes"
+    labels = {"left": "FLAP!", "right": "", "escape": ""}
+    url = "https://nebezb.com/floppybird/"
+    viewport = {"width": 480, "height": 720}
+    clip_box = (0, 0, 480, 640)
+    dt = 0.01                  # 10 ms brain steps steer in time better than 20 ms
+    settings = {"target": 1.0, "spread": 0.35, "rate_tau": 0.05, "threshold": 6.0, "escape": 1e9}
+
+    def __init__(self, easy: bool = False, gap: int = 0):
+        self.easy, self.gap = easy, gap
+        if easy:
+            self.url += "?easy"
+
+    def ready(self, seed: int) -> dict:
+        self.page.clock.run_for(1500)                  # the splash settles
+        if self.gap:                                   # the game's own pipe gap (90 px normal, 200 in ?easy)
+            self.page.evaluate("g => { pipeheight = g; }", self.gap)
+        self.page.keyboard.press("Space")              # start (the game gives one jump at start)
+        self.flap = Tap(0.25)
+        self.dt = 0.02
+        return self.read()
+
+    def read(self) -> dict:
+        return self.page.evaluate(READ_JS)
+
+    def tick(self, seconds: float):
+        self.dt = seconds
+        return super().tick(seconds)
+
+    def sense(self):
+        s = self.state
+        up = math.atan2(s["by"] - s["gy"], max(s["gdx"], 60.0))   # + = the opening is above = the fly's left
+        return [Thing(bearing=-up, size=0.1, kind="target", key="gap")]
+
+    def act(self, d: Decision) -> None:
+        if self.flap(d.left, self.dt):
+            self.page.keyboard.press("Space")