class_name Ship
extends RigidBody3D

# Physics-driven spaceship. All movement is force/torque-based, applied in
# _integrate_forces from a ShipAction supplied by a pluggable ShipController
# child node (player input, AI policy, or network replication — see
# set_controller). A ship without a controller is inert but still simulated,
# which is what a placeholder opponent or a headless RL ship needs.
# Physics properties (mass, inertia, friction material) live in ship.tscn.

@export_group("Movement")
@export var thrust_power = 150.0         # Main thruster power
@export var maneuvering_thrust = 75.0    # Side thruster power
@export var vertical_thrust = 120.0      # Up/down thruster power
@export var turbo_multiplier = 2.5       # Turbo boost multiplier
@export var max_speed = 35.0             # Maximum velocity
@export var rotation_power = 20.0        # Angular thrust power
@export var max_angular_speed = 3.0      # Maximum rotation speed
@export var drag_coefficient = 0.98      # Linear drag (air resistance)
@export var angular_drag = 0.95          # Rotational drag
@export var idle_angular_drag = 0.9      # Rotational drag when no rotation input is held

@export_group("Surface Pull")
@export var wall_pull_strength = 6.0     # Wall grav-plating strength (m/s^2-equivalent)
@export var wall_pull_range = 3.0        # Metres from a wall where pull begins
@export var ceiling_pull_strength = 11.5 # Ceiling grav-plating strength; nets above gravity so a ship can hold a ceiling
@export var ceiling_pull_range = 3.0     # Metres from the ceiling where pull begins

# Non-tinted hull meshes, runtime-merged into one ArrayMesh by
# _build_merged_hull() (Nose/TailFin stay separate MeshInstance3Ds since
# _apply_team_color() retints them per-team and must keep addressing them by
# name). Verified via get_surface_count()/surface_get_material() before
# writing this: hull and canopy are each a single surface with their own
# distinct opaque StandardMaterial3D (canopy is NOT alpha/transparent despite
# the name), and engine_l/engine_r are each 2 surfaces, also all distinct
# materials — none of the 6 source surfaces share a material with any other,
# including the L/R engine pair. So this merge does not collapse draw calls
# the way TODO.md's "6 draw calls down to 3" assumed (Godot still issues one
# draw call per surface regardless of how many MeshInstance3Ds they're spread
# across); the real win is scene-tree node count, 4 MeshInstance3D children
# down to 1, cutting per-frame transform/visibility overhead.
const MERGED_MESH_PATHS := [
	"res://assets/models/ship_hull.res",
	"res://assets/models/ship_canopy.res",
	"res://assets/models/ship_engine_l.res",
	"res://assets/models/ship_engine_r.res",
]
const MERGED_MESH_TRANSFORMS := [
	Transform3D(Basis(Vector3(-1, 0, 0), Vector3(0, 1, 0), Vector3(0, 0, -1)), Vector3(0, 0, 0)),             # Hull
	Transform3D(Basis(Vector3(-1, 0, 0), Vector3(0, 1, 0), Vector3(0, 0, -1)), Vector3(0, 0.31, -0.55)),      # Canopy
	Transform3D(Basis(Vector3(-1, 0, 0), Vector3(0, 1, 0), Vector3(0, 0, -1)), Vector3(-0.42, -0.05, 0.95)),  # EngineGlowL
	Transform3D(Basis(Vector3(-1, 0, 0), Vector3(0, 1, 0), Vector3(0, 0, -1)), Vector3(0.42, -0.05, 0.95)),   # EngineGlowR
]

# Which team this ship plays for (0 or 1). Set by the game mode on spawn.
var team: int = 0:
	set(value):
		team = value
		_apply_team_color()

# This ship's index within its team's roster (0, 1, 2, ...), set once by
# GameMode.spawn_ship and never changed afterward. The stable identity
# AIShipController/ShipAIController sort teammates/opponents by, so both
# training and in-game inference assign the same ship to the same
# observation-vector slot for the whole match (see ShipObservations).
var spawn_index: int = -1

# Shared per-team accent material, built once per team and reused by every
# ship — avoids allocating a fresh StandardMaterial3D from both _ready and
# the team setter (previously ran at least twice per ship).
static var _team_materials: Dictionary = {}  # team:int -> StandardMaterial3D


