fcode 2.2.0__cp313-cp313-win_amd64.whl

fcode/commands/test_matches.py

@@ -0,0 +1,59 @@
+"""fcode test-matches — list your remote test runs."""
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from fcode.api import api_get
+
+console = Console()
+
+
+def _show_test_matches(limit: int = 20):
+    """Core implementation for listing test matches."""
+    data = api_get("/api/matches/test-runs")
+    match_list = data.get("matches", [])[:limit]
+
+    if not match_list:
+        console.print("[dim]No test runs found.[/dim]")
+        return
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Match ID", style="dim")
+    table.add_column("Score", justify="center")
+    table.add_column("Status")
+    table.add_column("Stage", style="dim")
+    table.add_column("By", style="dim")
+    table.add_column("Date", style="dim")
+
+    for m in match_list:
+        score = f"{m.get('scoreA', 0)}-{m.get('scoreB', 0)}"
+        status = m.get("status", "?")
+        stage = m.get("stage") or ""
+        match_id = m.get("id", "?")
+        requested_by = m.get("requestedByName") or ""
+
+        if status == "complete":
+            status = f"[green]{status}[/green]"
+        elif status == "error":
+            status = f"[red]{status}[/red]"
+            if m.get("errorMessage"):
+                stage = m["errorMessage"][:60]
+        elif status == "running":
+            status = f"[yellow]{status}[/yellow]"
+
+        date = ""
+        raw_date = m.get("completedAt") or m.get("createdAt")
+        if raw_date:
+            date = raw_date[:16].replace("T", " ")
+
+        table.add_row(match_id, score, status, stage, requested_by, date)
+
+    console.print(table)
+
+
+@click.command("test-matches")
+@click.option("--limit", default=20, type=int, help="Number of test runs to show")
+def test_matches(limit: int):
+    """List your remote test run matches."""
+    _show_test_matches(limit)

fcode/commands/test_run.py

@@ -0,0 +1,125 @@
+"""fcode test-run — run a remote test match with local bots and TLE enforcement."""
+
+import io
+import os
+import zipfile
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from fcode.api import api_post_multipart
+from fcode.config import find_config
+
+console = Console()
+
+
+def _zip_bot(bot_path: str, bots_dir: Path) -> bytes:
+    """Resolve a bot path and return it as a zip in memory."""
+    p = Path(bot_path)
+    if not p.exists() and not p.is_absolute():
+        candidate = bots_dir / bot_path
+        if candidate.exists():
+            p = candidate
+
+    if p.is_dir():
+        main_py = p / "main.py"
+        if not main_py.is_file():
+            raise click.BadParameter(f"Directory '{bot_path}' does not contain main.py")
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+            for root, _dirs, files in os.walk(p):
+                for f in files:
+                    full = Path(root) / f
+                    arcname = str(full.relative_to(p))
+                    zf.write(full, arcname)
+        return buf.getvalue()
+
+    if p.is_file() and p.name == "main.py":
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+            zf.write(p, "main.py")
+        return buf.getvalue()
+
+    if p.is_file() and p.suffix == ".zip":
+        return p.read_bytes()
+
+    raise click.BadParameter(f"Bot not found or invalid: '{bot_path}'")
+
+
+def _show_test_run(bot_a: str, bot_b: str, maps: tuple[str, ...]):
+    """Core implementation for running a remote test match."""
+    config, project_root = find_config()
+    bots_dir = (project_root / config.bots_dir).resolve()
+    maps_dir = (project_root / config.maps_dir).resolve()
+
+    console.print("[bold]Packaging bots...[/bold]")
+    try:
+        zip_a = _zip_bot(bot_a, bots_dir)
+        zip_b = _zip_bot(bot_b, bots_dir)
+    except click.BadParameter as e:
+        console.print(f"[red]{e.format_message()}[/red]")
+        raise SystemExit(1)
+
+    files: dict[str, tuple[str, bytes, str]] = {
+        "bot_a": ("bot_a.zip", zip_a, "application/zip"),
+        "bot_b": ("bot_b.zip", zip_b, "application/zip"),
+    }
+    text_fields: dict[str, str] = {
+        "bot_a_name": Path(bot_a).stem,
+        "bot_b_name": Path(bot_b).stem,
+    }
+
+    if len(maps) > 5:
+        console.print("[red]Maximum 5 maps per test run.[/red]")
+        raise SystemExit(1)
+
+    if maps:
+        from fcode.commands.run import resolve_map_path
+
+        resolved_maps: list[Path] = []
+        for map_arg in maps:
+            mp = resolve_map_path(map_arg, maps_dir)
+            if not mp.is_file():
+                console.print(f"[red]Map file not found: {map_arg}[/red]")
+                raise SystemExit(1)
+            resolved_maps.append(mp)
+
+        for i, mp in enumerate(resolved_maps):
+            files[f"map_{i}"] = (mp.name, mp.read_bytes(), "application/octet-stream")
+        text_fields["num_maps"] = str(len(resolved_maps))
+
+        map_names = ", ".join(mp.stem for mp in resolved_maps)
+        console.print(f"  Maps: {map_names} ({len(resolved_maps)} game{'s' if len(resolved_maps) != 1 else ''})")
+
+    console.print("[bold]Uploading and submitting test run...[/bold]")
+    data = api_post_multipart("/api/matches/test-run", files, text_fields)
+
+    match_id = data.get("matchId")
+    if not match_id:
+        console.print("[red]Unexpected response from server.[/red]")
+        raise SystemExit(1)
+
+    console.print(f"[green]Test run queued![/green] Match ID: {match_id}")
+    console.print(f"  Check status: fcode match tests")
+
+
+@click.command("test-run")
+@click.argument("bot_a")
+@click.argument("bot_b")
+@click.argument("maps", nargs=-1)
+def test_run(bot_a: str, bot_b: str, maps: tuple[str, ...]):
+    """Run a remote test match between two local bots with TLE enforcement.
+
+    \b
+    BOT_A and BOT_B can be directories (containing main.py), single .py files,
+    or .zip archives — same as `fcode run`.
+    MAPS are optional .map26 files — one per game. If omitted, 5 random maps.
+
+    \b
+    Examples:
+      fcode test-run starter starter
+      fcode test-run bot_a bot_b arena.map26
+      fcode test-run bot_a bot_b arena.map26 canyon.map26 arena.map26
+    """
+    _show_test_run(bot_a, bot_b, maps)

