.editorconfig

@@ -1,4 +1,46 @@
 root = true
 
 [*]
+end_of_line = lf
 charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+indent_style = tab
+indent_size = 4
+
+[*.gd]
+indent_style = tab
+indent_size = 4
+max_line_length = 120
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.tscn]
+indent_style = tab
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.tres]
+indent_style = tab
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.md]
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+max_line_length = 120
+insert_final_newline = true
+
+[*.cfg]
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[.env*]
+charset = utf-8
+indent_style = unset
+trim_trailing_whitespace = false
+end_of_line = unset
+insert_final_newline = unset
+max_line_length = unset

characters/player/player_base.tscn

@@ -0,0 +1,15 @@
+[gd_scene load_steps=2 format=3 uid="uid://player_base"]
+
+[ext_resource type="Script" path="res://movement/player_movement_controller.gd" id="1"]
+
+[node name="PlayerBase" type="CharacterBody3D"]
+
+[node name="PlayerMovementController" type="Node" parent="."]
+script = ExtResource("1")
+
+[node name="MovementStateMachine" type="Node" parent="PlayerMovementController"]
+
+[node name="Camera3D" type="Camera3D" parent="PlayerMovementController"]
+
+[node name="CapsuleShape3D" type="CollisionShape3D" parent="."]
+shape = SubResource("")

icon.svg.import

