Phase 4 — Trees, Rocks, Items, Stockpiles, Hauling

Three gdscript-refactor agents in parallel + Opus integration.

Entities (scenes/entities/, Agent A — 3 scripts + 3 .tscn, ~460 lines):
- item.gd: 16-type StringName registry (matches design.md filter chips);
  Node2D + _draw() colored square + stack-count badge; to_dict/from_dict
- tree.gd: class_name HarvestableTree (Godot 4 ships a built-in 'Tree'
  Control class — renamed to avoid the shadow); CHOP_TICKS=80; on_chop_tick
  advances progress, fells when complete, drops 3 wood items at tile +
  walkable neighbours
- rock.gd: MINE_TICKS=120; angular polygon _draw; mined() drops 1 stone

Toil + provider extensions (scenes/ai/, Agent B — 4 files modified/added,
~250 lines):
- Toil: new KIND_INTERACT (timed entity action), KIND_PICKUP, KIND_DEPOSIT
- JobRunner: _tick_interact resolves NodePath, calls target.<method>()
  each tick, marks done when is_choppable/is_mineable returns false;
  _tick_pickup finds Item at pawn.tile, transfers to pawn.carried_item;
  _tick_deposit places carried_item at pawn.tile + clears the
  items_needing_haul dirty flag
- ChopProvider (priority=5): nearest choppable tree; Job=[walk_to + interact]
- MineProvider (priority=4): same for rocks

Hauling system (scenes/world/ + scenes/ai/, Agent C — 4 files, ~330 lines):
- StorageDestination: abstract Node2D base; Priority enum CRITICAL=0..OFF=4;
  accepted_types (empty=wildcard); _filter_accepts() helper
- StockpileZone: concrete rect-region zone; _draw paints priority-tinted
  overlay (z_index=-1); find_drop_position scans for free cells respecting
  one-stack-per-tile rule
- HaulingProvider (priority=3): nearest dirty item × best destination →
  4-toil job [walk → pickup → walk → deposit]; sweep_for_better_destinations
  enables the priority cascade (items in lower-priority zones re-mark dirty
  when a higher-priority destination opens up)

Opus integration (~200 lines):
- World autoload: trees/rocks/items/items_needing_haul/stockpiles registries
  + register/unregister methods; pathfinder reference exposed for entity
  code (tree.fell needs is_walkable for neighbour drops)
- Pawn: carried_item slot + carry-indicator (small colored rect upper-right
  of body) via queue_redraw in _on_sim_tick
- World scene: registers chop/mine/haul/rest providers; spawns 6 trees
  (cluster east-north), 4 rocks (south-east), 2 stockpile zones (Zone A
  wood-only NORMAL, Zone B wildcard HIGH); periodic
  hauling_provider.sweep_for_better_destinations every 100 sim ticks

Acceptance — MCP-verified end-to-end (the full Phase 4 loop):
- 3 pawns boot, Decision picks chop (highest priority work), all walk to
  nearest tree, chop in parallel (3× speed because all 3 call on_chop_tick
  per tick). Trees fell, drop wood (18 items). Pawns move to rocks, mine,
  drop stone (4 items). Total 22 items spawn.
