Merge pull request #113 from chickensoft-games/fix/qol

fix: allow configuring whether `OnEnter` callbacks should run when restoring a state

Author: Joanna May

Chickensoft.LogicBlocks.Tests/test/fixtures/SerializableLogicBlockWithOnEnter.cs

@@ -0,0 +1,59 @@
+namespace Chickensoft.LogicBlocks.Tests.Fixtures;
+
+using Chickensoft.Introspection;
+
+[Meta, Id("serializable_logic_block_with_on_enter")]
+[LogicBlock(typeof(State), Diagram = false)]
+public partial class SerializableLogicBlockWithOnEnter :
+LogicBlock<SerializableLogicBlockWithOnEnter.State> {
+  public override Transition GetInitialState() => To<StateA>();
+
+  public SerializableLogicBlockWithOnEnter() {
+    Set(new Data());
+  }
+
+  public record Data {
+    public bool AutomaticallyLeaveAOnEnter { get; set; }
+  }
+
+  public static class Input {
+    public readonly record struct GoToA;
+    public readonly record struct GoToB;
+  }
+
+  public static class Output {
+    public readonly record struct StateEntered;
+    public readonly record struct StateAEntered;
+    public readonly record struct StateBEntered;
+  }
+
+  [Meta]
+  public abstract partial record State : StateLogic<State>,
+  IGet<Input.GoToA>, IGet<Input.GoToB> {
+    public State() {
+      this.OnEnter(() => Output(new Output.StateEntered()));
+    }
+
+    public Transition On(in Input.GoToA input) => To<StateA>();
+    public Transition On(in Input.GoToB input) => To<StateB>();
+  }
+
+  [Meta, Id("serializable_logic_block_with_on_enter_state_a")]
+  public partial record StateA : State {
+    public StateA() {
+      this.OnEnter(() => {
+        Output(new Output.StateAEntered());
+        if (Get<Data>().AutomaticallyLeaveAOnEnter) {
+          Input(new Input.GoToB());
+        }
+      });
+    }
+  }
+
+  [Meta, Id("serializable_logic_block_with_on_enter_state_b")]
+  public partial record StateB : State {
+    public StateB() {
+      this.OnEnter(() => Output(new Output.StateBEntered()));
+    }
+  }
+}

Chickensoft.LogicBlocks.Tests/test/src/InternalStateTest.cs

@@ -34,7 +34,7 @@ public void InteractsWithUnderlyingContext() {
 
   [Fact]
   public void EqualsAnythingElse() {
-    var state = new InternalState();
+    var state = new InternalState(new FakeLogicBlock.ContextAdapter());
     state.Equals(new object()).ShouldBeTrue();
   }
 }

Chickensoft.LogicBlocks.Tests/test/src/LogicBlockTest.cs

