Struct GhostSendSystemData

Singleton entity that contains all the tweakable settings for the GhostSendSystem.

Implements
IComponentData
IQueryTypeParameter
Inherited Members
Namespace: Unity.NetCode
Assembly: Unity.NetCode.dll
Syntax
[Serializable]
public struct GhostSendSystemData : IComponentData, IQueryTypeParameter

Fields

CleanupConnectionStatePerTick

The number of connections to cleanup unused serialization data for, in a single tick. Setting this higher can recover memory faster, but uses more CPU time.

Declaration
[Tooltip("The number of connections to cleanup unused serialization data for, in a single tick. Setting this higher can recover memory faster, but uses more CPU time.\n\nDefaults to 1.")]
[Min(1)]
public int CleanupConnectionStatePerTick
Field Value
Type Description
int

DefaultSnapshotPacketSize

If not 0, denotes the desired size of an individual snapshot (unless the per-connection NetworkStreamSnapshotTargetSize component is present). If zero, Unity.Networking.Transport.NetworkParameterConstants.MTU is used (minus headers).

Declaration
[Tooltip("- If zero (the default), <b>NetworkParameterConstants.MTU</b> is used (minus headers).\n\n - Otherwise, denotes the desired size of an individual snapshot (unless the per-connection <b>NetworkStreamSnapshotTargetSize</b> component is present).")]
[Min(0)]
public int DefaultSnapshotPacketSize
Field Value
Type Description
int

MaxIterateChunks

Denotes the maximum number of chunks the GhostSendSystem will iterate over in a single tick, for a given connection, within a single NetworkTickRate snapshot send interval. It's an optimization in use-cases where you have many thousands of static ghosts (and thus hundreds of static chunks which are iterated over unneccessarily to find ones containing possible changes).

Declaration
[Tooltip("Denotes the maximum number of chunks the <b>GhostSendSystem</b> will iterate over in a single tick, for a given connection, within a single <b>NetworkTickRate</b> snapshot send interval.\n\nIt's an optimization in use-cases where you have many thousands of static ghosts (and thus hundreds of static chunks which are iterated over unneccessarily to find ones containing possible changes).\n\nDefaults to 0 (i.e. use <b>MinSendImportance</b>)\nRecommendation: ~10\n\n - A positive value will clamp the maximum number of chunks we iterate over (but cannot be less than <b>MaxSendChunks</b>, thus clamped automatically to it).\n - Use 0 to denote that <b>MaxIterateChunks</b> should use <b>MaxSendChunks</b>.\n\n - Use -1 to denote that you want to iterate until the packet is filled - or send rules (like <b>MaxSendChunks</b>) are encountered.")]
[Min(0)]
public int MaxIterateChunks
Field Value
Type Description
int
Remarks

A positive value will clamp the maximum number of chunks we iterate over (but cannot be less than MaxSendChunks, thus clamped automatically to it). Use 0 (the default) to denote that you want to use the MaxSendChunks value as the MaxIterateChunks value (but note that this can lead to snapshot packets being less full than expected). Use -1 to denote that you want to iterate until the packet is filled (or send rules like MaxSendChunks are encountered).
1st Warning: If netcode cannot fill the packet within MaxIterateChunks chunks (for any reason), any ghost chunks after this index will not be processed (even if there is still space in the packet). Therefore, if you're encountering less-than-full packets in cases where you expect the packet to be full, increase this!
2nd Warning: MaxIterateChunks limits the number of chunks we process, and this filtering is applied BEFORE we check if ghosts are irrelevant. Therefore, if MaxIterateChunks is 4 (for example), and the 4 highest importance chunks ONLY contain irrelevant ghosts, we will NOT send ANY ghosts in this snapshot. Therefore, we recommend setting MaxIterateChunks to a value at least 2x higher than MaxSendChunks.

MaxSendChunks

