CRecipientFilter

From Valve Developer Community
Jump to: navigation, search

The CRecipientFilter class enables the server to pick and choose which clients it passes an item of data to. Most server-to-client communication supports it.

Alongside adding/removing clients individually or all at once, it can filter by Potentially Audible Set, Potentially Visible Set and Team.

Examples

CRecipientFilter MyFilter;
	MyFilter.AddRecipientsByPVS( GetAbsOrigin() );	// Clients within the entity's PVS will be added.
	MyFilter.MakeReliable();
CRecipientFilter MyInverseFilter;
	MyInverseFilter.AddAllPlayers();
	MyInverseFilter.RemoveRecipientsByPVS( GetAbsOrigin() );	// Leaving only players outside the PVS
	MyInverseFilter.MakeReliable();

Reliable vs. Unreliable

MakeReliable() gives any command using the filter instance a higher network transmission priority. It causes the data to be sent early on in the next network update, and to be queued if it can't be sent immediately. Data with an unreliable filter is sent at the end of the next packet if there is any room left, and is dropped and forgotten about if not transmitted immediately.

This is useful for prioritising network data at times of heavy traffic. To do: Confirm/expand this.

Derived classes

Several derived classes exist to automate the creation of common filters, with constructors set up to directly return an appropriately-configured instance.

Warning: These are unreliable unless otherwise noted!

CBroadcastRecipientFilter()
CReliableBroadcastRecipientFilter()
All players.
CPASFilter(origin)
CPASAttenuationFilter(<various constructors>)
All players in the origin's PAS. CPASAttenuationFilter will additionally remove those too far away to hear the sound.
CPVSFilter(origin)
All players in the origin's PVS.
CSingleUserRecipientFilter(CBasePlayer)
A specific player.
CTeamRecipientFilter(int team, bool isReliable = false)
A multiplayer team.
CLocalPlayerFilter()
The local player. Used as a dummy filter when calling functions requiring one on the client. Reliability is irrelevant.

Example

To make an entity produce a sound from another location:

EmitSound( CPASFilter(pPuppet->GetAbsOrigin()),pPuppet->entindex(),"Ventriloquist.Hello" );

See also

Tip:You don't need to use the filter entities as a programmer - you already have direct access to the relevant data.