fcode/commands/watch.py

@@ -0,0 +1,123 @@
+"""fcode watch — open replay in local or platform visualizer."""
+
+import click
+from rich.console import Console
+
+console = Console()
+
+
+@click.command()
+@click.argument("replay_file", required=False, type=click.Path(exists=True))
+@click.option("--match", "match_id", type=str, help="Match ID to view on platform")
+@click.option("--game", "game_number", type=int, help="Game number within match")
+def watch(replay_file: str | None, match_id: str | None, game_number: int | None):
+    """Open replay in visualizer.
+
+    \b
+    Examples:
+      fcode watch replay.replay26        # View local replay file
+      fcode watch --match <id>           # Open match on platform
+      fcode watch --match <id> --game 3  # Open specific game
+    """
+    if match_id:
+        _open_platform(match_id, game_number)
+        return
+
+    if not replay_file:
+        console.print("[red]Provide a replay file or use --match <id>[/red]")
+        console.print("[dim]  fcode watch replay.replay26[/dim]")
+        console.print("[dim]  fcode watch --match <match-id>[/dim]")
+        raise SystemExit(1)
+
+    _serve_local(replay_file)
+
+
+def _open_platform(match_id: str, game_number: int | None) -> None:
+    """Open the platform visualiser page in the user's browser."""
+    import webbrowser
+    from fcode.auth import get_api_url
+
+    base_url = get_api_url()
+    url = f"{base_url}/visualiser?matchId={match_id}"
+    if game_number is not None:
+        url += f"&game={game_number}"
+
+    console.print(f"Opening visualiser: [link={url}]{url}[/link]")
+    webbrowser.open(url)
+
+
+def _find_dist() -> "str | None":
+    """Find the visualiser dist directory. Returns dist_path or None."""
+    from pathlib import Path
+
+    mono_dist = Path(__file__).parent.parent.parent.parent.parent / "visualiser" / "dist"
+    bundled_dist = Path(__file__).parent.parent / "data" / "visualiser"
+
+    if (mono_dist / "index.html").is_file():
+        return str(mono_dist.resolve())
+    if (bundled_dist / "index.html").is_file():
+        return str(bundled_dist.resolve())
+    return None
+
+
+def _serve_local(replay_file: str) -> None:
+    """Serve the visualiser locally with a replay file auto-loaded."""
+    import http.server
+    import threading
+    import webbrowser
+    from pathlib import Path
+
+    replay_path = Path(replay_file).resolve()
+
+    dist_path = _find_dist()
+    if not dist_path:
+        console.print(
+            "[red]Visualiser not found. "
+            "Try reinstalling fcode or use --match <id> to view on the platform.[/red]"
+        )
+        raise SystemExit(1)
+
+    # Ensure correct MIME types on Windows (registry may map .js to text/plain)
+    import mimetypes
+
+    mimetypes.add_type("application/javascript", ".js")
+    mimetypes.add_type("application/javascript", ".mjs")
+    mimetypes.add_type("application/wasm", ".wasm")
+    mimetypes.add_type("text/css", ".css")
+
+    class ReplayHandler(http.server.SimpleHTTPRequestHandler):
+        def __init__(self, *args, **kwargs):
+            super().__init__(*args, directory=dist_path, **kwargs)
+
+        def do_GET(self):
+            if self.path == "/local-replay":
+                try:
+                    data = replay_path.read_bytes()
+                    self.send_response(200)
+                    self.send_header("Content-Type", "application/octet-stream")
+                    self.send_header("Content-Length", str(len(data)))
+                    self.end_headers()
+                    self.wfile.write(data)
+                except Exception:
+                    self.send_error(500, "Failed to read replay file")
+                return
+            super().do_GET()
+
+        def log_message(self, format, *args):
+            pass
+
+    server = http.server.HTTPServer(("127.0.0.1", 0), ReplayHandler)
+    port = server.server_address[1]
+
+    url = f"http://127.0.0.1:{port}/?replayUrl=/local-replay"
+    console.print(f"Serving visualiser at [link={url}]{url}[/link]")
+    console.print(f"Replay: {replay_path.name}")
+    console.print("[dim]Press Ctrl+C to stop[/dim]")
+
+    threading.Timer(0.5, lambda: webbrowser.open(url)).start()
+
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        console.print("\n[dim]Stopped.[/dim]")
+        server.shutdown()

