Robocode Bot Workspace

A Robocode Tank Royale battle lab.

Build bots. Run controlled fights. Inspect the evidence. Feed what you learn back into targeting, movement, and benchmark opponents.

Upstream: robocode-dev/tank-royale and robocode.dev.

The Arena

Area	Purpose
bots/	Local bots, ported opponents, and shared bot_core code.
scripts/	Setup, packaging, battle, battle-series, telemetry, and A/B entry points.
tools/	Battle runner, telemetry viewer, summaries, motion sanity, audits, and utilities.
docs/	Workflow, architecture, telemetry, and tuning documentation.
tests/	Unit tests for shared bot logic and tooling.

Current local roster:

Bot	Role
Adaptive Prime	Champion candidate with surfing, potential fields, and adaptive firepower.
Chase Lock	Pressure fighter that keeps targets pinned by range and lock discipline.
Circle Strafer	Defensive orbit bot built around survival, spacing, and wall recovery.
Sweep Pressure	Direct-fire pressure bot with sweeping movement and projected wall avoidance.
BasicGFSurfer Port	Ported legacy benchmark and surfer-style sparring partner.

Fastest Fight

Requirements: Python 3.x compatible with the project virtualenv, Java, and a Bash-compatible shell.

cp .env.example .env
scripts/setup.sh
scripts/package.sh
scripts/run-battle.sh --rounds 1 bots/adaptive-prime bots/chase-lock

Watch the instruments:

scripts/run-battle.sh --telemetry --telemetry-open --rounds 1 bots/adaptive-prime bots/chase-lock

CLI battle artifacts are written under battle-results/runs/<timestamp>/. Important files are results.json, runner.log, process.log, optional debug/, optional telemetry/, and optional recordings.

Quick health checks:

PYTHONPATH=bots .venv/bin/python -m pytest
scripts/run-battle.sh --rounds 1 bots/adaptive-prime bots/chase-lock

Core loop: build -> fight -> inspect telemetry -> compare A/B -> tune -> repeat.

Documentation

Need	Read
Setup, packaging, battle running, telemetry, A/B, port-first opponent policy	Tooling
Shared behavior: radar, virtual guns, movement, fire gates, telemetry	Shared Bot Systems
Shared implementation structures: targets, waves, KNN, GF profiles, telemetry records	Bot Core Data Structures
Concrete gun package behavior	Gun Component Docs
Generated telemetry event contract	Telemetry Event Schema
Port converted legacy bots to native Python	Legacy Bot Porting Guideline
Specific bot behavior	Bot Docs
Local championship snapshot	Championship Results

Common workflow anchors:

Workflow	Entry Point
Setup and package bots	Tooling: Setup
Run CLI battles	Tooling: Battles
Use telemetry viewer or schema generation	Tooling: Telemetry
Audit telemetry and summarize gun/combat results	Tooling: Experiment Analysis
Compare baseline and candidate bots	Tooling: A/B Runs
Repeat battles without A/B worktrees	Tooling: Battle Series
Use converted legacy bots for reference or porting	Tooling: Converted Legacy Bots
Port a useful legacy opponent	Legacy Bot Porting Guideline

Local Configuration

Copy .env.example to .env and keep machine-specific paths there. .env, .env.guns, battle-results/, dist/, .venv/, and legacy-bots/ are ignored.

Common settings:

PYTHON_BIN
ROBOCODE_PYTHON_BIN
ROBOCODE_TELEMETRY_DIR
ROBOCODE_TELEMETRY_HOST
ROBOCODE_TELEMETRY_PORT
ROBOCODE_TELEMETRY_OPEN
ROBOCODE_GUN_MODE
ROBOCODE_GUN_SET
ROBOCODE_LEGACY_BOTS_ROOT

Converted legacy bots are optional and mainly for parity or porting reference. Prefer native Python ports under bots/ports/ for repeatable tuning.

License

Licensed under the Apache License, Version 2.0. See LICENSE.