bhouston/behave-graph

Open, extensible, small and simple behaviour-graph execution engine. Discord here: https://discord.gg/mrags8WyuH

behave-graph's Issues

Enable custom events.

It should be possible to listen to any event by a string identifier. And it should be possible to call any custom event by string identifier.

Add ability to following which events are executing.

This will enable a web based node interface to highlight which nodes are executing.

node spec json file needs to be available in published version

needs exporting in index.ts

Add readonly and private TypeScript type modifiers.

dist has two copies of the library and type definitions

this is causing vscode to show everything twice in autocomplete, possibly no other side effects, but should tidy up anyway

i think this was introduced when the examples got bundled, the del commands probably need double checking

Export node type definitions as a json node specification file

This would allow for importing into: https://github.com/beeglebug/behave-flow

saveGraph to JSON

Implement a means to save in a JSON format compatible with the readGraph call.

Convert examples back to TypeScript files.

Support generic-style TypeScript interface to typed sockets.

Basically allow for Socket or Socket style syntax and have it work correctly. This would allow for better type checking of values passed around sockets.

Validation: Ensure no "flow" input sockets have values on them.

This makes no sense so prevent it from happening.

nodes attempting to set output values on flow sockets

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)

Make sure state get/set is type safe.

Right now state is stored in the graph without any type information. Thus it can pass out a number to a getString state node. This is unsafe. The state store should be typed and enforce those types at run-time.

Support async output of node results. Required for delay node.

Do not require nodes to output their results in a purely synchonous fashion. Allow for async output of results. Support this natively so it is not a big hack.

This should be compatible with the multiple outputs per node feature: #1

Allow debug output to be redirect to other places other than just console.

Enable library users to add SocketValueTypes

The types that flow through the graph should not be limited to only those pre-defined in this library. This probably means we have to move away from an enum and towards a list of registered types.

Enable limiting execution by time-slice allocation

This should be another evaluateWithinTimeslice( milliseconds: number ) call.

Enable complex value types to parse/stringify themselves.

Currently the library only supports types that are a single JSON element, not complex types.

Maybe easier to use a stack to manage execution rather than work queue?

I am starting to wonder if the main method of evaluating these behavior graphs is actually a stack rather than a work queue.

The reason why a stack would be easier is:

• The sequence node would just put its children on the stack in reverse order.
• The for-loop would put itself on the stack and then its loopBody. When it gets executed again after the loopBody is done, it will put itself again on the stack and then the next iteration of loopBody.

I think that once the stack is completed, you go back to look for new events?

I think this doesn't handle the case where you want to "break" a for-loop. In those cases you either need a loop in the graph (non-DAG) or as Unity does it, it has an event that is raised in the loopBody and then executes and sets a "break" flow socket on the for-loop (but this violates the stack execution model, as the events wouldn't be fired until the for-loop is done.)

Thus this isn't yet sufficient.

Adopt formal EventEmitter, EventListener pattern

Create reusable library form.

Currently this is not in a true library form, rather it just allows for local tests to be run. For this to be truly usable, it needs to be converted and published to an npm accessible library.

Spelling mistake: Uniary -> Unary

@javagl pointed out this spelling mistake.

Validate: ensure links go to valid nodes/sockets

We should have explicit error messages when a socket link goes to a non-existent node or it connects to a non-existent socket on that node.

Write a Trigger-Action List to Behavior Graph converter.

Prove that it can work!

Support beautiful coding interface as well

See if you can learn from https://twitter.com/hmans/status/1556971439386918914?s=21&t=3GtLvLF_P85x-9azSLYm9w

Validate: On load, ensure all node uuids are unique.

I just ran into a case of a hand written graph json that had duplicate node ids and it just overwrote one during import. That is dangerous and not proper.

Support event/stateChanged event - when state changes

It should be possible to listen to state identifiers and have an event fire when the state is changed.

Q: Should there be a central registry of state data? Like a list of member variables, or should I keep the very arbitrary map-based method? The central registry on a per graph basis may lead to better type checking.

Support per node metadata/user data - load and save from JSON without changing it

