# Pymageddon

> Pymageddon is a free-to-play, browser-based MMO survival game that simulates a living ecosystem with real predator-prey dynamics. Plants, herbivores and predators all need food to survive, so populations rise and crash like in nature. Players either steer a creature live (keyboard or touch joystick) or deploy a sandboxed Python bot that drives it every tick and competes on a public leaderboard.

Key facts:

- Website: https://pymageddon.adamland.net/
- Price: free. No download required; works on desktop and mobile browsers.
- Genres: MMO, survival, strategy, programming game, ecosystem simulation.
- Source code: https://github.com/snow884/pymageddon

## Pages

- [Home](https://pymageddon.adamland.net/): game overview and gameplay video
- [Play](https://pymageddon.adamland.net/play): live game client (requires a login or a guest account)
- [Start a game](https://pymageddon.adamland.net/start_game_page): choose to play as a guest or log in
- [Write a bot](https://pymageddon.adamland.net/create_bot_page): editor for deploying a Python bot
- [Species explorer](https://pymageddon.adamland.net/explorer): every animal, plant and object in the world, with live populations
- [World map](https://pymageddon.adamland.net/world_map): live map of the whole world and population history charts
- [Players](https://pymageddon.adamland.net/players): leaderboard of players and bot families

## Species

- [Hedgehog](https://pymageddon.adamland.net/explorer/type/Hedgehog/): Eats snails, caterpillars and snake eggs.
- [Scarecrow](https://pymageddon.adamland.net/explorer/type/Scarecrow/): A scarecrow guarding the fields.
- [LivingStones](https://pymageddon.adamland.net/explorer/type/LivingStones/): Succulents disguised as stones. Only tortoises see through it.
- [Anthill](https://pymageddon.adamland.net/explorer/type/Anthill/): A busy anthill.
- [SaltDeposit](https://pymageddon.adamland.net/explorer/type/SaltDeposit/): A mineral salt lick. It slowly grows crystals and erodes. Deer and cows lick it.
- [FallenLog](https://pymageddon.adamland.net/explorer/type/FallenLog/): A fallen log blocking the way.
- [BerryBush](https://pymageddon.adamland.net/explorer/type/BerryBush/): A berry bush. Deer, bears and tortoises love it.
- [Grass3](https://pymageddon.adamland.net/explorer/type/Grass3/): Grass is a plant. Grass can produce seeds.
- [Carrot](https://pymageddon.adamland.net/explorer/type/Carrot/): A carrot. A rabbit favourite.
- [MossyBoulder](https://pymageddon.adamland.net/explorer/type/MossyBoulder/): A heavy mossy boulder.
- [Clover](https://pymageddon.adamland.net/explorer/type/Clover/): A clover patch loved by rabbits and cows.
- [Stone](https://pymageddon.adamland.net/explorer/type/Stone/): A stone is just passively siting in one place and acts as an obstacle.
- [Deer](https://pymageddon.adamland.net/explorer/type/Deer/): A large herbivore browsing ferns, berry bushes and oak saplings. Prey of wolves and bears.
- [Puddle](https://pymageddon.adamland.net/explorer/type/Puddle/): A small puddle of water.
- [Frog](https://pymageddon.adamland.net/explorer/type/Frog/): Eats insects and snails. Prey of snakes, owls and bears.
- [MossCarpet](https://pymageddon.adamland.net/explorer/type/MossCarpet/): Mossy stones. Snails and deer graze here.
- [HayBale](https://pymageddon.adamland.net/explorer/type/HayBale/): A hay bale left by a farmer.
- [Stone2](https://pymageddon.adamland.net/explorer/type/Stone2/): A stone is just passively siting in one place and acts as an obstacle.
- [Owl](https://pymageddon.adamland.net/explorer/type/Owl/): A night hunter of mice, frogs, snakes and squirrels.
- [Fern](https://pymageddon.adamland.net/explorer/type/Fern/): A fern eaten by deer, snails and caterpillars.
- [Chicken](https://pymageddon.adamland.net/explorer/type/Chicken/): Animal representing a chicken that can move, eats seeds and caterpillars and lays eggs. Chicken can be eaten by a fox.
- [BeeEgg](https://pymageddon.adamland.net/explorer/type/BeeEgg/): Honeycomb is an egg that will hatch into a bee when other animal comes close.
- [AppleTree](https://pymageddon.adamland.net/explorer/type/AppleTree/): An apple tree dropping apples. Deer and bears love them.
- [BlackberryBramble](https://pymageddon.adamland.net/explorer/type/BlackberryBramble/): A thorny bramble full of blackberries.
- [Angel](https://pymageddon.adamland.net/explorer/type/Angel/): An angel acts as randomizer in the game. It has the ability to randomly lay eggs of all animal spices as well as seeds of all plants.
- [Signpost](https://pymageddon.adamland.net/explorer/type/Signpost/): A wooden signpost.
- [Grass2](https://pymageddon.adamland.net/explorer/type/Grass2/): Grass is a plant. Grass can produce seeds.
- [Tortoise](https://pymageddon.adamland.net/explorer/type/Tortoise/): A slow, long-lived herbivore that eats cacti, pumpkins and reeds.
- [CrystalCluster](https://pymageddon.adamland.net/explorer/type/CrystalCluster/): A mysterious glowing crystal cluster.
- [HazelBush](https://pymageddon.adamland.net/explorer/type/HazelBush/): A hazel bush dropping nuts.
- [Squirrel](https://pymageddon.adamland.net/explorer/type/Squirrel/): Eats acorns and seeds and raids owl nests. Hunted by foxes and owls.
- [Reed](https://pymageddon.adamland.net/explorer/type/Reed/): Reeds feeding tadpoles and tortoises.
- [Pumpkin](https://pymageddon.adamland.net/explorer/type/Pumpkin/): A pumpkin on the vine.
- [TreeStump](https://pymageddon.adamland.net/explorer/type/TreeStump/): An old tree stump.
- [Wolf](https://pymageddon.adamland.net/explorer/type/Wolf/): An apex predator hunting deer, cows, foxes and rabbits.
- [LotusFlower](https://pymageddon.adamland.net/explorer/type/LotusFlower/): A blooming lotus.
- [WoodenBarrel](https://pymageddon.adamland.net/explorer/type/WoodenBarrel/): An old wooden barrel.
- [Snake](https://pymageddon.adamland.net/explorer/type/Snake/): Hunts mice, frogs and raids nests. Hunted by owls and bears.
- [OakTree](https://pymageddon.adamland.net/explorer/type/OakTree/): A young oak tree dropping acorns.
- [Fox](https://pymageddon.adamland.net/explorer/type/Fox/): An animal representing a fox. A fox moves, eats chickens, cows, rabbits, mice, squirrels and eggs. Foxes can also lay eggs.
- [Snail](https://pymageddon.adamland.net/explorer/type/Snail/): A slow herbivore that eats ferns, pumpkins and mushrooms. Food for frogs, hedgehogs and badgers.
- [StrawberryPatch](https://pymageddon.adamland.net/explorer/type/StrawberryPatch/): A strawberry patch.
- [StoneWell](https://pymageddon.adamland.net/explorer/type/StoneWell/): An old stone well.
- [Grass](https://pymageddon.adamland.net/explorer/type/Grass/): Grass is a plant. Grass can produce seeds.
- [Mouse](https://pymageddon.adamland.net/explorer/type/Mouse/): A seed eater. Food for foxes, snakes and owls.
- [Dandelion](https://pymageddon.adamland.net/explorer/type/Dandelion/): A dandelion.
- [PineTree](https://pymageddon.adamland.net/explorer/type/PineTree/): An evergreen pine tree.
- [Bear](https://pymageddon.adamland.net/explorer/type/Bear/): An omnivore eating berries, acorns, honeycombs, deer, wolves and tortoises.
- [Butterfly](https://pymageddon.adamland.net/explorer/type/Butterfly/): Drinks nectar from flowers. Eaten by frogs and owls.
- [Mushroom2](https://pymageddon.adamland.net/explorer/type/Mushroom2/): Mushroom is a type of edible fungus similar to plants. Mushroom can produce spores and that is how they spread.
- [Rabbit](https://pymageddon.adamland.net/explorer/type/Rabbit/): A fast herbivore. Eats clover, carrots and dandelions. Hunted by foxes, wolves and owls.
- [WheatStalks](https://pymageddon.adamland.net/explorer/type/WheatStalks/): Ripe wheat.
- [Sunflower](https://pymageddon.adamland.net/explorer/type/Sunflower/): A sunflower producing seeds.
- [Cactus](https://pymageddon.adamland.net/explorer/type/Cactus/): A hardy cactus. Only tortoises dare to eat it.
- [Cow](https://pymageddon.adamland.net/explorer/type/Cow/): Animal representing a cow that moves, eats plants, eat seeds and lays eggs. A cow can be eaten by a fox.
- [Mushroom](https://pymageddon.adamland.net/explorer/type/Mushroom/): Mushroom is a type of edible fungus similar to plants. Mushroom can produce spores and that is how they spread.
- [Bee](https://pymageddon.adamland.net/explorer/type/Bee/): An animal representing a bee. A bee hatches from a honeycomb when other animal touches the honeycomb after that it follows the animal that caused it to hatch.
- [CarnivorousFlower](https://pymageddon.adamland.net/explorer/type/CarnivorousFlower/): A flower that has the ability to eat other animals when they walk into it.
- [ChickenEgg](https://pymageddon.adamland.net/explorer/type/ChickenEgg/): An egg that will hatch into chicken.
- [FoxEgg](https://pymageddon.adamland.net/explorer/type/FoxEgg/): An egg that will hatch into a fox.
- [Hoglet](https://pymageddon.adamland.net/explorer/type/Hoglet/): A young hedgehog.
- [FoxKit](https://pymageddon.adamland.net/explorer/type/FoxKit/): A young fox.
- [BadgerEgg](https://pymageddon.adamland.net/explorer/type/BadgerEgg/): An egg that will hatch into a badger.
- [Bunny](https://pymageddon.adamland.net/explorer/type/Bunny/): A young rabbit. Eats clover, carrots and dandelions and grows into a rabbit.
- [SnakeEgg](https://pymageddon.adamland.net/explorer/type/SnakeEgg/): A clutch of snake eggs.
- [SnakeHatchling](https://pymageddon.adamland.net/explorer/type/SnakeHatchling/): A young snake.
- [Owlet](https://pymageddon.adamland.net/explorer/type/Owlet/): A fluffy young owl.
- [BearDen](https://pymageddon.adamland.net/explorer/type/BearDen/): A den with newborn bear cubs.
- [Tadpole](https://pymageddon.adamland.net/explorer/type/Tadpole/): A tadpole eating reeds. Grows into a frog.
- [Fawn](https://pymageddon.adamland.net/explorer/type/Fawn/): A young deer. Browses ferns and berry bushes.
- [TortoiseHatchling](https://pymageddon.adamland.net/explorer/type/TortoiseHatchling/): A young tortoise.
- [Calf](https://pymageddon.adamland.net/explorer/type/Calf/): A young cow. Grazes on grass and seeds and grows into a cow.
- [BadgerCub](https://pymageddon.adamland.net/explorer/type/BadgerCub/): A young badger.
- [Chick](https://pymageddon.adamland.net/explorer/type/Chick/): A young chicken pecking at seeds.
- [RabbitNest](https://pymageddon.adamland.net/explorer/type/RabbitNest/): A fur-lined nest of newborn rabbits. The kits leave the nest after a while.
- [CowEgg](https://pymageddon.adamland.net/explorer/type/CowEgg/): An egg that will hatch into a calf.
- [HedgehogNest](https://pymageddon.adamland.net/explorer/type/HedgehogNest/): A leaf nest of baby hedgehogs.
- [BabySnail](https://pymageddon.adamland.net/explorer/type/BabySnail/): A young snail slowly munching leaves.
- [HazelSapling](https://pymageddon.adamland.net/explorer/type/HazelSapling/): A young hazel.
- [OwlEgg](https://pymageddon.adamland.net/explorer/type/OwlEgg/): Owl eggs in a twig nest.
- [WolfPup](https://pymageddon.adamland.net/explorer/type/WolfPup/): A playful young wolf.
- [TortoiseEgg](https://pymageddon.adamland.net/explorer/type/TortoiseEgg/): Tortoise eggs buried in the sand.
- [ButterflyEgg](https://pymageddon.adamland.net/explorer/type/ButterflyEgg/): Butterfly eggs laid on a leaf.
- [MousePup](https://pymageddon.adamland.net/explorer/type/MousePup/): A young mouse foraging for seeds.
- [MouseNest](https://pymageddon.adamland.net/explorer/type/MouseNest/): A straw nest full of newborn mice.
- [LithopsSprout](https://pymageddon.adamland.net/explorer/type/LithopsSprout/): A young living stone.
- [SnailEgg](https://pymageddon.adamland.net/explorer/type/SnailEgg/): A clutch of snail eggs.
- [WolfDen](https://pymageddon.adamland.net/explorer/type/WolfDen/): A den with newborn wolf pups.
- [CactusSeed](https://pymageddon.adamland.net/explorer/type/CactusSeed/): A cactus fruit with seeds.
- [Frogspawn](https://pymageddon.adamland.net/explorer/type/Frogspawn/): A clump of frog eggs.
- [SaltCrystal](https://pymageddon.adamland.net/explorer/type/SaltCrystal/): A growing salt crystal.
- [PumpkinSeed](https://pymageddon.adamland.net/explorer/type/PumpkinSeed/): A pumpkin seed.
- [BrambleSprout](https://pymageddon.adamland.net/explorer/type/BrambleSprout/): A young bramble shoot.
- [WheatSprout](https://pymageddon.adamland.net/explorer/type/WheatSprout/): Young wheat.
- [StrawberryRunner](https://pymageddon.adamland.net/explorer/type/StrawberryRunner/): A strawberry runner taking root.
- [SunflowerSeed](https://pymageddon.adamland.net/explorer/type/SunflowerSeed/): A sunflower seed. Favourite of mice, squirrels and chickens.
- [Acorn](https://pymageddon.adamland.net/explorer/type/Acorn/): An acorn that grows into an oak.
- [Caterpillar](https://pymageddon.adamland.net/explorer/type/Caterpillar/): A hungry larva eating leaves. Turns into a chrysalis.
- [LotusBud](https://pymageddon.adamland.net/explorer/type/LotusBud/): A lotus bud on a lily pad.
- [AppleSapling](https://pymageddon.adamland.net/explorer/type/AppleSapling/): A young apple tree.
- [Seed](https://pymageddon.adamland.net/explorer/type/Seed/): A seed that turns into a flower
- [PineCone](https://pymageddon.adamland.net/explorer/type/PineCone/): A pine cone full of seeds. Squirrels hoard them.
- [Spore](https://pymageddon.adamland.net/explorer/type/Spore/): A spore is a type of a seed that turns into a mushroom
- [BerrySeed](https://pymageddon.adamland.net/explorer/type/BerrySeed/): A berry carrying the seed of a berry bush.
- [DeerNewborn](https://pymageddon.adamland.net/explorer/type/DeerNewborn/): A newborn fawn hiding motionless in the grass.
- [Strawberry](https://pymageddon.adamland.net/explorer/type/Strawberry/): A sweet strawberry covered in tiny seeds.
- [CloverSeed](https://pymageddon.adamland.net/explorer/type/CloverSeed/): A clover seed.
- [FernSpore](https://pymageddon.adamland.net/explorer/type/FernSpore/): A fern spore sprouting into a fiddlehead.
- [CarrotSeed](https://pymageddon.adamland.net/explorer/type/CarrotSeed/): Carrot seeds.
- [SaltGrain](https://pymageddon.adamland.net/explorer/type/SaltGrain/): Salt grains. Chickens peck them as grit.
- [Spore2](https://pymageddon.adamland.net/explorer/type/Spore2/): A spore is a type of a seed that turns into a mushroom
- [DandelionSeed](https://pymageddon.adamland.net/explorer/type/DandelionSeed/): A fluffy dandelion seed head.
- [Badger](https://pymageddon.adamland.net/explorer/type/Badger/): Animal representing a badger that moves, eats mushrooms, snails and tortoise eggs and lays eggs. A badger can be eaten by a fox or a wolf.
- [SquirrelKit](https://pymageddon.adamland.net/explorer/type/SquirrelKit/): A young squirrel collecting acorns.
- [Apple](https://pymageddon.adamland.net/explorer/type/Apple/): A fallen apple. Its seeds grow into an apple tree.
- [Chrysalis](https://pymageddon.adamland.net/explorer/type/Chrysalis/): A chrysalis. A butterfly is forming inside.
- [Hazelnut](https://pymageddon.adamland.net/explorer/type/Hazelnut/): A hazelnut.
- [MossSpore](https://pymageddon.adamland.net/explorer/type/MossSpore/): Moss spores on a pebble.
- [Seed2](https://pymageddon.adamland.net/explorer/type/Seed2/): A seed that turns into a flower
- [PineSeedling](https://pymageddon.adamland.net/explorer/type/PineSeedling/): A young pine.
- [ReedSeed](https://pymageddon.adamland.net/explorer/type/ReedSeed/): A fluffy reed seed.
- [LotusSeed](https://pymageddon.adamland.net/explorer/type/LotusSeed/): A lotus seed pod.
- [Seed3](https://pymageddon.adamland.net/explorer/type/Seed3/): A seed that turns into a flower
- [Blackberry](https://pymageddon.adamland.net/explorer/type/Blackberry/): A juicy blackberry.
- [LithopsSeed](https://pymageddon.adamland.net/explorer/type/LithopsSeed/): A seed of the living stones.

## HTTP API

- [OpenAPI schema](https://pymageddon.adamland.net/openapi.json): machine-readable description of every endpoint
- [Interactive API docs](https://pymageddon.adamland.net/docs): Swagger UI

To get an access token, call `POST /token` with `{"is_guest": true}` for a guest account, or with `{"username": "...", "password": "..."}` for a registered account. Then send the token as `Authorization: Bearer <token>`. Create a registered account with `POST /create_player` and the body `{"username", "password", "verify_password"}`.

| Method | Path | Purpose |
|---|---|---|
| POST | /new_game | Join the world as a player creature |
| POST | /create_bot | Deploy bot code `{"code_str": "..."}` and spectate it |
| POST | /control | Send held keys `{"ArrowUp","ArrowDown","ArrowLeft","ArrowRight"}` (booleans) |
| GET | /get_map | Visible map window: tiles, objects, particles, player status |
| GET | /score | Your scores and ranks |
| POST | /end_game | Leave the current game |
| GET | /me | Name of the authenticated user |

The world runs in epochs of about 0.33 s. `/get_map` returns `global_params.status` (`stopped` or `running`) and `time_left` until the next epoch. Pass `?since_epoch=N` to get an empty `204` while the map is still at epoch `N`.

## Bot language

Bot code is a safe subset of Python, evaluated once per tick in a sandbox that is limited to 1000 steps. Set the variable `intent` to one of the following:

- `"MOVE_FORWARD"`
- `"ROTATE_UP"`
- `"ROTATE_RIGHT"`
- `"ROTATE_DOWN"`
- `"ROTATE_LEFT"`

If you leave `intent` unset (`None`), the bot idles.

Allowed syntax and functions:

- Allowed syntax: assignments, `if` / `elif` / `else`, `global`, arithmetic, comparisons, `and` / `or` / `not`, `in` / `not in`, list / tuple / dict literals, and indexing. Loops, imports, attribute access, `def` and `print` are rejected.
- `and` / `or` evaluate both sides, so nest `if` statements instead of writing `x and x["y"]`.
- `parent_object` is a dict with `x`, `y` and `rotation` (`"UP"`, `"RIGHT"`, `"DOWN"` or `"LEFT"`) describing your creature. The y axis points down.
- `find_nearest_xy(x, y, type_name_or_list, rad=10)` returns the nearest object of that type (for example `"Grass"`, `"Cow"` or `["Fox", "Badger"]`) as `{x, y, rotation}`, or `None`.
- `random_randint(a, b)` and `random_choice(list)` return random values.
- `get_index(list, i)` and `set_index(list, i, value)` read and write list elements.
- Every variable persists between ticks. Reading a variable that has never been assigned is an error, so declare it with `global name` first; this initializes it to `None` on the first tick.
- Any error discards the bot's variables, and the creature idles for that tick.

Example: walk toward the nearest grass and wander when none is in range.

```python
global steps
if not steps:
    steps = 0
steps = steps + 1
me = parent_object
target = find_nearest_xy(me["x"], me["y"], "Grass")
intent = "MOVE_FORWARD"
if target:
    if target["x"] > me["x"]:
        want = "RIGHT"
    elif target["x"] < me["x"]:
        want = "LEFT"
    elif target["y"] < me["y"]:
        want = "UP"
    else:
        want = "DOWN"
    if me["rotation"] != want:
        intent = "ROTATE_" + want
elif steps % 5 == 0:
    intent = random_choice(["ROTATE_UP", "ROTATE_RIGHT", "ROTATE_DOWN", "ROTATE_LEFT"])
```

## Optional

- [Sitemap](https://pymageddon.adamland.net/sitemap.xml)
- [Robots](https://pymageddon.adamland.net/robots.txt)