fcode/compat.py

@@ -0,0 +1,36 @@
+"""Backwards-compatibility helpers for CLI restructuring."""
+
+import click
+from rich.console import Console
+
+console = Console()
+
+_SHOWN_WARNINGS: set[str] = set()
+
+
+def deprecation_warning(old: str, new: str) -> None:
+    """Print a one-time deprecation warning suggesting the new command."""
+    key = f"{old}->{new}"
+    if key not in _SHOWN_WARNINGS:
+        _SHOWN_WARNINGS.add(key)
+        console.print(
+            f"[yellow]Warning: `fcode {old}` is deprecated. Use: fcode {new}[/yellow]\n"
+        )
+
+
+class SmartGroup(click.Group):
+    """A Click group that routes unknown subcommands to a default command.
+
+    If the first argument isn't a known subcommand, it's treated as an
+    argument to the default command (e.g. `fcode match <uuid>` routes to
+    `fcode match info <uuid>`).
+    """
+
+    def __init__(self, *args, default_cmd: str = "info", **kwargs):
+        super().__init__(*args, **kwargs)
+        self.default_cmd = default_cmd
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        if args and args[0] not in self.commands and not args[0].startswith("-"):
+            args = [self.default_cmd] + args
+        return super().parse_args(ctx, args)

fcode/config.py

@@ -0,0 +1,47 @@
+import sys
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    try:
+        import tomllib
+    except ModuleNotFoundError:
+        import tomli as tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+CONFIG_FILENAME = "fcode.toml"
+
+
+@dataclass
+class FcodeConfig:
+    bots_dir: str = "bots"
+    maps_dir: str = "maps"
+    replay: str = "replay.replay26"
+    seed: int = 1
+
+
+def find_config() -> tuple[FcodeConfig, Path]:
+    """Walk up from cwd to find fcode.toml. Returns (config, project_root)."""
+    cwd = Path.cwd().resolve()
+    for directory in [cwd] + list(cwd.parents):
+        config_path = directory / CONFIG_FILENAME
+        if config_path.is_file():
+            raw = config_path.read_bytes()
+            try:
+                data = tomllib.loads(raw.decode("utf-8"))
+            except UnicodeDecodeError:
+                # Fix files written with system encoding (e.g. cp1252 on Windows)
+                data = tomllib.loads(raw.decode("utf-8", errors="replace"))
+                config_path.write_bytes(raw.decode("utf-8", errors="replace").encode("utf-8"))
+            return _parse_config(data), directory
+    return FcodeConfig(), cwd
+
+
+def _parse_config(data: dict) -> FcodeConfig:
+    return FcodeConfig(
+        bots_dir=data.get("bots_dir", FcodeConfig.bots_dir),
+        maps_dir=data.get("maps_dir", FcodeConfig.maps_dir),
+        replay=data.get("replay", FcodeConfig.replay),
+        seed=data.get("seed", FcodeConfig.seed),
+    )

