agario-kit 2026.1.0__tar.gz

agario_kit-2026.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Environments
+.env
+.venv
+venv
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+eggs/
+.eggs/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# IDE specific files
+.idea/
+.vscode/
+*.swp
+*.swo
+pyrightconfig.json
+
+# udit's specific files
+todo.md
+.ignore/
+
+# Submission files
+**/submission*/
+**/output/
+**/input/
+/.agario/

agario_kit-2026.1.0/.python-version

@@ -0,0 +1 @@
+3.13

agario_kit-2026.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: agario-kit
+Version: 2026.1.0
+Summary: Public Agar.io competition package
+Requires-Python: >=3.12
+Requires-Dist: dotmap>=1.3.30
+Requires-Dist: pydantic>=2.11.7
+Description-Content-Type: text/markdown
+
+# agario-public
+
+Public source repository for the Agar.io bot competition.
+
+This repo publishes a single Python package:
+
+- `agario-kit`
+
+That one distribution contains the modules competitors and private
+infrastructure use:
+
+- `lib`: shared models, config, and protocol types
+- `helper`: helper API that student bots import
+- `engine`: the authoritative game engine
+- `agario_visualiser`: local match launcher and first-person visualiser
+
+## Layout
+
+```text
+src/
+  agario_kit/
+  agario_visualiser/
+  engine/
+  helper/
+  lib/
+examples/
+  submissions/
+docs/
+tests/
+```
+
+## Local development
+
+```bash
+uv sync
+uv run pytest
+uv run agario-local-match --submission examples/submissions/bot_1.py --submission examples/submissions/bot_2.py --submission examples/submissions/aggressive.py --masquerade
+```

agario_kit-2026.1.0/README.md

@@ -0,0 +1,38 @@
+# agario-public
+
+Public source repository for the Agar.io bot competition.
+
+This repo publishes a single Python package:
+
+- `agario-kit`
+
+That one distribution contains the modules competitors and private
+infrastructure use:
+
+- `lib`: shared models, config, and protocol types
+- `helper`: helper API that student bots import
+- `engine`: the authoritative game engine
+- `agario_visualiser`: local match launcher and first-person visualiser
+
+## Layout
+
+```text
+src/
+  agario_kit/
+  agario_visualiser/
+  engine/
+  helper/
+  lib/
+examples/
+  submissions/
+docs/
+tests/
+```
+
+## Local development
+
+```bash
+uv sync
+uv run pytest
+uv run agario-local-match --submission examples/submissions/bot_1.py --submission examples/submissions/bot_2.py --submission examples/submissions/aggressive.py --masquerade
+```

agario_kit-2026.1.0/docs/game_rules.md

@@ -0,0 +1,72 @@
+# Agar Bot Battle Rules
+
+## Arena
+
+- The game takes place in a square arena.
+- The arena size and player count are controlled by config values.
+- Food is spawned randomly and maintained at a fixed count.
+
+## Player State
+
+Each player controls one or more circular blobs with:
+
+- Absolute `x, y` position for each blob
+- Radius for each blob
+- Alive/dead state
+- Per-blob merge cooldown after splitting
+
+## Vision
+
+Each player has a single square view centered on the mass-weighted centroid of
+their blobs.
+
+Players can observe:
+
+- Their own authoritative blob list with absolute coordinates, sizes, and cooldowns
+- Food within their current vision square
+- Other visible blobs with absolute coordinates and size
+
+The vision size is recalculated by the engine each turn as a function of the
+sum of the player's blob radii.
+
+## Turns
+
+On each round, every living player submits a movement direction and may optionally request a split.
+
+Supported direction formats:
+
+- A vector using `x` and `y`
+- An angle in `degrees`
+
+The engine normalizes the direction and applies movement using the configured base speed. Larger players move more slowly according to a size-based speed factor.
+
+## Splitting And Merging
+
+- A blob may split only if its mass is at least the configured split threshold.
+- Mass is proportional to area, so splitting conserves `radius^2`.
+- When a split happens, the new blob is ejected in the submitted movement direction with a configured launch speed.
+- Split blobs cannot merge until their cooldown expires.
+- Blobs owned by the same player are kept non-overlapping by the engine at all times.
+- Same-player blobs are gently pulled together over time, and merge automatically once they are both off cooldown and touching.
+
+## Eating Food
+
+- Food is eaten when it lies inside any owned blob's radius.
+- Eating food increases that blob's size.
+- After food is consumed, the engine respawns food until the configured food count is restored.
+
+## Eating Players
+
+- A blob may eat an enemy blob only if it is at least 10% larger.
+- The smaller blob's center must lie inside the larger blob's radius.
+- When a blob is eaten, the larger blob absorbs its size contribution.
+- A player is eliminated only when all of their blobs have been eaten.
+
+## End Condition
+
+The game ends when either:
+
+- Only one player remains alive
+- The configured round limit is reached
+
+The winner is the highest-ranked remaining player by alive state and final size.

