Clean APIs and document

Author: eelstork

Documentation/Overview.md

@@ -0,0 +1,178 @@
+# A User Guide *Beyond GOAP* [DRAFT]
+
+## What is GOAP?
+
+GOAP (Goal oriented action planning) refers to a family of planning AIs inspired by [Jeff Orkin's GOAP](http://alumni.media.mit.edu/~jorkin/gdc2006_orkin_jeff_fear.pdf).
+
+In GOAP, an agent are assigned a goal (escape a room, take cover, knock a target down, heal, ...) and utilize actions whose *preconditions*, *cost* and *effects* are known to fulfill the goal condition.
+
+A search algorithm (such as A*) resolves the action sequence which constitutes a path to the goal.
+
+A *heuristic*, estimating the extra cost to reach the goal, is often provided.
+
+## While you GOAP
+
+While reading, also check the [Sentinel demo](https://youtu.be/mbLNALyt5So) and associate [project files](https://github.com/active-logic/xgoap-demos).
+
+## Planning Agent/Model
+
+This library provides a solver and APIs to help you implement your own planning AIs.
+
+The critical part of your AI is the model, aka 'agent'; the model represents an AI's knowledge of the environment they operate in, including itself.
+
+- Your model is a class implementing `Agent` or `Mapped` (to express planning actions, aka 'options').
+
+The solver needs to generate and organize copies of the model object, therefore cloning, hashing and comparing for equality are common operations applied many times over.
+
+- Minimally, tag your model [*Serializable*](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/serialization/) or (much better) implement `Clonable`.
+- Override `Equals()` and `GetHashCode()` (sloppy hashcodes decrease performance)
+
+### Planning actions
+
+Specify planning actions (options) via `Agent` and/or `Mapped` (or both!)
+
+Usually, `Agent` suffices - easier to implement, and (currently) faster.
+
+```cs
+Option[] Agent.Options() => new Option[]{ JumpForward, Shoot, ... };
+
+public Cost JumpForward{ ... }
+```
+
+Use `Mapped` when you need to parameterize planning actions:
+
+```cs
+(Option, Action)[] Mapped.Options(){
+    var n   = inventory.Length;
+    var opt = new (Option, Action)[n];
+    for(int i = 0; i < n; i++){
+        var j = i;  // don't capture the iterator!
+        opt[i] = ( () => Use(j),
+                   () => client.Use(inventory[j]) );
+    }
+    return opt;
+}
+```
+
+In the above example:
+- An inventory is considered
+- An option is generated for each item in the inventory
+- Options are mapped to game action via `(Option, System.Action)` tuples
+
+NOTE: *In the above we are careful* not *to use the iterator `i` inside the lambda, otherwise all invocations of the lambda function would end up using a value of `n-1`*.
+
+`Mapped` options are flexible and type safe, giving you complete control over how a planning action maps to a game action; `Agent` is much faster to implement.
+
+### The Clonable interface
+
+Implement `Allocate()` to create a model object instance. The purpose of this function is to perform all memory allocations upfront, not determine state.
+
+Implement `Clone(T storage)` to copy model state. This function **must** assign all fields (to avoid leaking dirty state).
+
+```cs
+class MyModel : Clonable<MyModel>{
+
+    T byRef;               // Assuming T : Clonable<T>; not required but handy
+    int byValue;
+
+    MyModel(){
+        byRef = new T();  // allocate everything
+        // byValue = 5;   // let's not do extra work
+    }
+
+    public MyModel Allocate() => new MyModel();
+
+    public MyModel Clone(MyModel storage){
+        this.byRef.Clone(storage.byRef);    // Don't shallow copy
+        byValue = 5;                        // Set all fields
+    }
+
+}
+```
+
+Designed for instance reuse, this API enables optimizations, such as pooling.
+
+Note: *The `Allocate` API is required because newing a `T : class, new()` object resolves to an `AlloceSlow` variant (the name says it all)*
+
+### Test your model
+
+Beyond GOAP cleanly separates your planning model from the game engine and/or actor (the object implementing actual game actions). This allows putting your model under test even before integrating an actual game actor.
+
+## Integration
+
+With a working model handy, you want to plug this into your game/simulation. The library provides a simple integration, mainly intended for (but not tied to) Unity3D.
+
+The integration implements a two step *(planning -> action)* cycle:
+
+1 - A plan is generated
+2 - The *first* action in the plan is applied
+(Rinse and repeat until the goal is attained)
+
+We might plan once and step through all steps; however since world state changes dynamically, re-planning often keeps our agents on track.
+
+NOTE: *In the future the integration will give you more control over how often replanning is applied*
+
+To use the integration, subclass `GameAI`, as explained below.
+
+### Subclassing `GameAI`
+
+A `Goal` consists in a function, which verifies whether an instance of the model `T` satisfies the goal, and a heuristic function 'h', which measures the distance/cost between a model state designated as 'current' and the goal.
+Sometimes you don't have a heuristic, or can't come up with anything just yet. That's okay (still, a heuristic dramatically speeds up planning).
+
+[`GameAI`](../Runtime/GameAI.cs) specifies a handful of functions that you need to implement in order to get your game actors going:
+
+- Supply a goal for the agent to strive towards.
+- Link your planning model
+- (optionally) implement an `Idle()` mode.
+- Implement `IsActing()` to indicate when the actor are available for planning.
+
+The `Goal()` method (assume `x` of type `T`):
+
+```cs
+override public Goal<T> Goal() => (
+    x => cond,     // such as `x.someValue == true`
+    x => heuristic // such as `x.DistTo(x.target)` or null if unavailable
+);
+```
+
+Your implementation of `T Model()` should a model instance which represents the current state of the agent and their environment, for example:
+
+```cs
+// Model definition
+class MyModel{ float x, float z; }
+
+// inside MyAI : GameAI<MyModel>
+override public MyModel Model(){
+    return new MyModel(transform.position.x, transform.position.z);
+}
+```
+
+While `IsActing()` returns false, the planner will be running and evaluating the next action; how you implement this (whether event based, or testing the state of the game actor...) is entirely up to you; likewise the `Idle()` function.
+
+```cs
+override public bool IsActing() => SomeCondition() && SomeOther();
+```
+
+### Providing counterparts for planning options
+
+Since planning actions aren't 'real' game actions, your `GameAI` implementation must supply these.
+
+- With `Agent`, all planning actions must have same-name, no-arg counterparts in `GameAI`.
+- With `Mapped`, one approach consists in defining an interface, which specifies methods to be implemented both as planning actions, and as game actions. The [Baker](`../Tests/Models/Baker.cs`) example illustrates this approach.
+
+## Running your AI (Unity 3D only)
+
+Once you have implemented your `GameAI` subclass, it can be added to any game object (In Unity, `GameAI` derives from `Monobehaviour`).
+
+Additionally, tweaks are available...
+
+- *verbose* - gives you basic information (in the console) about what actions are applied to the game AI
+
+Then, under 'solver params':
+
+- *Frame budget* - max number of planning actions per game frame.
+- *Max nodes* - max number of states that should exist within the planner at any given time.
+- *Max iter* - the max number of iterations allowed to find a solution; after which the planner just bails out.
+- *Tolerance* - represents how closely the heuristic should be followed. For example if you don't care about a $10 difference (if 'cost' represents money) or a 0.5 seconds delta (if 'time cost' is the heuristic), set this to $10 or 0.5 seconds.
+Leaving this number to zero forces a full ordering, which significantly slows down the planner; but if you set this too high, you weaken the heuristic (which is also slower!) so there's no point in cranking it up.
+- *Safe* - If your actions are cleanly implemented, a failing action won't mutate model state; then, uncheck this and get a small performance bonus. If unsure, leave unchecked.

Documentation/Overview.md.meta

@@ -0,0 +1,9 @@
+# Semantic sugar in API design
+
+## Problem being solved
+
+In XGOAP, there was both 'planning actions' and 'planning functions'. The intention simply is to support both no-arg and parametric planning moves.
+
+In practice, however, the solver does not deal with parametric functions, it only deals with parameterized invocations. In other words, choosing argument sets is still the client's responsibility.
+
+As a result, how 'planning functions' are implemented is via explicit mappings between the planning action and the actual move performed by the agent, which created a need for naming this mapping.

Documentation/Semantic sugar.md

@@ -43,46 +43,41 @@ A woodcutter has the *GetAxe*, *ChopLog* and *CollectBranches* actions. Here is
 ```cs
 using Activ.GOAP;
 
-[Serializable]  // Helps cloning model state (or implement `Clonable`)
-public class WoodChopper : Agent{
+public class WoodChopper : Agent, Clonable<WoodChopper>{
 
     public bool hasAxe, hasFirewood;
+    Option[] opt;  // Caching reduces array alloc overheads
 
-    // In production, cache your action list(s) to avoid GC overheads
-    public Func<Cost>[] Actions() => new Func<Cost>[]{
-        ChopLog, GetAxe, CollectBranches
-    };
+    public Option[] Options()
+    => opt = opt ?? new Option[]{ ChopLog, GetAxe, CollectBranches };
 
     public Cost GetAxe(){
         if(hasAxe) return false;
         hasAxe = true;
         return 2;
     }
 
-    public bool ChopLog(){
-        if(!hasAxe) return false;
-        hasFirewood = true;
-        return 4;
-    }
+    public Cost ChopLog() => hasAxe ? (Cost)(hasFirewood = true, 4f) : (Cost)false;
+
+    public Cost CollectBranches() => (hasFirewood = true, 8);
+
+    // Clonable<WoodChopper>
 
-    // Expression-bodied shorthands are supported
-    public bool CollectBranches() => (hasFirewood = true, 8);
+    public WoodChopper Allocate() => new WoodChopper();
 
-    // Needed to avoid reentering previously visited states while searching
-    override public bool Equals(object other){
-        if(other == null) return false;
-        if(other is WoodChopper that){
-            return this.hasAxe == that.hasAxe
-                && this.hasFirewood == that.hasFirewood;
-        } else return false;
+    public WoodChopper Clone(WoodChopper x){
+        x.hasAxe      = hasAxe;
+        x.hasFirewood = hasFirewood;
+        return x;
     }
 
-    // Helps quickly finding duplicate states
-    override public int GetHashCode()
-    => (hasAxe ? 1 : 0) + (hasFirewood ? 2 : 0);
+    // Override for correctness (don't compare refs) and faster hashes
 
-    override public string ToString()
-    => $"WoodChopper[axe:{hasAxe} f.wood:{hasFirewood} ]";
+    override public bool Equals(object other) => other is WoodChopper that
+        && hasAxe == that.hasAxe && hasFirewood == that.hasFirewood;
+
+    override public int GetHashCode() => (hasAxe ? 1 : 0)
+                                       + (hasFirewood ? 2 : 0);
 
 }
 ```
@@ -92,15 +87,15 @@ Run the model and get the next planned action:
 ```cs
 var chopper = new WoodChopper();
 var solver  = new Solver<WoodChopper>();
-var next    = solver.Next(chopper, new Goal<WoodChopper>(x => x.hasFirewood));
+var next    = solver.Next(chopper, goal: (x => x.hasFirewood, null));
 ```
 
 Parametric actions are supported; they are concise and type safe. Check the [Baker](Tests/Models/Baker.cs) example.
 
-The goal argument (here, `x => x.hasFirewood`) returns a `bool` to indicate whether the goal has been reached.
-
 Quick and simple Unity integration via [GameAI.cs](Runtime/GameAI.cs) - for details, [read here](Documentation/BakerUnity.md).
 
+Ready to GOAP?, [follow the guide](Documentation/Overview.md)
+
 ## Getting involved
 
 If you'd like to get involved, consider opening (or fixing) an issue.

Documentation/Semantic sugar.md.meta

@@ -2,12 +2,14 @@
 
 namespace Activ.GOAP{
 
+public delegate Cost Option();
+
 public interface Agent{
-    Func<Cost>[] Actions();
+    Option[] Options();
 }
 
-public interface Parametric{
-    Complex[] Functions();
+public interface Mapped{
+    (Option option, Action action)[] Options();
 }
 
 public interface Clonable<T>{

README.md

@@ -1,13 +1,12 @@
 using System;
 using ArgEx = System.ArgumentException;
+using static Activ.GOAP.Strings;
 
 namespace Activ.GOAP{
 // Note: in general cost values not strictly positive are unsafe;
 // however this isn't checked here since it depends on the solver
 public readonly struct Cost{
 
-    const string CostRangeErr = "Cost must be strictly positive";
-
     public readonly bool done;
     public readonly float cost;
 
@@ -19,8 +18,7 @@ public static implicit operator Cost(bool flag)
     public static implicit operator Cost(float cost)
     => new Cost(true, cost);
 
-    public static implicit operator Cost(ValueTuple<object, float> t){
-        return new Cost(true, t.Item2);
-    }
+    public static implicit operator Cost((object, float cost) t)
+    => new Cost(true, t.cost);
 
 }}

Runtime/Agent.cs

@@ -4,13 +4,13 @@ namespace Activ.GOAP{
 public class Node<T> : Base{
 
     public readonly Node<T>    prev;
-    public readonly Func<Cost> source;
+    public readonly Option source;
     public readonly T          state;
     public float value;
     public float cost{ get; private set; }
     readonly object  effect;
 
-    public Node(Func<Cost> planningAction, T result,
+    public Node(Option planningAction, T result,
                 Node<T> prev = null, float   cost = 0f){
         this.source = Assert(planningAction, "Action");;
         this.state  = Assert(result, "Result");