Guide to Prediction

// In Content.Server/PredictionExample/PredictionExampleComponent.cs

using Robust.Shared.Audio;

namespace Content.Server.PredictionExample;

/// <summary>
/// A simple test component that
/// - plays a sound and shows a popup when interacted with, either by activating it or by using a verb
/// - has an examination text
/// </summary>
[RegisterComponent]
public sealed partial class PredictionExampleComponent : Component
{
    /// <summary>
    /// How often the entity has been interacted with.
    /// </summary>
    [DataField]
    public int Counter = 0;

    /// <summary>
    /// The sound to play when interacted with.
    /// </summary>
    [DataField]
    public SoundSpecifier Sound = new SoundPathSpecifier("/Audio/Machines/machine_switch.ogg");
}

// In Content.Server/PredictionExample/PredictionExampleSystem.cs

using Content.Shared.Examine;
using Content.Shared.Interaction;
using Content.Shared.Popups;
using Content.Shared.Verbs;
using Robust.Shared.Audio.Systems;

namespace Content.Server.PredictionExample;

// This system is server-side and therefore not predicted yet.
public sealed class PredictionExampleSystem : EntitySystem
{
    [Dependency] private readonly SharedAudioSystem _audio = default!;
    [Dependency] private readonly SharedPopupSystem _popup = default!;

    public override void Initialize()
    {
        base.Initialize();

        SubscribeLocalEvent<PredictionExampleComponent, GetVerbsEvent<Verb>>(OnGetVerb);
        SubscribeLocalEvent<PredictionExampleComponent, ActivateInWorldEvent>(OnActivate);
        SubscribeLocalEvent<PredictionExampleComponent, ExaminedEvent>(OnExamine);
    }

    // A simple right click verb
    private void OnGetVerb(Entity<PredictionExampleComponent> ent, ref GetVerbsEvent<Verb> args)
    {
        args.Verbs.Add(new()
        {
            Text = "Interaction Verb", // This should be localized, but I'm skipping that for this example.
            Act = () => Interact(ent),
        });
    }

    // Event that is raised when clicking on an entity or using it in your hand.
    private void OnActivate(Entity<PredictionExampleComponent> ent, ref ActivateInWorldEvent args)
    {
        Interact(ent);
    }

    // Increments an integer datafield, shows a popup and plays a sound.
    public void Interact(Entity<PredictionExampleComponent> ent)
    {
        // Increment the counter.
        ent.Comp.Counter++;

        // Play a sound at the location of the entity.
        _audio.PlayPvs(ent.Comp.Sound, ent.Owner);

        // Show a popup over the entity.
        // This should be localized, but I'm skipping that for this example.
        _popup.PopupEntity($"Interacted {ent.Comp.Counter} times.", ent.Owner);
    }

    // Show the counter in the examine text.
    public void OnExamine(Entity<PredictionExampleComponent> ent, ref ExaminedEvent args)
    {
        // This should be localized, but I'm skipping that for this example.
        args.PushMarkup($"Interacted {ent.Comp.Counter} times.");
    }
}

# in Resources/Prototypes/test.yml
- type: entity
  parent: BaseItem
  id: ExampleItem
  name: Prediction Example Item
  components:
  - type: Sprite
    sprite: Objects/Fun/Plushies/lizard.rsi
    state: icon
  - type: PredictionExample

// In Content.Shared/PredictionExample/PredictionExampleComponent.cs

using Robust.Shared.Audio;
using Robust.Shared.GameStates;

namespace Content.Shared.PredictionExample;

/// <summary>
/// We add NetworkedComponent so that the component itself is networked
/// and AutoGenerateComponentState to enable autonetworking for its datafields.
/// </summary>
[RegisterComponent, NetworkedComponent, AutoGenerateComponentState]
public sealed partial class PredictionExampleComponent : Component
{
    /// <summary>
    /// We add AutoNetworkedField to mark this datafield to be networked when we dirty the component.
    /// </summary>
    [DataField, AutoNetworkedField]
    public int Counter = 0;