static func _get_team_material(team: int) -> StandardMaterial3D:
	if _team_materials.has(team):
		return _team_materials[team]
	var color: Color = TeamColors.TEAM_COLORS.get(team, TeamColors.TEAM_COLORS[0])
	var accent := StandardMaterial3D.new()
	accent.albedo_color = color
	accent.metallic = 0.3
	accent.roughness = 0.5
	accent.emission_enabled = true
	accent.emission = color
	accent.emission_energy_multiplier = 0.35
	_team_materials[team] = accent
	return accent

var controller: ShipController
var _current_action: ShipAction = ShipAction.new()
var _inert_action: ShipAction = ShipAction.new()
var _boundary: ArenaBoundary

# Instrument signals for efficient data distribution
signal speed_changed(speed: float)
signal attitude_changed(pitch: float, roll: float, yaw: float)
signal altitude_changed(altitude: float)
signal thrust_changed(thrust_percent: float)
signal angular_velocity_changed(angular_speed: float)
signal heading_changed(heading_degrees: float)
signal ball_contact(intensity: float, world_position: Vector3)

# Performance optimization - track last emitted values to avoid unnecessary signals
var _last_speed: float = -1.0
var _last_altitude: float = -999999.0
var _last_angular_speed: float = -1.0
var _last_pitch: float = -999.0
var _last_roll: float = -999.0
var _last_yaw: float = -999.0
var _last_heading: float = -999.0
var _last_thrust: float = -1.0

# Thresholds for signal emission (only emit if change is significant)
const SPEED_THRESHOLD = 0.1          # m/s
const ALTITUDE_THRESHOLD = 0.5       # meters
const ANGULAR_THRESHOLD = 0.01       # rad/s
const ATTITUDE_THRESHOLD = 1.0       # degrees
const THRUST_THRESHOLD = 1.0         # percent

var _engine_cores: Array[MeshInstance3D] = []
var _engine_flames: Array[MeshInstance3D] = []
var _engine_lights: Array[OmniLight3D] = []
var _impact_sparks: GPUParticles3D


func _ready():
	# Add ship to group for instrument discovery
	add_to_group("ship")

	# Pick up a controller placed in the scene, if any; game modes usually
	# attach one at spawn time via set_controller instead.
	for child in get_children():
		if child is ShipController:
			controller = child
			break

	# Always on (moved here from ShipAIController.setup, which only enabled
	# it for training-side ships): ShipObservations now reads own-contact
	# state (see its "contact" section) for every ship, training or shipped,
	# so the RigidBody3D contact list must exist unconditionally rather than
	# only for whichever ship happened to be a training agent. Cheap — a
	# short per-tick contact list from the physics engine, not a rendering
	# cost like the headless skips just below.
	contact_monitor = true
	max_contacts_reported = 8

	_apply_team_color()

	_boundary = get_tree().get_first_node_in_group("arena_boundary")

	# Telemetry emission and the merged-hull visual mesh are both render-only
	# work; headless (RL/CI) instances never render or have a HUD watching
	# them, so skip both rather than relying on later no-ops.
	if DisplayServer.get_name() == "headless":
		set_physics_process(false)
	else:
		_build_merged_hull()
		_build_movement_vfx()
		body_entered.connect(_on_body_entered)


func _apply_team_color() -> void:
	if not is_inside_tree():
		return
	var accent := _get_team_material(team)
	for mesh_name in ["Nose", "TailFin"]:
		var mesh := get_node_or_null(mesh_name) as MeshInstance3D
		if mesh:
			mesh.material_override = accent


