Use sim time

Author: eelstork

Doc/QuickStart.md

@@ -5,7 +5,18 @@
 
 Be welcome! Here is a hands-on introduction to Active Logic. Let's get started.
 
-This introduction is engine agnostic; if you are using Unity, read the [Unity Quick Start Guide](QuickStart-Unity.md).
+This introduction is engine agnostic. Unity users may prefer the [Unity Quick Start Guide](QuickStart-Unity.md).
+
+## Setting the time
+
+Before evaluating a behaviour tree, set the time:
+
+```
+// Set at game frame start or before invoking your ticker
+SimTime.time = System.DateTime.Now.TotalMilliseconds/1000f;
+```
+
+Active Logic uses [simulated time](Reference/SimTime.md) to evaluate certain decorators, such as intervals and cooldowns.
 
 ## Status expressions and the update loop
 

Doc/Reference/SimTime.md

@@ -0,0 +1,25 @@
+*Sources: SimTime.cs - Last Updated: 2021.07.18*
+
+# SimTime Reference
+
+In order for time-reliant decorators (cooldown, delay, interval, timeout, wait and perhaps others) to work as expected, the time should be correctly set.
+
+- In a video game, usually you want game time; this (ordinarily) is different from real time.
+- When evaluating a simulation, set the time at the beginning of each iteration.
+- For some applications, real time may be just what you need.
+
+## Setting the time
+
+Depending on the intended use case, there's a couple of approaches to setting the time:
+
+1- If all the agents/tickers in your game use the same time, consider setting `SimTime.time` at the beginning of each iteration (or game/physics frame)
+
+2- In less common cases, different agents may each use their own time. For example, in a turn based game, 'tactical time' (round count) may be used to evaluate some agents while other parts of your game may use real time for animation.
+
+**Sim time is not thread safe** - you may use sim time in a multi-threaded environment, provided all agents use the same time, and all threads complete work within the current iteration.
+
+Note: in *Unity*, time defaults to `UnityEngine.Time.time`; you may change this on a stepper basis (see [Steppers](Unity/Steppers.md))
+
+## Fields & Properties
+
+`time` - get/set the current time.

Src/SimTime.cs

@@ -0,0 +1,7 @@
+// Doc/Reference/SimTime.md
+namespace Active.Core{
+public static class SimTime{
+
+    public static float time;
+
+}}

Src/Stateful/AbstractDecorator.cs

@@ -9,13 +9,7 @@ namespace Active.Core{
 public abstract partial class AbstractDecorator : IDecorator,
                                                   Resettable{
 
-    internal virtual float time{ get{
-      #if UNITY_2018_1_OR_NEWER
-        return UnityEngine.Time.time;
-      #else
-        return System.DateTime.Now.Millisecond/1000f;
-      #endif
-    }}
+    internal float time => SimTime.time;
 
     protected static int ID(int id) => id == 0 ? ++MaxId : id;
 

Tests/Decorators/AbstractDecoratorTest.cs

@@ -6,7 +6,10 @@
 public class AbstractDecoratorTest
              : DecoratorTest<AbstractDecoratorTest.C>{
 
-    [Test] public void Time() => o( x.GetTime() != 0 );
+    [Test] public void Time(){
+        SimTime.time = 10f;
+        o( x.GetTime(), 10f );
+    }
 
     public class C : AbstractDecorator{
         public C(){}

Tests/Decorators/TestCooldown.cs

@@ -92,15 +92,10 @@ [Test] public void Format(){
   #endif
 
 	public class Cooldown : Active.Core.Cooldown{
-		public int time_;
 		public Cooldown() : base(){}
 		public Cooldown(float duration) : base(duration){}
-		override internal float time => time_;
 	}
 
-	int t{
-		set => x.time_ = value;
-		get => x.time_;
-	}
+	int t{ set => SimTime.time = value; }
 
 }

Tests/Decorators/TestInterval.cs

@@ -10,7 +10,7 @@ public class TestInterval : DecoratorTest<TestInterval.Interval> {
 
 	bool _log;
 
-	static float t; // Time.time value for testing
+	static float t{ set => SimTime.time = value; }
 
 	[SetUp] override public void Setup(){
 		t = 0;
@@ -132,7 +132,6 @@ public class Interval : Active.Core.Interval{
 		public Interval() : base(){}
 		public Interval(float period, float offset=0f)
 	    : base(period, offset){}
-		override internal float time => TestInterval.t;
 	}
 
 }

Tests/Decorators/TestTimeout.cs

@@ -5,7 +5,7 @@
 /* Timeout limits the duration of the target task */
 public class TestTimeout : DecoratorTest<TestTimeout.Timeout> {
 
-	static float t;  // Replaces Time.time (see derived class at end)
+	static float t{ set => SimTime.time = value; }
 
 	[SetUp] override public void Setup(){ t = 0; base.Setup(); }
 
@@ -66,10 +66,8 @@ [Test] public void DisarmedOnFail(){
 	}
 
 	public class Timeout : Active.Core.Timeout{
-		public float time_ => TestTimeout.t;
 		public Timeout() : base(){}
 		public Timeout(float duration) : base(duration){}
-		override internal float time => time_;
 	}
 
 }