agario_kit-2026.1.0/docs/releasing.md

@@ -0,0 +1,62 @@
+# Releasing `agario-public`
+
+## What gets published
+
+This repository builds and publishes one Python distribution package:
+
+- `agario-kit`
+
+That single distribution contains the runtime modules competitors and private
+infrastructure use:
+
+- `lib`
+- `helper`
+- `engine`
+- `agario_visualiser`
+
+## GitHub Actions
+
+- `.github/workflows/ci.yml` runs tests on pushes to `main` and on pull requests.
+- `.github/workflows/publish.yml`:
+  - publishes to PyPI on git tags matching `v*`
+  - can publish to TestPyPI manually via `workflow_dispatch`
+
+The publish workflow builds the distribution into `dist/`, checks it with
+`twine check`, then uploads them through `pypa/gh-action-pypi-publish`.
+
+## Trusted Publishing setup
+
+Configure the GitHub workflow as a Trusted Publisher for the `agario-kit`
+project on both PyPI and TestPyPI.
+
+Use these values when configuring each publisher:
+
+- Repository owner: your GitHub org or username
+- Repository name: `agario-public`
+- Workflow filename: `publish.yml`
+- GitHub environment:
+  - `pypi` for PyPI
+  - `testpypi` for TestPyPI
+
+## Release steps
+
+1. Update the version in the root `pyproject.toml`.
+2. Commit and push to `main`.
+3. Run the `Publish Package` workflow manually with `repository=testpypi`.
+4. Verify installs from TestPyPI.
+5. Create and push a tag such as `v2026.1.1`.
+6. Approve the `pypi` environment deployment in GitHub if required.
+7. Announce the release to competitors:
+
+```bash
+uv lock --upgrade-package agario-kit==2026.1.1
+uv sync
+```
+
+## Competitor install target
+
+Competitors install only this package:
+
+```bash
+uv add agario-kit==2026.1.1
+```

agario_kit-2026.1.0/docs/scoring.md

@@ -0,0 +1,13 @@
+# Scoring and Ranks
+- Previously Bot Battle used win rates, with set interval round-robin game runs. I am not sure how I feel about this since, it is not robust to reactions.
+    - It also discourages scoring-oriented or deliberately adversarial strategies in a round-robin format.
+    
+- What I am thinking is Round Robin "Tournament" Should be held at a set interval
+    - Overall Rank is a sliding window of the last 30 (not finalised) minutes (so if a game is every minute 30 roundrobin tournaments decide your rank)
+    - Ideally the number of points you get should be _offset_ (but not weighted) but how difficult opponent bots are.
+        - Offset = k1 * (your_score - agg_opp_mean) / (agg_opp_sd + ε) \
+           + k2 * (your_mean - agg_opp_mean) / (your_sd + agg_opp_sd + ε) capped at [2, -4]
+
+        - Win Bonus - +4 First, +2 for Second
+
+> Definitely not fixed. The advantage of winrate is that it can be run at an arbitrary interval. So to be discussed.

