cogames-agents 0.0.0.7__cp312-cp312-macosx_11_0_arm64.whl

cogames_agents/policy/scripted_agent/planky/README.md

@@ -0,0 +1,214 @@
+# Planky — Goal-Tree Scripted Agent
+
+Planky is a goal-tree scripted policy where each agent evaluates a priority-ordered list of goals each tick. The first
+unsatisfied goal decomposes into preconditions, and the deepest unsatisfied leaf produces an action.
+
+## Quick Start
+
+```bash
+# Watch planky play a cogsguard match (GUI mode)
+cogames play --mission cogsguard_machina_1.basic \
+  --policy "metta://policy/planky"
+
+# Terminal mode (no GUI needed)
+cogames play --mission cogsguard_machina_1.basic \
+  --policy "metta://policy/planky" \
+  --render unicode
+
+# Run a multi-episode scrimmage
+cogames scrimmage --mission cogsguard_machina_1.basic \
+  --policy "metta://policy/planky" \
+  --episodes 10
+```
+
+## Policy URI Parameters
+
+Configure agent role counts and tracing via query string:
+
+```
+metta://policy/planky?miner=4&scout=0&aligner=2&scrambler=4&stem=0&trace=0
+```
+
+| Parameter     | Default | Description                                   |
+| ------------- | ------- | --------------------------------------------- |
+| `miner`       | 0       | Number of miner agents                        |
+| `scout`       | 0       | Number of scout agents                        |
+| `aligner`     | 0       | Number of aligner agents                      |
+| `scrambler`   | 4       | Number of scrambler agents                    |
+| `stem`        | 0       | Number of stem agents (auto-select role)      |
+| `trace`       | 0       | Enable tracing (1=on)                         |
+| `trace_level` | 1       | Trace verbosity: 1=minimal, 2=context, 3=full |
+| `trace_agent` | -1      | Trace only this agent ID (-1=all)             |
+
+Agents beyond the total count stay on "default" vibe (inactive/noop).
+
+## Debugging with Tracing
+
+### Enable trace output
+
+```bash
+# Trace all agents at level 1 (one line per tick: goal chain + action)
+cogames play --mission cogsguard_machina_1.basic \
+  --policy "metta://policy/planky?miner=2&scrambler=2&trace=1"
+
+# Trace only agent 0 at level 2 (shows why each goal was skipped)
+cogames play --mission cogsguard_machina_1.basic \
+  --policy "metta://policy/planky?miner=2&scrambler=2&trace=1&trace_agent=0&trace_level=2"
+
+# Maximum detail — level 3
+cogames play --mission cogsguard_machina_1.basic \
+  --policy "metta://policy/planky?miner=1&trace=1&trace_agent=0&trace_level=3"
+```
+
+### Trace output format
+
+**Level 1** — Goal chain and action:
+
+```
+[planky] [t=142 a=2 miner (105,98) hp=73] MineResource>BeNearExtractor → move_east
+```
+
+**Level 2** — Adds skip reasons, blackboard, navigation target:
+
+```
+[planky] [t=142 a=2 miner (105,98) hp=73] skip:Survive(ok) skip:GetMinerGear(ok) skip:DepositCargo(ok) → MineResource dist=13 → move_east | bb={target_resource=carbon}
+```
+
+**Level 3** — Full detail including all goal evaluations:
+
+```
+[planky] [t=142 a=2 miner (105,98) hp=73] skip:Survive(ok) skip:GetMinerGear(ok) skip:PickResource(ok) skip:DepositCargo(ok) ACTIVE:MineResource() nav_target=(110,95) → move_east bb={target_resource=carbon}
+```
+
+### Filtering trace output
+
+Pipe through grep to focus on specific events:
+
+```bash
+# Only retreat events
+cogames play -m cogsguard_machina_1.basic \
+  -p "metta://policy/planky?miner=2&trace=1&trace_level=2" 2>&1 | grep Survive
+
+# Only a specific agent
+cogames play -m cogsguard_machina_1.basic \
+  -p "metta://policy/planky?miner=4&trace=1" 2>&1 | grep "a=2"
+
+# Watch goal transitions (when active goal changes)
+cogames play -m cogsguard_machina_1.basic \
+  -p "metta://policy/planky?miner=2&trace=1" --render log 2>&1 | grep planky
+```
+
+## Role Configurations
+
+### Mining-heavy (resource gathering)
+
+```bash
+cogames play -m cogsguard_machina_1.basic \
+  -p "metta://policy/planky?miner=6&aligner=2&scrambler=2"
+```
+
+### Balanced (default)
+
+```bash
+cogames play -m cogsguard_machina_1.basic \
+  -p "metta://policy/planky?miner=4&aligner=2&scrambler=4"
+```
+
+### Combat-heavy (territory control)
+
+```bash
+cogames play -m cogsguard_machina_1.basic \
+  -p "metta://policy/planky?miner=2&aligner=3&scrambler=5"
+```
+
+### With scouting
+
+```bash
+cogames play -m cogsguard_machina_1.basic \
+  -p "metta://policy/planky?miner=3&scout=2&aligner=2&scrambler=3"
+```
+
+### Stem agents (auto-role selection)
+
+```bash
+cogames play -m cogsguard_machina_1.basic \
+  -p "metta://policy/planky?stem=10"
+```
+
+## Comparing Planky vs Pinky
+
+Run both agents on the same mission and compare:
+
+```bash
+# Planky scrimmage
+cogames scrimmage -m cogsguard_machina_1.basic \
+  -p "metta://policy/planky?miner=4&aligner=2&scrambler=4" \
+  --episodes 10
+
+# Pinky scrimmage
+cogames scrimmage -m cogsguard_machina_1.basic \
+  -p "metta://policy/pinky?miner=4&aligner=2&scrambler=4" \
+  --episodes 10
+```
+
+Or head-to-head with `cogames run`:
+
+```bash
+cogames run -m cogsguard_machina_1.basic \
+  -p "metta://policy/planky?miner=4&aligner=2&scrambler=4" \
+  -p "metta://policy/pinky?miner=4&aligner=2&scrambler=4" \
+  --episodes 10
+```
+
+## Alternative Policy Specification
+
+All of these are equivalent:
+
+```bash
+# URI format
+-p "metta://policy/planky?miner=4&trace=1"
+
+# class= format with kw. prefix
+-p "class=planky,kw.miner=4,kw.trace=1"
+
+# shorthand with kw. prefix
+-p "planky,kw.miner=4,kw.trace=1"
+```
+
+## Architecture Overview
+
+```
+Observation → StateSnapshot → Goal Planner → Action
+                  ↓
+             EntityMap update
+```
+
+Each tick:
+
+1. Parse observation into `StateSnapshot` (source of truth — no internal drift)
+2. Update sparse `EntityMap` with visible entities
+3. Evaluate role's priority-ordered goal list top-down
+4. First unsatisfied goal decomposes via `preconditions()` recursion
+5. Deepest unsatisfied leaf calls `execute()` → returns an `Action`
+
+### File Structure
+
+```
+planky/
+├── policy.py          # PlankyPolicy + PlankyBrain (entry point)
+├── context.py         # PlankyContext, StateSnapshot
+├── entity_map.py      # Sparse EntityMap with find/query
+├── navigator.py       # A* pathfinding, stuck detection, exploration
+├── obs_parser.py      # Observation token → StateSnapshot + entities
+├── goal.py            # Goal base class, evaluate_goals()
+├── trace.py           # TraceLog with 3 verbosity levels
+└── goals/
+    ├── survive.py     # SurviveGoal (HP-based retreat)
+    ├── gear.py        # GetGearGoal (generic station navigation)
+    ├── shared.py      # GetHeartsGoal (used by aligner + scrambler)
+    ├── miner.py       # PickResource, DepositCargo, MineResource
+    ├── scout.py       # ExploreGoal, GetScoutGearGoal
+    ├── aligner.py     # AlignJunctionGoal (neutral, outside enemy AOE)
+    ├── scrambler.py   # ScrambleJunctionGoal (enemy, scored by blocking)
+    └── stem.py        # SelectRoleGoal (heuristic role selection)
+```