# Runtime-bakes Hull/Canopy/EngineGlowL/EngineGlowR (see MERGED_MESH_PATHS
# comment above) into one ArrayMesh, one destination surface per source
# surface via SurfaceTool.append_from, each keeping its own original
# material — preserves current visuals exactly regardless of surface count.
# Mirrors the runtime-bake pattern already used by goal.gd/arena_boundary.gd.
# Skipped in headless mode (see _ready): purely visual, costs nothing
# physics/RL cares about.
func _build_merged_hull() -> void:
	var mesh := ArrayMesh.new()
	var dest_idx := 0
	for i in MERGED_MESH_PATHS.size():
		var src: ArrayMesh = load(MERGED_MESH_PATHS[i])
		var xform: Transform3D = MERGED_MESH_TRANSFORMS[i]
		for surf in src.get_surface_count():
			var st := SurfaceTool.new()
			st.begin(Mesh.PRIMITIVE_TRIANGLES)
			st.append_from(src, surf, xform)
			st.commit(mesh)
			mesh.surface_set_material(dest_idx, src.surface_get_material(surf))
			dest_idx += 1
	var instance := MeshInstance3D.new()
	instance.name = "MergedHull"
	instance.mesh = mesh
	add_child(instance)


# Attach the node that drives this ship (player, AI, or network). Replaces
# any existing controller; parents the new one under the ship if needed.
func set_controller(new_controller: ShipController) -> void:
	if is_instance_valid(controller) and controller.get_parent() == self:
		controller.queue_free()
	controller = new_controller
	if new_controller and new_controller.get_parent() == null:
		add_child(new_controller)


func _physics_process(_delta):
	_update_movement_vfx()
	if _has_telemetry_listeners():
		_emit_telemetry_data()


func _build_movement_vfx() -> void:
	for x in [-0.42, 0.42]:
		var engine_pos := Vector3(x, -0.05, 1.42)

		var core_mat := _vfx_material(Color(1.0, 0.48, 0.1, 1.0), 1.0)
		var core_mesh := SphereMesh.new()
		core_mesh.radius = 0.11
		core_mesh.height = 0.22
		core_mesh.material = core_mat
		var core := MeshInstance3D.new()
		core.name = "EngineCoreL" if x < 0.0 else "EngineCoreR"
		core.position = engine_pos
		core.mesh = core_mesh
		core.cast_shadow = GeometryInstance3D.SHADOW_CASTING_SETTING_OFF
		add_child(core)
		_engine_cores.append(core)

		# A single conventional orange flame replaces the layered particle plume
		# and separate purple turbo effect. Turbo only lengthens and brightens the
		# same flame, keeping the engine silhouette simple and readable.
		var flame_mat := StandardMaterial3D.new()
		flame_mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
		flame_mat.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
		flame_mat.cull_mode = BaseMaterial3D.CULL_DISABLED
		flame_mat.albedo_color = Color(1.0, 0.34, 0.04, 0.92)
		flame_mat.emission_enabled = true
		flame_mat.emission = Color(1.0, 0.16, 0.015)
		flame_mat.emission_energy_multiplier = 2.0
		var flame_mesh := CylinderMesh.new()
		flame_mesh.top_radius = 0.015
		flame_mesh.bottom_radius = 0.14
		flame_mesh.height = 1.0
		flame_mesh.radial_segments = 12
		flame_mesh.material = flame_mat
		var flame := MeshInstance3D.new()
		flame.name = "EngineFlameL" if x < 0.0 else "EngineFlameR"
		flame.position = engine_pos + Vector3(0, 0, 0.3)
		flame.rotation_degrees.x = 90.0
		flame.mesh = flame_mesh
		flame.visible = false
		flame.cast_shadow = GeometryInstance3D.SHADOW_CASTING_SETTING_OFF
		add_child(flame)
		_engine_flames.append(flame)

		var light := OmniLight3D.new()
		light.name = "EngineLightL" if x < 0.0 else "EngineLightR"
		light.position = engine_pos
		light.light_color = Color(1.0, 0.32, 0.08)
		light.omni_range = 3.5
		light.omni_attenuation = 2.0
		light.shadow_enabled = false
		add_child(light)
		_engine_lights.append(light)

	_impact_sparks = _make_particles(
		"ImpactSparks", Color(1.0, 0.72, 0.22, 1.0), Vector2(0.09, 0.3),
		28, 0.32, Vector3.UP, 180.0, 5.0, 12.0
	)
	_impact_sparks.one_shot = true
	_impact_sparks.explosiveness = 1.0
	_impact_sparks.local_coords = false
	_impact_sparks.emitting = false
	add_child(_impact_sparks)