fcode/data/docs/spec.md

@@ -0,0 +1,290 @@
+# Background
+
+The year is 2076. Titan, Saturn's largest moon, has become the new frontier for autonomous resource extraction. At least six corporations have deployed robotic fleets to its surface, claiming deposits, building infrastructure, and contesting rival operations. None of this has been publicly disclosed.
+
+Titan is lethal to humans: −179°C, a nitrogen-methane atmosphere, and a 76-minute communication delay to Earth. All operations are carried out by robots.
+
+You are a programmer employed by **Meridian Industries** under the classified ASO (Autonomous Systems Operations) programme. Your job is to write the software that controls Meridian's fleet: mining ore, delivering resources, and outcompeting whoever else is out there.
+
+# Objective
+
+The objective of the game is to collect resources and destroy the enemy's core.
+To do this, you must find ore deposits, build harvesters, deliver resources back to the core using conveyors, and expand your territory.
+
+If both teams' cores are still alive after 1000 rounds, the winner is decided by the following tiebreakers, in order:
+
+- Total amount of titanium delivered to the core
+- Number of harvesters currently alive
+- Total titanium currently stored
+- Coinflip
+
+# Map
+
+The map is a rectangular grid whose size is between 8x8 and 30x30 inclusive.
+The top left (northwest) corner of the map is position (0, 0).
+It is guaranteed that the map is symmetric by either reflection or rotation.
+
+Each grid cell is one of the following:
+
+- Wall
+- Titanium ore
+- Empty
+
+Walls prevent building anything on the tile they occupy.
+Ores are tiles on which harvesters may be built to mine resources.
+
+# Resources
+
+## Titanium
+
+Titanium is the primary resource used to construct most buildings in the game.
+Each team starts with 500 global titanium.
+Additionally, each team gains 10 passive titanium every 4 rounds.
+
+# Communication
+
+Each team has a **Global Communication Store**: 16 integer slots (indexed 0-15), readable and writable by every unit on that team via `read_store(index)` / `write_store(index, value)`. Each team's store is private -- the opposing team can neither read nor write it.
+
+Writes are buffered: a write made during a round is not visible until the following round, not even to the unit that made it. This guarantees every unit sees a consistent snapshot of the store for the entire round, regardless of the order units act in.
+
+# Units and Buildings
+
+## Units
+
+Units are game entities which run an independent instance of the code that you submit.
+The core, builder bots, and turrets are units. Harvesters are **not** units.
+
+Each round, units take their turns in the order they were spawned.
+After all units have taken their turn, resources are distributed (see below).
+
+Each team may have at most 50 living units at once, including its core.
+Bots can query their current usage of this cap with `get_unit_count()` and compare it against `GameConstants.MAX_TEAM_UNITS`.
+
+Units have a **vision radius** and an **action radius**.
+The vision radius is the area in which the unit can sense its environment.
+The action radius is the area in which the unit can perform actions, such as building or destroying buildings.
+All units have an action radius of sqrt(2), except the core, which has an action radius of sqrt(8) (measured from its centre).
+Turrets also have a **attack range** which is different from its action radius.
+
+All units have action and move cooldowns which are nonnegative integers that decrease by 1 at the end of each round.
+(The move cooldown is only used by the builder bot.)
+Actions and movement can only be done when the respective cooldown is 0.
+
+Units may self-destruct at any time.
+
+## Buildings
+
+Buildings are game entities which are immovable. All entities are buildings except builder bots.
+In particular, the core and turrets are considered _both a unit and a building_.
+
+## Note: cost scaling
+
+The cost of a building or unit is floor(scale \* base cost) where scale starts at 1.0 and increases with each entity built:
+conveyors, splitters, barriers add +1% each; harvesters add +5% each; gunners, launchers add +10% each; builder bots and sentinels add +20% each.
+When an entity is destroyed, its contribution is removed. This is to encourage you to be efficient with what you build!
+
+## Core
+
+The core is each team's central building -- if your core is destroyed, you lose the game.
+Each team starts with one core.
+
+It has a 2x2 footprint and has a vision radius of 6 and an action radius of sqrt(8) (measured from the nearest tile of its footprint).
+Resources must be transferred to the core (via conveyors) to be added to the global pool which is used for building.
+
+The core can spawn up to one builder bot per turn on any tile immediately surrounding its footprint (orthogonally or diagonally adjacent, but not on the footprint itself), which costs one action cooldown.
+
+HP: 500
+
+## Builder bot
+
+Builder bots are the only mobile unit -- they are responsible for constructing buildings.
+
+Builder bots have a vision radius of sqrt(20) and an action radius of sqrt(2).
+
+Builder bots can move onto any tile that does not contain another builder bot, provided it is not a wall and either has no building on it, or has a conveyor or splitter belonging to either team.
+These are considered _walkable_ tiles.
+The direction of the conveyor or splitter does not matter, and neither does the presence of resources on the tile.
+
+A builder bot may move to an adjacent (including diagonal) tile if its move cooldown is 0, increasing it by 1.
+
+If its action cooldown is 0, a builder bot may perform one of the following actions, increasing its action cooldown by 1:
+
+**Build**: build any building or turret on a tile without a building within its action radius.
+Only _walkable_ buildings (conveyors and splitters) may be built on a tile which contains a builder bot.
+
+**Attack**: spend 2 Ti to deal 2 damage to the building on the tile it is standing on.
+
+**Heal**: spend 1 Ti to heal all friendly entities on a tile within the builder bot's action radius by 4 HP.
+If a friendly builder bot is standing on a friendly building there, both are healed.
+
+Builder bots may also destroy any allied building within its action radius any number of times per turn.
+
+Finally, self-destructing a builder bot deals no damage.
+
+HP: 40
+Base cost: 30 Ti
+Scaling contribution: 20%
+
+## Note: resource distribution
+
+Some buildings, such as conveyors, may store, accept and output resources.
+Resources are always stored and moved in stacks of 10.
+
+At the end of each round, resources are distributed. Buildings may accept resources, output resources, or both.
+**Resources may be outputted to a building belonging to the opposing team.**
+
+The details of resource distribution are given in the per-building descriptions below.
+
+## Conveyors
+
+All conveyors can hold one stack of any resource, and both accept input and produce output.
+Basic conveyors and splitters point in one of the cardinal directions.
+
+### Conveyor
+
+Accepts resources from any of its three non-output directions.
+Sends its contents in the direction it is pointing if that tile can accept a resource.
+
+Base cost: 3 Ti
+Scaling contribution: 1%
+HP: 20
+
+### Splitter
+
+Alternates between outputting in three directions: the primary output direction and the two adjacent directions.
+Only accepts input from the back.
+Prioritises outputting in directions which were used the least recently.
+
+Base cost: 6 Ti
+Scaling contribution: 1%
+HP: 20
+
+## Harvester
+
+Can be placed on an ore deposit. Outputs one stack of the corresponding resource to an adjacent building every 4 rounds.
+The first resource will be outputted immediately on the round the harvester is built.
+
+Prioritises outputting in directions which were used the least recently.
+
+Base cost: 20 Ti
+Scaling contribution: 5%
+HP: 30
+
+## Barrier
+
+Cheap, takes up space and has high HP.
+
+Base cost: 3 Ti
+Scaling contribution: 1%
+HP: 30
+
+## Turrets
+
+Every turret except the launcher faces in one of 8 directions.
+Ammo must be fed to turrets via conveyors, from any direction apart except the direction the turret is facing.
+Diagonal turrets can be fed from all four sides.
+A turret can hold up to one stack of one type of resource and only accepts incoming resources when it is completely empty.
+If a tile containing both a building and a builder bot is hit, only the builder bot takes damage.
+
+### Gunner
+
+Has a vision radius of sqrt(13). A gunner traces a straight line in the direction it is facing. Empty tiles do not block this line. Walls block the line but are not targetable. Builder bots and buildings are both targetable and blocking.
+Gunners can also rotate to any other direction by calling `rotate(direction)`, spending 10 Ti and taking a 1-turn cooldown.
+
+Base cost: 10 Ti
+Scaling contribution: 10%
+HP: 40
+Damage: 10
+Reload: 1
+Resources per shot: 2
+
+### Sentinel
+
+High range, low damage support turret.
+Vision range is sqrt(32). Can hit all tiles within 1 king move (chebyshev distance) of the straight line in the direction it's facing, within vision range.
+
+Base cost: 30 Ti
+Scaling contribution: 20%
+HP: 30
+Damage: 18
+Reload: 3
+Resources per shot: 10
+
+### Launcher
+
+Can pick up and throw adjacent (including diagonal) builder bots. The target tile must be bot-passable.
+
+Vision range and attack range are both sqrt(26).
+
+Base cost: 20 Ti
+Scaling contribution: 10%
+HP: 30
+Reload: 1
+
+# Reference table
+
+| Entity      | HP  | Base cost | Scale % | Notes                                                            |
+| ----------- | --- | --------- | ------- | ---------------------------------------------------------------- |
+| Core        | 500 | —         | —       | 2×2 footprint; spawns builder bots                               |
+| Builder bot | 40  | 30 Ti     | 20%     | Mobile; can build and heal in action radius, and attack own tile |
+| Conveyor    | 20  | 3 Ti      | 1%      | Cardinal direction; 3 inputs, 1 output                           |
+| Splitter    | 20  | 6 Ti      | 1%      | 1 input (back), 3 rotating outputs                               |
+| Harvester   | 30  | 20 Ti     | 5%      | Outputs a stack of resources every 4 rounds                      |
+| Barrier     | 30  | 3 Ti      | 1%      |                                                                  |
+| Gunner      | 40  | 10 Ti     | 10%     | Targets occupied tiles in facing direction; can rotate for 10 Ti |
+| Sentinel    | 30  | 30 Ti     | 20%     | Line AoE ±1                                                      |
+| Launcher    | 30  | 20 Ti     | 10%     | Throws adjacent builder bots                                     |
+
+## Unit stats
+
+| Unit        | Vision r² | Action r²  | Attack r²     | Damage                   | Reload | Ammo/shot |
+| ----------- | --------- | ---------- | ------------- | ------------------------ | ------ | --------- |
+| Core        | 36        | 8          | —             | —                        | —      | —         |
+| Builder bot | 20        | 2          | 0 (own tile)  | 2 (building on own tile) | 1      | 2 Ti      |
+| Gunner      | 13        | 2          | 13 (= vision) | 10                       | 1      | 2         |
+| Sentinel    | 32        | 2          | 32 (= vision) | 18                       | 3      | 10        |
+| Launcher    | 26        | 2 (pickup) | 26 (throw)    | —                        | 1      | —         |
+
+# Appendix: implementation details
+
+## Documentation
+
+API methods are not all covered in this document.
+Refer to the documentation for a comprehensive list of all available methods.
+
+## Entity IDs
+
+All entities (buildings and units) in the game have a unique integer ID.
+All controller methods which deal with entities will accept and return entity IDs.
+Properties of an entity can be queried with the appropriate getter function, for example, `get_hp(id)`.
+This API design was chosen for performance reasons, as constructing Python objects to return is very slow.
+
+Resources moving through storage and conveyors also have unique integer IDs.
+These are resource stack IDs, not entity IDs, and can be queried with `get_stored_resource_id(id)`.
+
+## Computation limit
+
+Each unit is allocated 10 milliseconds of CPU time per turn.
+If your code exceeds the time limit, execution will be interrupted, and the next turn the run() function will be called again.
+**Your bot does not resume next turn where it left off.**
+
+To mitigate variance in runtime, each unit has an **extra time buffer** that is 5% of the time limit.
+If the bot takes longer than the normal time limit, then the difference is deducted from the extra time buffer.
+Once the bot reaches (time limit + extra time) runtime, it is interrupted.
+**If the bot takes less time than the time limit, then the difference is refunded to the extra time buffer.**
+The extra time buffer is capped at 5% of the normal time limit.
+
+### Testing against the time limit
+
+The local runner will not check for the time limit, as execution time differs by machine.
+Instead, we will provide execution servers for you to test your own bots against the time limit on the same machines that run ladder matches.
+
+## Debugging
+
+We provide several debugging utilities.
+
+Printing to stdout (normal `print()`) is captured by the engine and saved to the replay.
+You can then view your units' stdout output in the visualiser.
+To print to the console, use stderr.
+
+You can also use `draw_indicator_line()` and `draw_indicator_dot()` to draw debugging information on the map itself.