    /// <summary>
    /// This datafield does not need to be networked, as it never changes after the entity is spawned.
    /// </summary>
    [DataField]
    public SoundSpecifier Sound = new SoundPathSpecifier("/Audio/Machines/machine_switch.ogg");
}

// In Content.Shared/PredictionExample/PredictionExampleSystem.cs

using Content.Shared.Examine;
using Content.Shared.Interaction;
using Content.Shared.Popups;
using Content.Shared.Verbs;
using Robust.Shared.Audio.Systems;

namespace Content.Shared.PredictionExample;

// Now this system is predicted.
// No need to make it abstract and inherit it on the server and client
// because we don't have server or client exclusive code in this example.
public sealed class PredictionExampleSystem : EntitySystem
{
    [Dependency] private readonly SharedAudioSystem _audio = default!;
    [Dependency] private readonly SharedPopupSystem _popup = default!;

    public override void Initialize()
    {
        base.Initialize();

        SubscribeLocalEvent<PredictionExampleComponent, GetVerbsEvent<Verb>>(OnGetVerb);
        SubscribeLocalEvent<PredictionExampleComponent, ActivateInWorldEvent>(OnActivate);
        SubscribeLocalEvent<PredictionExampleComponent, ExaminedEvent>(OnExamine);
    }

    // The same subscription as before, just in Content.Shared.
    private void OnGetVerb(Entity<PredictionExampleComponent> ent, ref GetVerbsEvent<Verb> args)
    {
        var user = args.User; // We need to save this as a variable since we cannot use ref parameters inside lambda expressions.
        args.Verbs.Add(new()
        {
            Text = "Interaction Verb",
            Act = () => Interact(ent, user),
        });
    }

    // The same subscription as before, just in Content.Shared.
    private void OnActivate(Entity<PredictionExampleComponent> ent, ref ActivateInWorldEvent args)
    {
        Interact(ent, args.User);
    }

    // We now need to pass in the user so we can predict the popup and audio.
    public void Interact(Entity<PredictionExampleComponent> ent, EntityUid user)
    {
        // Increment the counter.
        ent.Comp.Counter++;

        // Dirty the component since we changed one of its datafields.
        // It does not matter where exactly we put this as long as it happens in the same game tick.
        // I like calling it directly below to make sure I don't forget doing so.
        Dirty(ent);

        // Use PlayPredicted instead of PlayPvs and pass in the client that predicted the interaction.
        _audio.PlayPredicted(ent.Comp.Sound, ent.Owner, user);

        // Use PopupPredicted instead of PopupEntity and pass in the client that predicted the interaction.
        // This popup will be visible to everyone. If you want to show it only to the user then use PopupClient instead.
        _popup.PopupPredicted($"Interacted {ent.Comp.Counter} times.", ent.Owner, user);
    }

    // The same subscription as before, just in Content.Shared.
    public void OnExamine(Entity<PredictionExampleComponent> ent, ref ExaminedEvent args)
    {
        args.PushMarkup($"Interacted {ent.Comp.Counter} times.");
    }
}

// In Content.Shared/Explosion/EntitySystems/SharedExplosionSystem.cs
// This method is empty and does nothing on the client.
public virtual void TriggerExplosive(EntityUid uid, ExplosiveComponent? explosive = null, bool delete = true, float? totalIntensity = null, float? radius = null, EntityUid? user = null)
{
}

// In Content.Server/Explosion/EntitySystems/ExplosionSystem.cs
// This contains the actual code and only runs on the server, but can still be called from shared, since shared code runs on both the server and client.
public override void TriggerExplosive(EntityUid uid, ExplosiveComponent? explosive = null, bool delete = true, float? totalIntensity = null, float? radius = null, EntityUid? user = null)
{
    // Some code in here that creates the explosion
}