cogames_agents/policy/scripted_agent/planky/STRATEGY.md

@@ -0,0 +1,100 @@
+# CogsGuard Strategy Overview
+
+**CogsGuard** is a territory control game where your team (Cogs) competes against an AI opponent (Clips) to control
+**junctions** on the map.
+
+## Game Mechanics
+
+### Junction States
+
+Junctions (junctions on the map) have three states:
+
+- **Neutral** (unaligned)
+- **Cogs-aligned** (your team controls)
+- **Clips-aligned** (enemy controls)
+
+### Junction AOE Effects (10 tile radius)
+
+- Friendly junctions give you **+10 influence, +100 energy, +100 HP** per tick
+- Enemy junctions **attack you**: -1 HP, -100 influence per tick
+
+### Clips Behavior (AI opponent)
+
+- At timestep 10, Clips claims one initial junction
+- Every ~100 steps, Clips **scrambles** a nearby Cogs junction to neutral
+- Every ~100 steps, Clips **aligns** a nearby neutral junction to Clips
+- Clips expands outward from their controlled junctions (25 tile radius)
+
+### Reward
+
+Points based on how many junctions Cogs controls over time (scaled: 100 / max_steps per junction held).
+
+## Role System
+
+| Role             | Gear Cost       | Purpose                                                      |
+| ---------------- | --------------- | ------------------------------------------------------------ |
+| **Miner** ⛏️     | C1 O1 **G3** S1 | Extract resources faster (+40 cargo), deposits to collective |
+| **Scout** 🔭     | C1 O1 G1 **S3** | Explore map (+100 energy, +400 HP)                           |
+| **Aligner** 🔗   | **C3** O1 G1 S1 | Convert neutral junctions to Cogs (+20 influence)            |
+| **Scrambler** 🌀 | C1 **O3** G1 S1 | Convert Clips junctions to neutral (+200 HP)                 |
+
+### Critical Costs
+
+- **Heart** (required for align/scramble): 1 of each element from collective
+- **Align**: 1 heart + 1 influence + aligner gear
+- **Scramble**: 1 heart + scrambler gear
+
+## The Strategic Loop
+
+```
+Resources (extractors) → Collective → Hearts (chest) → Junction control
+```
+
+1. **Miners** gather resources from extractors → deposit at Hub/Junction → funds collective
+2. **Collective** resources can buy hearts at chest (1 of each element)
+3. **Aligners** spend hearts to convert neutral junctions
+4. **Scramblers** spend hearts to break enemy junctions
+
+## Key Strategic Considerations
+
+### Economy Priority
+
+You need a steady stream of hearts. Without miners depositing resources, aligners/scramblers can't act.
+
+### Territory Expansion
+
+Clips expands from existing junctions. The optimal counter is:
+
+- **Scramble** enemy junctions to break their expansion radius
+- **Align** neutral junctions **outside** enemy AOE (the aligner goal already checks this)
+
+### Junction Targeting
+
+Current scrambler logic prioritizes junctions that block the most neutral junctions from being captured.
+
+### Role Balance
+
+Default is `stem=10` which lets agents dynamically choose roles based on game state. Only use explicit role counts when
+testing specific role behaviors.
+
+## Improvement Areas
+
+### Early Game Economy
+
+- Bootstrap resource gathering before combat roles become effective
+- Consider dynamic role allocation based on collective resources
+
+### Smarter Role Transitions (Stem Agents)
+
+- Stem agents can auto-select roles based on game state
+- Could be improved to respond to economy/territory balance
+
+### Better Junction Targeting Heuristics
+
+- Prioritize junctions that would give strategic map control
+- Consider path distances and clustering
+
+### Coordination Between Roles
+
+- Scramblers and aligners could coordinate to chain-capture junctions
+- Miners could prioritize resources needed for hearts vs gear