The maximum number of chunks the GhostSendSystem will add to the snapshot for any given connection, within a single NetworkTickRate snapshot send interval. Only incremented when at least one ghost is added to the snapshot for a chunk.
Warning: MaxSendChunks may lead to unnecessarily empty snapshot packets, in cases where adding this many chunks to the snapshot does not completely fill it. See MaxIterateChunks for resolution.

Declaration
[Tooltip("The maximum number of chunks the GhostSendSystem will add to the snapshot for any given connection, within a single NetworkTickRate snapshot send interval. Only incremented when at least one ghost is added to the snapshot for a chunk. Warning: <b>MaxSendChunks</b> may lead to unnecessarily empty snapshot packets, in cases where adding this many chunks to the snapshot does not completely fill it. See <b>MaxIterateChunks</b> for resolution.\n\nDefaults to 0 (OFF).")]
[Min(0)]
public int MaxSendChunks
Field Value
Type Description
int

MaxSendEntities

The maximum number of entities the GhostSendSystem will add to the snapshot for any given connection, within a single NetworkTickRate snapshot send interval. Ignores irrelevant ghosts and cancelled sends (e.g. zero change static optimized chunks). This can be used to reduce / control CPU time on the server. Warning: MaxSendChunks may lead to unnecessarily empty snapshot packets, in cases where adding this many entities to the snapshot does not completely fill it. Prefer MaxSendChunks and MaxIterateChunks.

Declaration
[Tooltip("<b>Obsolete: No longer functional!</b>\n\nThe maximum number of entities the <b>GhostSendSystem</b> will add to the snapshot for any given connection, within a single <b>NetworkTickRate</b> snapshot send interval. Ignores irrelevant ghosts and cancelled sends (e.g. zero change static optimized chunks). This can be used to reduce / control CPU time on the server.\n\n<b>Warning</b>: <b>MaxSendChunks</b> may lead to unnecessarily empty snapshot packets, in cases where adding this many entities to the snapshot does not completely fill it. Prefer <b>MaxSendChunks</b> and <b>MaxIterateChunks</b>.\n\nDefaults to 0 (OFF).")]
[Min(0)]
[ReadOnly]
[Obsolete("No longer functional! Prefer MaxSendChunks and MaxIterateChunks to tweak GhostSendSystem CPU characteristics. (RemovedAfter 1.x)", false)]
public int MaxSendEntities
Field Value
Type Description
int
Remarks

An implementation detail to be aware of here is that we can currently only check this value after a chunk has been written (partially or in full) to the snapshot. Therefore, in practice, a value of 1 is equivalent to MaxSendChunks = 1;.

MinDistanceScaledSendImportance

The minimum importance considered for inclusion in a snapshot after applying distance based priority scaling to the ghost chunk. Any ghost chunk with a downscaled importance value lower than this will not be added to the snapshot, even if there is enough space in the packet.

Declaration
[Tooltip("The minimum importance considered for inclusion in a snapshot after applying distance based priority scaling to the ghost chunk. Any ghost chunk with a downscaled importance value lower than this will not be added to the snapshot, even if there is enough space in the packet.\n\nDefaults to 0 (OFF).")]
[Min(0)]
public int MinDistanceScaledSendImportance
Field Value
Type Description
int

MinSendImportance

The minimum importance considered for inclusion in a snapshot. Any ghost chunk with an importance value lower than this value will not be added to the snapshot, even if there is enough space in the packet.

Declaration
[Tooltip("The minimum importance considered for inclusion in a snapshot. The Defaults to 0 (disabled).\n\nAny ghost chunk with an importance value lower than this value will not be added to the snapshot, even if there is enough space in the packet. Use to reduce send-rate for low-importance ghosts.\n\nDefaults to 0 (OFF).")]
[Min(0)]
public int MinSendImportance
Field Value
Type Description
int
Remarks