func _vfx_material(color: Color, energy: float) -> StandardMaterial3D:
	var mat := StandardMaterial3D.new()
	mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
	mat.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
	mat.billboard_mode = BaseMaterial3D.BILLBOARD_ENABLED
	mat.albedo_color = color
	mat.emission_enabled = true
	mat.emission = Color(color.r, color.g, color.b)
	mat.emission_energy_multiplier = energy
	return mat


func _make_particles(
	particle_name: String, color: Color, size: Vector2, amount: int,
	lifetime: float, direction: Vector3, spread: float,
	velocity_min: float, velocity_max: float
) -> GPUParticles3D:
	var quad := QuadMesh.new()
	quad.size = size
	quad.material = _vfx_material(color, 2.2)
	var process := ParticleProcessMaterial.new()
	process.direction = direction
	process.spread = spread
	process.initial_velocity_min = velocity_min
	process.initial_velocity_max = velocity_max
	process.gravity = Vector3.ZERO
	process.scale_min = 0.35
	process.scale_max = 1.0
	var particles := GPUParticles3D.new()
	particles.name = particle_name
	particles.amount = amount
	particles.lifetime = lifetime
	particles.local_coords = true
	particles.process_material = process
	particles.draw_pass_1 = quad
	particles.visibility_aabb = AABB(Vector3(-3, -3, -1), Vector3(6, 6, 12))
	particles.emitting = false
	return particles


func _update_movement_vfx() -> void:
	if _engine_flames.is_empty():
		return
	# These are the two rear main engines, so lateral/vertical maneuvering jets
	# must not make them flare. Reverse thrust also comes from separate attitude
	# jets conceptually; only positive Z drives this rear-facing flame.
	var thrust := clampf(maxf(_current_action.thrust.z, 0.0), 0.0, 1.0)
	var turbo := _current_action.turbo and thrust > 0.05
	for i in _engine_flames.size():
		var flame := _engine_flames[i]
		var flame_length := 0.28 + thrust * 0.82 + (0.62 if turbo else 0.0)
		var flame_width := 0.72 + thrust * 0.32 + (0.12 if turbo else 0.0)
		flame.visible = thrust > 0.02
		flame.scale = Vector3(flame_width, flame_length, flame_width)
		# CylinderMesh is centred on local Y (rotated to ship +Z), so moving its
		# centre by half the length keeps the flame root fixed at the engine bell.
		flame.position.z = 1.48 + flame_length * 0.5
		var flame_mat := flame.mesh.material as StandardMaterial3D
		flame_mat.emission_energy_multiplier = 1.8 + thrust * 2.2 + (1.8 if turbo else 0.0)
		_engine_lights[i].light_energy = 0.35 + thrust * 2.1 + (2.3 if turbo else 0.0)
		var core_mat := _engine_cores[i].mesh.material as StandardMaterial3D
		core_mat.emission_energy_multiplier = 0.65 + thrust * 2.0 + (2.0 if turbo else 0.0)
		_engine_cores[i].scale = Vector3.ONE * (0.8 + thrust * 0.3 + (0.25 if turbo else 0.0))


func get_speed_ratio() -> float:
	return clampf(linear_velocity.length() / maxf(max_speed, 0.001), 0.0, 1.0)


func is_turbo_active() -> bool:
	return _current_action.turbo and _current_action.thrust.z > 0.05


func _on_body_entered(body: Node) -> void:
	if not body is Ball:
		return
	var relative_speed := (linear_velocity - (body as Ball).linear_velocity).length()
	var intensity := clampf(inverse_lerp(3.0, 24.0, relative_speed), 0.12, 1.0)
	var contact_pos := (global_position + (body as Ball).global_position) * 0.5
	if _impact_sparks:
		_impact_sparks.position = to_local(contact_pos)
		_impact_sparks.amount_ratio = lerpf(0.25, 1.0, intensity)
		_impact_sparks.restart()
	ball_contact.emit(intensity, contact_pos)


# Covers a second/AI ship with no HUD watching it - headless mode is already
# handled by disabling _physics_process entirely in _ready.
func _has_telemetry_listeners() -> bool:
	return speed_changed.get_connections().size() > 0 \
		or altitude_changed.get_connections().size() > 0 \
		or attitude_changed.get_connections().size() > 0 \
		or heading_changed.get_connections().size() > 0 \
		or thrust_changed.get_connections().size() > 0