// GluedComponent will make an item temporarily unremovable if you pick it up.
private void OnHandPickUp(Entity<GluedComponent> entity, ref GotEquippedHandEvent args)
{
    // When your client predicts picking up an item, due to the game state being repeatedly reset and your input being reapplied
    // the item will be rapidly inserted and dropped from your hand (about 10 times each) during prediction. 
    // This will raise both GotEquippedHandEvent and GotUnequippedHandEvent in alternating order.
    // Similarly when you predict dropping a glued item prediction will reinsert the item into the hand when rerolling the state to a previous one.
    // So dropping the item would add UnremoveableComponent on the client without this guard statement,
    // preventing the client from picking it up again, which would cause mispredicts.
    // However, adding and removing the UnremovableComponent and setting the datafields is already applied with the same game state,
    // so we don't have to do anything in that case, fixing the problem.
    if (_timing.ApplyingState)
        return;

    var comp = EnsureComp<UnremoveableComponent>(entity);
    comp.DeleteOnDrop = false;
    entity.Comp.Until = _timing.CurTime + entity.Comp.Duration;
    Dirty(entity.Owner, comp);
    Dirty(entity);
}

/// <summary>
/// Unpredicted example.
/// </summary>
[RegisterComponent]
public sealed partial class UpdateLoopExampleComponent : Component
{
    /// <summary>
    /// How much time has passed since the last update?
    /// In seconds.
    /// </summary>
    [DataField]
    public float Accumulator = 0f;

    /// <summary>
    /// The time interval for the update loop (we don't want to run it every single tick for performance reasons).
    /// In seconds.
    /// </summary>
    [DataField]
    public float UpdateInterval = 1f;
}

public sealed class UpdateLoopExampleSystem : EntitySystem
{
    public override void Update(float frameTime)
    {
        // Loop over all components, ignoring paused entities.
        var query = EntityQueryEnumerator<UpdateLoopExampleComponent>();
        while (query.MoveNext(out var uid, out var comp))
        {
            comp.Accumulator += frameTime;

            if (comp.Accumulator < UpdateInterval)
                continue; // Not enough time has passed since the last update.
        
            // Reset the accumulator.
            comp.Accumulator -= UpdateInterval;
        
            // Do stuff here.
        }
    }
}

/// <summary>
/// Predicted example.
/// We need to network the component for this.
/// </summary>
[RegisterComponent, NetworkedComponent]
[AutoGenerateComponentState, AutoGenerateComponentPause]
public sealed partial class UpdateLoopExampleComponent : Component
{
    /// <summary>
    /// The server time at which the next update will happen.
    /// We use AutoPausedField so that this is automatically incremented if the server is paused and unpaused again.
    /// Otherwise all update loops would instantly fire when unpausing.
    /// We use the TimeOffsetSerializer to let this datafield be serialized relative to the current server time.
    /// This is important for persistance and without it you would get different results depending on when you load a game save.
    /// This datafield needs to be networked so that the server and client will be able to update simultaneously.
    /// </summary>
    [DataField(customTypeSerializer: typeof(TimeOffsetSerializer))]
    [AutoNetworkedField, AutoPausedField]
    public TimeSpan NextUpdate = TimeSpan.Zero;

    /// <summary>
    /// The time interval for the update loop (we don't want to run it every single tick for performance reasons).
    /// Does not need to be networked since this value remains constant in this example.
    /// </summary>
    [DataField]
    public TimeSpan UpdateInterval = TimeSpan.FromSeconds(1);
}

public sealed class UpdateLoopExampleSystem : EntitySystem
{
    [Dependency] private readonly IGameTiming _timing = default!;

    public override void Initialize()
    {
        SubscribeLocalEvent<UpdateLoopExampleComponent, MapInitEvent>(OnMapInit)
    }
    