As of 1.4, prefer MaxSendRate, which you can author via the GhostAuthoringComponent. Counted on a per-connection, per-chunk basis, where importance increases by the Importance value every tick, until sent (NOT confirmed delivered). E.g. MinSendImportance=60, SimulationTickRate=60, GhostAuthoringComponent.Importance=1 implies a ghost will be replicated roughly once per second.

Properties

EnablePerComponentProfiling

Enable profiling scopes for each component in a ghost. This can help track down why a ghost is expensive to serialize - but it comes with a performance cost, so is not enabled by default.

Declaration
public bool EnablePerComponentProfiling { get; set; }
Property Value
Type Description
bool

FirstSendImportanceMultiplier

Non-zero values for MinSendImportance can cause both:

  1. 'unchanged chunks that are "new" to a new-joiner' and b) 'newly spawned chunks' to be ignored by the replication priority system for multiple seconds. If this behaviour is undesirable, set this to be above MinSendImportance. This multiplies the importance value used on those "new" (to the player or to the world) ghost chunks. Note: This does not guarantee delivery of all "new" chunks, it only guarantees that every ghost chunk will get serialized and sent at least once per connection, as quickly as possible (e.g. assuming you have the bandwidth for it).
Declaration
public uint FirstSendImportanceMultiplier { get; set; }
Property Value
Type Description
uint

ForcePreSerialize

Debug Feature: Force all ghosts to use pre-serialization. This means part of the serialization will be done once for all connection, instead of once per-connection. This can increase CPU time for simple ghosts and ghosts which are rarely sent. This switch is meant as a DEBUG feature, providing a way of measuring which ghosts would benefit from using pre-serialization.

Declaration
public bool ForcePreSerialize { get; set; }
Property Value
Type Description
bool
Remarks

Should not be enabled in Production!

ForceSingleBaseline

Force all ghosts to use a single snapshot delta-compression value prediction baseline. This will reduce CPU usage at the expense of increased bandwidth usage. This is mostly meant as a way of measuring which ghosts should use static optimization instead of dynamic. If the bits / ghost does not significantly increase when enabling this the ghost can use static optimization to save CPU.

Declaration
public bool ForceSingleBaseline { get; set; }
Property Value
Type Description
bool

IrrelevantImportanceDownScale

Value used to scale down the importance of chunks where all entities were irrelevant last time it was sent. The importance is divided by this value. It can be used together with MinSendImportance to make sure relevancy is not updated every frame for things with low importance.

Declaration
public int IrrelevantImportanceDownScale { get; set; }
Property Value
Type Description
int

KeepSnapshotHistoryOnStructuralChange

Try to keep the snapshot history buffer for an entity when there is a structural change. Doing this will require a lookup and copy of data whenever a ghost has a structural change, which will add additional CPU cost on the server. Keeping the snapshot history will not always be possible, so, this flag does no give a 100% guarantee, and you are expected to measure CPU and bandwidth when changing this.

Declaration
public bool KeepSnapshotHistoryOnStructuralChange { get; set; }
Property Value
Type Description
bool

TempStreamInitialSize

Value used to set the initial size of the internal temporary stream in which ghost data is serialized. Using a small size will incur in extra serialization costs (because of multiple round of serialization), while using a larger size provide better performance (overall). The minimum size of this buffer is forced to be the initial capacity of the outgoing data stream (usually MaxMessageSize or larger for fragmented payloads). The suggested default (8kb), while extremely large in respect to the packet size, would allow the GhostSendSystem to be able to to write a large range of mid/small ghost entities types, with varying size (up to hundreds of bytes each), without incurring in extra serialization overhead.

Declaration
public int TempStreamInitialSize { get; set; }
Property Value
Type Description
int

UseCustomSerializer

When set, enables support for using any registered GhostPrefabCustomSerializer to serialize ghost chunks.

Declaration
public int UseCustomSerializer { get; set; }
Property Value
Type Description
int

Implements

Unity.Entities.IComponentData
Unity.Entities.IQueryTypeParameter