Add prediction to Spill Container verb, add dummy TrySpill methods to shared (#25813)

* Moved abstract spill methods to shared; added prediction to spill container verb.

* Rerun tests

* Requested changes

* Note Client behavior in Spill method docs

Content.Shared/Fluids/SharedPuddleSystem.cs

@@ -1,12 +1,14 @@
 using Content.Shared.Chemistry.Components;
 using Content.Shared.Chemistry.EntitySystems;
 using Content.Shared.Chemistry.Reagent;
+using Content.Shared.DoAfter;
 using Content.Shared.DragDrop;
 using Content.Shared.Examine;
 using Content.Shared.FixedPoint;
 using Content.Shared.Fluids.Components;
 using Content.Shared.Movement.Events;
 using Content.Shared.StepTrigger.Components;
+using Robust.Shared.Map;
 using Robust.Shared.Prototypes;
 
 namespace Content.Shared.Fluids;
@@ -15,6 +17,7 @@ public abstract partial class SharedPuddleSystem : EntitySystem
 {
     [Dependency] private readonly IPrototypeManager _prototypeManager = default!;
     [Dependency] private readonly SharedSolutionContainerSystem _solutionContainerSystem = default!;
+    [Dependency] private readonly SharedDoAfterSystem _doAfterSystem = default!;
 
     /// <summary>
     /// The lowest threshold to be considered for puddle sprite states as well as slipperiness of a puddle.
@@ -106,4 +109,54 @@ public abstract partial class SharedPuddleSystem : EntitySystem
                 args.PushMarkup(Loc.GetString("puddle-component-examine-evaporating-no"));
         }
     }
+
+    #region Spill
+    // These methods are in Shared to make it easier to interact with PuddleSystem in Shared code.
+    // Note that they always fail when run on the client, not creating a puddle and returning false.
+    // Adding proper prediction to this system would require spawning temporary puddle entities on the
+    // client and replacing or merging them with the ones spawned by the server when the client goes to
+    // replicate those, and I am not enough of a wizard to attempt implementing that.
+
+    /// <summary>
+    ///     First splashes reagent on reactive entities near the spilling entity, then spills the rest regularly to a
+    ///     puddle. This is intended for 'destructive' spills, like when entities are destroyed or thrown.
+    /// </summary>
+    /// <remarks>
+    /// On the client, this will always set <paramref name="puddleUid"/> to <see cref="EntityUid.Invalid"> and return false.
+    /// </remarks>
+    public abstract bool TrySplashSpillAt(EntityUid uid,
+        EntityCoordinates coordinates,
+        Solution solution,
+        out EntityUid puddleUid,
+        bool sound = true,
+        EntityUid? user = null);
+
+    /// <summary>
+    ///     Spills solution at the specified coordinates.
+    /// Will add to an existing puddle if present or create a new one if not.
+    /// </summary>
+    /// <remarks>
+    /// On the client, this will always set <paramref name="puddleUid"/> to <see cref="EntityUid.Invalid"> and return false.
+    /// </remarks>
+    public abstract bool TrySpillAt(EntityCoordinates coordinates, Solution solution, out EntityUid puddleUid, bool sound = true);
+
+    /// <summary>
+    /// <see cref="TrySpillAt(EntityCoordinates, Solution, out EntityUid, bool)"/>
+    /// </summary>
+    /// <remarks>
+    /// On the client, this will always set <paramref name="puddleUid"/> to <see cref="EntityUid.Invalid"> and return false.
+    /// </remarks>
+    public abstract bool TrySpillAt(EntityUid uid, Solution solution, out EntityUid puddleUid, bool sound = true,
+        TransformComponent? transformComponent = null);
+
+    /// <summary>
+    /// <see cref="TrySpillAt(EntityCoordinates, Solution, out EntityUid, bool)"/>
+    /// </summary>
+    /// <remarks>
+    /// On the client, this will always set <paramref name="puddleUid"/> to <see cref="EntityUid.Invalid"> and return false.
+    /// </remarks>
+    public abstract bool TrySpillAt(TileRef tileRef, Solution solution, out EntityUid puddleUid, bool sound = true,
+        bool tileReact = true);
+
+    #endregion Spill
 }