This PR imports the code from @beeglebug's behave-flow into the main behave-graph monorepo, so that the flow code and be developed and updated in sync with the core library code.

A future V2 pr would separate out reusable components and hooks so that developers could import them and integrate them into their existing solution.

It also adds the following improvements, which it incorporates from @oveddan's interX:

Interactive 3d Scene Preview

GLB files can be rendered and interactive in a three.js scene side-by-side with the flow editor, and updates to the editor apply in real-time to the scene.

User can upload their own 3d model:

(todo: gif)

User can load examples that contain both a model and behave graph

...if only behave-graph loaded (without a 3d model), then view will not be split:

Split pane can be adjusted

A user can drag the split in the middle, and also change the split to be vertical or horizontal:

• react-three-fiber renderer for the 3d scene.
• new example with button that you press, it starts and elevator animation, and the button turns green
• a bunch of useful reusable hooks that encapsulates the react-flow functionality
• an extension of IScene that lets you query properties on a model
• a way to let the user generate the json path by selecting values from a dropdown

handle

ToDo:

• Update the main readme with instructions on how to run
• Deploy this somewhere (netlify?)
• Allow the user to adjust the environment of the scene stage.
• Documentation!

To be able to add custom value types For example

import { ValueType } from 'behave-graph`

type Vector3 = { x: number, y: number, z: number };

valuesRegistry.register(new ValueType('vector3', () => ({ x: 0, y: 0, z: 0 }), (text: any) => text, (value: Vector3) => value));

This PR breaks up the examples folder from the lib folder into separate workspaces, thus removing the dependency of three.js from the core lib and reducing its bundle size, and enabling examples to more freely import other dependencies that are not needed by the core lib, such as react, or @react-three/fiber.

Addresses #128

It takes inspiration from the workspace setup of react-three-fiber.

