Merge pull request #80 from active-logic/Misc

Sim time and logging err fix

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/Constants-and-logging.md

@@ -43,6 +43,23 @@ loop.cont()
 impending.done() // will not compile since 'impending' never succeeds
 ```
 
+## Using `undef()`
+
+If you defer implementing a status function, use `undef`:
+
+```cs
+status Defend() => undef();
+```
+
+Release and optimized builds do not support `undef`; this ensures your product is feature-complete before shipping.
+
+By default `undef` returns the failing status; this may be customized:
+
+```cs
+status Defend() => undef(cont);    // with Active.Raw
+status Defend() => undef(cont());  // with Active.Status
+```
+
 ## Expression wrappers
 
 Via `Active.Raw` or `Active.Status`, use a wrapper to include any expression within a status expression, then return an arbitrary status constant; here is an example:

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.

README.md

@@ -19,25 +19,23 @@ Active Logic seamlessly integrates with C#:
 ```cs
 class Duelist : UTask{
 
-    float health = 100;
-
-    Transform threat => null;
+    float     health = 100;
+    Transform threat;
 
     // BT selectors and sequences via || and &&
-    override public status Step() => Attack() || Defend() || Retreat();
+    override public status Step()
+        => Attack()
+        || Defend()
+        || Retreat();
 
     // Conditionals without 'conditional nodes'
-    status Attack() => threat && health > 25
-        ? Engage(threat) && Cooldown(1.0f)?[ Strike(threat) ]
-        : fail(log && $"No threat, or low hp ({health})");
-
-    // Special statuses (pending, impending, action, ...) are useful
-    // when you know a task will never fail, never succeed or similar.
-    // (optional but type safe!)
-    pending   Defend()                  => + undef();
-    status    Engage(Transform threat)  =>   undef();
-    impending Retreat()                 => - undef();
-    action    Strike(Transform threat)  =>   @void();
+    status Attack() => (threat && health > 25) ?
+        Engage(threat) && Cooldown(1.0f)?[ Strike(threat) ]
+      : fail(log && $"No threat, or low hp ({health})");
+
+    status Defend() => ...;
+
+    // ...
 
 }
 ```

Src/Decorators/Cooldown.cs

@@ -30,11 +30,9 @@ public Gate? this[float s]
 
 }
 
-#if !AL_BEST_PERF
 partial class Task{
 	public Conditional.Gate? Cooldown(float duration, [Tag] int key = -1)
 	=> store.Decorator<Cooldown>(key, Active.Core.Cooldown.id)[duration];
 }
-#endif
 
 }

Src/Decorators/Delay.cs

@@ -37,12 +37,10 @@ public Gate? this[float duration]{ get{
 
 }
 
-#if !AL_BEST_PERF
 partial class Task{
 	public Waiter.Gate? After(float delay, [Tag] int key = -1)
 	=> store.Decorator<Delay>(key, Active.Core.Delay.id)[delay];
 }
-#endif
 
 }  // Active.Core
 

Src/Decorators/Drive.cs

@@ -67,7 +67,6 @@ public StatusRef this[status s]{ get{
 
 }
 
-#if !AL_BEST_PERF
 partial class Task{
 	public Self.Gate? While(status @in, [Tag] int key = -1)
 	=> store.Decorator<Self>(key, Self.id)[@in, crit: false];
@@ -78,6 +77,5 @@ partial class Task{
     public Self.Gate? Tie(bool @in, [Tag] int key = -1)
     => store.Decorator<Self>(key, Self.id)[@in, crit: true];
 }
-#endif
 
 }

Src/Decorators/FrameDelay.cs

@@ -37,13 +37,11 @@ public Gate? this[int duration]{ get{
 
 }
 
-#if !AL_BEST_PERF
 partial class Task{
 	public Waiter.Gate? AfterFrames(int frames, [Tag] int key = -1)
 	=> store.Decorator<FrameDelay>(key,
                                    Active.Core.FrameDelay.id)[frames];
 }
-#endif
 
 }  // Active.Core
 

Src/Decorators/InOut.cs

@@ -23,11 +23,9 @@ public class InOut : Conditional{
 
 }
 
-#if !AL_BEST_PERF
 partial class Task{
     public Conditional.Gate? InOut(bool @in, bool @out, [Tag] int key = -1)
     => store.Decorator<InOut>(key, Active.Core.InOut.id)[@in, @out];
 }
-#endif
 
 }

Src/Decorators/Init.cs

@@ -56,11 +56,9 @@ public readonly struct Gate{
 
 }
 
-#if !AL_BEST_PERF
 partial class Task{
     public Init With([Tag] int key = -1)
     => store.Decorator<Init>(key, Active.Core.Init.id).pass;
 }
-#endif
 
 }  // end-Active.Core