@@ -18,8 +18,6 @@ dest_files=["res://.godot/imported/icon.svg-218a8f2b3041327d8a5756f3a245f83b.cte
 compress/mode=0
 compress/high_quality=false
 compress/lossy_quality=0.7
-compress/uastc_level=0
-compress/rdo_quality_loss=0.0
 compress/hdr_compression=1
 compress/normal_map=0
 compress/channel_pack=0
@@ -27,10 +25,6 @@ mipmaps/generate=false
 mipmaps/limit=-1
 roughness/mode=0
 roughness/src_normal=""
-process/channel_remap/red=0
-process/channel_remap/green=1
-process/channel_remap/blue=2
-process/channel_remap/alpha=3
 process/fix_alpha_border=true
 process/premult_alpha=false
 process/normal_map_invert_y=false

input_map.cfg

@@ -0,0 +1,114 @@
+; Papaya-Shooter Input Map
+; Copy these into Project Settings > Input Map manually or load at runtime.
+
+[jump]
+type=physical
+deadzone=0.0
+events/0=Key(Space)
+
+[sprint]
+type=physical
+deadzone=0.0
+events/0=Key(Shift)
+
+[crouch]
+type=physical
+deadzone=0.0
+events/0=Key(Control)
+
+[dash]
+type=physical
+deadzone=0.0
+events/0=Key(Shift, pressed=false, double_click=true) ; optional double-tap
+events/1=Key(LShift)
+
+[fire]
+type=physical
+deadzone=0.0
+events/0=MouseButton(button_index=1) ; right click
+events/1=Key(F)
+
+[fire_alt]
+type=physical
+deadzone=0.0
+events/0=MouseButton(button_index=0) ; left click
+
+[reload]
+type=physical
+deadzone=0.0
+events/0=Key(R)
+
+[weapon_1]
+type=physical
+deadzone=0.0
+events/0=Key(1)
+
+[weapon_2]
+type=physical
+deadzone=0.0
+events/0=Key(2)
+
+[weapon_3]
+type=physical
+deadzone=0.0
+events/0=Key(3)
+
+[weapon_4]
+type=physical
+deadzone=0.0
+events/0=Key(4)
+
+[weapon_next]
+type=physical
+deadzone=0.0
+events/0=MouseWheel(direction=1)
+
+[weapon_prev]
+type=physical
+deadzone=0.0
+events/0=MouseWheel(direction=-1)
+
+[move_forward]
+type=physical
+deadzone=0.0
+events/0=Key(W)
+
+[move_back]
+type=physical
+deadzone=0.0
+events/0=Key(S)
+
+[move_left]
+type=physical
+deadzone=0.0
+events/0=Key(A)
+
+[move_right]
+type=physical
+deadzone=0.0
+events/0=Key(D)
+
+[look_x]
+type=axis
+deadzone=0.0
+events/0=MouseMotion(axis=1, position=1) ; horizontal mouse
+
+[look_y]
+type=axis
+deadzone=0.0
+events/0=MouseMotion(axis=1, position=-1) ; vertical mouse (inverted)
+
+[reload]
+type=physical
+deadzone=0.0
+events/0=Key(R)
+
+[interact]
+type=physical
+deadzone=0.0
+events/0=Key(E)
+
+[jump]
+type=physical
+deadzone=0.0
+events/0=Key(Space)

movement/movement_params.gd

@@ -0,0 +1,76 @@
+extends Resource
+class_name MovementParams
+
+# ── Ground ────────────────────────────────────────────────────────────────────
+@export var walk_speed: float = 7.0
+@export var sprint_speed: float = 11.0
+@export var crouch_speed: float = 4.0
+@export var ground_friction: float = 8.0
+@export var ground_acceleration: float = 30.0
+@export var ground_deceleration: float = 20.0
+
+# ── Jump / Air ────────────────────────────────────────────────────────────────
+@export var jump_velocity: float = 8.5
+@export var coyote_time: float = 0.15
+@export var jump_buffer: float = 0.12
+@export var air_control: float = 0.3
+@export var air_acceleration: float = 25.0
+@export var max_air_speed: float = 16.0
+@export var gravity: float = 20.0
+@export var fall_multiplier: float = 2.0
+@export var low_jump_multiplier: float = 1.5
+
+# ── Bunny Hop ─────────────────────────────────────────────────────────────────
+@export var bunny_hop_impulse: float = 1.15
+@export var bunny_hop_speed_gain: float = 0.5
+@export var bunny_hop_speed_cap: float = 16.0
+
+# ── Slide ─────────────────────────────────────────────────────────────────────
+@export var slide_speed: float = 14.0
+@export var slide_friction: float = 0.88
+@export var slide_min_speed: float = 12.0
+@export var slide_duration: float = 0.8
+@export var slide_into_sprint_delay: float = 0.15
+
+# ── Wall Run ──────────────────────────────────────────────────────────────────
+@export var wall_run_speed: float = 12.0
+@export var wall_run_vertical_speed: float = 8.0
+@export var wall_run_duration: float = 1.2
+@export var wall_run_gravity: float = -2.0
+@export var wall_run_auto_jump_speed: float = 15.0
+@export var wall_run_jump_horizontal: float = 14.0
+@export var wall_run_jump_off_normal: float = 9.0
+@export var wall_angle_threshold: float = 70.0
+@export var wall_detect_distance: float = 1.0
+@export var wall_ray_up_height: float = 1.2
+@export var wall_ray_down_height: float = 0.4
+
+# ── Wall Cling ────────────────────────────────────────────────────────────────
+@export var wall_cling_horizontal_speed: float = 0.0
+@export var wall_cling_vertical_speed: float = 0.0
+@export var wall_cling_stamina_drain: float = 2.0
+@export var wall_cling_max_stamina: float = 2.0
+
+# ── Dash ──────────────────────────────────────────────────────────────────────
+@export var dash_speed: float = 18.0
+@export var dash_duration: float = 0.25
+@export var dash_cooldown: float = 1.0
+@export var dash_invulnerability_time: float = 0.1
+
+# ── Rocket Jump ───────────────────────────────────────────────────────────────
+@export var rocket_jump_self_damage: float = 15.0
+@export var rocket_jump_up_impulse: float = 20.0
+@export var rocket_jump_explosion_radius: float = 6.0
+@export var rocket_jump_falloff: float = 1.5
+
+# ── Shotgun Jump ──────────────────────────────────────────────────────────────
+@export var shotgun_jump_impulse: float = 20.0
+
+# ── Double Jump ───────────────────────────────────────────────────────────────
+@export var double_jump_velocity: float = 8.0
+@export var double_jump_max_count: int = 1
+
+# ── Chaining ──────────────────────────────────────────────────────────────────
+@export var chain_bonus_per_success: float = 0.05
+@export var chain_bonus_cap: float = 0.50
+@export var chain_window: float = 0.4

movement/movement_state_machine.gd

@@ -0,0 +1,103 @@
+extends Node
+class_name MovementStateMachine
+
+## Generic state machine for player movement.
+## Each state is a Node child; the machine switches between them.
+## States must call `self.transition_to(new_state_name)` to change states.
+
+signal state_changed(from_state: String, to_state: String)
+signal movement_event(event_name: String, data: Dictionary)
+
+var current_state: String = ""
+var states: Dictionary = {}
+
+var player: CharacterBody3D
+var params: MovementParams
+var input_dir: Vector2 = Vector2.ZERO
+var input_jump_pressed: bool = false
+var input_jump_just_pressed: bool = false
+var input_sprint: bool = false
+var input_crouch: bool = false
+var input_dash: bool = false
+var wall_normal: Vector3 = Vector3.ZERO
+var on_ground: bool = false
+var last_ground_time: float = 0.0
+var jump_buffer_time: float = 0.0
+var coyote_timer: float = 0.0
+var current_jump_count: int = 0
+var chain_timer: float = 0.0
+var chain_count: int = 0
+var current_chain_bonus: float = 0.0
+
+
+func _ready() -> void:
+	for child in get_children():
+		if child is Node and child.name.begins_with("state_"):
+			states[child.name.replace("state_", "")] = child
+			child.machine = self
+	if current_state.is_empty() and not states.is_empty():
+		switch_to(states.keys()[0])
+
+
+func _physics_process(delta: float) -> void:
+	# Update coyote time
+	if on_ground:
+		coyote_timer = params.coyote_time
+	else:
+		coyote_timer -= delta
+
+	# Update jump buffer
+	if input_jump_just_pressed:
+		jump_buffer_time = params.jump_buffer
+	else:
+		jump_buffer_time -= delta
+
+	# Update chain timer
+	if chain_timer > 0.0:
+		chain_timer -= delta
+	else:
+		chain_count = 0
+		current_chain_bonus = 0.0
+
+	if current_state.is_empty():
+		return
+	var state_node = states[current_state]
+	if state_node.has_method("update"):
+		state_node.update(delta)
+	# Apply gravity that was accumulated during state update, regardless of state.
+	# CharacterBody3D handles gravity automatically via move_and_slide but
+	# we tune it per-position here.
+
+
+func switch_to(new_state_name: String, data: Dictionary = {}) -> void:
+	if new_state_name == current_state:
+		return
+	var prev = current_state
+	current_state = new_state_name
+	for key in states:
+		var st = states[key]
+		if key == new_state_name:
+			st.enter(data)
+		else:
+			st.exit()
+	state_changed.emit(prev, new_state_name)
+
+
+func register_chain_mechanic(mechanic_name: String) -> void:
+	if chain_timer > 0.0 and chain_count > 0:
+		chain_count = min(chain_count + 1, 10)
+	else:
+		chain_count = 1
+	chain_timer = params.chain_window
+	current_chain_bonus = min(
+		float(chain_count) * params.chain_bonus_per_success,
+		params.chain_bonus_cap
+	)
+	movement_event.emit("chain_updated", {
+		"count": chain_count,
+		"bonus": current_chain_bonus
+	})
+
+
+func get_effective_speed(base_speed: float) -> float:
+	return base_speed * (1.0 + current_chain_bonus)

movement/player_movement_controller.gd

@@ -0,0 +1,50 @@
+extends CharacterBody3D
+class_name PlayerMovementController
+
+## PlayerMovementController — root node for all player 3D locomotion.
+## Attach to a CharacterBody3D with a CollisionShape3D.
+## States are expected to be children: state_ground, state_air,
+## state_wall_run, state_wall_cling, state_slide, state_dash.
+
+signal chain_updated(count: int, bonus: float)
+
+@export var params: MovementParams = preload("res://movement/movement_params.gd").new()
+
+var machine: MovementStateMachine
+var jump_buffered: bool = false
+
+# ── Input references ─────────────────────────────────────────────────────────
+func _unhandled_input(event: InputEvent) -> void:
+	if event.is_action_pressed("ui_accept"):
+		# Space / jump
+		pass
+	_machine.input_jump_just_pressed = Input.is_action_just_pressed("jump")
+	_machine.input_jump_pressed = Input.is_action_pressed("jump")
+	_machine.input_sprint = Input.is_action_pressed("sprint")
+	_machine.input_crouch = Input.is_action_pressed("crouch")
+	_machine.input_dash = Input.is_action_just_pressed("dash")
+	var input_v := Input.get_vector("move_left", "move_right", "move_forward", "move_back")
+	_machine.input_dir = input_v
+
+
+@onready var _machine: MovementStateMachine = $MovementStateMachine
+
+
+func _ready() -> void:
+	_machine.player = self
+	_machine.params = params
+	# Mirror signal up
+	_machine.movement_event.connect(func(ev, data):
+		if ev == "chain_updated":
+			chain_updated.emit(data.count, data.bonus)
+	)
+
+
+func _process(_delta: float) -> void:
+	_machine.input_jump_just_pressed = Input.is_action_just_pressed("jump") and not _machine.input_jump_pressed
+	_machine.input_jump_pressed = Input.is_action_pressed("jump")
+	_machine.input_sprint = Input.is_action_pressed("sprint")
+	_machine.input_crouch = Input.is_action_pressed("crouch")
+	_machine.input_dash = Input.is_action_just_pressed("dash") and not _machine.input_dash
+	var input_v := Input.get_vector("move_left", "move_right", "move_forward", "move_back")
+	_machine.input_dir = input_v

movement/states/state_air.gd

@@ -0,0 +1,70 @@
+extends Node
+class_name StateAir
+
+var machine: MovementStateMachine
+var params: MovementParams:
+	get: return machine.params
+
+
+func enter(_data: Dictionary = {}) -> void:
+	pass
+
+
+func exit() -> void:
+	pass
+
+
+func update(delta: float) -> void:
+	var vel: Vector3 = machine.player.velocity
+
+	# Apply standard gravity
+	vel.y -= params.gravity * delta
+
+	# Input direction
+	var input_v := machine.input_dir
+	var wish_dir := Vector3(input_v.x, 0.0, -input_v.y)
+	if wish_dir.length_squared() > 1.0:
+		wish_dir = wish_dir.normalized()
+
+	var effective_speed := machine.get_effective_speed(params.max_air_speed)
+
+	var hvel := Vector3(vel.x, 0.0, vel.z)
+	var target_vel := wish_dir * effective_speed * params.air_control
+
+	hvel = hvel.lerp(Vector3(hvel.x + target_vel.x, 0.0, hvel.z + target_vel.z), 1.0 - exp(-params.air_acceleration * delta))
+
+	vel.x = hvel.x
+	vel.z = hvel.z
+
+	# Bunny hop: if jump pressed and on ground near-peak of arc → extra boost
+	if machine.input_jump_just_pressed and machine.on_ground:
+		vel.y = params.jump_velocity * params.bunny_hop_impulse
+		machine.player.velocity = vel
+		machine.register_chain_mechanic("bunny_hop")
+		machine.current_jump_count += 1
+		machine.on_ground = false
+		machine.switch_to("air")
+		return
+
+	# Double Jump
+	if machine.input_jump_just_pressed and not machine.on_ground and machine.current_jump_count < params.double_jump_max_count:
+		vel.y = params.double_jump_velocity
+		machine.player.velocity = vel
+		machine.current_jump_count += 1
+		machine.register_chain_mechanic("double_jump")
+		machine.switch_to("air")
+		return
+
+	machine.player.velocity = vel
+	machine.player.move_and_slide()
+
+	# Landing
+	if machine.player.is_on_floor():
+		machine.on_ground = true
+		machine.current_jump_count = 0
+		machine.switch_to("ground")
+		return
+
+	# Wall run transition
+	if not machine.wall_normal.is_zero_approx():
+		machine.switch_to("wall_run")

movement/states/state_dash.gd

@@ -0,0 +1,45 @@
+extends Node
+class_name StateDash
+
+var machine: MovementStateMachine
+var params: MovementParams:
+	get: return machine.params
+
+var elapsed: float = 0.0
+var direction: Vector3 = Vector3.ZERO
+var dash_cooldown_timer: float = 0.0
+
+
+func enter(_data: Dictionary = {}) -> void:
+	elapsed = 0.0
+	dash_cooldown_timer = params.dash_cooldown
+	var input_v := machine.input_dir
+	var wish_dir := Vector3(input_v.x, 0.0, -input_v.y)
+	if wish_dir.length_squared() > 0.0:
+		direction = wish_dir.normalized()
+	else:
+		direction = -machine.player.global_transform.basis.z.normalized()
+		direction.y = 0.0
+		direction = direction.normalized()
+	direction = (machine.player.global_transform.basis * Vector4(direction.x, 0.0, direction.y, 0.0)).normalized()
+	machine.register_chain_mechanic("dash")
+	machine.player.velocity = direction * machine.get_effective_speed(params.dash_speed)
+	machine.on_ground = false
+
+
+func exit() -> void:
+	pass
+
+
+func update(delta: float) -> void:
+	elapsed += delta
+	dash_cooldown_timer -= delta
+	if elapsed > params.dash_duration:
+		machine.switch_to("air")
+		return
+	# Skip gravity, maintain dash velocity
+	machine.player.velocity = direction * machine.get_effective_speed(params.dash_speed)
+	machine.player.move_and_slide()
+	if machine.player.is_on_floor():
+		machine.on_ground = true
+		machine.switch_to("ground")

movement/states/state_ground.gd

@@ -0,0 +1,109 @@
+extends Node
+class_name StateGround
+
+var machine: MovementStateMachine
+var params: MovementParams:
+	get: return machine.params
+
+
+func enter(_data: Dictionary = {}) -> void:
+	pass
+
+
+func exit() -> void:
+	pass
+
+
+func update(delta: float) -> void:
+	var vel: Vector3 = machine.player.velocity
+
+	# Input direction
+	var input_v := machine.input_dir
+	var wish_dir := Vector3(input_v.x, 0.0, -input_v.y)
+	if wish_dir.length_squared() > 1.0:
+		wish_dir = wish_dir.normalized()
+
+	var speed := params.walk_speed
+
+	if machine.input_sprint and wish_dir.length_squared() > 0.1:
+		speed = params.sprint_speed
+
+	var effective_speed := machine.get_effective_speed(speed)
+
+	# Horizontal movement
+	var hvel := Vector3(vel.x, 0.0, vel.z)
+	var target_vel := wish_dir * effective_speed
+
+	if wish_dir.length_squared() > 0.0:
+		var accel := params.ground_acceleration
+		hvel = hvel.lerp(target_vel, 1.0 - exp(-accel * delta))
+	else:
+		hvel = hvel.lerp(Vector3.ZERO, 1.0 - exp(-params.ground_deceleration * delta))
+
+	vel.x = hvel.x
+	vel.z = hvel.z
+
+	# Gravity (we apply tuned gravity so we don't double-apply from _velocity)
+	var actual_gravity := params.gravity
+	if vel.y < 0.0:
+		vel.y += actual_gravity * params.fall_multiplier * delta
+	elif vel.y > 0.0 and not machine.input_jump_pressed:
+		vel.y += actual_gravity * params.low_jump_multiplier * delta
+	else:
+		vel.y -= actual_gravity * delta
+
+	machine.player.velocity = vel
+	machine.player.move_and_slide()
+
+	var on_wall := detect_wall()
+	if on_wall and machine.input_dir.length() > 0.0:
+		machine.wall_normal = on_wall
+		machine.switch_to("wall_run")
+
+	if machine.input_jump_just_pressed and machine.coyote_timer > 0.0:
+		machine.player.velocity.y = params.jump_velocity
+		machine.current_jump_count = 1
+		machine.on_ground = false
+		machine.register_chain_mechanic("jump")
+		machine.switch_to("air")
+
+	if machine.player.is_on_floor():
+		machine.on_ground = true
+		machine.last_ground_time = machine.get_process_delta_time()
+		machine.current_jump_count = 0
+	else:
+		machine.on_ground = false
+		if machine.input_jump_just_pressed and machine.jump_buffer_time > 0.0:
+			machine.player.velocity.y = params.jump_velocity
+			machine.current_jump_count = 1
+			machine.register_chain_mechanic("jump")
+			machine.switch_to("air")
+		elif vel.y < 0.0:
+			machine.switch_to("air")
+
+	# Slide
+	if machine.input_crouch and machine.input_sprint and machine.player.velocity.length() > params.slide_min_speed:
+		machine.switch_to("slide")
+		return
+
+	# Dash
+	if machine.input_dash and machine.player.velocity.length() > 0.0:
+		machine.switch_to("dash")
+
+
+func detect_wall() -> Vector3:
+	var origin := machine.player.global_position
+	var hvel := Vector3(machine.player.velocity.x, 0.0, machine.player.velocity.z).normalized()
+	if hvel.length_squared() < 0.01:
+		hvel = Vector3.FORWARD
+	var space_state := machine.player.get_world_3d().direct_space_state
+	for offset_sign in [1.0, -1.0]:
+		var offset := hvel.cross(Vector3.UP) * offset_sign * machine.player.shape_owner_get_owner(0).shape_get_radius() if false else hvel.cross(Vector3.UP) * offset_sign * 0.4
+		var ray := PhysicsRayQueryParameters3D.create(origin + offset + Vector3.UP * params.wall_ray_up_height, origin + offset + Vector3.DOWN * params.wall_ray_down_height)
+		ray.exclude = [machine.player.get_rid()]
+		var hit := space_state.intersect_ray(ray)
+		if not hit.is_empty():
+			var n := hit.get("normal", Vector3.ZERO)
+			if n.y < 0.3 and n.length_squared() > 0.0:
+				return n.normalized()
+	return Vector3.ZERO

movement/states/state_slide.gd

@@ -0,0 +1,60 @@
+extends Node
+class_name StateSlide
+
+var machine: MovementStateMachine
+var params: MovementParams:
+	get: return machine.params
+
+var elapsed: float = 0.0
+
+
+func enter(_data: Dictionary = {}) -> void:
+	elapsed = 0.0
+	machine.register_chain_mechanic("slide")
+	# Lower player capsule
+	var player_node = machine.player
+	var shape: CapsuleShape3D = player_node.shape_owner_get_shape(0)
+	if shape:
+		shape.height = shape.height * 0.5
+
+
+func exit() -> void:
+	pass
+
+
+func update(delta: float) -> void:
+	elapsed += delta
+	var vel: Vector3 = machine.player.velocity
+	var forward: Vector3 = -machine.player.global_transform.basis.z
+	if forward.length_squared() > 1.0:
+		forward = forward.normalized()
+	vel.x = forward.x * params.slide_speed * machine.get_effective_speed(1.0)
+	vel.z = forward.z * params.slide_speed * machine.get_effective_speed(1.0)
+	vel.x *= pow(params.slide_friction, delta)
+	vel.z *= pow(params.slide_friction, delta)
+	machine.player.velocity = vel
+	machine.player.move_and_slide()
+
+	if machine.player.is_on_floor():
+		machine.on_ground = true
+		var speed := Vector3(vel.x, 0.0, vel.z).length()
+		if speed < params.slide_min_speed or elapsed > params.slide_duration:
+			var shape: CapsuleShape3D = machine.player.shape_owner_get_shape(0)
+			if shape:
+				shape.height = shape.height * 2.0
+			machine.register_chain_mechanic("slide_end")
+			machine.switch_to("ground")
+			return
+	else:
+		var shape2: CapsuleShape3D = machine.player.shape_owner_get_shape(0)
+		if shape2:
+			shape2.height = shape2.height * 2.0
+		machine.on_ground = false
+		machine.switch_to("air")
+
+	if not machine.input_crouch or not machine.input_sprint:
+		var shape3: CapsuleShape3D = machine.player.shape_owner_get_shape(0)
+		if shape3:
+			shape3.height = shape3.height * 2.0
+		machine.register_chain_mechanic("slide_cancel")
+		machine.switch_to("ground")

movement/states/state_wall_cling.gd

@@ -0,0 +1,52 @@
+extends Node
+class_name StateWallCling
+
+var machine: MovementStateMachine
+var params: MovementParams:
+	get: return machine.params
+
+var elapsed: float = 0.0
+
+
+func enter(_data: Dictionary = {}) -> void:
+	elapsed = 0.0
+	machine.register_chain_mechanic("wall_cling")
+
+
+func exit() -> void:
+	pass
+
+
+func update(delta: float) -> void:
+	elapsed += delta
+	var vel: Vector3 = machine.player.velocity
+	vel.x = params.wall_cling_horizontal_speed
+	vel.y = params.wall_cling_vertical_speed
+	vel.z = params.wall_cling_horizontal_speed
+	machine.player.velocity = vel
+	machine.player.move_and_slide()
+
+	# Jump off wall
+	if machine.input_jump_just_pressed:
+		var push_dir := machine.wall_normal * params.wall_run_jump_off_normal
+		var vel2 := Vector3(push_dir.x, params.jump_velocity, push_dir.z)
+		machine.player.velocity = vel2
+		machine.register_chain_mechanic("wall_cling_jump")
+		machine.switch_to("air")
+		return
+
+	# Re-enter wall run with input
+	if machine.input_dir.length() > 0.1:
+		machine.switch_to("wall_run")
+		return
+
+	# Fall
+	if not machine.wall_normal or machine.wall_normal.is_zero_approx():
+		machine.switch_to("air")
+		return
+
+	if machine.player.is_on_floor():
+		machine.on_ground = true
+		machine.wall_normal = Vector3.ZERO
+		machine.register_chain_mechanic("cling_land")
+		machine.switch_to("ground")

movement/states/state_wall_run.gd

@@ -0,0 +1,88 @@
+extends Node
+class_name StateWallRun
+
+const FLAG: int = 0  # unused
+
+var machine: MovementStateMachine
+var params: MovementParams:
+	get: return machine.params
+
+var elapsed: float = 0.0
+
+
+func enter(_data: Dictionary = {}) -> void:
+	elapsed = 0.0
+	machine.register_chain_mechanic("wall_run")
+	machine.player.velocity.y = params.wall_run_vertical_speed
+
+
+func exit() -> void:
+	pass
+
+
+func update(delta: float) -> void:
+	elapsed += delta
+	if elapsed > params.wall_run_duration:
+		machine.wall_normal = Vector3.ZERO
+		machine.switch_to("air")
+		return
+
+	var vel: Vector3 = machine.player.velocity
+
+	# Stick to wall
+	vel.y = min(vel.y, params.wall_run_vertical_speed)
+
+	# Move along wall: project velocity onto wall tangent
+	var wall_tangent := (machine.wall_normal.cross(Vector3.UP)).normalized()
+	if machine.input_dir.y < 0.0:
+		wall_tangent = -wall_tangent
+	var move_dir: Vector3 = wall_tangent * params.wall_run_speed
+	vel.x = move_dir.x
+	vel.z = move_dir.z
+
+	if machine.input_jump_just_pressed:
+		var jump_vel: Vector3 = vel + (machine.wall_normal * params.wall_run_jump_off_normal)
+		jump_vel.y = params.wall_run_auto_jump_speed
+		machine.player.velocity = jump_vel
+		machine.wall_normal = Vector3.ZERO
+		machine.register_chain_mechanic("wall_jump")
+		machine.switch_to("air")
+		return
+
+	# Wall cling fall-through
+	if machine.input_dir.length() < 0.1:
+		machine.switch_to("wall_cling")
+		return
+
+	# Lose wall contact
+	var still_on_wall := machine.wall_normal != Vector3.ZERO and
+		detect_wall(machine.wall_normal).length_squared() > 0.0
+	if not still_on_wall:
+		machine.wall_normal = Vector3.ZERO
+		machine.register_chain_mechanic("wall_run_off")
+		machine.switch_to("air")
+
+	machine.player.velocity = vel
+	machine.player.move_and_slide()
+
+	if machine.player.is_on_floor():
+		machine.on_ground = true
+		machine.wall_normal = Vector3.ZERO
+		machine.current_jump_count = 0
+		machine.register_chain_mechanic("wall_run_land")
+		machine.switch_to("ground")
+
+
+func detect_wall(expected_normal: Vector3) -> Vector3:
+	var origin := machine.player.global_position
+	var offset := expected_normal.cross(Vector3.UP).normalized()
+	var space_state := machine.player.get_world_3d().direct_space_state
+	for side in [1.0, -1.0]:
+		var ray_origin := origin + offset * side * params.wall_detect_distance + Vector3.UP * params.wall_ray_up_height
+		var ray_end := origin + offset * side * params.wall_detect_distance - Vector3.DOWN * params.wall_ray_down_height
+		var ray := PhysicsRayQueryParameters3D.create(ray_origin, ray_end)
+		ray.exclude = [machine.player.get_rid()]
+		var hit := space_state.intersect_ray(ray)
+		if not hit.is_empty():
+			return hit.get("normal", Vector3.ZERO).normalized()
+	return Vector3.ZERO

movement/tests/test_fsm_runner.gd

@@ -0,0 +1,169 @@
+extends Node
+class_name MovementStateMachineTest
+
+## Tests for MovementStateMachine logic.
+## Run: godot --headless --path . --script movement/tests/test_fsm_runner.gd --quit
+
+var sm: MovementStateMachine
+var fake_player: CharacterBody3D
+var params: MovementParams
+var fail_log := []
+
+var tests_passed: int = 0
+var tests_failed: int = 0
+
+
+func run_all() -> void:
+	print("=== MovementStateMachine tests ===")
+	tests_passed = 0
+	tests_failed = 0
+	params = MovementParams.new()
+	fake_player = CharacterBody3D.new()
+	sm = MovementStateMachine.new()
+	sm.player = fake_player
+	sm.params = params
+
+	var tests := [
+		test_states_initialize_with_ground,
+		test_ground_transitions_to_air_on_jump,
+		test_air_transitions_to_ground_on_land,
+		test_double_jump_allowed_once,
+		test_wall_run_started_when_near_wall,
+		test_chain_bonus_caps_at_50pct,
+		test_sliding_reduces_speed,
+		test_dash_speed_under_effective_cap,
+	]
+	for t in tests:
+		_fresh()
+		call(t)
+		var ok := fail_log.is_empty()
+		print("  %s: %s" % ["PASS" if ok else "FAIL", t])
+		if ok:
+			tests_passed += 1
+		else:
+			tests_failed += 1
+			for msg in fail_log:
+				print("    ", msg)
+			fail_log.clear()
+
+	print("=== Results: %d passed, %d failed ===" % [tests_passed, tests_failed])
+	if tests_failed > 0:
+		print("SOME TESTS FAILED")
+		get_tree().quit(1)
+	else:
+		print("ALL TESTS PASSED")
+		get_tree().quit(0)
+
+
+# ── helpers ─────────────────────────────────────────────────────────────────
+
+func _fresh() -> void:
+	sm.current_state = ""
+	sm.chain_count = 0
+	sm.current_chain_bonus = 0.0
+	sm.chain_timer = 0.0
+	sm.on_ground = false
+	sm.coyote_timer = 0.0
+	sm.jump_buffer_time = 0.0
+	sm.current_jump_count = 0
+	sm.wall_normal = Vector3.ZERO
+	sm.input_dir = Vector2.ZERO
+	sm.input_jump_pressed = false
+	sm.input_jump_just_pressed = false
+	sm.input_sprint = false
+	sm.input_crouch = false
+	sm.input_dash = false
+	fake_player.velocity = Vector3.ZERO
+	fake_player.set_floor_max_angle(0.01)
+	for c in sm.get_children():
+		sm.remove_child(c)
+
+
+func _expect(cond: bool, msg: String) -> void:
+	if not cond:
+		fail_log.append(msg)
+
+
+func _eq(a: Variant, b: Variant, msg: String = "") -> void:
+	if a != b:
+		fail_log.append(msg if not msg.is_empty() else ("expected %s == %s" % [a, b]))
+
+
+# ── tests ───────────────────────────────────────────────────────────────────
+
+func test_states_initialize_with_ground() -> void:
+	var g = Node.new(); g.name = "state_ground"; g.machine = sm; sm.add_child(g)
+	var a = Node.new(); a.name = "state_air"; a.machine = sm; sm.add_child(a)
+	sm.switch_to("ground")
+	_eq(sm.current_state, "ground")
+
+
+func test_ground_transitions_to_air_on_jump() -> void:
+	var g = Node.new(); g.name = "state_ground"; g.machine = sm; sm.add_child(g)
+	var a = Node.new(); a.name = "state_air"; a.machine = sm; sm.add_child(a)
+	sm.on_ground = true
+	sm.switch_to("air")
+	_eq(sm.current_state, "air")
+
+
+func test_air_transitions_to_ground_on_land() -> void:
+	var a = Node.new(); a.name = "state_air"; a.machine = sm; sm.add_child(a)
+	sm.switch_to("ground")
+	sm.on_ground = false
+	fake_player.velocity = Vector3.ZERO
+	fake_player.set_floor_max_angle(0.01)
+	sm.switch_to("air")
+	fake_player.velocity = Vector3.ZERO
+	fake_player.set_floor_max_angle(0.01)
+	sm.switch_to("ground")
+	_eq(sm.current_state, "ground")
+
+
+func test_double_jump_allowed_once() -> void:
+	params.double_jump_max_count = 1
+	var a = Node.new(); a.name = "state_air"; a.machine = sm; sm.add_child(a)
+	sm.on_ground = false
+	sm.current_jump_count = 1
+	_eq(sm.current_jump_count, 1)
+	_expect(sm.current_jump_count < params.double_jump_max_count + 1,
+			"should allow double jump once")
+
+
+func test_wall_run_started_when_near_wall() -> void:
+	var g = Node.new(); g.name = "state_ground"; g.machine = sm; sm.add_child(g)
+	var a = Node.new(); a.name = "state_air"; a.machine = sm; sm.add_child(a)
+	sm.wall_normal = Vector3.RIGHT.normalized()
+	sm.switch_to("wall_run")
+	_eq(sm.current_state, "wall_run")
+
+
+func test_chain_bonus_caps_at_50pct() -> void:
+	params.chain_bonus_per_success = 0.05
+	params.chain_bonus_cap = 0.50
+	sm.register_chain_mechanic("jump")
+	sm.register_chain_mechanic("slide")
+	sm.register_chain_mechanic("wall_run")
+	_expect(sm.chain_count == 3, "chain_count 3 after 3 mechanics")
+	_expect(sm.current_chain_bonus <= params.chain_bonus_cap + 0.001,
+			"bonus should be bounded by cap")
+
+
+func test_sliding_reduces_speed() -> void:
+	params.slide_speed = 14.0
+	params.slide_min_speed = 12.0
+	_expect(params.slide_min_speed < params.slide_speed,
+			"slide_min_speed must be below slide_speed")
+
+
+func test_dash_speed_under_effective_cap() -> void:
+	var d = Node.new(); d.name = "state_dash"; d.machine = sm; sm.add_child(d)
+	sm.on_ground = false
+	var eff := sm.get_effective_speed(params.dash_speed)
+	_expect(eff <= params.dash_speed * (1.0 + params.chain_bonus_cap),
+			"dash effective speed should respect chain cap")
+
+
+func test_rocket_jump_impulse_sets_upward_velocity() -> void:
+	# Unit test: verify impulse formula in state_machine
+	params.rocket_jump_up_impulse = 20.0
+	_expect(params.rocket_jump_up_impulse > 0.0, "rocket jump must have positive upward impulse")