Syncing Properties

In a multiplayer game, each client runs its own copy of the simulation. Replication is the mechanism that keeps these copies consistent: the authority (a client in Shared-Authority, or the simulation server in Client-Server) writes the definitive values for an object's properties, and the Photon Cloud distributes them to every other client. Without replication, each player would see a different game.

Fusion replicates at the property level. Individual values like position, health or score are tracked independently. The server only sends properties that have changed since the last update, minimizing bandwidth.

For how authority is assigned and transferred between clients, see Ownership Modes.

The Replicator Node

FusionSharedReplicator handles property sync for networked objects. Add it as a child of your networked scene's root node. The authority client writes values to the server; remote clients receive and optionally smooth them.

Root Replication Modes

The replication mode controls which properties the replicator syncs automatically based on the root node type.

• REPLICATION_NONE - no auto-sync; add custom properties via the replicator's bottom panel
• REPLICATION_AUTO - auto-detects root node type and syncs accordingly:
• RigidBody2D/3D → position, rotation, linear_velocity, angular_velocity (forecast smoothing)
• CharacterBody2D/3D → position, rotation, velocity (interpolation smoothing)
• Other nodes → position, rotation (interpolation smoothing)

Smoothing

When root_smoothing is true (default), remote values are corrected smoothly instead of snapped. Physics bodies use velocity-based forecast; non-physics nodes use snapshot interpolation by default, or exponential decay if selected. Set root_smoothing = false for direct value application.

Custom Properties

Custom properties are added directly via the replicator's bottom panel in the editor. Use this for game data (health, score, name) beyond what the replication mode auto-syncs. Transform and physics properties should not be added. They are handled by REPLICATION_AUTO.

Supported types: bool, int, float, String, Vector2, Vector3, Vector4, Quaternion, Color, Node references, PackedByteArray, PackedFloat32Array, PackedInt32Array, PackedVector2Array. Dictionary is not supported - use individual properties or arrays instead.

Property Path Syntax

Property paths use a node:property syntax relative to the replicator's root node.

• :property - property on the root node
• child:property - property on a child node
• child/grandchild:property - nested child

GDScript

":health"             # Root node
"Sprite2D:modulate"   # Child Sprite2D

Strings and Arrays

Strings use 2 words (StringHeap handle + generation). Handles are freed automatically when the value changes.

Arrays (PackedFloat32Array, PackedInt32Array, PackedVector2Array, etc.) require a fixed max_capacity set before spawning.

Node References

Properties of type Node (or Object) can reference other networked root nodes. On the wire, each reference is stored as a Fusion ObjectId (2 words: Origin + Counter).

The referenced node must be a networked root, the parent node of a replicator. This includes spawned object roots, sub-object roots and scene object roots. Child nodes within a networked object cannot be referenced. Non-networked nodes and null both serialize as (0, 0) and resolve to null on the remote end.

GDScript

# Authority sets a reference to another networked node
partner = get_node("/root/Main/Player2")

# Remote must null-check - reference resolves to null if target is outside AoI or destroyed
if partner:
    print(partner.name)  # "Player2"

Resolution rules:

• If the referenced node is in the remote client's Area of Interest, it resolves to the local Node.
• If the referenced node is outside AoI, destroyed, or not yet spawned, it resolves to null.
• Setting the property to null or a non-networked node on authority sends null to all remotes.
• Scene objects loaded via Fusion.load_scene() work the same way. The reference resolves once the remote client has loaded the scene.

Interest Management (AOI)

Interest management controls which objects each client receives updates for, reducing bandwidth in large worlds. Objects publish an interest key via interest_mode on the replicator; clients subscribe to keys via Fusion.

• INTEREST_GLOBAL (default) - visible to all clients
• INTEREST_AREA - spatial grid key auto-computed from position (cell size in Project Settings fusion/interest_management/area_of_interest_cell_size)
• INTEREST_USER - custom group key via interest_key
  Subscribe with one or more FusionInterestArea nodes (auto-manages grid subscriptions, typically following camera or player node) or manually:

GDScript

Fusion.set_area_keys([[cell_key, 0]])   # area keys (refresh each frame)
Fusion.add_user_key(42)                  # user keys (persistent)

Enter/exit signals: Fusion.interest_enter / interest_exit.

Key Properties

These inspector properties control replication behavior on each replicator instance.

• root_path (NodePath, "..") - node whose properties are synced
• root_replication_mode - NONE or AUTO
• root_smoothing (bool, true)
• update_interval (int, 1) - server send interval in ticks
• root_teleport_threshold (float, 100.0) - snap if error exceeds this
• root_spring_stiffness (float, 50.0) / root_spring_damping (float, 10.0) — physics correction tuning (visible only on physics replicators with non-blend correction mode)

Signals

The replicator emits signals when authority changes or the network stomps state.

• authority_changed(has_authority: bool) - ownership changed
• state_reset(info: FusionStateResetInfo) - network reset this replicator's state. info.reason identifies the cause: REASON_REMOTE_RECEIVED (regular inbound sync), REASON_PREDICTION_RESET (client-server prediction rollback), or REASON_STATE_OVERRIDE (cloud stomped the authority). Not emitted on the local authority's outbound ticks.

See Ownership Modes for authority transfer patterns.

Advanced: reset_state()

reset_state() resets the node to the current Fusion network buffer, bypassing smoothing. Emits state_reset(REASON_REMOTE_RECEIVED).

Intended for custom prediction on replicated nodes - when your script advances the node's state manually and needs a lever to resync with the server buffer in between normal state-reset calls (which are still called normally).

GDScript

@onready var replicator: FusionSharedReplicator = $FusionSharedReplicator

func _physics_process(delta: float) -> void:
    position += velocity * delta   # custom prediction

# Elsewhere, on whatever trigger your game defines:
replicator.reset_state()

For full control, combine with Root Smoothing off. reset_state() itself bypasses smoothing, but leaving smoothing on means the built-in smoothing keeps applying toward the last-received target between your frames - typically fighting your custom extrapolation. Smoothing only affects auto-replicated transform / physics; user properties are never smoothed.

If your goal is just non-smoothed auto-replication on changed data (no custom prediction involved), disabling smoothing alone is enough. Every receive then snaps directly.

Back to top