agario_kit-2026.1.0/mypy.ini

@@ -0,0 +1,5 @@
+[mypy]
+files = src
+python_executable = .venv/bin/python 
+strict = true
+disable_error_code = import-untyped

agario_kit-2026.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "agario-kit"
+version = "2026.1.0"
+description = "Public Agar.io competition package"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+  "dotmap>=1.3.30",
+  "pydantic>=2.11.7",
+]
+
+[project.scripts]
+agario-engine = "engine.__main__:main"
+engine = "engine.__main__:main"
+agario-local-match = "agario_visualiser.launch_local_match:main"
+agario-visualiser-submission = "agario_visualiser.visualiser_submission:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+  "build",
+  "mypy",
+  "pre-commit",
+  "pytest>=8.4.1",
+  "twine",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = [
+  "src/agario_kit",
+  "src/agario_visualiser",
+  "src/engine",
+  "src/helper",
+  "src/lib",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/agario_kit",
+  "src/agario_visualiser",
+  "src/engine",
+  "src/helper",
+  "src/lib",
+  "examples",
+  "docs",
+  "tests",
+  "scripts",
+  ".gitignore",
+  ".python-version",
+  "README.md",
+  "mypy.ini",
+  "pyproject.toml",
+  "ruff.toml",
+]

agario_kit-2026.1.0/ruff.toml

@@ -0,0 +1,77 @@
+# Exclude a variety of commonly ignored directories.
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pyenv",
+    ".pytest_cache",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    ".vscode",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "site-packages",
+    "venv",
+]
+
+# Same as Black.
+line-length = 88
+indent-width = 4
+
+# Assume Python 3.9
+target-version = "py313"
+
+[lint]
+# Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`) codes by default.
+# Unlike Flake8, Ruff doesn't enable pycodestyle warnings (`W`) or
+# McCabe complexity (`C901`) by default.
+select = ["E4", "E7", "E9", "F"]
+ignore = []
+
+# Allow fix for all enabled rules (when `--fix`) is provided.
+fixable = ["ALL"]
+unfixable = []
+
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[format]
+# Like Black, use double quotes for strings.
+quote-style = "double"
+
+# Like Black, indent with spaces, rather than tabs.
+indent-style = "space"
+
+# Like Black, respect magic trailing commas.
+skip-magic-trailing-comma = false
+
+# Like Black, automatically detect the appropriate line ending.
+line-ending = "auto"
+
+# Enable auto-formatting of code examples in docstrings. Markdown,
+# reStructuredText code/literal blocks and doctests are all supported.
+#
+# This is currently disabled by default, but it is planned for this
+# to be opt-out in the future.
+docstring-code-format = false
+
+# Set the line length limit used when formatting code snippets in
+# docstrings.
+#
+# This only has an effect when the `docstring-code-format` setting is
+# enabled.
+docstring-code-line-length = "dynamic"

