Papersseum

Getting started

Five bots drop into a circular arena for 180 seconds. Leave your land and you draw a trail; close the loop and everything inside becomes yours. Cut a rival's trail and you take their land. Whoever owns the most of the map at the end wins.

1. Install the package

pip install papersseum

Or from a clone of the repository: pip install -e .

Rendering match videos (--render) needs pip install "papersseum[viewer]" and ffmpeg on your PATH.

2. Write an agent

papersseum new my_agent.py

Your file defines a class named Agent with two methods:

class Agent:
    def reset(self, config: dict) -> None:
        """Called once per match with the constants and a seed."""

    def act(self, obs: dict) -> int:
        """Called every decision. Return 0 (straight), 1 (left) or 2 (right)."""

obs holds a global view (16, 120, 120), a local view (16, 31, 31) rotated so your heading points up, and scalars such as your coverage, speed and time left. Use papersseum.channels for named channel indices.

3. Test it locally

papersseum validate my_agent.py                 # the same scan and a short local test match; the server's check is stricter
papersseum play my_agent.py --vs greedy,hunter --render match.mp4
papersseum eval my_agent.py --games 30           # placements, coverage and rating

Add --save-replay game.jsonl.gz to play and watch the match in your browser on the replay page. The file isn't uploaded.

4. Limits

  • One .py file, up to 1 MB.
  • reset() gets 2 seconds. Each act() gets 50 ms; a late or invalid answer plays straight.
  • A bot that is too slow is stopped and plays straight for the rest of that match. That happens if, once it has played 50 moves, more than 20% of its moves are late, or if its late moves add up to more than 20 seconds over the budget in total.
  • Allowed imports: numpy, math, random, itertools, collections, functools, heapq, bisect, typing, dataclasses, enum, json, copy, operator, statistics, array, re, string, time, abc, fractions, decimal, numbers, contextlib and papersseum.
  • torch is not available. It isn't installed in the sandbox, and the upload check rejects import torch. Train with torch on your machine, then run the forward pass with numpy or papersseum.nn and embed the weights in your file with papersseum pack.
  • Blocked calls include, for example, open, eval, exec, getattr and vars, and raw numpy.load. The list is not exhaustive. Weights files can't be uploaded through the website yet, so keep everything your agent needs inside the one .py file.

5. Upload

Sign in and upload your file. It plays a test match first; if it passes it joins the ladder and plays a match every 15 minutes. One upload every 10 minutes.

How ranking works

Every match updates each bot's Elo from how it placed and how much land it held. The leaderboard ranks by rating, which is Elo minus twice its uncertainty: the uncertainty shrinks as a bot plays more games, so a new bot can't top the table after a few lucky wins.