• It uses preconstruct to handle the monorepo dev and code needs, including being able to locally link packages (in examples we can now do import { Vec3 } frombehave-graph`
• It builds the code with rollup and babel - this also generates nice source maps which i don't believe exist in the current build (I'm currently unable to step into code from the lib in chrome debugger when importing it from another app)
• It runs the example using vite, a fast, modern, and well-documented front-end webdev environment.

Now, examples can import behave-graph code the 'normal' way (not by relative path), enabling the code to be copied and pasted more easily to those who want to do their own modifications on it:

Example code before:

import { Assert } from '../../lib/Diagnostics/Assert.js';
import { EventEmitter } from '../../lib/Events/EventEmitter.js';
import { IScene } from '../../lib/Profiles/Scene/Abstractions/IScene.js';
import { Vec3 } from '../../lib/Profiles/Scene/Values/Internal/Vec3.js';
import { Vec4 } from '../../lib/Profiles/Scene/Values/Internal/Vec4.js';

After:

import { Assert, EventEmitter, IScene, Vec3, Vec4 } from 'behave-graph';

Main organizational changes:

• created /lib folder for the core package - maybe this can be eventually put into packaages/core
• src/lib -> lib/src
• src/graphs ->lib/graph`
• src/examples ->examples/src`
• added package.json to lib - this is the core lib package.json, and now behave-graph is the package name in there - should it be? Or should we do something like @behave-graph/core

Still todo:

• [x] fix export-node-spec script
• [x] figure out proper entrypoint for examples - right now there is an index.html in the root of examples that points to the three.js example
• [x] FIx the three example
• [ ] update readme

Hi, I was interested in using this library, but noticed an open issue to get it bundled and published, so thought i'd have a quick stab at a basic rollup config.

In this initial version i've only exported the files necessary to replicate the code in runner.js (GraphEvaluator, loadGraph, NodeRegistry and registerGenericNodes).

I assume there is other code which would be helpful to a user of the library, but until I can play around with it a bit more, I thought it best to raise it now and ask what else to add.

From experience, prettier is the nicest solution to keeping a clean, consistently formatted codebase while removing any possible arguments about the details. It's used by thousands of other open source JS projects, so contributors will be familiar with it.

We could auto format everything once in a single cleanup commit and be done with it, most modern IDE's will handle prettier automatically and format on save.

We can then strip out most of the eslint config (certainly any bits pertaining to code formatting).

This adopts the convention that nodes now have a "configuration" section that is for non-run-time parameters.

For example, Sequence node can have variable number of outputs. Now you can specify numOutputs for sequence in its configuration.

Here is the list of nodes that currently support configuration:

• Sequence: numOutputs
• WaitAll: numInputs
• VariableSet: variableId
• VariableGet: variableId
• CustomEvent Trigger: customEventId
• CustomEvent On Trigger: customEventId

For example this:

   {
       "type": "customEvent/trigger/0",
       "id": "1"
     },

Becomes this:

  {
       "type": "customEvent/trigger",
       "configuration": {
         "customEventId": 0
       },
       "id": "9"
     }

This PR makes the getter and setters from AbstractionRegistry strongly typed, making the API easier to consume when using typescript.

For example, before, if you wanted to call:

get on the AbstractionRegistry there's no way to know what the possible keys are, nor what the type returned is without finding everywhere set is called.

Existing api call:

const logger = context.graph.registry.abstractions.get<ILogger>('ILogger');

New api call:

const logger = context.graph.registry.abstractions.get('ILogger');

You can now now intellicence for abstractionName when calling the api.

I would suggest splitting up this monorepo into multiple workspaces within the monorepo, each with its own package.json.

I would like to do an implementation of ThreeScene using @react-three/fiber but I don't wan't to pollute the dependencies in the main package.json with those dependencies. So I think it would make sense to have each of the following workspaces, each with their own package.jsons:

• one that defines the json schema/standard for this behavior-graph data format
• a lib with the current implementation to parse it. - this can be imported directly using npmjs without needing to import three.js
• a folder for 3d scene functionality with three.js as a dependency.
• different folders for different example implementations - one for three.js and one for @react-three/fiber
• eventually a folder could be created for unity implementation

Confirm that integer is a real thing. I think it is.

Interestingly enough, vec4 and quat are the same type. I may not want that in this system because quat operations are different than vec4. But I could have a transformer that converts both to the same underlying type.

Several flow nodes are throwing errors when you attempt to run a graph, complaining about attempting to set output values on flow sockets.

I think i've fixed flipflop, as that was the one I was attempting to use when I saw the issue, but I suspect some of the others are still doing it (I was hesitant to touch things like "flow/sequence" which seem incomplete anyway)

it would be nice to see in the examples this:

import { Node } from 'behaviour-graph';

Rather than:

import { Node } from '../../../dist/lib/index';

I think this can be done with some config variables in the tsconfig.json file...

While navigating through the Unreal Blueprint API documentation to get some inspiration for our docs, I noticed for some Nodes they do support Union types. I think this could be a nice to have feature, specially if we include structured data support, but also for some generic functions which might accept ie both float & integer values

Although perhaps outside the scope of this project, I think it would be great to support structured data as well. Depending on what you think, we have 3 options in order to do this:

• Implement the value types and very tiny nodes to work with on the core package and a separate package/profile with some extended tools
• Implement it as a separate package/profile inside this repository (officially supported/maintained)
• Implement it as a separate package/profile in other repository (community maintained)

I have a working example here with some examples I was working on in the last days: behave-graph/struct I also deployed them here to test the github-actions and the docs I did for this repo, but in this case just with that specific profile

I personally would prefer the 1st or 2nd option and include it in the main repository as an optional profile, same as the Scene one but it's up to you as I don't know if this makes sense.

cc @bhouston @oveddan

As discussed here I have been working on improving the docs. Here's a first approach by using Docusaurus

Landing Page:

Core Concepts (+ dark theme which I personally prefer):

Auto-generated pages for Values and Nodes (for Core and Scene profiles):

Auto-generated pages with the Examples found in the graphs folder:

Easy to use blog in case we need it (can be disabled if there's no plans to use it):

That said, there are some troubles I found during the development and should be discussed:

• Many different interfaces for Nodes (NodeDescription, NodeDescription2, Node Instance, NodeSpecJSON) and some misalingments between them. It would be nice to be able to generate the Node pages just with the NodeSpecJSON but right now it's not possible:

• • writeNodeSpecsToJSON fails when executing on a Registry with just the Scene profile so I need to load 2 registries, to be able to check which Nodes are from each Profile
• • the NodeSpecJSON doesn't include some fields such as the helperText which in this case it's quite useful
• • the NodeSpecJSON doesn't include any information about dynamic I/O as they are defined with the new configuration property, so I have to do really weird tricks to do this. Again, I think would be nice to be able to determine this based only on the NodeSpecJSON, this is the main interface for the Node definitions on the reactflow implementation

• The reactflow component has some issues that makes it hard to reuse it right now:

• • The styles are defined by some kind of css class utility library (maybe Tailwind? Idk) so in order to use them inside the docs I would need to find/redefine them and load them into the blog and also taking the risk to arise conflicts. I would favor some styles-in-js implementation such as emotion.
• • The presentational components are very tied to the reactflow engine (mainly because of the hooks they're using) so I hard to rewrite the entire node inside the docs
• • The runner function is defined deep inside the components so there's no way to override it with custom profiles rn

As we're having many changes on the core interfaces (NodeDescription) and the way we define the nodes, I don't think it makes sense to update the reactflow component till those changes are completed. But once we have polished those details, I would like to improve the visual editor so we can integrate it inside the docs and provide a visual execution environment for the examples section.

Also, we should include a GH Action to deploy the website to GH pages. I can work on that before we merge this PR and include it with the changes.

cc @bhouston @oveddan

This PR is the start of doing what was discussed in #191:

• It creates interfaces for NodeDefinitions.
• Changes node definitions to be purely functional and stateless, which improves testability; they can be setup easily without needing to define a graph first.
• When defining nodes, gets rid of tons of boilerplate code; instead of having to create a class that inherits another class and have to pass a definition and graph to the super class, you can just now define the inputs/outputs and the execution function.
• on trigger/exec functions, read, write, and commit now restrict what socket name can be called based on the defined input/output sockets.
• for flow nodes, state is passed as an argument, and updated state must be returned from the triggered function; the state is strongly typed based on the initialState parameter.
• There is a new IGraphApi which minimally defines an api for what is needed by nodes for their execution - this is passed to the nodes instead of the whole Graph class.
• Engine and Fiber now consume nodes as interfaces: INode which means the implementation of Node can be abstracted.

This makes everything more testable, and allows someone to more easily create their own graph execution engine and integrate it with these definitions.

It also reduces the amount of boilerplate needed to create node defs.

So far, all of the Value and Event based nodes have been migrated to use this new definition format which was made easy by the awesome work done in #192 . Some Flow nodes have been migrated too.

An example of before / after:

Counter Node

Before:

import { Fiber } from '../../../Execution/Fiber';
import { Graph } from '../../../Graphs/Graph';
import { FlowNode } from '../../../Nodes/FlowNode';
import { NodeDescription } from '../../../Nodes/Registry/NodeDescription';
import { Socket } from '../../../Sockets/Socket';

export class Counter extends FlowNode {
  public static Description = new NodeDescription(
    'flow/counter',
    'Flow',
    'Counter',
    (description, graph) => new Counter(description, graph)
  );

  constructor(description: NodeDescription, graph: Graph) {
    super(
      description,
      graph,
      [new Socket('flow', 'flow'), new Socket('flow', 'reset')],
      [new Socket('flow', 'flow'), new Socket('integer', 'count')]
    );
  }

  private count = 0;

  triggered(fiber: Fiber, triggeringSocketName: string) {
    switch (triggeringSocketName) {
      case 'flow': {
        this.count++;
        this.writeOutput('count', this.count);
        fiber.commit(this, 'flow');
        break;
      }
      case 'reset': {
        this.count = 0;
        break;
      }
      default:
        throw new Error('should not get here');
    }
  }
}

after

// we now only need to import one helper function
import { makeFlowNodeDefinition, NodeCategory } from 'packages/core/src/Nodes/NodeDefinition';

// helper function that allows us to declare a strongly typed flow node definition without needing to explicitly define the generic params
export const Counter = makeFlowNodeDefinition({
  typeName: 'flow/counter',
  label: 'Counter',
  in: {
    flow: 'flow',
    reset: 'flow'
  },
  out: {
    flow: 'flow',
    count: 'integer'
  },
  initialState: {
    count: 0
  },
  category: NodeCategory.Flow,
  triggered: ({ commit, write, triggeringSocketName, state }) => {
    // state has the same type as initialState
    let count = state.count;
    switch (triggeringSocketName) {
      case 'flow': {
        count++;
        // through type enforcement, write and commit can only write to one of the keys of `out`
        write('count', count);
        commit('flow');
        break;
      }
      case 'reset': {
        count = 0;
        break;
      }
      default:
        throw new Error('should not get here');
    }

    // return updated state - must have same type as initial state
    return {
      count
    };
  }
});

Opening this PR to get some feedback, before proceeding further. @bhouston let me know what you think!

I have some freetime this week so I'd be glad to migrate the rest of the node defs.

Did some refactoring on FunctionDesc to make it more readable and simpler to consume:

• Got rid of being able to have inputs/outputs be declared either as an array or key<->value, its confusing to have an api that can be called in multiple ways like this. I know the desire is to move to key<-> value pairs, but it doesn't seem like that is being used now for function node, so why don't we wait til we do it the right way (i.e. as top level api) first.
• Refactored the code to have a reusable function: toOrderedSockets that converts from Array -> Socket, with an argument for how to determine the keys of each element.

Some nodes now support "configuration". This is for non-run-time configuration of nodes, right now that exclusively deals with changing the actual socket structure of the nodes.

The first few nodes I've applied this to are: (1) Sequence, (2) WaitAll, (3) Custom Event Trigger and (4) On Custom Event. There is also a PR for (5) Switch.

We now need to update the Flow library to handle modifying nodes by changing their configuration.

For example for Sequence, we have to increase/decrease the "numOutputs" of the configuration and then recreate the node and replace the existing node with this new version. When replacing the node with the new version, we should aim to keep as many of the existing connections as possible.

I think we probably need to make custom UI elements for each of these nodes that has configuration parameters? Or maybe we can formalize it so that we can auto-create UI elements for them?

What do people think?