    private void OnMapInit(Entity<UpdateLoopExampleComponent> ent, ref MapInitEvent args)
    {
        // Set the first update time after the entity is spawned.
        // Without this it would update every single tick until NextUpdate catches up with the server time.
        ent.Comp.NextUpdate = _timing.CurTime + ent.Comp.UpdateInterval;
        Dirty(ent);
    }

    public override void Update(float frameTime)
    {
        // CurTime is calculated so we do it only once outside the update loop instead of for every sigle entity.
        var curTime = _timing.Curtime;
        // Loop over all components, ignoring paused entities.
        var query = EntityQueryEnumerator<UpdateLoopExampleComponent>();
        while (query.MoveNext(out var uid, out var comp))
        {
            if (comp.NextUpdate < curTime)
                continue; // Not enough time has passed since the last update.
        
            // Set the time for the next update.
            // Don't use
            // comp.NextUpdate = curTime + UpdateInterval;
            // because that eats the remainder with every update, causing the update loop to run slightly less often
            // than given by UpdateInterval, which will be imprecise and can cause problems over large time durations.
            comp.NextUpdate += UpdateInterval;
        
            // Dirty the component so that the client can reroll the NextUpdate datafield during predcition.
            // Without this you will get mispredicts.
            Dirty(uid, comp);
        
            // Do stuff here.
        }
    }
}

// EntitySystem dependencies:
// [Dependency] private readonly IGameTiming _timing = default!;
// [Dependency] private readonly IRobustRandom _random = default!;

// This will mispredict:
bool randomBool = _random.Prob(0.5f);
double randomDouble = _random.NextDouble();

// Instead use this:
bool randomBoolPredicted = SharedRandomExtensions.PredictedProb(_timing, 0.5f, GetNetEntity(uid)); // Helper method that directly gives you a bool.
var rand = SharedRandomExtensions.PredictedRandom(_timing, GetNetEntity(uid)); // Create a new System.Random instance that is the same on the server and client.
double randomDoublePredicted = rand.NextDouble(); // Create some random number from it.

// Same for any other method in IRobustRandom, since it is just a System.Random wrapper.
// If you generate multiple random numbers in the same tick for the same entity then you can re-use the System.Random instance instead of instantiating a new one for each call.

Can't resolve "Robust.Shared.GameObjects.MetaDataComponent" on entity 957132/n0D!
   at System.Environment.get_StackTrace()
   at Robust.Shared.GameObjects.EntityManager.GetNetEntity(EntityUid uid, MetaDataComponent metadata) in /home/runner/work/space-station-14/space-station-14/RobustToolbox/Robust.Shared/GameObjects/EntityManager.Network.cs:line 186
...

// inside an EntitySystem

public void SetExampleDataField(Entity<ExampleComponent?> ent, int newValue)
{
    if (!Resolve(ent, ref ent.Comp))
        return; // do nothing if the entity does not have the component
    
    if (ent.Comp.ExampleDataField == newValue)
        return; // nothing changed, no need to dirty
        
    // set the datafield and dirty the component
    ent.Comp.ExampleDataField = newValue;
    Dirty(ent);
}

// In Content.Shared/SomeNamespace/SomeSystem.cs
public sealed class SomeSystem : EntitySystem
{
    // ...
}

// In Content.Shared/SomeNamespace/SharedSomeSystem.cs
public abstract class SharedSomeSystem : EntitySystem
{
    // ...
}

// In Content.Server/SomeNamespace/SomeSystem.cs
public sealed class SomeSystem : SharedSomeSystem
{
    // ...
}

// In Content.Client/SomeNamespace/SomeSystem.cs
public sealed class SomeSystem : SharedSomeSystem
{
    // ...
}

private void OnEntRemoved(Entity<UdderComponent> entity, ref EntRemovedFromContainerMessage args)
{
    // Make sure the removed entity was our contained solution
    if (entity.Comp.Solution == null || args.Entity != entity.Comp.Solution.Value.Owner)
        return;

    // Cleared our cached reference to the solution entity
    entity.Comp.Solution = null;
}