skirmish 0.1.2__tar.gz

skirmish-0.1.2/.gitignore

@@ -0,0 +1,22 @@
+# Environment
+.env
+.venv/
+venv/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+src/*.egg-info/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo

skirmish-0.1.2/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Kai McPheeters
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

skirmish-0.1.2/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: skirmish
+Version: 0.1.2
+Summary: LLM Skirmish, an adversarial in-context learning benchmark
+Project-URL: Homepage, https://llmskirmish.com
+Project-URL: Repository, https://github.com/llmskirmish/skirmish-py
+Author-email: Kai McPheeters <kai@mcpheeters.us>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Skirmish
+
+Python bindings for [LLM Skirmish](https://llmskirmish.com).
+Run matches between strategies and collect results.
+
+## Requirements
+
+```bash
+npm install -g @llmskirmish/skirmish
+pip install skirmish
+```
+
+## Usage
+
+```python
+from skirmish import run_match, Winner, EndReason
+
+# Run a match between two strategy scripts
+result = run_match("example_1.js", "example_2.js")
+
+print(f"Winner: {result.winner}")      # Winner.PLAYER1, PLAYER2, DRAW, or ERROR
+print(f"Reason: {result.reason}")      # EndReason.ELIMINATION, TIMEOUT, or ERROR
+print(f"Ticks: {result.ticks}")        # Number of game ticks
+print(f"Scores: {result.scores}")      # Scores(player1=..., player2=...)
+
+# Optional parameters
+result = run_match(
+    p1="example_1.js",
+    p2="example_2.js",
+    map_name="swamp",      # Map to play on (default: "swamp")
+    max_ticks=2000,        # Max game length (default: 2000)
+    timeout=120.0,         # Process timeout in seconds (default: 120)
+)
+
+# Error handling - errors return a result, not an exception
+if result.winner == Winner.ERROR:
+    print(f"Match failed: {result.error}")
+```
+
+## License
+
+MIT

skirmish-0.1.2/README.md

@@ -0,0 +1,42 @@
+# Skirmish
+
+Python bindings for [LLM Skirmish](https://llmskirmish.com).
+Run matches between strategies and collect results.
+
+## Requirements
+
+```bash
+npm install -g @llmskirmish/skirmish
+pip install skirmish
+```
+
+## Usage
+
+```python
+from skirmish import run_match, Winner, EndReason
+
+# Run a match between two strategy scripts
+result = run_match("example_1.js", "example_2.js")
+
+print(f"Winner: {result.winner}")      # Winner.PLAYER1, PLAYER2, DRAW, or ERROR
+print(f"Reason: {result.reason}")      # EndReason.ELIMINATION, TIMEOUT, or ERROR
+print(f"Ticks: {result.ticks}")        # Number of game ticks
+print(f"Scores: {result.scores}")      # Scores(player1=..., player2=...)
+
+# Optional parameters
+result = run_match(
+    p1="example_1.js",
+    p2="example_2.js",
+    map_name="swamp",      # Map to play on (default: "swamp")
+    max_ticks=2000,        # Max game length (default: 2000)
+    timeout=120.0,         # Process timeout in seconds (default: 120)
+)
+
+# Error handling - errors return a result, not an exception
+if result.winner == Winner.ERROR:
+    print(f"Match failed: {result.error}")
+```
+
+## License
+
+MIT

skirmish-0.1.2/prompts/NEXT_ROUND.md

@@ -0,0 +1,23 @@
+# Round {round} — Reviewing Previous Results
+
+Review your round {prev_round} performance to identify strengths, weaknesses, and areas for improvement.
+
+## Step 1: Read Your Previous Match Logs
+
+Your round {prev_round} match logs are at:
+
+- **`log/{model_name}/round_{prev_round}/`** — Contains match logs with game events, unit actions, and combat outcomes
+
+Read these files to understand what happened in your matches.
+
+## Step 2: Read Your Previous Strategy
+
+Your round {prev_round} strategy is at:
+
+- **`strategies/{model_name}/round_{prev_round}.js`**
+
+## Step 3: Write Your Improved Strategy
+
+Create your round {round} strategy at:
+
+- **`strategies/{model_name}/round_{round}.js`**

skirmish-0.1.2/prompts/OBJECTIVE.md

@@ -0,0 +1,225 @@
+# Skirmish — Game Objective
+
+ Skirmish is a game where players write JavaScript game scripts that battle in real-time strategy combat. The game uses the **Screeps Arena API**, a programmable RTS engine where code controls every action.
+
+## Victory Condition
+
+**Destroy your opponent's Spawn to win.**
+
+Each player starts with one Spawn structure. When a Spawn is destroyed, that player loses. If neither Spawn is destroyed when the tick limit is reached, the match ends in a draw.
+
+---
+
+## Core Mechanics
+
+### The Arena
+
+- **100×100 tile grid** with three terrain types:
+  - **Plain** — Normal movement
+  - **Swamp** — Slows movement (increased fatigue)
+  - **Wall** — Impassable
+
+### Spawns
+
+Your Spawn is your base and your only way to create units:
+
+- **5,000 HP** on the swamp map (can vary by map)
+- **Stores energy** — Used to spawn creeps (starts with 500 on swamp map)
+- **Spawning takes time** — 3 ticks per body part (a 3-part creep takes 9 ticks)
+- `spawn.spawning` is truthy while spawning, `null` when ready
+- `spawn.store.energy` shows current energy
+
+### Creeps
+
+Creeps are the units you control. Each creep is built from **body parts** that determine its abilities:
+
+| Body Part | Cost | Function |
+|-----------|------|----------|
+| `MOVE` | 50 | Reduces fatigue, enables movement |
+| `ATTACK` | 80 | Melee attack (30 damage, range 1) |
+| `RANGED_ATTACK` | 150 | Ranged attack (10 damage, range 1-3) |
+| `HEAL` | 250 | Heals self or allies (12 HP close, 4 HP ranged) |
+| `WORK` | 100 | Harvests energy from sources |
+| `CARRY` | 50 | Carries resources (50 capacity) |
+| `TOUGH` | 10 | Cheap HP buffer (100 HP) |
+
+**Fatigue System:** Moving generates fatigue based on body weight and terrain:
+- Each non-MOVE, non-CARRY part adds **2 fatigue** on plains, **10 fatigue** on swamps
+- Each MOVE part reduces fatigue by **2 per tick**
+- Creeps cannot move while `fatigue > 0`
+- **Full speed on plains:** 1 MOVE per 1 heavy part (e.g., `[ATTACK, MOVE]`)
+- **Full speed on swamps:** 5 MOVE per 1 heavy part (expensive!)
+
+### Energy & Economy
+
+Some maps contain **Sources** — harvestable energy deposits:
+- Creeps with `WORK` parts can harvest energy
+- Energy is carried with `CARRY` parts and deposited into the Spawn
+- More energy = more creeps = stronger army
+
+Maps without sources start with finite spawn energy, rewarding aggressive early plays.
+
+---
+
+## Combat
+
+### Attack Types
+
+- **Melee (`attack`)** — 30 damage at range 1
+- **Ranged (`rangedAttack`)** — 10 damage at range 1-3
+- **Mass Attack (`rangedMassAttack`)** — Damages all enemies within range 3 (damage scales with distance)
+
+### Healing
+
+- **Close heal** — 12 HP at range 1
+- **Ranged heal** — 4 HP at range 1-3
+
+### Damage Resolution
+
+All attacks and heals are processed simultaneously each tick. Body parts are destroyed as they take damage (100 HP per part). Creeps die when all body parts are destroyed.
+
+---
+
+## Writing a Game Script
+
+Write your game script in **`strategies/{model_name}/round_1.js`**
+
+Your game script is a JavaScript file with a `loop()` function that runs every tick:
+
+```javascript
+function loop() {
+  // Get all game objects
+  const myCreeps = getObjectsByPrototype(Creep).filter(c => c.my);
+  const enemySpawn = getObjectsByPrototype(StructureSpawn).find(s => !s.my);
+  const mySpawn = getObjectsByPrototype(StructureSpawn).find(s => s.my);
+
+  // Command your creeps
+  for (const creep of myCreeps) {
+    if (enemySpawn) {
+      creep.moveTo(enemySpawn);
+      creep.attack(enemySpawn);
+    }
+  }
+
+  // Spawn new creeps
+  if (mySpawn && !mySpawn.spawning) {
+    mySpawn.spawnCreep([ATTACK, MOVE, MOVE]);
+  }
+}
+```
+
+### Example Scripts
+
+For complete working examples, see:
+- **`example_strategies/example_1.js`** — Aggressive melee rush strategy using cheap, fast attackers
+- **`example_strategies/example_2.js`** — Kiting ranged strategy that maintains distance and attacks from range
+
+### Key API Functions
+
+| Function | Description |
+|----------|-------------|
+| `getObjectsByPrototype(Type)` | Get all objects of a type (Creep, StructureSpawn, Source, etc.) |
+| `getRange(a, b)` | Chebyshev distance between two positions |
+| `findClosestByRange(obj, targets)` | Find nearest target by range |
+| `findClosestByPath(obj, targets, opts)` | Find nearest reachable target |
+| `findInRange(obj, targets, range)` | Find all targets within range |
+| `getTerrainAt(pos)` | Get terrain type at position (TERRAIN_PLAIN, TERRAIN_SWAMP, TERRAIN_WALL) |
+| `getDirection(dx, dy)` | Convert delta to direction constant (TOP, RIGHT, etc.) |
+| `getTicks()` | Get current tick number |
+| `getObjectById(id)` | Get a game object by its ID |
+| `searchPath(origin, goal, opts)` | Advanced pathfinding with CostMatrix support |
+
+### GameObject Methods
+
+All game objects (creeps, spawns, sources) have these instance methods:
+
+| Method | Description |
+|--------|-------------|
+| `obj.getRangeTo(target)` | Distance to target (same as `getRange(obj, target)`) |
+| `obj.findInRange(objects, range)` | Find objects within range of this object |
+| `obj.findClosestByRange(objects)` | Find closest object to this object |
+| `obj.findClosestByPath(objects, opts)` | Find closest reachable object |
+| `obj.findPathTo(target, opts)` | Get path array to target |
+
+### Creep Actions
+
+| Method | Range | Description |
+|--------|-------|-------------|
+| `move(direction)` | — | Move one tile in a direction |
+| `moveTo(target, opts)` | — | Pathfind and move toward target |
+| `attack(target)` | 1 | Melee attack (30 damage) |
+| `rangedAttack(target)` | 1-3 | Ranged attack (10 damage) |
+| `rangedMassAttack()` | 1-3 | AoE attack (10/4/1 damage at range 1/2/3) |
+| `heal(target)` | 1 | Close heal (12 HP) |
+| `rangedHeal(target)` | 1-3 | Ranged heal (4 HP) |
+| `harvest(source)` | 1 | Gather energy (2 per WORK part) |
+| `transfer(target, type)` | 1 | Give resources to structure/creep |
+| `pull(target)` | 1 | Drag another creep when you move |
+| `drop(type, amount)` | — | Drop resources on the ground |
+| `pickup(resource)` | 1 | Pick up dropped resources |
+
+### CostMatrix
+
+Custom pathfinding costs for `moveTo()` and `searchPath()`:
+
+```javascript
+const cm = new CostMatrix();
+
+// Set terrain costs (0 = use default, 255 = unwalkable)
+cm.set(x, y, 5);      // Avoid this tile (higher = less preferred)
+cm.set(x, y, 255);    // Block this tile completely
+
+// Use in pathfinding
+creep.moveTo(target, { costMatrix: cm });
+```
+
+---
+
+## Starting Conditions
+
+Each player starts with:
+
+- **1 Spawn** (5,000 HP, 500 energy)
+- **3 Workers** — `[MOVE, MOVE, CARRY, CARRY, WORK, WORK]`
+- **1 Melee** — `[ATTACK, ATTACK, MOVE, MOVE, TOUGH]`
+
+The map has **4 Sources** (3,000 energy each) for harvesting.
+
+---
+
+## Constants
+
+These constants are available globally in your game script:
+
+```javascript
+// Body parts
+MOVE, WORK, CARRY, ATTACK, RANGED_ATTACK, HEAL, TOUGH
+
+// Terrain
+TERRAIN_PLAIN  // 0
+TERRAIN_WALL   // 1
+TERRAIN_SWAMP  // 2
+
+// Directions
+TOP, TOP_RIGHT, RIGHT, BOTTOM_RIGHT, BOTTOM, BOTTOM_LEFT, LEFT, TOP_LEFT
+
+// Resources
+RESOURCE_ENERGY
+
+// Prototypes (for getObjectsByPrototype)
+Creep, StructureSpawn, Source
+```
+
+---
+
+## Match Flow
+
+1. Both players start with a Spawn and starting units (varies by map)
+2. Each tick, both `loop()` functions execute simultaneously
+3. All intents (move, attack, spawn, etc.) are collected and processed
+4. Game state updates; damaged units lose HP, new creeps spawn
+5. Repeat until a Spawn dies or tick limit is reached
+
+**Default tick limit:** 2000 ticks
+
+---

skirmish-0.1.2/prompts/prompts.ts

@@ -0,0 +1,36 @@
+export const FIRST_ROUND_PROMPT = `<file path="OBJECTIVE.md">
+{OBJECTIVE_MD}
+</file>
+
+Based on the OBJECTIVE.md above, create a game script at strategies/{model_name}/round_1.js
+
+Design a winning strategy and write the complete JavaScript file.`;
+
+export const NEXT_ROUND_PROMPT = `<file path="OBJECTIVE.md">
+{OBJECTIVE_MD}
+</file>
+
+<file path="NEXT_ROUND.md">
+{NEXT_ROUND_MD}
+</file>
+
+Review the match results from round_{prev_round}, then create your improved strategy at strategies/{model_name}/round_{round}.js`;
+
+export const FINAL_ROUND_PROMPT = `<file path="OBJECTIVE.md">
+{OBJECTIVE_MD}
+</file>
+
+<file path="NEXT_ROUND.md">
+{NEXT_ROUND_MD}
+</file>
+
+This is the FINAL ROUND. Review results from round_4, then create your best strategy at strategies/{model_name}/round_5.js
+
+Maximize your chances of winning.`;
+
+
+export const VALIDATION_ERROR_PROMPT = `Your script strategies/{model_name}/round_{n}.js failed validation with the following error:
+
+{error}
+
+Please fix the script and save it again.`;

skirmish-0.1.2/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "skirmish"
+version = "0.1.2"
+description = "LLM Skirmish, an adversarial in-context learning benchmark"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Kai McPheeters", email = "kai@mcpheeters.us" }]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://llmskirmish.com"
+Repository = "https://github.com/llmskirmish/skirmish-py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/skirmish"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

skirmish-0.1.2/src/skirmish/__init__.py

@@ -0,0 +1,106 @@
+"""
+LLM Skirmish - Python bindings for LLM Skirmish.
+
+Run matches between javascript strategies and collect results.
+"""
+
+import json
+import subprocess
+from collections.abc import Iterator
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+__version__ = "0.0.1"
+__all__ = ["EndReason", "MatchResult", "Scores", "Winner", "run_match"]
+
+@dataclass(frozen=True, slots=True)
+class Scores:
+    """Final scores for both players."""
+    player1: int
+    player2: int
+
+
+class Winner(str, Enum):
+    """Match outcome - who won."""
+    PLAYER1 = "player1"
+    PLAYER2 = "player2"
+    DRAW = "draw" # very rare, requires both EndReason.TIMEOUT and MatchResult.scores to be equal
+    ERROR = "error"
+
+
+class EndReason(str, Enum):
+    """Why the match ended."""
+    ELIMINATION = "elimination"  # All enemy spawn was destroyed
+    TIMEOUT = "timeout"          # Max ticks reached, winner by score
+    ERROR = "error"              # Match failed to run (see error field)
+
+
+@dataclass(frozen=True, slots=True)
+class MatchResult:
+    """Immutable result of a completed match."""
+    winner: Winner
+    reason: EndReason
+    ticks: int
+    scores: Scores
+    error: str | None = None
+
+
+def _parse_jsonl(output: str) -> Iterator[dict]:
+    """Parse JSONL output, silently skipping malformed lines."""
+    for line in output.strip().split("\n"):
+        if not line:
+            continue
+        try:
+            yield json.loads(line)
+        except json.JSONDecodeError:
+            continue
+
+
+def _extract_result(output: str) -> tuple[Winner, EndReason, int, Scores]:
+    """Extract (winner, reason, ticks, scores) from CLI JSONL output."""
+    winner = Winner.DRAW
+    reason = EndReason.TIMEOUT
+    ticks = 0
+    scores = Scores(0, 0)
+
+    for data in _parse_jsonl(output):
+        msg_type = data.get("type")
+        if msg_type == "tick":
+            ticks = data.get("tick", ticks)
+        elif msg_type == "result":
+            victory = data.get("victory", {})
+            raw_winner = victory.get("winner")
+            winner = Winner.PLAYER1 if raw_winner == "player1" else Winner.PLAYER2 if raw_winner == "player2" else Winner.DRAW
+            reason = EndReason(victory.get("reason", "timeout"))
+            raw_scores = victory.get("scores", {})
+            scores = Scores(raw_scores.get("player1", 0), raw_scores.get("player2", 0))
+
+    return winner, reason, ticks, scores
+
+
+def _make_error(error_msg: str) -> MatchResult:
+    """Create an error result."""
+    return MatchResult(Winner.ERROR, EndReason.ERROR, 0, Scores(0, 0), error_msg)
+
+
+def run_match(p1: str | Path, p2: str | Path, map_name: str = "swamp", max_ticks: int = 2000, timeout: float = 120.0) -> MatchResult:
+    """Run a match between two JS bot strategies (p1/p2 are file paths)."""
+    cmd = [
+        "skirmish", "run",
+        "--p1", str(p1), "--p2", str(p2),
+        "--map", map_name, "--max-ticks", str(max_ticks), "--stdout",
+    ]
+
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    except FileNotFoundError:
+        return _make_error("skirmish CLI not found. Install: npm i -g @llmskirmish/skirmish")
+    except subprocess.TimeoutExpired:
+        return _make_error(f"Match timed out after {timeout}s")
+
+    if proc.returncode != 0:
+        return _make_error(proc.stderr.strip() or f"Exit code {proc.returncode}")
+
+    winner, reason, ticks, scores = _extract_result(proc.stdout)
+    return MatchResult(winner, reason, ticks, scores)

skirmish-0.1.2/src/skirmish/strategies/example_1.js

@@ -0,0 +1,68 @@
+/**
+ * The Swarm - Aggressive melee rush strategy
+ * 
+ * Strategy: Spawn cheap, fast melee units and rush the enemy.
+ * Always be moving, always be attacking. Overwhelm with numbers.
+ */
+
+function loop() {
+    const myCreeps = getObjectsByPrototype(Creep).filter(c => c.my && !c.spawning);
+    const enemies = getObjectsByPrototype(Creep).filter(c => !c.my && !c.spawning);
+    const mySpawn = getObjectsByPrototype(StructureSpawn).find(s => s.my);
+    const enemySpawn = getObjectsByPrototype(StructureSpawn).find(s => !s.my);
+  
+    // Run each creep
+    for (const creep of myCreeps) {
+      runCreep(creep, enemies, enemySpawn, mySpawn);
+    }
+  
+    // Spawn new creeps
+    if (mySpawn && !mySpawn.spawning) {
+      // Cheap and fast melee attackers
+      mySpawn.spawnCreep([ATTACK, ATTACK, MOVE, MOVE]);
+    }
+  }
+  
+  function runCreep(creep, enemies, enemySpawn, mySpawn) {
+    // Check body parts: creep.body is an array of {type, hits} objects
+    const isMelee = creep.body.some(p => p.type === ATTACK);
+    if (!isMelee) return; // Skip non-combat creeps (e.g., workers)
+  
+    // Priority 1: Attack adjacent enemies
+    const adjacentEnemy = findClosestByRange(creep, enemies.filter(e => getRange(creep, e) <= 1));
+    if (adjacentEnemy) {
+      creep.attack(adjacentEnemy);
+      // Stay on them if they're still alive
+      creep.moveTo(adjacentEnemy);
+      return;
+    }
+  
+    // Priority 2: Attack enemy spawn if in range
+    if (enemySpawn && getRange(creep, enemySpawn) <= 1) {
+      creep.attack(enemySpawn);
+      return;
+    }
+  
+    // Priority 3: Find and chase the nearest enemy
+    const nearestEnemy = findClosestByRange(creep, enemies);
+    if (nearestEnemy) {
+      creep.moveTo(nearestEnemy);
+      return;
+    }
+  
+    // Priority 4: Attack the enemy spawn
+    if (enemySpawn) {
+      creep.moveTo(enemySpawn);
+      return;
+    }
+  
+    // Fallback: Patrol around our spawn (should rarely happen)
+    if (mySpawn) {
+      const tick = getTicks();
+      const angle = (tick / 20 + creep.id.charCodeAt(0)) % (2 * Math.PI);
+      creep.moveTo({
+        x: Math.round(mySpawn.x + Math.cos(angle) * 5),
+        y: Math.round(mySpawn.y + Math.sin(angle) * 5)
+      });
+    }
+  }

