[X02][Codex] Implement Ghost Archer

README.md

@@ -33,7 +33,7 @@ The main scene is `res://scenes/main.tscn`. There are no external dependencies 
 | --- | --- |
 | `F1` | Toggle the RunState readout (seed, phase, player state, every stat, snapshot hash) |
 | `F2` / `F3` | Heal / damage the player |
-| `F4` | Spawn a reference enemy next to the player |
+| `F4` | Spawn a Ghost Archer next to the player |
 | `F5` | Start the boss encounter |
 | `F6` / `F7` | Preview / apply the sacrifice |
 | `F8` | Toggle hit, hurt and body boxes |

actors/enemies/ghost_archer.gd

@@ -0,0 +1,115 @@
+class_name GhostArcher
+extends EnemyBase
+## Concrete ranged enemy. EnemyBase's frozen states map to:
+## IDLE=patrol, CHASE=spacing/reposition, WINDUP=aim, ATTACK=shoot,
+## RECOVER=post-shot recovery/cooldown.
+
+signal arrow_fired(arrow: GhostArrow)
+
+@export var archer_config: GhostArcherConfig
+
+var _patrol_origin_x: float
+var _patrol_direction: int = 1
+
+
+func _ready() -> void:
+	super._ready()
+	# This archetype deals damage only through GhostArrow.
+	attack_hitbox.collision_mask = 0
+	attack_hitbox.set_active(false)
+
+
+func initialize(enemy_config: EnemyConfig, target: Node2D) -> void:
+	_patrol_origin_x = global_position.x
+	super.initialize(enemy_config, target)
+
+
+func _enter_state(next: int) -> void:
+	super._enter_state(next)
+	if next == State.ATTACK:
+		attack_hitbox.set_active(false)
+		_shoot()
+
+
+func _update_state(delta: float) -> void:
+	match _state:
+		State.IDLE:
+			_patrol()
+			if _target_in_range(config.detection_range):
+				change_state(State.CHASE)
+		State.CHASE:
+			_update_spacing(delta)
+		State.WINDUP:
+			_decelerate(delta)
+			_face_target()
+			if _state_elapsed >= config.attack_windup:
+				change_state(State.ATTACK)
+		State.ATTACK:
+			_decelerate(delta)
+			if _state_elapsed >= config.attack_active:
+				change_state(State.RECOVER)
+		State.RECOVER:
+			_decelerate(delta)
+			if _state_elapsed >= config.attack_recovery:
+				_cooldown = config.attack_cooldown
+				change_state(State.CHASE if _target_in_range(config.detection_range) else State.IDLE)
+		State.HURT:
+			_decelerate(delta)
+			if _state_elapsed >= config.hurt_duration:
+				change_state(State.CHASE if _target_in_range(config.detection_range) else State.IDLE)
+		State.DEAD:
+			pass
+
+
+func _patrol() -> void:
+	if archer_config == null:
+		velocity.x = 0.0
+		return
+	if is_on_wall() or absf(global_position.x - _patrol_origin_x) >= archer_config.patrol_radius:
+		_patrol_direction *= -1
+	_facing = _patrol_direction
+	sprite.flip_h = _facing < 0
+	velocity.x = _facing * config.move_speed * archer_config.patrol_speed_multiplier
+
+
+func _update_spacing(delta: float) -> void:
+	if archer_config == null or not _target_in_range(config.detection_range):
+		change_state(State.IDLE)
+		return
+	_face_target()
+	var distance := _distance_to_target()
+	if distance < archer_config.retreat_distance:
+		velocity.x = -_facing * config.move_speed
+		return
+	if distance > archer_config.preferred_distance:
+		velocity.x = _facing * config.move_speed
+		return
+	_decelerate(delta)
+	if distance <= config.attack_range and _cooldown <= 0.0:
+		change_state(State.WINDUP)
+
+
+func _shoot() -> void:
+	if _is_dead or archer_config == null or archer_config.projectile_scene == null:
+		return
+	if _target == null or not is_instance_valid(_target):
+		return
+	var arrow := archer_config.projectile_scene.instantiate() as GhostArrow
+	if arrow == null:
+		return
+	var spawn_offset := archer_config.projectile_spawn_offset
+	spawn_offset.x *= _facing
+	var spawn_position := global_position + spawn_offset
+	var direction := (_target.global_position - spawn_position).normalized()
+	arrow.configure(
+		actor_id(),
+		self,
+		direction,
+		config.attack_damage,
+		config.attack_skill_multiplier,
+		archer_config.projectile_speed,
+		archer_config.projectile_lifetime
+	)
+	get_parent().add_child(arrow)
+	arrow.global_position = spawn_position
+	arrow_fired.emit(arrow)

actors/enemies/ghost_archer.tscn

