View source

{{otherlang2
| ru = Working With Prediction:ru
}}

{{toc-right}}

'''Prediction''' is the notion of the client predicting the effects of the local player's actions without waiting for the server to confirm them. An entity's predicted state is tested against server commands as they arrive until either a match or a mis-match is detected.

In the vast majority of cases the client's prediction is confirmed by the server and it continues happily as if there was no latency. If there is a mis-match, which is rare if the prediction code is written correctly, then the client goes back and re-simulates all of the commands it ran with bad data. Depending on the severity of the error this can cause a noticeable hitch in the player's position and state, and possibly the state of the world too.

Prediction is closely linked to [[lag compensation]], but is separate from [[interpolation]]. It only exists on the client.

{{warning|Don't under any circumstances be tempted into thinking "these two values won't ever go out of synch". There is ''always'' the possibility of packet loss!}}

{{note|Because only [[CBasePlayer|players]] are lag compensated, attempts to hit other entities (not least NPCs) do not benefit from prediction - you still have to lead your aim by latency. If this is an issue, consider [[NPC_Lag_Compensation|lag compensating your npcs]].}}

== Implementation ==

To predict an entity:

# The entity should be '''manipulable by the local player'''. Otherwise, what is the point in predicting it?
# The functions that are to be predicted must '''exist and be identical on both the client and server'''. This is achieved by making them [[shared code]].
# The entity must make the call '''<code>SetPredictionEligible(true)</code>''', preferably in its constructor.
# The entity must have two functions that return true when it should be predicted:
#* <code>bool '''ShouldPredict()'''</code>, on the client
#* <code>bool '''IsPredicted()'''</code>, on the server
# Any variables that must be synchronised between the client and server must be both [[Networking Entities|networked]] and present in the entity's prediction table.

=== Prediction tables ===

All client-side variables modified by predicted player input must be added to a prediction table. There are three behaviours you can choose between:

; <code>FTYPEDESC_INSENDTABLE</code>
: This is a networked variable. The client's predicted value will be tested against received server values, and if the two go out of synch a prediction error will be created.
; <code>FTYPEDESC_NOERRORCHECK</code>
: This is a predicted value that can go out of synch without generating a prediction error. It may or may not be networked.
; <code>FTYPEDESC_PRIVATE</code>
: This isn't predicted or networked at all, but is still registered so that it can inspected with <code>cl_pdump</code>. {{note|This type of variable won't be saved/restored when the prediction system winds time back to test against a new server command. If a predicted function increments it, the increment will be applied over and over again on the client as each new command is tested.}}

These behaviours are implemented with the <code>DEFINE_PRED_FIELD()</code> and <code>DEFINE_PRED_FIELD_TOL()</code> macros. The latter allows you to specify a tolerance within which an int or float is allowed to differ without generating prediction errors. This is mainly intended for use when a value has been rounded prior to transmission: floats are often trimmed to 1ms resolution, for instance (the #define <code>TD_MSECTOLERANCE</code> exists especially for this situation - otherwise, you should pass a numeric value).

Be cautious when extrapolating from a rounded figure in these circumstances. Small differences in the transmitted value can lead to large changes in the results of your calculations!

==== Example ====

<source lang=cpp>#ifdef CLIENT_DLL
BEGIN_PREDICTION_DATA( CBaseCombatWeapon )
	DEFINE_PRED_FIELD( m_nNextThinkTick, FIELD_INTEGER, FTYPEDESC_INSENDTABLE ),
	DEFINE_PRED_FIELD( m_hOwner, FIELD_EHANDLE, FTYPEDESC_INSENDTABLE ),
	DEFINE_PRED_FIELD_TOL( m_flNextPrimaryAttack, FIELD_FLOAT, FTYPEDESC_INSENDTABLE, TD_MSECTOLERANCE ),	
END_PREDICTION_DATA()
#endif</source>

== Tools and tricks ==

=== IsFirstTimePredicted() ===

Testing <code>prediction->IsFirstTimePredicted()</code> ensures that code is only executed when the client first predicts an action, and not when it checks against subsequent server updates. You must <code>#include "prediction.h"</code> to access it.

=== SharedRandom() ===

Use this function for random numbers. The seed it uses is based on the usercmd number, making the result identical on client and server.

=== CDisablePredictionFiltering ===

{{todo}}

=== Suppressing network data ===

Non-critical events like weapon effects can be done entirely on the client. Suppressing that data is a good idea as it results in reduced bandwidth usage.

<code>[[IPredictionSystem]]::SuppressHostEvents()</code> is meant for this. When it is called, all network data to the given player is halted. Sending NULL again will turn transmission back on. For example:

<source lang=cpp>if ( pPlayer->IsPredictingWeapons() )
	IPredictionSystem::SuppressHostEvents( pPlayer );

pWeapon->CreateEffects();

IPredictionSystem::SuppressHostEvents( NULL );</source>

Note that after doing the above you will need to write code somewhere else that makes the suppressed player's client generate the effects itself.

== Sample ==

[[Prediction/Sample weapon|Here is a simple weapon that prints prediction information to the console.]] Use its rapid secondary fire with net_fakelag 200 (or above) to see how the engine handles multiple predicted shots.

{{note|The gun will appear jittery when lagged unless your player entity is creating a predicted viewmodel.}}

== Troubleshooting ==

If you add functionality to weapons and forget to follow the steps above, then an entity may jerk around or animate strangely. You can use <code>[[cl_predictionlist]]</code> and <code>[[cl_pdump]]</code> to debug this. Changing <code>[[cl_pred_optimize]]</code> can also help sometimes.

Now let's say you see a variable that turns red in the <code>cl_pdump</code> panel from time to time. Now you know that somehow the client is producing a different value for this variable than the server is. This can usually be traced down to one of the following problems:

# The client is not running some code that the server is running. This would be the case if you had an <code>#ifdef GAME_DLL</code> or an <code>#ifndef CLIENT_DLL</code> around a piece of code that could affect the value of the variable that's turning red.
# Another variable that can wind up affecting the value of the red variable is not being transmitted via the data table. In this case, the client's value for that variable would always be wrong (since the server never transmitted it).
# It's also possible that you just forgot to add in the appropriate tolerance using the <code>DEFINE_PRED_FIELD_TOL</code> macro. For example, if you're transmitting a floating point variable with a value range of 0.0 - 255.0, and you only give it 4 bits of precision, then you're going to need a tolerance of about 17.0, or else the prediction system will think the variable's value is wrong when it is actually just different because the variable was compressed into 4 bits before sending it to the client.

Tracking down prediction problems is usually a matter of walking through any code that can affect the values that are turning red, and noticing which other variables affect their values. It can be tedious at first, but once you get the hang of it, you can track down prediction problems quickly.

== See also ==

* [[Source Multiplayer Networking#Input prediction]]
* [[Lag compensation]]
* [[Interpolation]]

[[Category:Networking]]