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 doesn't happen every frame and has impact on the game view are usually better represented by events. But if such game data needs to be sent every tick, events are likely gonna perform worse than polling. However, Quantum events are fire-and-forget, meaning that late joiners are not gonna execute events which were executed before the player joined. So anything visual that was created from events will need to be manually re-created on late joiners just from reading the game state.
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 (like 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 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. 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.