This would allow for external editors (e.g https://github.com/beeglebug/behave-flow) to add positional data or other forms of augmented data and have it persist untouched.

Allow an upstream node to "wait" for a downstream subgraph to complete execution.

This is required for the "for loop" node in Unreal Engine and Unity Visual Scripting.

https://docs.unrealengine.com/4.26/en-US/ProgrammingAndScripting/Blueprints/UserGuide/FlowControl/

Also required by "Sequence". These nodes wait for the subgraph connected to their output flow socket to execute and then they will pass execution to either to the same output flow socket (loopBody) or to another flow output socket (complete.).

Instead of relying on Events being triggered externally, allow them to self-register

In the current implementation, it is required that one trigger Events explicitly. You can see this in all of the examples where after loading the graph, one triggers the "events/start" event explicitly.

Instead, one could have all events in the graph execute immediately upon startup and they all return promises, which means that they are pending. And then when they fire, they resolve their promises. This would make it much simpler to add new event types to the system.

remove .vscode directory

Having this checked in makes it a bit tougher for other developers to use their own workspace settings when working on the project, it should probably be removed and gitignored.

how does a graph connect to an external environment?

This is a larger question about how a behave-graph graph interacts/binds itself to some external environment, be it a threejs scene or something else.

This codesandbox is me experimenting with a simple connection between a graph and a threejs scene, but at the moment the connection is very manual.

https://codesandbox.io/s/behave-graph-three-test-ijdzj6

What i'm wondering, is what do we think that connection will eventually look like? I imagine a node such as my test "input/mouseClick" would also have an input of some sort to select a mesh in the scene (in this case the cube), and then would only be triggered by clicks on that cube.

We would then also want a way to transmit effects back into the scene, for example I might want a graph which looks like the following:

const graphDef: GraphJSON = {
  nodes: [
    {
      id: "1",
      type: "input/mouseClick",
    },
    {
      id: "2",
      type: "material/setColor",
      inputs: {
        text: {
          value: "#0000FF",
        },
        flow: {
          links: [
            {
              nodeId: "1",
              socket: "flow",
            },
          ],
        },
      },
    },
  ],
};

ie, when the user clicks on the cube, the material changes colour to blue.

I think it would be really useful to sketch out some more "real world" examples of graphs which actually do something in a less abstract environment to get an idea of what changes might be required in the core library to support the required nodes.

Validation: ensure valuetyoenames are registered

Add an invalid example that uses an unsupported valuetyoename and ensure it fails to pass validation

Need a logo

Something to use on the website, discord, etc.

Implement assertion nodes for unit testing.

It would be nice to have Assert nodes that check for a specific input and fail otherwise. This would allow one to create a large series of graphs that if they run successful are basically unit tests for the system.

Bug: triggerEvents with outputs doesn't apply provided value

Codesandbox with reproduction

I added custom event node (StartWithOutputNode) with output socket
I want to trigger this node with value

graphEvaluator.triggerEvents(
    "event/startWithOutput",
    new Map([["str", "provided string"]])
);

Expected: "provided string" in log
Actual: empty message in log

Examples: add unsupported graphs

Add a for loop and a sequence example in an unsupported sub folder of examples.

Graph validation: Loop detection

We should validate that a graph is a true DAG and contains no degenerate loops.

remove invalid graph examples in favour of tests

Now the test suite is working, we can port all the "invalid" examples to test cases. I've done some of them already, but left the deletion of the examples for now.

Nodes should declare themselves ahead of time whether they are async or not.

Validate: Error on trying to set values/links on non-existent sockets

If you try to set a value or link for a socket who actually doesn't exist on the specified node, error out.

Add types for json data.

At the moment, readGraphFromJSON and writeGraphToJSON both deal with a type of any, which is fine, but open to errors.

For better interoperability with other code, it would be good to specify a type for the JSON version of a graph.

Create Three.js example.

It should be relatively easy to create a Three.jS example once we have it running in the browser via #3.

Ensure that once in async mode, node only fires async commits.

And also ensure that if a node is not in async, it doesn't fire async commits.

Validate Graph: Type alignment

Enforcing typing alignment:

• Connected Input and Output Sockets agree on their type.
• Input Socket types align with the type of their constant values.

When a series of identical events are scheduled, should each event have its own output values?

Let's say there is an event that fires, "door state", and it has an output value called "isOpen." If it fires 2 separate times, one with "isOpen = true" and a second "isOpen = false." then I guess we have to somehow set these values on the event when it fires as output values.

Support multi-outputs per node execution

In order to support for-loops and delayed sequences, I need to be able to return outputs multiple times so that the downstream graph executes multiple times.

How should this be done?

I think at minimum a promise should be returned and then it will resolve when the next set of outputs are ready. And part of that response will be another promise if there are subsequent outputs that should be waited upon.

This needs a nice API.

eslint fails to run

ESLint couldn't find the plugin "eslint-plugin-react". looks like a dependency of eslint-config-airbnb?

add prettier config

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).

Setup package alias so one can import in examples easily.

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...

Create web browser example.

Right now I only have command line examples. Having an example that runs in the web browser would be very nice.