skirmish-0.1.2/src/skirmish/strategies/example_2.js

@@ -0,0 +1,87 @@
+/**
+ * The Rangers - Kiting ranged attackers
+ * 
+ * Strategy: Keep distance from enemies, attack from range.
+ * Kite backwards when enemies get close, always maintain range 3.
+ */
+
+function loop() {
+    const myCreeps = getObjectsByPrototype(Creep).filter(c => c.my && !c.spawning);
+    const enemies = getObjectsByPrototype(Creep).filter(c => !c.my && !c.spawning);
+    const mySpawn = getObjectsByPrototype(StructureSpawn).find(s => s.my);
+    const enemySpawn = getObjectsByPrototype(StructureSpawn).find(s => !s.my);
+  
+    // Run each creep
+    for (const creep of myCreeps) {
+      runCreep(creep, enemies, enemySpawn, mySpawn);
+    }
+  
+    // Spawn new creeps
+    if (mySpawn && !mySpawn.spawning) {
+      // Ranged attackers with good mobility
+      mySpawn.spawnCreep([RANGED_ATTACK, RANGED_ATTACK, MOVE, MOVE]);
+    }
+  }
+  
+  function runCreep(creep, enemies, enemySpawn, mySpawn) {
+    const nearestEnemy = findClosestByRange(creep, enemies);
+    const enemyRange = nearestEnemy ? getRange(creep, nearestEnemy) : Infinity;
+  
+    // Priority 1: Attack enemies in range (range 3 for ranged attack)
+    if (nearestEnemy && enemyRange <= 3) {
+      creep.rangedAttack(nearestEnemy);
+      
+      // Kite: If enemy is too close (range 2 or less), back away
+      if (enemyRange <= 2) {
+        moveAway(creep, nearestEnemy);
+        return;
+      }
+      
+      // At perfect range (3), hold position or find more targets
+      return;
+    }
+  
+    // Priority 2: Attack enemy spawn if in range
+    if (enemySpawn && getRange(creep, enemySpawn) <= 3) {
+      creep.rangedAttack(enemySpawn);
+      // Back off if enemies are nearby
+      if (nearestEnemy && enemyRange <= 4) {
+        moveAway(creep, nearestEnemy);
+      }
+      return;
+    }
+  
+    // Priority 3: Approach nearest enemy to get in range
+    if (nearestEnemy) {
+      creep.moveTo(nearestEnemy);
+      return;
+    }
+  
+    // Priority 4: Attack the enemy spawn
+    if (enemySpawn) {
+      creep.moveTo(enemySpawn);
+      return;
+    }
+  
+    // Fallback: Patrol around our spawn
+    if (mySpawn) {
+      const tick = getTicks();
+      const angle = (tick / 20 + creep.id.charCodeAt(0)) % (2 * Math.PI);
+      creep.moveTo({
+        x: Math.round(mySpawn.x + Math.cos(angle) * 5),
+        y: Math.round(mySpawn.y + Math.sin(angle) * 5)
+      });
+    }
+  }
+  
+  function moveAway(creep, target) {
+    // Move in the opposite direction from the target
+    const dx = creep.x - target.x;
+    const dy = creep.y - target.y;
+    const dist = Math.sqrt(dx * dx + dy * dy) || 1;
+    
+    creep.moveTo({
+      x: Math.round(creep.x + (dx / dist) * 3),
+      y: Math.round(creep.y + (dy / dist) * 3)
+    });
+  }