agario_kit-2026.1.0/scripts/match_simulator.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python
+
+import json
+import shutil
+from signal import SIGKILL
+import subprocess
+import sys
+import os
+from typing import Tuple
+
+from lib.config.arena import NUM_PLAYERS
+
+PIPE_PERMISSIONS = 0o660
+FILE_PERMISSIOSN = 0o664
+DIRECTORY_PERMISSIONS = 0o775
+
+
+def main():
+    # uv run python scripts/match_simulator.py --submissions 3:examples/submissions/example.py 1:examples/submissions/aggressive.py --engine
+
+    commands = parse_cmd_args(sys.argv[1:])
+
+    try:
+        sources = [
+            (int(x.split(":")[0]), x.split(":")[1]) for x in commands["--submissions"]
+        ]
+    except (ValueError, KeyError):
+        print_usage()
+
+    if sum([x[0] for x in sources]) != NUM_PLAYERS:
+        print(f"Total players in the match must be {NUM_PLAYERS}.")
+        print_usage()
+
+    setup_environments(sources)
+    submission_pids = start_submissions()
+
+    if "--engine" in commands:
+        if len(commands["--engine"]) != 0:
+            print_usage()
+        start_engine()
+
+    else:
+        print(
+            "Once you have finished running the engine, press [Enter] to terminate any still-running submission processes."
+        )
+        input()
+
+    for pid in submission_pids:
+        print(f"[simulator]: terminating submission pid {pid}.")
+        os.kill(pid, SIGKILL)
+
+    print("[simulator] simulation complete.")
+
+
+def parse_cmd_args(args: list[str]):
+    commands = {}
+
+    current_command = None
+    for arg in args:
+        if arg[:2] == "--":
+            current_command = arg
+            commands[current_command] = []
+            continue
+
+        if current_command is None:
+            print_usage()
+
+        commands[current_command].append(arg)
+
+    for command in commands.keys():
+        if command not in ["--submissions", "--engine"]:
+            print_usage()
+
+    return commands
+
+
+def print_usage():
+    print(
+        "Usage: python3 match_simulator.py [options]\n"
+        "   options:\n"
+        "       --submissions {<count> | d}:<path> ...      Sets the source files for the submissions to run in this match. If <count> is specified, <count> copies\n"
+        "                                                       of the submission will play in the match, else if 'd' is specified a single copy will play and it\n"
+        "                                                       will not be automatically started.\n"
+        "       --engine                                    If present, the simulator will start the engine. To run the match without this flag you need to manually\n"
+        "                                                       start the engine (for example, while debugging it).\n"
+        "\n"
+        "   examples:\n"
+        "       uv run python scripts/match_simulator.py --submissions 4:examples/submissions/example.py --engine\n"
+        "       uv run python scripts/match_simulator.py --submissions 1:examples/submissions/example.py 3:my_submission.py --engine\n"
+        "       uv run python scripts/match_simulator.py --submissions 3:examples/submissions/example.py d:my_submission.py --engine\n"
+    )
+    sys.exit(0)
+
+
+def setup_environments(sources: list[Tuple[int, str]]):
+    shutil.rmtree("output", ignore_errors=True)
+    os.mkdir("output")
+    shutil.rmtree("input", ignore_errors=True)
+    os.mkdir("input")
+
+    count = 0
+    source = sources.pop(0)
+    for player in range(NUM_PLAYERS):
+        if count >= source[0]:
+            count = 0
+            source = sources.pop(0)
+
+        clean_environment_for_player(player)
+        setup_environment_for_player(player, source[1])
+
+        count += 1
+
+    catalog = [{"team_id": i} for i in range(NUM_PLAYERS)]
+    with open("input/catalog.json", "w") as f:
+        f.write(json.dumps(catalog))
+
+
+def start_submissions() -> list[int]:
+    player_pids = []
+    for player in range(NUM_PLAYERS):
+        os.chdir(f"submission{player}")
+
+        with (
+            open("io/submission.log", "w") as f_log,
+            open("io/submission.err", "w") as f_err,
+        ):
+            process = subprocess.Popen(
+                ["python3", "submission.py"], stdout=f_log, stderr=f_err
+            )
+
+        player_pids.append(process.pid)
+        print(f"[simulator]: started submission {player} (pid={process.pid}).")
+        os.chdir("..")
+
+    return player_pids
+
+
+def start_engine():
+    print("[simulator] started engine.")
+    with (
+        open("output/engine.log", "w") as f_log,
+        open("output/engine.err", "w") as f_err,
+    ):
+        process = subprocess.Popen(
+            ["python3", "-m", "engine", "--print-recording-interactive"],
+            stdout=subprocess.PIPE,
+            stderr=f_err,
+            text=True,
+            universal_newlines=True,
+            bufsize=1,
+        )
+
+        while True:
+            if process.stdout is not None:
+                data = process.stdout.read(1)
+                if not data:
+                    break
+                print(data, end="", flush=True)
+                f_log.write(data)
+
+    print("[simulator] engine terminated.")
+
+
+def setup_environment_for_player(player: int, source: str):
+    os.makedirs(f"submission{player}/io", mode=DIRECTORY_PERMISSIONS)
+    os.mkfifo(f"submission{player}/io/to_engine.pipe", mode=PIPE_PERMISSIONS)
+    os.mkfifo(f"submission{player}/io/from_engine.pipe", mode=PIPE_PERMISSIONS)
+    shutil.copy(source, f"submission{player}/submission.py")
+
+
+def clean_environment_for_player(player: int):
+    shutil.rmtree(f"submission{player}", ignore_errors=True)
+
+
+if __name__ == "__main__":
+    main()

