Behave/ReadMe.md

# Behave

A simple implementation of behavior trees in MoonScript / Lua. Define behaviors
as functions or small tables, then call `behave.make` on them to get a function
you can call repeatedly to execute behaviors.

A node should return a truthy or falsy value to indicate success or failure, or
`behave.running` to indicate that the node needs to be called again to continue
running.

Examples are in MoonScript, but shouldn't be too difficult to understand even if
you are unfamiliar with its syntax.

## Example

```
TODO
```

## Leaf Nodes

The easiest node is just a function that will be passed all arguments sent to a
behavior tree it is part of. There is a slightly more complex leaf node for
maintaining an internal state, and optional `start`/`finish` functions only
called at the beginning and end of processing.

```
WalkPath = {
  start: (state, entity) ->
    state.path = findPath(entity, entity.target)
    return state.path
  run: (state, entity) ->
    -- this will not run if start fails
    state.path.step!
  finish: (state, entity) ->
    -- this will run only if run returns a truthy value besides behave.running
    state.path = nil
}
```

## Decorator Nodes

Basic extensions to leaf nodes. Decorator allows you to specify a function to
modify returned results (except for `behave.running`). Inverted inverts the
result of its node. Repeat allows you to repeatedly call a node a specified
number of times. Once allows you to make a node only get called once.

```
ManuallyInvertedSomeNode = {
  decorator: (result) ->
    return not result
  SomeNode
}
InvertedSomeNode = {
  type: behave.Inverted
  SomeNode
}
SomeNodeRepeated = {
  repeat: 20
  SomeNode
}
SomeNodeOnce = {
  type: behave.Once
  SomeNode
}
```

## Composite Nodes

Selector skips any failures and returns on the first node that returns a truthy
value (or returns `false` if nothing succeeds). Sequence continues until there
is a failure or returns success. Random executes a random node underneath it.

```
Behaviors = {
  type: behave.Random
  WalkRandomly, LookAtPhone, LeaveArea
}
```

## Custom Nodes

You can create custom nodes and easily use them. Rather than explaining how to,
here's an example inverter (note: `behave.Inverted` offers this feature):

```
-- defining the node type:
Invert = (tab) ->                   -- your fn will be passed a table describing the node
  node = behave.make tab[1]         -- call make on any sub-nodes that you will be using, save the result
  return (...) ->                   -- use variable arguments, so sub-nodes can
    result = node(...)              -- get what they need
    unless result == behave.running -- running nodes should not be interrupted
      result = not result           -- and finally we invert the result before
    return result                   -- returning it

-- using the node type:
SomeInvertedNode = {
  type: Invert       -- this is how the library knows what function to call
  SomeNode           -- this is the node that will be inverted
}
```