@woosh/meep-engine 2.43.40 → 2.43.43

package/engine/intelligence/behavior/Behavior.js

@@ -2,6 +2,7 @@ import { BehaviorStatus } from "./BehaviorStatus.js";
 
 /**
  * Base class of behavior tree implementation
+ * @see "The Behavior Tree Starter Kit" by Alex J. Champandard and Philip Dunstan
  * @template CTX
  */
 export class Behavior {
@@ -14,9 +15,9 @@ export class Behavior {
     }
 
     /**
-     * Main update function
+     * Main update function. Every behavior executes some logic, some behaviors are long-running and some are instantaneous
      * @param {number} timeDelta time step in seconds
-     * @returns {BehaviorStatus}
+     * @returns {BehaviorStatus} signals status of the behavior, "success" or "failure" are used to signal completion of the behavior
      */
     tick(timeDelta) {
         throw new Error('Abstract method, needs to be overridden');
@@ -25,7 +26,7 @@ export class Behavior {
     /**
      * Called before behavior gets executed via {@link #tick} for the first time
      * Used to prepare the behavior for execution
-     * @param {*} [context]
+     * @param {CTX} [context]
      */
     initialize(context) {
         this.context = context;

package/engine/intelligence/behavior/BehaviorStatus.d.ts

@@ -0,0 +1,8 @@
+export enum BehaviorStatus {
+    Initial = 0,
+    Running = 1,
+    Succeeded = 2,
+    Failed = 3,
+    Suspended = 4,
+    Invalid = 5
+}

package/engine/intelligence/behavior/SelectorBehavior.js

@@ -46,7 +46,9 @@ export class SelectorBehavior extends CompositeBehavior {
         }
     }
 
-    initialize() {
+    initialize(context) {
+        super.initialize(context);
+     
         this.__currentBehaviourIndex = 0;
         this.__currentBehaviour = this.__children[0];
 

package/engine/intelligence/behavior/behavior_to_dot.js

@@ -0,0 +1,251 @@
+import LineBuilder from "../../../core/codegen/LineBuilder.js";
+import { Behavior } from "./Behavior.js";
+
+/**
+ *
+ * @param {Behavior} behavior
+ * @return {string}
+ */
+function compute_behavior_name(behavior) {
+
+    // try to get name from the constructor field
+    const typeName = behavior.constructor.typeName;
+    if (typeof typeName === "string") {
+        return typeName;
+    }
+
+    const constructor_name = behavior.constructor.name;
+    if (typeof constructor_name === "string") {
+        return constructor_name;
+    }
+
+    return '$Behavior';
+}
+
+
+/**
+ *
+ * @param {Behavior|SequenceBehavior|ParallelBehavior} behavior
+ * @return {Object}
+ */
+function behavior_node_attributes(behavior) {
+    const result = {};
+
+    if (behavior.isCompositeBehavior === true) {
+
+        result.fillcolor = "orange";
+
+        if (behavior.isSequenceBehavior === true) {
+            result.fillcolor = "paleturquoise";
+        } else if (behavior.isParallelBehavior === true) {
+            result.fillcolor = "plum";
+        }
+    } else {
+
+    }
+
+    return result;
+}
+
+/**
+ *
+ * @param {Object} attributes
+ * @return {string}
+ */
+function attributes_to_dot(attributes) {
+    const key_names = Object.keys(attributes);
+
+    return key_names.map(key => {
+
+        return `${key}=${attributes[key]}`;
+
+    }).join(', ');
+}
+
+/**
+ *
+ * @param {string} prop
+ * @param {Object} object
+ */
+function should_property_be_included(prop, object) {
+    if (prop.startsWith('_')) {
+        // private field
+        return false;
+    }
+
+    const value = object[prop];
+
+    if (object.constructor.prototype[prop] === value) {
+        return false;
+    }
+
+    const typeof_value = typeof value;
+
+    if (value === null || typeof_value === "undefined" || typeof_value === "symbol") {
+        return false;
+    }
+
+    if (typeof_value === "object" && String(value) === '[object Object]') {
+        return false;
+    }
+
+    return true;
+}
+
+function property_to_string(value, max_length = 200) {
+
+
+    let string_value;
+
+    if (typeof value !== "string") {
+        string_value = String(value);
+    } else {
+        string_value = `\"${value}\"`;
+    }
+
+    const sanitized = string_value.replace(/\n/, "\n");
+
+    if (sanitized.length > max_length) {
+        return '[...]';
+    }
+
+    return sanitized;
+}
+
+/**
+ *
+ * @param {Behavior} behavior
+ * @param {number} max_props
+ */
+function build_node_properties_string(behavior, max_props = 10) {
+
+    const properties = {};
+
+    let qualified_property_count = 0;
+
+    for (const behaviorKey in behavior) {
+
+        if (should_property_be_included(behaviorKey, behavior)) {
+            if (qualified_property_count < max_props) {
+                properties[behaviorKey] = property_to_string(behavior[behaviorKey]);
+            }
+
+            qualified_property_count++;
+        }
+
+    }
+
+    // stringify and concatenate
+    return Object.keys(properties).map(key => `${key} = ${properties[key]}`).join('<BR/>');
+
+}
+
+/**
+ *
+ * @param {Behavior} behavior
+ * @return {boolean}
+ */
+function should_behavior_have_properties_string(behavior) {
+    if (behavior.isCompositeBehavior === true) {
+        return false;
+    }
+
+    return true;
+}
+
+function build_node_label(behavior) {
+    const node_name = compute_behavior_name(behavior);
+
+    const label_pieces = [];
+
+    label_pieces.push(`<B>${node_name}</B>`);
+
+    if (should_behavior_have_properties_string(behavior)) {
+        const properties = build_node_properties_string(behavior);
+
+        if (properties.trim().length > 0) {
+
+            label_pieces.push(properties);
+
+        }
+    }
+
+    return `<{ {${label_pieces.join('<BR/>')} } }>`;
+}
+
+/**
+ *
+ * @param {LineBuilder} out
+ * @param {Behavior|CompositeBehavior} behavior
+ * @param {{id_counter:number, node_ids:Map<Behavior,string>}} context
+ * @returns {string}
+ */
+function parse_behavior(out, behavior, context) {
+    const id = context.id_counter++;
+    const node_id = `Node_${id}`;
+
+    context.node_ids.set(behavior, node_id);
+
+    const attributes = {
+        label: build_node_label(behavior),
+        style: "\"rounded,filled\""
+    };
+
+    Object.assign(attributes, behavior_node_attributes(behavior));
+
+    out.add(`${node_id} [${attributes_to_dot(attributes)}]`);
+
+    if (behavior.isCompositeBehavior === true) {
+        // is a composite behavior, which means it includes other behaviors
+
+        const children = behavior.getChildren();
+
+        const child_count = children.length;
+
+        for (let i = 0; i < child_count; i++) {
+            const child = children[i];
+
+            const child_id = parse_behavior(out, child, context);
+
+            // create edge
+            out.add(`${node_id} -> ${child_id} [label="№${i + 1}"];`);
+        }
+
+    }
+
+    return node_id;
+}
+
+/**
+ * Produces a diagram of behavior tree in DOT format, useful for debugging and exploration of complex trees
+ *
+ * @see https://en.wikipedia.org/wiki/DOT_(graph_description_language)
+ * @param {Behavior} behavior
+ * @returns {string}
+ */
+export function behavior_to_dot(behavior) {
+    const out = new LineBuilder();
+
+    const context = {
+        id_counter: 0,
+        node_ids: new Map()
+    };
+
+    const font = {
+        name: "helvetica",
+        size: 10
+    };
+
+    out.add("digraph BehaviorTree {");
+    out.indent();
+    out.add("graph [style=invis, rankdir=\"TB\" ordering=out, splines=spline]");
+    out.add(`node [shape=record, fontname=\"${font.name}\", fontsize=${font.size}, margin=\"0.2,0.03\", fillcolor=ivory]`);
+    out.add(`edge [labelfontname=\"${font.name}\", labelfontsize=${font.size}, fontname=\"${font.name}\", fontsize=${font.size}, fontcolor=grey]`);
+
+    parse_behavior(out, behavior, context);
+
+    out.dedent();
+    out.add("}");
+
+    return out.build();
+}

package/engine/intelligence/behavior/behavior_to_dot.prototype.js

@@ -0,0 +1,55 @@
+import { SequenceBehavior } from "./composite/SequenceBehavior.js";
+import { SucceedingBehavior } from "./primitive/SucceedingBehavior.js";
+import { Behavior } from "./Behavior.js";
+import { ParallelBehavior } from "./composite/ParallelBehavior.js";
+import { behavior_to_dot } from "./behavior_to_dot.js";
+import { DelayBehavior } from "./util/DelayBehavior.js";
+
+
+class CenterCameraOnObject extends Behavior{
+    object = "whiteboard"
+}
+
+class UserControlsDisable extends  Behavior{
+
+}
+
+class PlayVideoInPopup extends  Behavior{
+    url = "url/how_to_use_whiteboard.mp4"
+}
+
+class DrawCurvesOnWhiteBoard extends Behavior{
+    curve = "hello"
+
+}
+
+class UserControlsEnable extends Behavior{
+
+}
+
+const complex = SequenceBehavior.from([
+    new SucceedingBehavior(),
+    SequenceBehavior.from([
+        new Behavior()
+    ]),
+    ParallelBehavior.from([
+        new SucceedingBehavior(),
+        DelayBehavior.from(17)
+    ])
+]);
+
+const tutorial = SequenceBehavior.from([ // will execute all members one after another
+
+    ParallelBehavior.from([ // will execute all members at the same time, completes when last member completes
+
+        new CenterCameraOnObject( ), // center camera on whiteboard
+        new UserControlsDisable(),
+        new PlayVideoInPopup() // plays a video in a popup, behavior finishes when video does
+
+    ]),
+    new DrawCurvesOnWhiteBoard(),
+    new UserControlsEnable()
+
+])
+
+console.log(behavior_to_dot(tutorial));

package/engine/intelligence/behavior/composite/CompositeBehavior.js

@@ -54,3 +54,9 @@ export class CompositeBehavior extends Behavior {
         this.__children = [];
     }
 }
+
+/**
+ *
+ * @type {boolean}
+ */
+CompositeBehavior.prototype.isCompositeBehavior = true;

package/engine/intelligence/behavior/composite/ParallelBehavior.js

@@ -226,5 +226,15 @@ export class ParallelBehavior extends CompositeBehavior {
     }
 }
 
+/**
+ * @readonly
+ * @type {boolean}
+ */
+ParallelBehavior.prototype.isParallelBehavior = true;
+
+/**
+ * @readonly
+ * @type {string}
+ */
 ParallelBehavior.typeName = "ParallelBehavior";
 

package/engine/intelligence/behavior/composite/SequenceBehavior.js

@@ -1,9 +1,6 @@
 import { Behavior } from "../Behavior.js";
 import { CompositeBehavior } from "./CompositeBehavior.js";
 import { BehaviorStatus } from "../BehaviorStatus.js";
-import {
-    ObjectBasedClassSerializationAdapter
-} from "../../../ecs/storage/binary/object/ObjectBasedClassSerializationAdapter.js";
 import { assert } from "../../../../core/assert.js";
 
 export class SequenceBehavior extends CompositeBehavior {
@@ -115,52 +112,11 @@ export class SequenceBehavior extends CompositeBehavior {
     }
 }
 
-SequenceBehavior.typeName = "SequenceBehavior";
-
-export class SequenceBehaviorSerializationAdapter extends ObjectBasedClassSerializationAdapter {
-    constructor() {
-        super();
-
-        this.klass = SequenceBehavior;
-        this.version = 0;
-    }
-
-    /**
-     *
-     * @param {BinaryBuffer} buffer
-     * @param {SequenceBehavior} value
-     */
-    serialize(buffer, value) {
-        const children = value.getChildren();
-
-        const n = children.length;
-        buffer.writeUintVar(n);
-
-        for (let i = 0; i < n; i++) {
-            const behavior = children[i];
+/**
+ * @readonly
+ * @type {boolean}
+ */
+SequenceBehavior.prototype.isSequenceBehavior = true;
 
-            this.objectAdapter.serialize(buffer, behavior);
-        }
-    }
-
-    /**
-     *
-     * @param {BinaryBuffer} buffer
-     * @param {SequenceBehavior} value
-     */
-    deserialize(buffer, value) {
-        const n = buffer.readUintVar();
-
-        value.clearChildren();
-
-        for (let i = 0; i < n; i++) {
-            /**
-             *
-             * @type {Behavior}
-             */
-            const behavior = this.objectAdapter.deserialize(buffer);
+SequenceBehavior.typeName = "SequenceBehavior";
 
-            value.addChild(behavior);
-        }
-    }
-}

package/engine/intelligence/behavior/composite/SequenceBehaviorSerializationAdapter.js

@@ -0,0 +1,52 @@
+import {
+    ObjectBasedClassSerializationAdapter
+} from "../../../ecs/storage/binary/object/ObjectBasedClassSerializationAdapter.js";
+import { SequenceBehavior } from "./SequenceBehavior.js";
+
+export class SequenceBehaviorSerializationAdapter extends ObjectBasedClassSerializationAdapter {
+    constructor() {
+        super();
+
+        this.klass = SequenceBehavior;
+        this.version = 0;
+    }
+
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {SequenceBehavior} value
+     */
+    serialize(buffer, value) {
+        const children = value.getChildren();
+
+        const n = children.length;
+        buffer.writeUintVar(n);
+
+        for (let i = 0; i < n; i++) {
+            const behavior = children[i];
+
+            this.objectAdapter.serialize(buffer, behavior);
+        }
+    }
+
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {SequenceBehavior} value
+     */
+    deserialize(buffer, value) {
+        const n = buffer.readUintVar();
+
+        value.clearChildren();
+
+        for (let i = 0; i < n; i++) {
+            /**
+             *
+             * @type {Behavior}
+             */
+            const behavior = this.objectAdapter.deserialize(buffer);
+
+            value.addChild(behavior);
+        }
+    }
+}

package/engine/intelligence/behavior/ecs/BehaviorComponent.js

@@ -4,16 +4,11 @@ import { RepeatBehavior } from "../decorator/RepeatBehavior.js";
 import { ActionBehavior } from "../primitive/ActionBehavior.js";
 import { SequenceBehavior } from "../composite/SequenceBehavior.js";
 
-export const BehaviorComponentFlag = {
-    AllowSleep: 1,
-    Resolved: 2
-};
-
 export class BehaviorComponent {
     constructor() {
 
         /**
-         *
+         * What clock should be used for ticking associated behavior
          * @type {ClockChannelType|number}
          */
         this.clock = ClockChannelType.Simulation;
@@ -135,8 +130,8 @@ export class BehaviorComponent {
      * @returns {BehaviorComponent}
      */
     static fromOne(b) {
-        assert.notEqual(b, undefined, 'behavior is undefined');
-        assert.notEqual(b, null, 'behavior is null');
+        assert.defined(b,  'behavior');
+        assert.notNull(b,  'behavior');
         assert.equal(b.isBehavior, true, 'b.isBehavior !== true');
 
         const result = new BehaviorComponent();

package/engine/intelligence/behavior/ecs/BehaviorComponentFlag.js

@@ -0,0 +1,7 @@
+export const BehaviorComponentFlag = {
+    AllowSleep: 1,
+    /**
+     * Behavior has completed
+     */
+    Resolved: 2
+};

package/engine/intelligence/behavior/ecs/BehaviorSystem.js

@@ -1,8 +1,9 @@
 import { System } from "../../../ecs/System.js";
-import { BehaviorComponent, BehaviorComponentFlag } from "./BehaviorComponent.js";
+import { BehaviorComponent } from "./BehaviorComponent.js";
 import { BehaviorStatus } from "../BehaviorStatus.js";
 import Clock from "../../../Clock.js";
 import { ClockChannelType } from "./ClockChannelType.js";
+import { BehaviorComponentFlag } from "./BehaviorComponentFlag.js";
 
 /**
  *

package/engine/intelligence/behavior/ecs/ClockChannelType.js

@@ -3,6 +3,13 @@
  * @enum {number}
  */
 export const ClockChannelType = {
+    /**
+     * Simulation clock is the one that the entire world is running on
+     */
     Simulation: 0,
+    /**
+     * System clock is essentially real-time
+     * Useful for things that need to run even when the world simulation is paused
+     */
     System: 1
 };

package/engine/intelligence/behavior/primitive/SucceedingBehavior.js

@@ -1,6 +1,5 @@
 import { Behavior } from "../Behavior.js";
 import { BehaviorStatus } from "../BehaviorStatus.js";
-import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
 
 /**
  * Behavior that always succeeds
@@ -25,7 +24,7 @@ export class SucceedingBehavior extends Behavior {
         return r;
     }
 
-    tick() {
+    tick(timeDelta) {
         if (this.delayTicks === 0) {
             return BehaviorStatus.Succeeded;
         } else {
@@ -37,29 +36,3 @@ export class SucceedingBehavior extends Behavior {
 
 SucceedingBehavior.typeName = "SucceedingBehavior";
 
-export class SucceedingBehaviorSerializationAdapter extends BinaryClassSerializationAdapter {
-    constructor() {
-        super();
-
-        this.klass = SucceedingBehavior;
-        this.version = 0;
-    }
-
-    /**
-     *
-     * @param {BinaryBuffer} buffer
-     * @param {SucceedingBehavior} value
-     */
-    serialize(buffer, value) {
-        buffer.writeUintVar(value.delayTicks);
-    }
-
-    /**
-     *
-     * @param {BinaryBuffer} buffer
-     * @param {SucceedingBehavior} value
-     */
-    deserialize(buffer, value) {
-        value.delayTicks = buffer.readUintVar();
-    }
-}

package/engine/intelligence/behavior/primitive/SucceedingBehaviorSerializationAdapter.js

@@ -0,0 +1,29 @@
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { SucceedingBehavior } from "./SucceedingBehavior.js";
+
+export class SucceedingBehaviorSerializationAdapter extends BinaryClassSerializationAdapter {
+    constructor() {
+        super();
+
+        this.klass = SucceedingBehavior;
+        this.version = 0;
+    }
+
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {SucceedingBehavior} value
+     */
+    serialize(buffer, value) {
+        buffer.writeUintVar(value.delayTicks);
+    }
+
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {SucceedingBehavior} value
+     */
+    deserialize(buffer, value) {
+        value.delayTicks = buffer.readUintVar();
+    }
+}

package/engine/intelligence/blackboard/AbstractBlackboard.js

@@ -13,6 +13,14 @@ export class AbstractBlackboard {
         throw new Error('Not implemented');
     }
 
+    /**
+     * Produces a list of all held keys
+     * @returns {string[]}
+     */
+    getKeys() {
+        throw new Error('Not implemented');
+    }
+
     /**
      * @template T
      * @param {string} name
@@ -30,7 +38,7 @@ export class AbstractBlackboard {
      * @returns {void}
      */
     release(name) {
-
+        throw new Error('Not implemented');
     }
 
     /**