agario_kit-2026.1.0/src/agario_kit/__init__.py

@@ -0,0 +1 @@
+"""Convenience meta-package for the public Agar.io stack."""

agario_kit-2026.1.0/src/agario_visualiser/__init__.py

@@ -0,0 +1 @@
+"""Public visualiser package."""

agario_kit-2026.1.0/src/agario_visualiser/__main__.py

@@ -0,0 +1,5 @@
+from agario_visualiser.launch_local_match import main
+
+
+if __name__ == "__main__":
+    main()

agario_kit-2026.1.0/src/agario_visualiser/examples/__init__.py

@@ -0,0 +1 @@
+"""Packaged example submissions for fallback local runs."""

agario_kit-2026.1.0/src/agario_visualiser/examples/example.py

@@ -0,0 +1,63 @@
+from helper.game import Game
+from lib.interface.events.moves.move_player import MovePlayer
+from lib.interface.events.moves.typing import MoveType
+from lib.interface.queries.query_move import QueryMovePlayer
+from lib.interface.queries.typing import QueryType
+from lib.models.penguin_model import DirectionModel
+
+
+def choose_direction(game: Game) -> tuple[float, float]:
+    center_x = game.state.me.x
+    center_y = game.state.me.y
+    my_radius = game.state.me.radius
+
+    threats = [
+        (blob.pos[0] - center_x, blob.pos[1] - center_y)
+        for blob in game.state.visible_blobs
+        if blob.radius > my_radius * 1.1
+    ]
+    if threats:
+        nearest = min(threats, key=lambda pos: pos[0] * pos[0] + pos[1] * pos[1])
+        return (-nearest[0], -nearest[1])
+
+    prey = [
+        (blob.pos[0] - center_x, blob.pos[1] - center_y)
+        for blob in game.state.visible_blobs
+        if my_radius > blob.radius * 1.1
+    ]
+    if prey:
+        return min(prey, key=lambda pos: pos[0] * pos[0] + pos[1] * pos[1])
+
+    if game.state.visible_food:
+        return min(
+            [
+                (food.pos[0] - center_x, food.pos[1] - center_y)
+                for food in game.state.visible_food
+            ],
+            key=lambda pos: pos[0] * pos[0] + pos[1] * pos[1],
+        )
+
+    return (0.0, 0.0)
+
+
+def main() -> None:
+    game = Game()
+
+    while True:
+        query = game.get_next_query()
+
+        def choose_move(query: QueryType) -> MoveType:
+            match query:
+                case QueryMovePlayer():
+                    dx, dy = choose_direction(game)
+                    return MovePlayer(
+                        player_id=game.state.me.player_id,
+                        direction=DirectionModel(x=dx, y=dy),
+                    )
+            raise RuntimeError(f"Unsupported query type: {type(query)}")
+
+        game.send_move(choose_move(query))
+
+
+if __name__ == "__main__":
+    main()