cogames_agents/policy/scripted_agent/planky/__init__.py

@@ -0,0 +1,5 @@
+"""Planky policy - goal-tree scripted agent."""
+
+from .policy import PlankyPolicy
+
+__all__ = ["PlankyPolicy"]

cogames_agents/policy/scripted_agent/planky/context.py

@@ -0,0 +1,68 @@
+"""Context and state snapshot for Planky policy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Optional
+
+if TYPE_CHECKING:
+    from .entity_map import EntityMap
+    from .navigator import Navigator
+    from .trace import TraceLog
+
+
+@dataclass
+class StateSnapshot:
+    """Rebuilt every tick from observation tokens. Observation is source of truth."""
+
+    position: tuple[int, int] = (0, 0)
+
+    # Inventory
+    carbon: int = 0
+    oxygen: int = 0
+    germanium: int = 0
+    silicon: int = 0
+    heart: int = 0
+    influence: int = 0
+    hp: int = 100
+    energy: int = 100
+
+    # Gear flags
+    miner_gear: bool = False
+    scout_gear: bool = False
+    aligner_gear: bool = False
+    scrambler_gear: bool = False
+
+    # Vibe
+    vibe: str = "default"
+
+    # Collective inventory
+    collective_carbon: int = 0
+    collective_oxygen: int = 0
+    collective_germanium: int = 0
+    collective_silicon: int = 0
+    collective_heart: int = 0
+    collective_influence: int = 0
+
+    @property
+    def cargo_total(self) -> int:
+        return self.carbon + self.oxygen + self.germanium + self.silicon
+
+    @property
+    def cargo_capacity(self) -> int:
+        return 40 if self.miner_gear else 4
+
+
+@dataclass
+class PlankyContext:
+    """Passed to all goals, bundles everything needed for decision-making."""
+
+    state: StateSnapshot
+    map: EntityMap
+    blackboard: dict[str, Any]
+    navigator: Navigator
+    trace: Optional[TraceLog]
+    action_names: list[str]
+    agent_id: int
+    step: int
+    my_collective_id: Optional[int] = None

cogames_agents/policy/scripted_agent/planky/entity_map.py

@@ -0,0 +1,152 @@
+"""Sparse entity map for Planky policy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class Entity:
+    """An object on the map."""
+
+    type: str  # e.g. "carbon_extractor", "miner_station", "wall", "agent"
+    properties: dict  # alignment, remaining_uses, inventory_amount, cooldown, etc.
+    last_seen: int = 0
+
+
+class EntityMap:
+    """Sparse map of entities. Only stores non-empty cells."""
+
+    def __init__(self) -> None:
+        self.entities: dict[tuple[int, int], Entity] = {}
+        self.explored: set[tuple[int, int]] = set()
+
+    def update_from_observation(
+        self,
+        agent_pos: tuple[int, int],
+        obs_half_height: int,
+        obs_half_width: int,
+        visible_entities: dict[tuple[int, int], Entity],
+        step: int,
+    ) -> None:
+        """Update map from current observation window.
+
+        All cells in the observation window are marked as explored.
+        Entities in the window are overwritten with fresh data.
+        Entities no longer visible in the window are removed.
+        """
+        # Mark all cells in observation window as explored
+        for obs_r in range(2 * obs_half_height + 1):
+            for obs_c in range(2 * obs_half_width + 1):
+                r = obs_r - obs_half_height + agent_pos[0]
+                c = obs_c - obs_half_width + agent_pos[1]
+                self.explored.add((r, c))
+
+        # Remove entities in observation window that are no longer visible
+        window_min_r = agent_pos[0] - obs_half_height
+        window_max_r = agent_pos[0] + obs_half_height
+        window_min_c = agent_pos[1] - obs_half_width
+        window_max_c = agent_pos[1] + obs_half_width
+
+        to_remove = []
+        for pos in self.entities:
+            if window_min_r <= pos[0] <= window_max_r and window_min_c <= pos[1] <= window_max_c:
+                if pos not in visible_entities:
+                    to_remove.append(pos)
+        for pos in to_remove:
+            del self.entities[pos]
+
+        # Add/update visible entities
+        for pos, entity in visible_entities.items():
+            entity.last_seen = step
+            self.entities[pos] = entity
+
+    def find(
+        self,
+        type: Optional[str] = None,
+        type_contains: Optional[str] = None,
+        property_filter: Optional[dict] = None,
+    ) -> list[tuple[tuple[int, int], Entity]]:
+        """Query entities by type and/or properties.
+
+        Args:
+            type: Exact type match
+            type_contains: Substring match on type
+            property_filter: Dict of property key-value pairs that must match
+        """
+        results = []
+        for pos, entity in self.entities.items():
+            if type is not None and entity.type != type:
+                continue
+            if type_contains is not None and type_contains not in entity.type:
+                continue
+            if property_filter is not None:
+                match = all(entity.properties.get(k) == v for k, v in property_filter.items())
+                if not match:
+                    continue
+            results.append((pos, entity))
+        return results
+
+    def find_nearest(
+        self,
+        from_pos: tuple[int, int],
+        type: Optional[str] = None,
+        type_contains: Optional[str] = None,
+        property_filter: Optional[dict] = None,
+        max_dist: Optional[int] = None,
+    ) -> Optional[tuple[tuple[int, int], Entity]]:
+        """Find nearest entity matching criteria."""
+        matches = self.find(type=type, type_contains=type_contains, property_filter=property_filter)
+        if not matches:
+            return None
+
+        best = None
+        best_dist = float("inf")
+        for pos, entity in matches:
+            dist = abs(pos[0] - from_pos[0]) + abs(pos[1] - from_pos[1])
+            if max_dist is not None and dist > max_dist:
+                continue
+            if dist < best_dist:
+                best = (pos, entity)
+                best_dist = dist
+        return best
+
+    def is_passable(self, pos: tuple[int, int]) -> bool:
+        """Check if a position is passable (explored and not a wall/obstacle)."""
+        if pos not in self.explored:
+            return False
+        entity = self.entities.get(pos)
+        if entity is None:
+            return True  # Explored empty cell
+        # Agents are temporary obstacles, everything else is permanent
+        if entity.type == "agent":
+            return False
+        # Walls are obstacles
+        if entity.type == "wall":
+            return False
+        # Structures are obstacles (stations, extractors, junctions, etc.)
+        # But we don't block pathfinding through them — goals that need adjacency
+        # handle that via reach_adjacent=True
+        return True  # Structures are passable for pathfinding
+
+    def is_wall(self, pos: tuple[int, int]) -> bool:
+        """Check if position is a wall."""
+        entity = self.entities.get(pos)
+        return entity is not None and entity.type == "wall"
+
+    def is_structure(self, pos: tuple[int, int]) -> bool:
+        """Check if position has a structure (non-wall, non-agent entity)."""
+        entity = self.entities.get(pos)
+        if entity is None:
+            return False
+        return entity.type not in ("wall", "agent")
+
+    def is_free(self, pos: tuple[int, int]) -> bool:
+        """Check if position is explored and has no entity."""
+        return pos in self.explored and pos not in self.entities
+
+    def has_agent(self, pos: tuple[int, int]) -> bool:
+        """Check if position has an agent."""
+        entity = self.entities.get(pos)
+        return entity is not None and entity.type == "agent"