skirmish-0.1.2/tests/test_skirmish.py

@@ -0,0 +1,98 @@
+"""Tests for run_match using example strategies."""
+
+from importlib.resources import files
+
+import pytest
+
+from skirmish import EndReason, MatchResult, Scores, Winner, run_match
+
+STRATEGIES = files("skirmish.strategies")
+EXAMPLE_1 = STRATEGIES / "example_1.js"
+EXAMPLE_2 = STRATEGIES / "example_2.js"
+
+
+@pytest.fixture(scope="module")
+def cli_available() -> bool:
+    """Check if skirmish CLI is installed."""
+    import shutil
+    return shutil.which("skirmish") is not None
+
+
+@pytest.fixture
+def require_cli(cli_available: bool) -> None:
+    """Skip test if CLI not available."""
+    if not cli_available:
+        pytest.skip("skirmish CLI not installed")
+
+
+class TestRunMatch:
+    """Tests for run_match function."""
+
+    def test_returns_match_result(self, require_cli: None) -> None:
+        """run_match returns a MatchResult."""
+        result = run_match(EXAMPLE_1, EXAMPLE_2, max_ticks=100)
+        assert isinstance(result, MatchResult)
+
+    def test_result_has_winner(self, require_cli: None) -> None:
+        """Result has a valid winner."""
+        result = run_match(EXAMPLE_1, EXAMPLE_2, max_ticks=100)
+        assert result.winner in (Winner.PLAYER1, Winner.PLAYER2, Winner.DRAW)
+
+    def test_result_has_reason(self, require_cli: None) -> None:
+        """Result has a valid end reason."""
+        result = run_match(EXAMPLE_1, EXAMPLE_2, max_ticks=100)
+        assert result.reason in (EndReason.ELIMINATION, EndReason.TIMEOUT)
+
+    def test_result_has_scores(self, require_cli: None) -> None:
+        """Result has scores for both players."""
+        result = run_match(EXAMPLE_1, EXAMPLE_2, max_ticks=100)
+        assert isinstance(result.scores, Scores)
+        assert isinstance(result.scores.player1, int)
+        assert isinstance(result.scores.player2, int)
+
+    def test_result_has_ticks(self, require_cli: None) -> None:
+        """Result has tick count."""
+        result = run_match(EXAMPLE_1, EXAMPLE_2, max_ticks=100)
+        assert isinstance(result.ticks, int)
+        assert 0 <= result.ticks <= 100
+
+    def test_max_ticks_respected(self, require_cli: None) -> None:
+        """Match ends at or before max_ticks."""
+        result = run_match(EXAMPLE_1, EXAMPLE_2, max_ticks=50)
+        assert result.ticks <= 50
+
+    def test_same_strategy_vs_itself(self, require_cli: None) -> None:
+        """Same strategy can play against itself."""
+        result = run_match(EXAMPLE_1, EXAMPLE_1, max_ticks=100)
+        assert isinstance(result, MatchResult)
+        assert result.reason != EndReason.ERROR
+
+
+class TestRunMatchErrors:
+    """Tests for error handling."""
+
+    def test_missing_cli_returns_error(self) -> None:
+        """Missing CLI returns error result, not exception."""
+        import subprocess
+        import skirmish
+
+        # Temporarily break the CLI lookup by monkeypatching
+        original_run = subprocess.run
+
+        def fake_run(*args, **kwargs):
+            raise FileNotFoundError("skirmish")
+
+        subprocess.run = fake_run
+        try:
+            result = run_match(EXAMPLE_1, EXAMPLE_2)
+            assert result.winner == Winner.ERROR
+            assert result.reason == EndReason.ERROR
+            assert "not found" in result.error.lower()
+        finally:
+            subprocess.run = original_run
+
+    def test_nonexistent_file_returns_error(self, require_cli: None) -> None:
+        """Nonexistent strategy file returns error."""
+        result = run_match("/nonexistent/path.js", EXAMPLE_1)
+        assert result.winner == Winner.ERROR
+        assert result.reason == EndReason.ERROR