@@ -192,11 +192,9 @@ public void DoesNothingOnUnhandledInput() {
   [Fact]
   public void CallsEnterAndExitOnStatesInProperOrder() {
     var logic = new TestMachine();
-    using var listener = Listen(logic);
-    var context = new TestMachine.DefaultContext(logic);
 
+    using var listener = Listen(logic);
     var outputs = new List<object>();
-
     void onOutput(object output) => outputs.Add(output);
 
     listener.OnOutput += onOutput;
@@ -521,6 +519,13 @@ public void RestoreStateThrowsIfStateAlreadyExists() {
   public class LogicBlockEquality {
     private sealed record TestValue(int Value);
 
+    [Fact]
+    public void EqualToItself() {
+      var logic = new FakeLogicBlock();
+
+      logic.Equals(logic).ShouldBeTrue();
+    }
+
     [Fact]
     public void NotEqualToNonLogicBlock() {
       var logic = new FakeLogicBlock();
@@ -629,5 +634,66 @@ public void RestoreFromCopiesStateAndBlackboard() {
       other.Value.ShouldBeOfType<FakeLogicBlock.State.StateB>();
       other.Get<string>().ShouldBe(data);
     }
+
+    [Fact]
+    public void RestoreFromCallsOnEnter() {
+      var logic = new SerializableLogicBlockWithOnEnter();
+      logic.Input(new SerializableLogicBlockWithOnEnter.Input.GoToA());
+
+      var other = new SerializableLogicBlockWithOnEnter();
+
+      using var listener = Listen(other);
+      var outputs = new List<object>();
+      void onOutput(object output) => outputs.Add(output);
+
+      listener.OnOutput += onOutput;
+
+      other.RestoreFrom(logic, shouldCallOnEnter: true);
+
+      other
+        .Get<SerializableLogicBlockWithOnEnter.Data>()
+        .AutomaticallyLeaveAOnEnter = true;
+
+      other.Start();
+
+      outputs.ShouldBe(new object[] {
+        new SerializableLogicBlockWithOnEnter.Output.StateEntered(),
+        new SerializableLogicBlockWithOnEnter.Output.StateAEntered(),
+        new SerializableLogicBlockWithOnEnter.Output.StateBEntered()
+      });
+
+      other
+        .Value
+        .ShouldBeOfType<SerializableLogicBlockWithOnEnter.StateB>();
+    }
+
+    [Fact]
+    public void RestoreFromDoesNotCallOnEnter() {
+      var logic = new SerializableLogicBlockWithOnEnter();
+      logic.Input(new SerializableLogicBlockWithOnEnter.Input.GoToA());
+
+      var other = new SerializableLogicBlockWithOnEnter();
+
+      using var listener = Listen(other);
+      var outputs = new List<object>();
+      void onOutput(object output) => outputs.Add(output);
+
+      listener.OnOutput += onOutput;
+
+      other.RestoreFrom(logic, shouldCallOnEnter: false);
+
+      other
+        .Get<SerializableLogicBlockWithOnEnter.Data>()
+        .AutomaticallyLeaveAOnEnter = true;
+
+      other.Start();
+
+      outputs.ShouldBeEmpty();
+
+      // Should be in StateA, since OnEnter was not called.
+      other
+        .Value
+        .ShouldBeOfType<SerializableLogicBlockWithOnEnter.StateA>();
+    }
   }
 }

Chickensoft.LogicBlocks/src/InternalState.cs

@@ -7,7 +7,7 @@ namespace Chickensoft.LogicBlocks;
 /// Internal state stored in each logic block state. This is used to store
 /// entrance and exit callbacks without tripping up equality checking.
 /// </summary>
-internal readonly struct InternalState {
+internal class InternalState {
   /// <summary>
   /// Callbacks to be invoked when the state is entered.
   /// </summary>

Chickensoft.LogicBlocks/src/LogicBlock.cs

@@ -104,7 +104,9 @@ public interface ILogicBlock<TState> :
   /// Restores the logic block from a deserialized logic block.
   /// </summary>
   /// <param name="logic">Other logic block.</param>
-  void RestoreFrom(ILogicBlock<TState> logic);
+  /// <param name="shouldCallOnEnter">Whether or not to call OnEnter callbacks
+  /// when entering the restored state.</param>
+  void RestoreFrom(ILogicBlock<TState> logic, bool shouldCallOnEnter = true);
 
   /// <summary>
   /// Adds a binding to the logic block. This is used internally by the standard
@@ -180,6 +182,11 @@ public override void RestoreState(object state) {
   private readonly BoxlessQueue _inputs;
   private readonly HashSet<ILogicBlockBinding<TState>> _bindings = new();
 
+  // Sometimes, it is preferable not to call OnEnter callbacks when starting
+  // a logic block, such as when restoring from a saved / serialized logic
+  // block.
+  private bool _shouldCallOnEnter = true;
+
   /// <summary>
   /// <para>Creates a new LogicBlock.</para>
   /// <para>
@@ -395,6 +402,8 @@ internal TState ProcessInputs<TInputType>(
 
     _isProcessing--;
 
+    _shouldCallOnEnter = true;
+
     return _value!;
   }
 
@@ -433,7 +442,11 @@ private void ChangeState(TState? state) {
 
     if (state is not null) {
       state.Attach(Context);
-      state.Enter(previous);
+
+      if (_shouldCallOnEnter) {
+        state.Enter(previous);
+      }
+
       if (stateIsDifferent) {
         AnnounceState(state);
       }
@@ -503,6 +516,8 @@ private TState Flush() {
   /// <param name="obj">Other logic block.</param>
   /// <returns>True if</returns>
   public override bool Equals(object? obj) {
+    if (ReferenceEquals(this, obj)) { return true; }
+
     if (obj is not LogicBlockBase logic) { return false; }
 
     if (GetType() != logic.GetType()) {
@@ -545,9 +560,16 @@ public override bool Equals(object? obj) {
   public override int GetHashCode() => base.GetHashCode();
 
   /// <inheritdoc />
-  public void RestoreFrom(ILogicBlock<TState> logic) {
+  public void RestoreFrom(
+    ILogicBlock<TState> logic, bool shouldCallOnEnter = true
+  ) {
+    _shouldCallOnEnter = shouldCallOnEnter;
+
     if ((logic.ValueAsObject ?? logic.RestoredState) is not TState state) {
-      throw new LogicBlockException($"Cannot restore from logic block {logic}.");
+      throw new LogicBlockException(
+        $"Cannot restore from an uninitialized logic block ({logic}). Please " +
+        "make sure you've called Start() on it first."
+      );
     }
 
     Stop();