func _integrate_forces(state):
	# One action per physics tick, pulled from the controller (deterministic)
	_current_action = controller.get_action() if controller else _inert_action

	# === TRANSLATION (Movement) ===
	apply_thruster_forces(state, _current_action)
	apply_surface_pull(state)

	# === ROTATION (Turning) ===
	apply_rotation_forces(state, _current_action.rotation)

	# === DRAG AND LIMITS ===
	apply_drag_and_limits(state, _current_action.rotation)


func apply_thruster_forces(state: PhysicsDirectBodyState3D, action: ShipAction):
	var thrust_input := action.thrust
	if thrust_input.length() < 0.01:
		return

	# Convert thrust input to world space forces based on ship orientation
	# Physics: F = m * a (Newton's Second Law: Force = mass × acceleration)
	# World force = Local force × Rotation matrix (basis transformation)
	var ship_basis = global_transform.basis
	var world_thrust = Vector3.ZERO

	# All thrusters should work relative to ship orientation
	# Physics: Vector transformation from local to world coordinates
	# F_world = R * F_local (where R is rotation matrix)

	# Forward/backward thrust (main engines)
	world_thrust += -ship_basis.z * thrust_input.z * thrust_power

	# Strafe thrust (left/right maneuvering thrusters)
	world_thrust += ship_basis.x * thrust_input.x * maneuvering_thrust

	# Vertical thrust (up/down thrusters relative to ship orientation)
	world_thrust += ship_basis.y * thrust_input.y * vertical_thrust

	# Turbo only boosts forward thrust
	if action.turbo and thrust_input.z > 0:
		world_thrust *= turbo_multiplier

	# Apply the force
	# Physics: Δv = F * Δt / m (change in velocity = force × time / mass)
	state.apply_central_force(world_thrust)


func apply_surface_pull(state: PhysicsDirectBodyState3D) -> void:
	if _boundary == null:
		return
	var pull := _boundary.get_surface_pull(
		global_position, wall_pull_strength, wall_pull_range,
		ceiling_pull_strength, ceiling_pull_range
	)
	state.apply_central_force(pull * mass)


func apply_rotation_forces(state: PhysicsDirectBodyState3D, rotation_input: Vector3):
	if rotation_input.length() < 0.01:
		return

	# Apply torque for rotation - simple and effective
	# Physics: τ = I * α (torque = moment of inertia × angular acceleration)
	# Also: α = τ / I (angular acceleration = torque / moment of inertia)
	# Lower inertia = higher angular acceleration for same torque
	var torque = Vector3(
		rotation_input.x * rotation_power,  # Pitch (rotation around X-axis)
		rotation_input.y * rotation_power,  # Yaw (rotation around Y-axis)
		rotation_input.z * rotation_power   # Roll (rotation around Z-axis)
	)

	# Physics: Δω = τ * Δt / I (change in angular velocity = torque × time / inertia)
	state.apply_torque(torque)


# Scales a per-tick decay multiplier `k` (defined at a 60 Hz reference rate)
# by the actual elapsed tick time `step`, so `v *= _tick_scaled(k, step)`
# decays at the same rate per second regardless of physics_ticks_per_second.
func _tick_scaled(k: float, step: float) -> float:
	return pow(k, step * 60.0)


