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>
This commit is contained in:
megaproxy 2026-05-10 21:32:39 +01:00
parent 5bf0f51efb
commit 91bceeebe8
28 changed files with 1252 additions and 23 deletions

151
scenes/entities/item.gd Normal file
View file

@ -0,0 +1,151 @@
## Dropped item entity — a single stack of one item type lying on the world floor.
##
## Visuals are drawn procedurally via _draw() (Phase 4 placeholder). Real
## ElvGames item icons land in Phase 5+.
##
## Item type constants mirror the 16 filter chips in docs/design.md. They are
## used by StockpileZone filter bitmasks and pawn-carry typing.
##
## World registration (World.register_item / World.unregister_item) is called
## here but the methods land in World during Opus integration. The script will
## parse cleanly; the call will fail at runtime until then.
class_name Item extends Node2D
const TILE_SIZE_PX: int = 16
# ── canonical type registry — matches docs/design.md "16 filter chips" ───────
const TYPE_WOOD: StringName = &"wood" # Wd
const TYPE_STONE: StringName = &"stone" # St
const TYPE_IRON_ORE: StringName = &"iron_ore" # Ir
const TYPE_COPPER_ORE: StringName = &"copper_ore" # Cu
const TYPE_SILVER: StringName = &"silver" # Ag
const TYPE_GOLD: StringName = &"gold" # Au
const TYPE_CLOTH: StringName = &"cloth" # Cl
const TYPE_VEGETABLE: StringName = &"vegetable" # Veg
const TYPE_MEAT: StringName = &"meat" # Mt
const TYPE_GRAIN: StringName = &"grain" # Gr
const TYPE_MEAL: StringName = &"meal" # Ck (cooked)
const TYPE_MEDICINE: StringName = &"medicine" # Md
const TYPE_TOOL: StringName = &"tool" # Tl
const TYPE_WEAPON: StringName = &"weapon" # Wp
const TYPE_ARMOR: StringName = &"armor" # Ar
const TYPE_CORPSE: StringName = &"corpse" # Co
const ALL_TYPES: Array[StringName] = [
TYPE_WOOD, TYPE_STONE, TYPE_IRON_ORE, TYPE_COPPER_ORE,
TYPE_SILVER, TYPE_GOLD, TYPE_CLOTH, TYPE_VEGETABLE,
TYPE_MEAT, TYPE_GRAIN, TYPE_MEAL, TYPE_MEDICINE,
TYPE_TOOL, TYPE_WEAPON, TYPE_ARMOR, TYPE_CORPSE,
]
# ── state ────────────────────────────────────────────────────────────────────
@export var item_type: StringName = TYPE_WOOD
@export var stack_size: int = 1
var tile: Vector2i = Vector2i.ZERO
## When true the on-floor visual is suppressed; the carrying pawn renders the
## carry indicator instead.
var being_carried: bool = false
# ── lifecycle ─────────────────────────────────────────────────────────────────
func _ready() -> void:
position = _tile_to_world(tile)
visible = not being_carried
func _exit_tree() -> void:
World.unregister_item(self)
# ── public API ────────────────────────────────────────────────────────────────
## One-shot initialiser called by the spawning code (Tree.fell, Rock.mined, etc.)
## Sets all fields, syncs position, and registers with World.
func setup(p_type: StringName, p_stack: int, p_tile: Vector2i) -> void:
item_type = p_type
stack_size = p_stack
tile = p_tile
position = _tile_to_world(tile)
visible = not being_carried
queue_redraw()
World.register_item(self)
Audit.log("item", "spawned %s×%d at %s" % [item_type, stack_size, tile])
## Hide/show the on-floor sprite when the pawn picks up or drops this item.
func set_being_carried(value: bool) -> void:
being_carried = value
visible = not being_carried
# ── save / load ───────────────────────────────────────────────────────────────
func to_dict() -> Dictionary:
return {
"type": String(item_type),
"stack_size": stack_size,
"tile_x": tile.x,
"tile_y": tile.y,
}
## Returns a plain Dictionary spec for World.load_items() to instantiate from.
## Items cannot reconstruct themselves standalone — they need a parent in the
## scene tree. World adds the node, then calls setup() from the returned dict.
static func from_dict(d: Dictionary) -> Dictionary:
return {
"type": StringName(d.get("type", "wood")),
"stack_size": int(d.get("stack_size", 1)),
"tile_x": int(d.get("tile_x", 0)),
"tile_y": int(d.get("tile_y", 0)),
}
# ── render ────────────────────────────────────────────────────────────────────
func _draw() -> void:
# 12×12 coloured square centered on the tile; colour hashed from item_type.
var hue := float(item_type.hash() % 360) / 360.0
var fill := Color.from_hsv(hue, 0.6, 0.85)
var half: int = 6
var square := Rect2(Vector2(-half, -half), Vector2(half * 2, half * 2))
draw_rect(square, fill)
draw_rect(square, Color(0.0, 0.0, 0.0, 0.75), false, 1.0)
# Stack count badge — bottom-right corner of the square, font_size 7.
if stack_size > 1:
var label := Strings.t(&"item.stack_count").format({"n": stack_size})
draw_string(
ThemeDB.fallback_font,
Vector2(half - 1, half - 1),
label,
HORIZONTAL_ALIGNMENT_RIGHT,
-1,
7,
Color(0.0, 0.0, 0.0, 0.6) # drop-shadow offset below
)
draw_string(
ThemeDB.fallback_font,
Vector2(half - 2, half - 2),
label,
HORIZONTAL_ALIGNMENT_RIGHT,
-1,
7,
Color(1.0, 1.0, 1.0, 1.0)
)
# ── helpers ───────────────────────────────────────────────────────────────────
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
)

View file

@ -0,0 +1 @@
uid://576k8p7pk4xx

