Documentation

Cloud Code

Version: 3.0.0  
Unity 6.7 (6000.7)+
Open Unity Dashboard

Cloud Code

Version: 3.0.0  
Unity 6.7 (6000.7)+

Player and match persistence in CloudBehaviours

Understand what Cloud Code persists for a CloudBehaviour between invocations, and how to control it.
Read time 2 minutesLast updated 12 days ago
Important
This page describes an experimental feature that might change significantly before release. It's not recommended to use or rely on experimental features in production environments due to potential instability.
Synchronization and persistence are independent. Synchronization controls whether a member reaches a client, and persistence controls whether a member survives between invocations. A member can synchronize, persist, do both, or do neither.

What persists by default

By default, a public member persists in the cloud between invocations, and a non-public member doesn't. Two attributes override that default, and both attributes apply to fields and properties:

Attribute

Effect

[CloudCodeSerializeProperty]
Persists the member. Use it to persist a non-public member.
[CloudCodeIgnoreProperty]
Keeps the member out of persistence. Use it to stop a public member from persisting.
Neither attribute changes whether a member synchronizes. A public member synchronizes and a non-public member doesn't, whichever attribute you apply.
Persistence applies member by member inside a persisted object too. A private field in a persisted custom type needs its own 
[CloudCodeSerializeProperty]
.
The following example applies both attributes:
// This field survives invocations, but Cloud Code never sends it to a client.[CloudCodeSerializeProperty]private string _correctAnswer;// This field synchronizes for display, but Cloud Code doesn't persist it.[CloudCodeIgnoreProperty]public int FramesSinceStart;

Player scope compared with session scope

Scope.Player
gives you one CloudBehaviour instance per player, bound to the player's Unity Gaming Services (UGS) identity. Use 
Scope.Player
for progression, inventory, and other state that outlives a single session.
Scope.MultiplayerSession
gives you one instance shared by everyone in a session. Use 
Scope.MultiplayerSession
for match state, such as turn order and shared scores, that only needs to last for the session.
Scopes and their lifetimes come from the underlying Stateful Cloud Code module. For the full serialization mechanics, refer to State serialization in Cloud Code.

Common persistence mistakes

Cloud Code saves only serialized members. A plain private field without 
[CloudCodeSerializeProperty]
can keep its value temporarily. However, the field resets whenever Cloud Code reloads your CloudBehaviour from saved state, which can happen between any two calls. If a value unexpectedly resets, confirm that the member is public or marked with 
[CloudCodeSerializeProperty]
.
A get-only or computed property that Cloud Code persists, such as 
public int Total => A + B;
, causes a compile-time error. Cloud Code can't restore a value into a property without a setter. Exclude the property with 
[CloudCodeIgnoreProperty]
, or give it a setter. A private setter is enough.

Additional resources