Events vs Polling
Introduction
Reading information from the simulation while inside Unity in order to display relevant data to the user is a common practice in Quantum games.
To do this, there are two approaches that can be taken. The first approach is polling, which involves requesting information from Unity at regular intervals, such as inside the Update loop. The second approach is using Quantum events, which involves subscribing methods to Quantum's event system and using them to update the view.
Polling
A simple approach to polling could look like this:
// This snippet is extracted from the Quantum API Sample.
// Update is called once per frame
private void Update()
{
// The QuantumGame used here can be found, for example, via "QuantumRunner.Default.Game"
var kcc = _game.Frames.Verified.Unsafe.GetPointer<CharacterController3D>(_entityRef);
bool isMoving = kcc->Velocity.Magnitude.AsFloat > 0.2f;
_animator.SetBool(BOOL_IS_MOVING, isMoving);
if (isMoving)
{
_animator.SetFloat(FLOAT_MOVEMENT_SPEED, kcc->Velocity.Magnitude.AsFloat);
_animator.SetFloat(FLOAT_MOVEMENT_VERTICAL, kcc->Velocity.Z.AsFloat);
}
else
{
_animator.SetFloat(FLOAT_MOVEMENT_SPEED, 0.0f);
_animator.SetFloat(FLOAT_MOVEMENT_VERTICAL, 0.0f);
}
}This snippet polls from the simulation to read the latest verified frame in order to read the player's KCC velocity and apply the appropriate animation.
Event Based
A simple approach to event based could look like this:
private void Start()
{
// subscribe to the simulation event
QuantumEvent.Subscribe<EventOnDamaged>(this, OnDamaged);
}
private void OnDamaged(EventOnDamaged e)
{
// play a particle effect to show a damage indication
GetComponent<ParticleSystem>().Play();
}This snippet subscribes to a user-created simulation event in order to spawn a particle effect inside Unity. It is even possible to send game data within the event class, which already contains a reference to the game from which the frame can be found.
For more information about events, visit Events & Callbacks.
Pros & Cons
Both of these methods have their own drawbacks.
Event based code can be more performant when the information doesn't need to be too frequently sent to Unity. Game situations that don't happen every frame and that have an impact on the game view are usually better represented by events. But if such game data needs to be sent every tick, event will likely perform worse than polling. However, Quantum events are fire-and-forget, meaning that late joiners will not receive events which were executed before they joined. So anything visual that was created from events will need to be manually re-created when the client joins.
Polling code is generally simpler to write and easier to understand, and is usually better used to represent visual data that can change very frequently (every frame). Due to the nature of polling, initializing visuals for late joiners is automatic as it guarantees all the data to build the visuals are already contained in the game state that was received by the late joiner.
Predicted Vs Verified
While using both of these techniques, you have the option of using either Predicted or Verified frames. Both have their own drawbacks and benefits. While predicted frames will give you more immediate feedback, they may be susceptible to being inaccurate due to rollbacks. Whereas verified frames are concrete, but they will take a moment to take effect as it includes a round trip to the server to verify them. Generally a developer would use a mix of these, for example, they could use verified frames to display game score and predicted frames for effects such as jump clouds or hit particles.