func apply_drag_and_limits(state: PhysicsDirectBodyState3D, rotation_input: Vector3):
	# Linear drag (air resistance)
	# Physics: F_drag = -½ * ρ * v² * C_d * A (drag force equation)
	# Simplified: v_new = v_old * drag_coefficient (exponential decay)
	# This simulates air resistance reducing velocity over time.
	# _tick_scaled makes the decay rate invariant to the physics tick rate —
	# drag_coefficient/angular_drag/idle_angular_drag are all defined as the
	# per-tick multiplier at a 60 Hz reference rate.
	state.linear_velocity *= _tick_scaled(drag_coefficient, state.step)

	# Angular drag (rotational resistance)
	# Physics: Similar to linear drag but for rotational motion
	# τ_drag = -C_angular * ω² (angular drag torque)
	# Simplified: ω_new = ω_old * angular_drag (exponential decay)
	if rotation_input.length() < 0.01:
		# More drag when not actively rotating to stop quicker
		state.angular_velocity *= _tick_scaled(idle_angular_drag, state.step)
	else:
		# Normal drag when actively rotating
		state.angular_velocity *= _tick_scaled(angular_drag, state.step)

	# Limit maximum speeds
	# Physics: Terminal velocity concept - maximum achievable speed
	# When thrust force = drag force, acceleration = 0, velocity = constant
	if state.linear_velocity.length() > max_speed:
		# Normalize to unit vector, then scale to max speed
		# Physics: v̂ = v / |v| (unit vector), v_limited = v̂ * v_max
		state.linear_velocity = state.linear_velocity.normalized() * max_speed

	if state.angular_velocity.length() > max_angular_speed:
		# Same concept for angular velocity
		# Physics: ω̂ = ω / |ω|, ω_limited = ω̂ * ω_max
		state.angular_velocity = state.angular_velocity.normalized() * max_angular_speed


func _emit_telemetry_data():
	# Ship only calculates and emits data - HUD handles display
	# Performance optimization: only emit signals when values change significantly

	# Speed telemetry
	# Physics: |v| = √(vₓ² + vᵧ² + vᵤ²) (magnitude of velocity vector)
	var current_speed = linear_velocity.length()
	if abs(current_speed - _last_speed) > SPEED_THRESHOLD:
		speed_changed.emit(current_speed)
		_last_speed = current_speed

	# Altitude telemetry
	# Physics: Height measurement from reference point (y = 0)
	var current_altitude = global_transform.origin.y
	if abs(current_altitude - _last_altitude) > ALTITUDE_THRESHOLD:
		altitude_changed.emit(current_altitude)
		_last_altitude = current_altitude

	# Angular velocity telemetry
	# Physics: |ω| = √(ωₓ² + ωᵧ² + ωᵤ²) (magnitude of angular velocity vector)
	var angular_speed = angular_velocity.length()
	if abs(angular_speed - _last_angular_speed) > ANGULAR_THRESHOLD:
		angular_velocity_changed.emit(angular_speed)
		_last_angular_speed = angular_speed

	# Attitude telemetry (pitch, roll, yaw from ship orientation)
	# Physics: Euler angles from rotation matrix
	# Aviation convention (yaw → pitch → roll, EULER_ORDER_YXZ): pitch stays in
	# ±90° and yaw covers the full circle. XYZ order would instead constrain
	# yaw to ±90°, so an upright ship facing "south" would be reported as
	# pitch 180 + roll 180 — mathematically equivalent, but it reads as
	# upside-down on the attitude indicator and breaks the heading readout.
	var ship_rotation = global_transform.basis.get_euler(EULER_ORDER_YXZ)
	var pitch_deg = rad_to_deg(ship_rotation.x)
	var roll_deg = rad_to_deg(ship_rotation.z)
	var yaw_deg = rad_to_deg(ship_rotation.y)

	if abs(pitch_deg - _last_pitch) > ATTITUDE_THRESHOLD or \
	   abs(roll_deg - _last_roll) > ATTITUDE_THRESHOLD or \
	   abs(yaw_deg - _last_yaw) > ATTITUDE_THRESHOLD:
		attitude_changed.emit(pitch_deg, roll_deg, yaw_deg)
		_last_pitch = pitch_deg
		_last_roll = roll_deg
		_last_yaw = yaw_deg

	# Heading telemetry (yaw - direction ship is facing)
	# Physics: Yaw = rotation around Y-axis (compass heading)
	# Convert to 0-360° range for traditional compass display
	var heading = fmod(yaw_deg + 360.0, 360.0)  # Normalize to 0-360°
	if abs(heading - _last_heading) > ATTITUDE_THRESHOLD:
		heading_changed.emit(heading)
		_last_heading = heading

	# Thrust telemetry
	# Physics: Thrust output as percentage of maximum available thrust
	var thrust_percent = _current_action.thrust.length() * 100.0
	if abs(thrust_percent - _last_thrust) > THRUST_THRESHOLD:
		thrust_changed.emit(thrust_percent)
		_last_thrust = thrust_percent