[DRAFT] Better shuttle logging

DEBUGGING_SHUTTLE_TRANSFER_LOGGING.md

@@ -0,0 +1,226 @@
+# Shuttle Transfer Debug Logging Recommendations
+
+## Critical Areas to Add Logging
+
+### 1. **Pre/Post Transfer Validation**
+Add logging before and after `initiate_docking()` to verify complete transfer:
+
+```dm
+// In controlled_ship_datum.dm, complete_dock proc
+/datum/overmap/ship/controlled/complete_dock(datum/overmap/dock_target, datum/docking_ticket/ticket)
+	// LOG: Pre-dock state
+	log_shuttle("[src] [REF(src)] PRE-DOCK: shuttle_port=[REF(shuttle_port)] z=[shuttle_port.z] virtual_z=[shuttle_port.virtual_z()] turf_count=[shuttle_port.turf_count]")
+	log_shuttle("[src] [REF(src)] PRE-DOCK: target_port=[REF(ticket.target_port)] z=[ticket.target_port.z] virtual_z=[ticket.target_port.virtual_z()]")
+
+	var/list/pre_turfs = shuttle_port.return_ordered_turfs(shuttle_port.x, shuttle_port.y, shuttle_port.z, shuttle_port.dir)
+	log_shuttle("[src] [REF(src)] PRE-DOCK: Counted [pre_turfs.len] turfs before dock")
+
+	shuttle_port.initiate_docking(ticket.target_port)
+
+	// LOG: Post-dock validation
+	var/list/post_turfs = shuttle_port.return_ordered_turfs(shuttle_port.x, shuttle_port.y, shuttle_port.z, shuttle_port.dir)
+	log_shuttle("[src] [REF(src)] POST-DOCK: Now at z=[shuttle_port.z] virtual_z=[shuttle_port.virtual_z()] turf_count=[shuttle_port.turf_count]")
+	log_shuttle("[src] [REF(src)] POST-DOCK: Counted [post_turfs.len] turfs after dock")
+
+	if(pre_turfs.len != post_turfs.len)
+		log_shuttle("WARNING: [src] [REF(src)] TURF COUNT MISMATCH: [pre_turfs.len] -> [post_turfs.len]")
+		message_admins("CRITICAL: Ship [src] experienced turf count mismatch during docking! Check shuttle logs.")
+
+	. = ..()
+	log_shuttle("[src] [REF(src)] COMPLETE DOCK: FINISHED DOCKING TO [dock_target] AT [ticket.target_port]")
+```
+
+### 2. **Exception Tracking in initiate_docking()**
+Add detailed exception logging:
+
+```dm
+// In docking.dm, preflight_check proc
+/obj/docking_port/mobile/proc/preflight_check(list/old_turfs, list/new_turfs, list/areas_to_move, rotation)
+	var/list/exceptions_list = list()
+	var/new_turf_count = 0
+
+	for(var/i = 1, i <= old_turfs.len, i++)
+		try
+			// ... existing code ...
+		catch(var/exception/e2)
+			log_shuttle("EXCEPTION in preflight_check [src] [REF(src)] turf [i]/[old_turfs.len]: [e2]")
+			log_shuttle("EXCEPTION DETAILS: oldT=[old_turfs[i]] newT=[new_turfs[i]]")
+			exceptions_list += e2
+
+	turf_count = new_turf_count
+
+	if(exceptions_list.len > 0)
+		log_shuttle("WARNING: [src] [REF(src)] preflight_check had [exceptions_list.len] exceptions")
+
+	for(var/exception/e3 in exceptions_list)
+		CHECK_TICK
+		log_shuttle("THROWING EXCEPTION: [e3]")
+		throw_exception(e3)
+```
+
+### 3. **Per-Turf Transfer Verification**
+Track individual turf transfers:
+
+```dm
+// In docking.dm, takeoff proc
+/obj/docking_port/mobile/proc/takeoff(...)
+	var/turfs_moved = 0
+	var/atoms_moved = 0
+
+	// After MOVE_CONTENTS loop
+	for(var/i = 1, i <= old_turfs.len, i++)
+		try
+			var/turf/oldT = old_turfs[i]
+			var/turf/newT = new_turfs[i]
+			var/move_mode = old_turfs[oldT]
+			if(move_mode & MOVE_CONTENTS)
+				for(var/k in oldT)
+					try
+						var/atom/movable/moving_atom = k
+						if(moving_atom.loc != oldT)
+							continue
+						if(moving_atom.onShuttleMove(newT, oldT, movement_force, movement_direction, old_dock, src, all_towed_shuttles))
+							moved_atoms[moving_atom] = oldT
+							atoms_moved++
+					catch(var/exception/e1)
+						log_shuttle("EXCEPTION moving atom [moving_atom] from [oldT] to [newT]: [e1]")
+						exceptions_list += e1
+		catch(var/exception/e1)
+			log_shuttle("EXCEPTION in MOVE_CONTENTS loop turf [i]: [e1]")
+			exceptions_list += e1
+
+	// After MOVE_TURF loop
+	log_shuttle("[src] [REF(src)] TAKEOFF PHASE: Moved [atoms_moved] atoms across [old_turfs.len] turfs")
+```
+
+### 4. **Virtual Z-Level Consistency Check**
+Add periodic validation:
+
+```dm
+// New proc in docking_port/mobile
+/obj/docking_port/mobile/proc/validate_virtual_z_consistency()
+	var/list/turfs = return_ordered_turfs(x, y, z, dir)
+	var/list/virtual_z_counts = list()
+
+	for(var/turf/T in turfs)
+		var/vz = T.virtual_z()
+		if(!virtual_z_counts["[vz]"])
+			virtual_z_counts["[vz]"] = 0
+		virtual_z_counts["[vz]"]++
+
+	if(virtual_z_counts.len > 1)
+		log_shuttle("CRITICAL: [src] [REF(src)] VIRTUAL_Z SPLIT DETECTED:")
+		for(var/vz_key in virtual_z_counts)
+			log_shuttle("  Virtual Z [vz_key]: [virtual_z_counts[vz_key]] turfs")
+		return FALSE
+
+	return TRUE
+
+// Call after docking completes
+/datum/overmap/ship/controlled/complete_dock(datum/overmap/dock_target, datum/docking_ticket/ticket)
+	shuttle_port.initiate_docking(ticket.target_port)
+	. = ..()
+
+	if(!shuttle_port.validate_virtual_z_consistency())
+		message_admins("CRITICAL: Ship [src] has split virtual z-levels after docking! Immediate investigation needed.")
+		log_shuttle("EMERGENCY: [src] [REF(src)] FAILED VIRTUAL Z CONSISTENCY CHECK AFTER DOCK")
+```
+
+### 5. **Towed Shuttle Relationship Tracking**
+Log towed shuttle state changes:
+
+```dm
+// In docking.dm, takeoff proc after towed shuttle handling
+if(old_dock && old_dock.owner_ship)
+	log_shuttle("[src] [REF(src)] TOWED: Removing from old parent [old_dock.owner_ship] [REF(old_dock.owner_ship)]")
+	old_dock.owner_ship.towed_shuttles -= src
+
+if(new_dock.owner_ship)
+	log_shuttle("[src] [REF(src)] TOWED: Adding to new parent [new_dock.owner_ship] [REF(new_dock.owner_ship)]")
+	new_dock.owner_ship.towed_shuttles |= src
+	parent_shuttles += new_dock.owner_ship
+
+// Later, after area updates
+log_shuttle("[src] [REF(src)] TOWED SHUTTLES STATE: [all_towed_shuttles.len] towed shuttles")
+for(var/obj/docking_port/mobile/M in all_towed_shuttles)
+	log_shuttle("  - [M] [REF(M)] parent=[M.docked?.owner_ship ? M.docked.owner_ship : "NONE"]")
+```
+
+### 6. **Undock Validation**
+Similar validation for undocking:
+
+```dm
+/datum/overmap/ship/controlled/complete_undock()
+	log_shuttle("[src] [REF(src)] UNDOCK: Pre-undock z=[shuttle_port.z] virtual_z=[shuttle_port.virtual_z()]")
+
+	var/obj/docking_port/stationary/target_transit = shuttle_port.assigned_transit
+	if(!target_transit)
+		log_shuttle("CRITICAL: [src] [REF(src)] UNDOCK: No assigned transit port!")
+		message_admins("CRITICAL: Ship [src] attempting to undock without assigned transit port!")
+
+	shuttle_port.initiate_docking(shuttle_port.assigned_transit)
+	log_shuttle("[src] [REF(src)] UNDOCK: Post-undock z=[shuttle_port.z] virtual_z=[shuttle_port.virtual_z()]")
+
+	if(!shuttle_port.validate_virtual_z_consistency())
+		message_admins("CRITICAL: Ship [src] has split virtual z-levels after undocking!")
+
+	log_shuttle("[src] [REF(src)] COMPLETE UNDOCK: FINISHED UNDOCK FROM [docked_to]")
+	return ..()
+```
+
+### 7. **Real-time Alert System**
+Add admin alerts for critical issues:
+
+```dm
+/obj/docking_port/mobile/proc/emergency_shuttle_alert(message)
+	log_shuttle("EMERGENCY: [src] [REF(src)]: [message]")
+	message_admins("SHUTTLE EMERGENCY - [src]: [message] [ADMIN_JMP(src)]")
+	// Optionally send to Discord webhook or other monitoring
+```
+
+## Monitoring Dashboard
+
+Create an admin verb to check shuttle health:
+
+```dm
+/client/proc/check_shuttle_health()
+	set name = "Check Shuttle Health"
+	set category = "Debug"
+
+	if(!check_rights(R_ADMIN))
+		return
+
+	var/output = "=== SHUTTLE HEALTH CHECK ===\n"
+
+	for(var/datum/overmap/ship/controlled/ship in SSovermap.controlled_ships)
+		output += "\n[ship.name] ([REF(ship)]):\n"
+		output += "  Z-Level: [ship.shuttle_port.z]\n"
+		output += "  Virtual Z: [ship.shuttle_port.virtual_z()]\n"
+		output += "  Docked: [ship.docked_to ? "Yes to [ship.docked_to]" : "No"]\n"
+		output += "  Docking: [ship.docking ? "Yes" : "No"]\n"
+		output += "  Turf Count: [ship.shuttle_port.turf_count]\n"
+
+		var/vz_valid = ship.shuttle_port.validate_virtual_z_consistency()
+		output += "  VZ Consistent: [vz_valid ? "YES" : "NO - CRITICAL!"]\n"
+
+		if(ship.towed_shuttles.len)
+			output += "  Towed Shuttles: [ship.towed_shuttles.len]\n"
+
+	to_chat(src, output)
+	log_admin("[key_name(src)] checked shuttle health")
+```
+
+## Files to Modify
+
+1. **code/modules/overmap/ships/controlled_ship_datum.dm** - Lines 204-234 (complete_dock and complete_undock)
+2. **code/modules/shuttle/docking.dm** - Lines 9-103 (initiate_docking, preflight_check, takeoff, cleanup_runway)
+3. **code/modules/shuttle/shuttle.dm** - Add new validation procs
+4. **code/modules/admin/verbs/shuttlepanel.dm** - Add health check verb
+
+## Configuration
+
+Add to config.txt:
+```
+## Enables verbose shuttle transfer logging
+LOG_SHUTTLE_VERBOSE
+```