@@ -0,0 +1,18 @@
+[gd_scene load_steps=5 format=3]
+
+[ext_resource type="PackedScene" path="res://actors/enemies/enemy_base.tscn" id="1_base"]
+[ext_resource type="Script" path="res://actors/enemies/ghost_archer.gd" id="2_script"]
+[ext_resource type="SpriteFrames" path="res://actors/enemies/ghost_archer_frames.tres" id="3_frames"]
+[ext_resource type="Resource" path="res://data/actors/ghost_archer_tactics.tres" id="4_tactics"]
+
+[node name="GhostArcher" instance=ExtResource("1_base")]
+script = ExtResource("2_script")
+archer_config = ExtResource("4_tactics")
+
+[node name="Sprite" parent="." index="0"]
+sprite_frames = ExtResource("3_frames")
+animation = &"idle"
+autoplay = "idle"
+
+[node name="Shape" parent="AttackHitbox" index="0"]
+disabled = true

actors/enemies/ghost_archer_config.gd

@@ -0,0 +1,16 @@
+class_name GhostArcherConfig
+extends Resource
+## Data-only spacing and projectile values for the concrete Ghost Archer.
+## Base vitals and shared attack timings remain in EnemyConfig.
+
+@export_group("Spacing")
+@export var patrol_radius: float
+@export var patrol_speed_multiplier: float
+@export var preferred_distance: float
+@export var retreat_distance: float
+
+@export_group("Projectile")
+@export var projectile_scene: PackedScene
+@export var projectile_speed: float
+@export var projectile_lifetime: float
+@export var projectile_spawn_offset: Vector2

actors/enemies/ghost_archer_frames.tres

@@ -0,0 +1,177 @@
+; Generated by tools/generate_sprite_frames.py from docs/ART_SPEC.md.
+; Do not hand-edit: re-run the generator instead.
+[gd_resource type="SpriteFrames" load_steps=26 format=3]
+
+[ext_resource type="Texture2D" path="res://assets/enemy/ghost_archer_idle.png" id="1_idle"]
+[ext_resource type="Texture2D" path="res://assets/enemy/ghost_archer_run.png" id="2_run"]
+[ext_resource type="Texture2D" path="res://assets/enemy/ghost_archer_attack.png" id="3_attack"]
+[ext_resource type="Texture2D" path="res://assets/enemy/ghost_archer_hurt.png" id="4_hurt"]
+[ext_resource type="Texture2D" path="res://assets/enemy/ghost_archer_death.png" id="5_death"]
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_idle_0"]
+atlas = ExtResource("1_idle")
+region = Rect2(0, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_idle_1"]
+atlas = ExtResource("1_idle")
+region = Rect2(48, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_idle_2"]
+atlas = ExtResource("1_idle")
+region = Rect2(96, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_idle_3"]
+atlas = ExtResource("1_idle")
+region = Rect2(144, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_run_0"]
+atlas = ExtResource("2_run")
+region = Rect2(0, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_run_1"]
+atlas = ExtResource("2_run")
+region = Rect2(48, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_run_2"]
+atlas = ExtResource("2_run")
+region = Rect2(96, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_run_3"]
+atlas = ExtResource("2_run")
+region = Rect2(144, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_run_4"]
+atlas = ExtResource("2_run")
+region = Rect2(192, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_run_5"]
+atlas = ExtResource("2_run")
+region = Rect2(240, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_attack_0"]
+atlas = ExtResource("3_attack")
+region = Rect2(0, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_attack_1"]
+atlas = ExtResource("3_attack")
+region = Rect2(48, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_attack_2"]
+atlas = ExtResource("3_attack")
+region = Rect2(96, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_attack_3"]
+atlas = ExtResource("3_attack")
+region = Rect2(144, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_hurt_0"]
+atlas = ExtResource("4_hurt")
+region = Rect2(0, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_hurt_1"]
+atlas = ExtResource("4_hurt")
+region = Rect2(48, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_death_0"]
+atlas = ExtResource("5_death")
+region = Rect2(0, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_death_1"]
+atlas = ExtResource("5_death")
+region = Rect2(48, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_death_2"]
+atlas = ExtResource("5_death")
+region = Rect2(96, 0, 48, 48)
+
+[sub_resource type="AtlasTexture" id="AtlasTexture_death_3"]
+atlas = ExtResource("5_death")
+region = Rect2(144, 0, 48, 48)
+
+[resource]
+animations = [{
+"frames": [{
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_idle_0")
+}, {
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_idle_1")
+}, {
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_idle_2")
+}, {
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_idle_3")
+}],
+"loop": true,
+"name": &"idle",
+"speed": 8.0
+}, {
+"frames": [{
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_run_0")
+}, {
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_run_1")
+}, {
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_run_2")
+}, {
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_run_3")
+}, {
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_run_4")
+}, {
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_run_5")
+}],
+"loop": true,
+"name": &"run",
+"speed": 10.0
+}, {
+"frames": [{
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_attack_0")
+}, {
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_attack_1")
+}, {
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_attack_2")
+}, {
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_attack_3")
+}],
+"loop": false,
+"name": &"attack",
+"speed": 12.0
+}, {
+"frames": [{
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_hurt_0")
+}, {
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_hurt_1")
+}],
+"loop": false,
+"name": &"hurt",
+"speed": 10.0
+}, {
+"frames": [{
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_death_0")
+}, {
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_death_1")
+}, {
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_death_2")
+}, {
+"duration": 1.0,
+"texture": SubResource("AtlasTexture_death_3")
+}],
+"loop": false,
+"name": &"death",
+"speed": 8.0
+}]