From 4976aec8c78504d28e1acf9da0af73a64954af11 Mon Sep 17 00:00:00 2001
From: Andrei Drexler <makro@rq3.com>
Date: Sun, 12 Nov 2023 15:35:04 +0100
Subject: [PATCH] Add comments to the Host_CheckAutosave function

---
 Quake/host.c | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/Quake/host.c b/Quake/host.c
index 3d620cd6f..4398dffb7 100644
--- a/Quake/host.c
+++ b/Quake/host.c
@@ -830,6 +830,7 @@ static void Host_CheckAutosave (void)
 
 	if (cls.signon == SIGNONS)
 	{
+		// Track new secrets
 		if (pr_global_struct->found_secrets != sv.autosave.prev_secrets)
 		{
 			sv.autosave.prev_secrets = pr_global_struct->found_secrets;
@@ -839,6 +840,7 @@ static void Host_CheckAutosave (void)
 			sv.autosave.secret_boost = q_max (0.f, sv.autosave.secret_boost - host_frametime / 1.5f);
 	}
 
+	// Track health changes
 	if (!sv.autosave.prev_health)
 		sv.autosave.prev_health = sv_player->v.health;
 	health_change = sv_player->v.health - sv.autosave.prev_health;
@@ -847,20 +849,26 @@ static void Host_CheckAutosave (void)
 			sv.autosave.hurt_time = qcvm->time;
 	sv.autosave.prev_health = sv_player->v.health;
 
+	// Track attacking
 	if (sv_player->v.button0)
 		sv.autosave.shoot_time = qcvm->time;
 
+	// Time spent with cheats active doesn't count
 	if (sv_player->v.movetype == MOVETYPE_NOCLIP || (int)sv_player->v.flags & (FL_GODMODE|FL_NOTARGET))
 	{
 		sv.autosave.cheat += host_frametime;
 		return;
 	}
 
+	// Don't save if the player has been hurt recently
 	if (qcvm->time - sv.autosave.hurt_time < 3.f)
 		return;
+
+	// Don't save if the player has fired recently
 	if (qcvm->time - sv.autosave.shoot_time < 3.f)
 		return;
 
+	// Only save when the player slows down a bit
 	speed = VectorLength (sv_player->v.velocity);
 	if (speed > 100.f)
 		return;
@@ -870,16 +878,27 @@ static void Host_CheckAutosave (void)
 	if ((int)sv_player->v.movetype == MOVETYPE_NONE)
 		return;
 
+	// Don't save too often
 	elapsed = qcvm->time - sv.autosave.time - sv.autosave.cheat;
 	if (elapsed < 3.f)
 		return;
 
+	// Compute a normalized autosave score
+
+	// Base value is the fraction of the autosave interval already passed
 	score = elapsed / sv_autosave_interval.value;
+	// Scale down the score if health + armor is below 100 (save less often with lower health)
 	score *= q_min (100.f, (sv_player->v.health + sv_player->v.armortype * sv_player->v.armorvalue)) / 100.f;
+	// Boost the score right after picking up health
 	score += q_max (0.f, health_change) / 100.f;
+	// Lower score a bit based on speed (favor standing still/slowing down)
 	score -= (speed / 100.f) * 0.25f;
+	// Boost the score after finding a secret
 	score += sv.autosave.secret_boost * 0.25f;
+	// Boost the score after teleporting
 	score += CLAMP (0.f, 1.f - (qcvm->time - sv_player->v.teleport_time) / 1.5f, 1.f) * 0.5f;
+
+	// Only save if the score is high enough
 	if (score < 1.f)
 		return;