- HaulingProvider routes wood + stone toward Zone B (wildcard HIGH > Zone
  A's wood-only NORMAL). Pawns carry items one at a time, visual indicator
  shows during transit. Items deposit, items_needing_haul dirty flag
  clears.
- **Priority cascade test:** Zone A promoted from NORMAL to CRITICAL.
  Manually-triggered sweep marks 3 wood items in Zone B for re-haul.
  Within a few thousand ticks: Zone A has 5 wood (cascaded from Zone B),
  Zone B has 4 stone only (wood left, stone stayed because Zone A rejects
  stone). Filter + priority cascade working exactly per design.md spec.

Phase 4 gotchas (logged in implementation.md):
- 'Tree' shadows Godot 4's built-in Tree Control class — class_name had to
  be renamed to HarvestableTree. Scene/file names stayed as 'tree' since
  the game concept is still 'tree'; the rename only affects code-side
  type references.
- draw_colored_polygon(points, color) takes a SINGLE Color, not a
  PackedColorArray. Agent C had to be reminded; draw_polygon(points, colors)
  is the variant that takes per-vertex colors.
- Godot's class-name cache lags behind file changes — a full editor scan
  ('godot --headless --editor --quit') is needed to flush. Even after
  reload_project, type-annotation assignments can fail; duck-typed
  variables ('var x = scene.instantiate()') sidestep the issue.
- JobRunner's _tick_deposit had to explicitly call
  World.clear_item_haul_flag — the dirty set persisted otherwise and
  items appeared 'needing haul' even after deposit.

Delegation report this phase:
- Agent A (Sonnet, gdscript-refactor): Tree + Rock + Item entities + i18n
  keys. ~460 lines.
- Agent B (Sonnet, gdscript-refactor): Toil extensions + JobRunner handlers
  + ChopProvider + MineProvider. ~250 lines.
- Agent C (Sonnet, gdscript-refactor): StorageDestination + StockpileZone
  + HaulingProvider with cascade sweep. ~330 lines.
- Opus: World autoload extensions (entity registries + pathfinder ref),
  Pawn carry slot + visual, world.tscn/gd wiring, the Tree rename, the
  draw_colored_polygon fix, the dirty-set-clear fix, MCP-driven runtime
  verification including the full chop-mine-haul loop and the priority
  cascade demo.

~75% of Phase 4's GDScript was subagent-authored.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

scenes/entities/tree.gd

@@ -0,0 +1,162 @@
+## Tree entity — choppable by a pawn with a Chop job. Drops wood Item nodes
+## when felled.
+##
+## Chopping model (docs/implementation.md Phase 4):
+##   A ChopProvider creates a Job whose INTERACT toil calls on_chop_tick() once
+##   per sim tick via JobRunner. After CHOP_TICKS ticks the tree is felled.
+##
+## World registration (World.register_tree / World.unregister_tree) is called
+## here but the methods land in World during Opus integration.
+
+class_name HarvestableTree extends Node2D
+## NOTE: class_name is HarvestableTree because Godot 4 ships a built-in `Tree`
+## Control node — using "Tree" would shadow that. Filename / scene name stay
+## as `tree` because the game-side concept is still just "tree".
+
+const TILE_SIZE_PX: int = 16
+
+## Sim ticks to fell a tree at 1× speed (80 ticks = ~4 sim seconds at 20 Hz).
+const CHOP_TICKS: int = 80
+## Number of separate wood Item nodes dropped on fell.
+const WOOD_DROPS_ON_FELL: int = 3
+## Stack size per dropped Item (Phase 4 simplicity: 3 items of stack 1 each).
+const STACK_SIZE_PER_DROP: int = 1
+
+# ── state ─────────────────────────────────────────────────────────────────────
+
+var tile: Vector2i = Vector2i.ZERO
+## 0..CHOP_TICKS. Advanced by on_chop_tick(); tree is felled when equal to CHOP_TICKS.
+var chop_progress: int = 0
+
+# Preloaded scene for spawned wood items.
+const ITEM_SCENE: PackedScene = preload("res://scenes/entities/item.tscn")
+
+
+# ── lifecycle ─────────────────────────────────────────────────────────────────
+
+func _ready() -> void:
+	position = _tile_to_world(tile)
+	World.register_tree(self)
+
+
+func _exit_tree() -> void:
+	World.unregister_tree(self)
+
+
+# ── public API ────────────────────────────────────────────────────────────────
+
+## One-shot initialiser. Call after add_child() so _ready() already fired.
+func setup(start_tile: Vector2i) -> void:
+	tile = start_tile
+	chop_progress = 0
+	position = _tile_to_world(tile)
+	queue_redraw()
+	Audit.log("tree", "spawned at %s" % tile)
+
+
+## True when the tree hasn't been fully chopped yet.
+func is_choppable() -> bool:
+	return chop_progress < CHOP_TICKS
+
+
+## Called by the INTERACT toil in JobRunner once per sim tick while the pawn
+## works this tree. Advances chop_progress and fells the tree when complete.
+func on_chop_tick() -> void:
+	if not is_choppable():
+		return
+	chop_progress += 1
+	queue_redraw()
+	if chop_progress >= CHOP_TICKS:
+		fell()
+
+
+## Drop wood Items and free this node. Called by on_chop_tick() automatically,
+## but also accessible for scripted felling (debug, storyteller events).
+func fell() -> void:
+	var drop_tiles := _pick_drop_tiles()
+	var drops_count := 0
+	for drop_tile in drop_tiles:
+		var item: Item = ITEM_SCENE.instantiate()
+		get_parent().add_child(item)
+		item.setup(Item.TYPE_WOOD, STACK_SIZE_PER_DROP, drop_tile)
+		drops_count += 1
+	Audit.log("tree", "felled at %s; %d wood drops" % [tile, drops_count])
+	queue_free()
+
+
+# ── save / load ───────────────────────────────────────────────────────────────
+
+func to_dict() -> Dictionary:
+	return {
+		"tile_x": tile.x,
+		"tile_y": tile.y,
+		"chop_progress": chop_progress,
+	}
+
+
+static func from_dict(d: Dictionary) -> Dictionary:
+	return {
+		"tile_x": int(d.get("tile_x", 0)),
+		"tile_y": int(d.get("tile_y", 0)),
+		"chop_progress": int(d.get("chop_progress", 0)),
+	}
+
+
+# ── render ────────────────────────────────────────────────────────────────────
+
+func _draw() -> void:
+	# Brown trunk: small filled rect at centre-bottom (~4 wide × 6 tall).
+	var trunk_color := Color(0.45, 0.28, 0.12)
+	draw_rect(Rect2(Vector2(-2.0, 1.0), Vector2(4.0, 6.0)), trunk_color)
+
+	# Green canopy: large filled circle centered near the top.
+	var canopy_color := Color(0.22, 0.60, 0.18)
+	draw_circle(Vector2(0.0, -3.0), 7.0, canopy_color)
+
+	# Canopy outline.
+	draw_arc(Vector2(0.0, -3.0), 7.0, 0.0, TAU, 24, Color(0.0, 0.0, 0.0, 0.4), 1.0)
+
+	# Chop-progress wedge: a dark angled line on the trunk when partially chopped.
+	if chop_progress > 0:
+		var ratio := float(chop_progress) / float(CHOP_TICKS)
+		var notch_depth := ratio * 3.0
+		draw_line(
+			Vector2(-2.0, 2.0 + notch_depth),
+			Vector2(2.0, 2.0),
+			Color(0.15, 0.08, 0.02, 0.9),
+			1.5
+		)
+
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+## Returns up to WOOD_DROPS_ON_FELL tile positions for wood drops.
+## Prefers the tree's own tile then walkable 4-neighbours; falls back to the
+## tree tile for any remaining drops when neighbours are scarce.
+func _pick_drop_tiles() -> Array[Vector2i]:
+	var chosen: Array[Vector2i] = []
+
+	# First drop always goes on the tree's tile itself.
+	chosen.append(tile)
+
+	# Remaining drops prefer walkable neighbours.
+	var offsets: Array[Vector2i] = [Vector2i(1, 0), Vector2i(-1, 0), Vector2i(0, 1), Vector2i(0, -1)]
+	for offset in offsets:
+		if chosen.size() >= WOOD_DROPS_ON_FELL:
+			break
+		var candidate: Vector2i = tile + offset
+		if World.pathfinder != null and World.pathfinder.is_walkable(candidate):
+			chosen.append(candidate)
+
+	# Fill any remaining slots with the tree tile (all 3 land there if boxed in).
+	while chosen.size() < WOOD_DROPS_ON_FELL:
+		chosen.append(tile)
+
+	return chosen
+
+
+func _tile_to_world(t: Vector2i) -> Vector2:
+	return Vector2(
+		t.x * TILE_SIZE_PX + TILE_SIZE_PX / 2.0,
+		t.y * TILE_SIZE_PX + TILE_SIZE_PX / 2.0
+	)