cogames_agents/policy/scripted_agent/planky/goal.py

@@ -0,0 +1,107 @@
+"""Goal base class and evaluation logic for Planky policy."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+from mettagrid.simulator import Action
+
+if TYPE_CHECKING:
+    from .context import PlankyContext
+
+
+class Goal:
+    """Base class for all goals in the goal tree.
+
+    Subclasses implement:
+    - is_satisfied(ctx) -> bool: whether this goal is already met
+    - preconditions() -> list[Goal]: sub-goals that must be satisfied first
+    - execute(ctx) -> Action | None: produce an action, or None to skip/defer
+    """
+
+    name: str = "Goal"
+
+    def is_satisfied(self, ctx: PlankyContext) -> bool:
+        """Check if this goal is already satisfied."""
+        return False
+
+    def preconditions(self) -> list[Goal]:
+        """Return sub-goals that must be satisfied before this goal can execute."""
+        return []
+
+    def execute(self, ctx: PlankyContext) -> Optional[Action]:
+        """Produce an action to work toward this goal, or None to skip."""
+        return Action(name="noop")
+
+
+def evaluate_goals(goals: list[Goal], ctx: PlankyContext) -> Action:
+    """Evaluate a priority-ordered goal list and return an action.
+
+    Walks the list top-down. The first unsatisfied goal becomes active.
+    Recursively checks preconditions to find the deepest unsatisfied leaf.
+    That leaf's execute() produces the action.
+
+    If execute() returns None, the goal is skipped and evaluation continues
+    with the next goal (allows goals to voluntarily defer).
+    """
+    for goal in goals:
+        if goal.is_satisfied(ctx):
+            if ctx.trace:
+                ctx.trace.skip(goal.name, _satisfaction_detail(goal, ctx))
+            continue
+
+        # Found unsatisfied goal — recurse into preconditions
+        leaf = _deepest_unsatisfied(goal, ctx)
+        action = leaf.execute(ctx)
+
+        # None means "skip me for now" — continue to next goal
+        if action is None:
+            if ctx.trace:
+                ctx.trace.skip(leaf.name, "deferred")
+            continue
+
+        if ctx.trace:
+            ctx.trace.active_goal_chain = _build_chain(goal, leaf)
+            ctx.trace.action_name = action.name
+
+        return action
+
+    return Action(name="noop")
+
+
+def _deepest_unsatisfied(goal: Goal, ctx: PlankyContext) -> Goal:
+    """Find the deepest unsatisfied precondition in the goal tree."""
+    for pre in goal.preconditions():
+        if not pre.is_satisfied(ctx):
+            if ctx.trace:
+                ctx.trace.activate(pre.name)
+            return _deepest_unsatisfied(pre, ctx)
+    return goal
+
+
+def _build_chain(root: Goal, leaf: Goal) -> str:
+    """Build a display chain like 'MineCarbon>BeNearExtractor'."""
+    if root is leaf:
+        return root.name
+    # Walk preconditions to find the path
+    chain = [root.name]
+    _find_path(root, leaf, chain)
+    return ">".join(chain)
+
+
+def _find_path(current: Goal, target: Goal, chain: list[str]) -> bool:
+    """DFS to find path from current to target goal."""
+    for pre in current.preconditions():
+        if pre is target:
+            chain.append(pre.name)
+            return True
+        chain.append(pre.name)
+        if _find_path(pre, target, chain):
+            return True
+        chain.pop()
+    return False
+
+
+def _satisfaction_detail(goal: Goal, ctx: PlankyContext) -> str:
+    """Generate a short detail string for why a goal is satisfied."""
+    return "ok"

cogames_agents/policy/scripted_agent/planky/goals/__init__.py

@@ -0,0 +1,27 @@
+"""Goal classes for Planky policy."""
+
+from .aligner import AlignJunctionGoal, GetAlignerGearGoal
+from .gear import GetGearGoal
+from .miner import DepositCargoGoal, GetMinerGearGoal, MineResourceGoal, PickResourceGoal
+from .scout import ExploreGoal, GetScoutGearGoal
+from .scrambler import GetScramblerGearGoal, ScrambleJunctionGoal
+from .shared import GetHeartsGoal
+from .stem import SelectRoleGoal
+from .survive import SurviveGoal
+
+__all__ = [
+    "SurviveGoal",
+    "GetGearGoal",
+    "GetAlignerGearGoal",
+    "GetMinerGearGoal",
+    "GetScoutGearGoal",
+    "GetScramblerGearGoal",
+    "GetHeartsGoal",
+    "PickResourceGoal",
+    "DepositCargoGoal",
+    "MineResourceGoal",
+    "ExploreGoal",
+    "AlignJunctionGoal",
+    "ScrambleJunctionGoal",
+    "SelectRoleGoal",
+]