From 1cbd41f66b540303326513c2d9903e113700ede6 Mon Sep 17 00:00:00 2001
From: Marco Hladik <marco@icculus.org>
Date: Sun, 8 Nov 2020 04:45:52 +0100
Subject: [PATCH] Documentation: Comment some of the prediction code more, as
 some may be reading it as we speak

---
 src/client/predict.c      | 23 ++++++++++++++---------
 src/client/valve/player.c | 16 +++++++++++-----
 src/server/plugins.c      |  2 --
 src/shared/pmove.c        |  5 ++++-
 4 files changed, 29 insertions(+), 17 deletions(-)

diff --git a/src/client/predict.c b/src/client/predict.c
index 0b47e078..98752b4b 100644
--- a/src/client/predict.c
+++ b/src/client/predict.c
@@ -26,6 +26,7 @@ Propagate our pmove state to whatever the current frame before its stomped on
 void
 Predict_PreFrame(player pl)
 {
+	/* base player attributes/fields we're going to roll back */
 	pl.net_origin = pl.origin;
 	pl.net_velocity = pl.velocity;
 	pl.net_flags = pl.flags;
@@ -40,14 +41,13 @@ Predict_PreFrame(player pl)
 	pl.net_ammo2 = pl.a_ammo2;
 	pl.net_ammo3 = pl.a_ammo3;
 	pl.net_weapontime = pl.weapontime;
-	
+
+	/* this is where a game/mod would decide to add more prediction rollback
+	 * information. */
 	GamePredict_PreFrame(pl);
 
-	//self.netpmove_flags = self.pmove_flags;
-
-	//we want to predict an exact copy of the data in the new packet
-	/*for (; self.pmove_frame <= servercommandframe; self.pmove_frame++) {
-		float flSuccess = getinputstate(self.pmove_frame);*/
+	/* run physics code for all the input frames which we've not heard back
+	 * from yet. This continues on in Player_ReceiveEntity! */
 	for (int i = pl.sequence + 1; i <= clientcommandframe; i++) {
 		float flSuccess = getinputstate(i);
 		if (flSuccess == FALSE) {
@@ -58,11 +58,15 @@ Predict_PreFrame(player pl)
 			CSQC_Input_Frame();
 		}
 
-		// Partial frames are the worst
+		/* don't do partial frames, aka incomplete input packets */
 		if (input_timelength == 0) {
 			break;
 		}
+
+		/* this global is for our shared random number seed */
 		input_sequence = i;
+
+		/* run our custom physics */
 		PMove_Run();
 	}
 }
@@ -79,6 +83,7 @@ Rewind our pmove state back to before we started predicting.
 void
 Predict_PostFrame(player pl)
 {
+	/* finally roll the values back */
 	pl.origin = pl.net_origin;
 	pl.velocity = pl.net_velocity;
 	pl.flags = pl.net_flags;
@@ -94,9 +99,9 @@ Predict_PostFrame(player pl)
 	pl.a_ammo3 = pl.net_ammo3;
 	pl.weapontime = pl.net_weapontime;
 
+	/* give the game/mod a chance to roll back its values too */
 	GamePredict_PostFrame(pl);
 
-	//self.pmove_flags = self.netpmove_flags;
+	/* update bounds */
 	setorigin(pl, pl.origin);
-	//self.pmove_frame = servercommandframe + 1;
 }
diff --git a/src/client/valve/player.c b/src/client/valve/player.c
index 964d577b..43dc25ca 100644
--- a/src/client/valve/player.c
+++ b/src/client/valve/player.c
@@ -57,14 +57,19 @@ Player_ReceiveEntity(float new)
 		pl.customphysics = Empty;
 		setsize(pl, VEC_HULL_MIN, VEC_HULL_MAX);
 	} else {
-		int i;
-		//FIXME: splitscreen
+		/* Go through all the physics code between the last received frame
+		 * and the newest frame and keep the changes this time around instead
+		 * of rolling back, because we'll apply the new server-verified values
+		 * right after anyway. */
+		/* FIXME: splitscreen */
 		if (pl.entnum == player_localentnum) {
-			//FIXME: splitscreen
+			/* FIXME: splitscreen */
 			pSeat = &g_seats[0];
-			for (i = pl.sequence+1; i <= servercommandframe; i++) {
+
+			for (int i = pl.sequence+1; i <= servercommandframe; i++) {
+				/* ...maybe the input state is too old? */
 				if (!getinputstate(i)) {
-					break;	//erk?... too old?
+					break;
 				}
 				input_sequence = i;
 				PMove_Run();
@@ -75,6 +80,7 @@ Player_ReceiveEntity(float new)
 		}
 	}
 
+	/* seed for our prediction table */
 	pl.sequence = servercommandframe;
 
 	fl = readfloat();
diff --git a/src/server/plugins.c b/src/server/plugins.c
index f855e106..1ecd9148 100644
--- a/src/server/plugins.c
+++ b/src/server/plugins.c
@@ -229,7 +229,6 @@ Plugin_PlayerConnect(base_player cl)
 	return rval;
 }
 
-
 /*
 =================
 Plugin_PlayerDisconnect
@@ -265,7 +264,6 @@ Plugin_PlayerDisconnect(base_player cl)
 	return rval;
 }
 
-
 /*
 =================
 Plugin_PlayerObituary
diff --git a/src/shared/pmove.c b/src/shared/pmove.c
index 47cabbed..ceaed191 100644
--- a/src/shared/pmove.c
+++ b/src/shared/pmove.c
@@ -708,7 +708,10 @@ PMove_Move(void)
 	self.velocity -= self.basevelocity;
 }
 
-/* it all starts here */
+/* it all starts here, this function is called by both CLIENT and SERVER for
+   obvious prediction purposes. The SERVER will usually do this in the
+   Game_RunClientCommand function and the CLIENT will do so in both the
+   prediction places of Predict_PreFrame and Player_ReceiveEntity */
 void
 PMove_Run(void)
 {