docs.unity3d.com
    Show / Hide Table of Contents

    Class GhostFieldAttribute

    Attribute used to specify how and which fields and properties of IComponentData or IBufferElementData should be replicated. When a component or buffer contains at least one field that is annotated with a GhostFieldAttribute, a struct implementing the component serialization is automatically code-generated.

    Inheritance
    Object
    Attribute
    GhostFieldAttribute
    Inherited Members
    Attribute.GetCustomAttributes(MemberInfo, Type)
    Attribute.GetCustomAttributes(MemberInfo, Type, Boolean)
    Attribute.GetCustomAttributes(MemberInfo)
    Attribute.GetCustomAttributes(MemberInfo, Boolean)
    Attribute.IsDefined(MemberInfo, Type)
    Attribute.IsDefined(MemberInfo, Type, Boolean)
    Attribute.GetCustomAttribute(MemberInfo, Type)
    Attribute.GetCustomAttribute(MemberInfo, Type, Boolean)
    Attribute.GetCustomAttributes(ParameterInfo)
    Attribute.GetCustomAttributes(ParameterInfo, Type)
    Attribute.GetCustomAttributes(ParameterInfo, Type, Boolean)
    Attribute.GetCustomAttributes(ParameterInfo, Boolean)
    Attribute.IsDefined(ParameterInfo, Type)
    Attribute.IsDefined(ParameterInfo, Type, Boolean)
    Attribute.GetCustomAttribute(ParameterInfo, Type)
    Attribute.GetCustomAttribute(ParameterInfo, Type, Boolean)
    Attribute.GetCustomAttributes(Module, Type)
    Attribute.GetCustomAttributes(Module)
    Attribute.GetCustomAttributes(Module, Boolean)
    Attribute.GetCustomAttributes(Module, Type, Boolean)
    Attribute.IsDefined(Module, Type)
    Attribute.IsDefined(Module, Type, Boolean)
    Attribute.GetCustomAttribute(Module, Type)
    Attribute.GetCustomAttribute(Module, Type, Boolean)
    Attribute.GetCustomAttributes(Assembly, Type)
    Attribute.GetCustomAttributes(Assembly, Type, Boolean)
    Attribute.GetCustomAttributes(Assembly)
    Attribute.GetCustomAttributes(Assembly, Boolean)
    Attribute.IsDefined(Assembly, Type)
    Attribute.IsDefined(Assembly, Type, Boolean)
    Attribute.GetCustomAttribute(Assembly, Type)
    Attribute.GetCustomAttribute(Assembly, Type, Boolean)
    Attribute.Equals(Object)
    Attribute.GetHashCode()
    Attribute.Match(Object)
    Attribute.IsDefaultAttribute()
    Attribute._Attribute.GetTypeInfoCount(UInt32)
    Attribute._Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)
    Attribute._Attribute.GetIDsOfNames(Guid, IntPtr, UInt32, UInt32, IntPtr)
    Attribute._Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)
    Attribute.TypeId
    Object.Equals(Object, Object)
    Object.ReferenceEquals(Object, Object)
    Object.GetType()
    Object.MemberwiseClone()
    Namespace: Unity.NetCode
    Syntax
    [AttributeUsage(AttributeTargets.Property | AttributeTargets.Field)]
    public class GhostFieldAttribute : Attribute, _Attribute
    Remarks

    Note that "enableable components" (IEnableableComponent) will still have their fields replicated, even when disabled. See GhostEnabledBitAttribute to replicate the enabled flag itself.

    Properties

    Composite

    Only applicable on GhostFieldAttributes applied to a non primitive struct containing multiple fields. If this value is not set (a.k.a. false, the default), a 'change bit' will be included 'per field, for every field inside the nested struct'. There will be no 'change bit' for the struct itself. I.e. If a single field inside the sub-struct changes, only that fields 'change bit' will be set. Otherwise (if this Composite bool is set, a.k.a. true), we instead use a single 'change bit' for 'the entire nested struct'. I.e. If any fields inside the sub-struct change, the single 'change bit' for the entire struct will be set. Check the Serialize/Deserialize code-generated methods in Library\NetCodeGenerated_Backup for examples.

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

    MaxSmoothingDistance

    The maximum distance between two snapshots for which smoothing will be applied. If the value changes more than this between two received snapshots the smoothing action will not be performed.

    Declaration
    public float MaxSmoothingDistance { get; set; }
    Property Value
    Type Description
    Single
    Remarks

    For quaternions the value specified should be sin(theta / 2) - where theta is the maximum angle you want to apply smoothing for.

    Quantization

    Floating point numbers will be multiplied by this number and rounded to an integer, enabling better delta-compression via huffman encoding. Specifying a Quantization is mandatory for floating point numbers and not supported for integer numbers. To send a floating point number unquantized, use 0. Examples: Quantization=0 implies full precision. Quantization=1 implies precision of 1f (i.e. round float values to integers). Quantization=2 implies precision of 0.5f. Quantization=10 implies precision of 0.1f. Quantization=20 implies precision of 0.05f. Quantization=1000 implies precision of 0.001f.

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

    SendData

    Default true. If unset (false), instructs code-generation to not include this field in the serialization data. I.e. Do not replicate this field. This is particularly useful for non primitive members (like structs), which will have all fields serialized by default.

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

    Smoothing

    Default is Clamp.

    Declaration
    public SmoothingAction Smoothing { get; set; }
    Property Value
    Type Description
    SmoothingAction

    SubType

    Allows you to specify a custom serializer for this GhostField using the GhostFieldSubType API.

    Declaration
    public int SubType { get; set; }
    Property Value
    Type Description
    Int32
    Remarks

    Why GhostFieldSubType is not an enum: The reason is that there are unfortunately caveats, some due to our compilation pipeline and others due to the limitation of the SourceGenerator api. First: MS SourceGenerator are additive only. That means we cannot modify the syntaxtree, removing or adding nodes to it (not the way Analyzers does). To overcome that limitation, a possible solution to inject the enums literals into the assembly is to use a small IL post processor instead. Because NetCode runtime assembly is re-imported every time a sub-type is added or removed, the assumption was that the IL post-processing will then correctly modify the dll before any dependent dll is compiled. Although it does, and Unity.NetCode.dll contains the correct metadata, the ILPostProcessorRunner run at a later time and some dlls are not compile correctly (depend on timing). With further investigation it might be possible to address that problem, however it seems like fighting against the compilation process again, something we wanted to avoid. Because all of that, a partial class to hold the integral constants it uses instead and users can add new const literals.

    Why the AssemblyDefinitionReference? Using source generator to add a partial class directly to NetCode.dll works fine but unfortunately will miss the IDE auto-completion functionality. No IDE at the moment provide support for that out of the box. VS has some workaround for normal C# projects (removing the original file from the solution etc) or by restarting the IDE, but Rider or VSCode does not work the same way. By using the Assembly Definition Reference, we are actually doing in principle the same job and completion works, making the user experience a little more pleasant.


    Did you find this page useful? Please give it a rating:

    Thanks for rating this page!

    Report a problem on this page

    What kind of problem would you like to report?

    • This page needs code samples
    • Code samples do not work
    • Information is missing
    • Information is incorrect
    • Information is unclear or confusing
    • There is a spelling/grammar error on this page
    • Something else

    Thanks for letting us know! This page has been marked for review based on your feedback.

    If you have time, you can provide more information to help us fix the problem faster.

    Provide more information

    You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:

    You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:

    You've told us there is information missing from this page. Please tell us more about what's missing:

    You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:

    You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:

    You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:

    You've told us this page has a problem. Please tell us more about what's wrong:

    Thank you for helping to make the Unity documentation better!

    Your feedback has been submitted as a ticket for our documentation team to review.

    We are not able to reply to every ticket submitted.

    In This Article
    • Properties
      • Composite
      • MaxSmoothingDistance
      • Quantization
      • SendData
      • Smoothing
      • SubType
    Back to top
    Copyright © 2023 Unity Technologies — Terms of use
    • Legal
    • Privacy Policy
    • Cookies
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)
    "Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.
    Generated by DocFX on 18 October 2023