View file

@ -0,0 +1,6 @@
[gd_scene load_steps=2 format=3 uid="uid://item_entity"]
[ext_resource type="Script" path="res://scenes/entities/item.gd" id="1_item"]
[node name="Item" type="Node2D"]
script = ExtResource("1_item")

147
scenes/entities/rock.gd Normal file
View file

@ -0,0 +1,147 @@
## Rock entity — mineable by a pawn with a Mine job. Drops a stone Item node
## when mined out.
##
## Mirrors Tree's chopping model; stone is harder so MINE_TICKS is longer.
## A MineProvider (Opus, Phase 4) creates a Job whose INTERACT toil calls
## on_mine_tick() once per sim tick via JobRunner.
##
## World registration (World.register_rock / World.unregister_rock) is called
## here but the methods land in World during Opus integration.
class_name Rock extends Node2D
const TILE_SIZE_PX: int = 16
## Sim ticks to mine a rock at 1× speed (120 ticks = 6 sim seconds at 20 Hz).
## Stone is harder than wood — MINE_TICKS > Tree.CHOP_TICKS.
const MINE_TICKS: int = 120
## Stone Items dropped on a successful mine.
const STONE_DROPS_ON_MINE: int = 1
# ── state ─────────────────────────────────────────────────────────────────────
var tile: Vector2i = Vector2i.ZERO
## 0..MINE_TICKS. Advanced by on_mine_tick(); rock is mined when equal to MINE_TICKS.
var mine_progress: int = 0
# Preloaded scene for spawned stone items.
const ITEM_SCENE: PackedScene = preload("res://scenes/entities/item.tscn")
# ── lifecycle ─────────────────────────────────────────────────────────────────
func _ready() -> void:
position = _tile_to_world(tile)
World.register_rock(self)
func _exit_tree() -> void:
World.unregister_rock(self)
# ── public API ────────────────────────────────────────────────────────────────
## One-shot initialiser. Call after add_child() so _ready() already fired.
func setup(start_tile: Vector2i) -> void:
tile = start_tile
mine_progress = 0
position = _tile_to_world(tile)
queue_redraw()
Audit.log("rock", "spawned at %s" % tile)
## True when the rock hasn't been fully mined yet.
func is_mineable() -> bool:
return mine_progress < MINE_TICKS
## Called by the INTERACT toil in JobRunner once per sim tick while the pawn
## works this rock. Advances mine_progress and triggers mined() when complete.
func on_mine_tick() -> void:
if not is_mineable():
return
mine_progress += 1
queue_redraw()
if mine_progress >= MINE_TICKS:
mined()
## Drop stone Item(s) and free this node. Called automatically by on_mine_tick()
## but also accessible for scripted removal (debug, storyteller events).
func mined() -> void:
# Single drop lands on the rock's own tile.
var item: Item = ITEM_SCENE.instantiate()
get_parent().add_child(item)
item.setup(Item.TYPE_STONE, 1, tile)
Audit.log("rock", "mined at %s; %d stone drop" % [tile, STONE_DROPS_ON_MINE])
queue_free()
# ── save / load ───────────────────────────────────────────────────────────────
func to_dict() -> Dictionary:
return {
"tile_x": tile.x,
"tile_y": tile.y,
"mine_progress": mine_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)),
"mine_progress": int(d.get("mine_progress", 0)),
}
# ── render ────────────────────────────────────────────────────────────────────
func _draw() -> void:
# Angular cluster of 34 triangles in a dark-grey / light-grey palette.
var c1 := Color(0.55, 0.55, 0.50) # light face
var c2 := Color(0.38, 0.38, 0.36) # shadow face
# Main body polygon (roughly an irregular hex).
var body := PackedVector2Array([
Vector2(-5.0, 3.0),
Vector2(-6.0, -1.0),
Vector2(-2.0, -6.0),
Vector2(3.0, -5.0),
Vector2(6.0, 0.0),
Vector2(4.0, 4.0),
])
draw_colored_polygon(body, c1)
# Shadow face on the bottom-right triangle to give depth.
var shadow := PackedVector2Array([
Vector2(3.0, -5.0),
Vector2(6.0, 0.0),
Vector2(4.0, 4.0),
Vector2(-5.0, 3.0),
])
draw_colored_polygon(shadow, c2)
# Outline.
draw_polyline(body, Color(0.0, 0.0, 0.0, 0.5), 1.0)
draw_line(body[5], body[0], Color(0.0, 0.0, 0.0, 0.5), 1.0)
# Mine-progress crack: a dark jagged line on the face when partially mined.
if mine_progress > 0:
var ratio := float(mine_progress) / float(MINE_TICKS)
var crack_len := ratio * 5.0
draw_line(
Vector2(-1.0, -2.0),
Vector2(-1.0 + crack_len, 1.0),
Color(0.15, 0.12, 0.10, 0.85),
1.5
)
# ── helpers ───────────────────────────────────────────────────────────────────
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
)

View file

@ -0,0 +1 @@
uid://dpy14o4grgsgt

View file

@ -0,0 +1,6 @@
[gd_scene load_steps=2 format=3 uid="uid://rock_entity"]
[ext_resource type="Script" path="res://scenes/entities/rock.gd" id="1_rock"]
[node name="Rock" type="Node2D"]
script = ExtResource("1_rock")

162
scenes/entities/tree.gd Normal file
View file

@ -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
)

View file

@ -0,0 +1 @@
uid://cpg0v8f6hajgi

View file

@ -0,0 +1,6 @@
[gd_scene load_steps=2 format=3 uid="uid://tree_entity"]
[ext_resource type="Script" path="res://scenes/entities/tree.gd" id="1_tree"]
[node name="Tree" type="Node2D"]
script = ExtResource("1_tree")