Merge pull request #42 from kagenash1/v2

Update to 2.0

Author: kagenash1

.gitignore

@@ -1,6 +1,11 @@
-.import/
+# Godot 4+ specific ignores
+.godot/
+/android/
+build/
 *.import
 *.png.import
 export.cfg
 export_presets.cfg
-project.godot
+.vscode/
+*.uid
+.tmp

LICENSE

@@ -1,26 +1,165 @@
-# godot-behavior-tree
-
-A GDScript implementation of a behavior tree for game AI, based on native Godot nodes and using the built in scene tree editor.
-
-C# VERSION -> https://github.com/MadFlyFish/godot-behavior-tree-csharp
-
-INSTALLATION
-- Copy the 'addons' folder into the main directory of your project.
-- Enable the plugin from project settings, THEN RESTART Godot, otherwise it will not recognize the new classes (that's a bug of the engine).
-- Optionally, you can also drag the bt_example folder into the main directory of your project.
-- To see the example working, run the agent.tscn scene. The ex_behavior_tree.tscn scene is an example of how the tree is built.
-
-![alt text](https://raw.githubusercontent.com/GabrieleTorini/godot-behavior-tree/main/bt_images/Screenshot%202021-03-13%20085615.png)![alt text](https://raw.githubusercontent.com/GabrieleTorini/godot-behavior-tree/main/bt_images/Screenshot%202021-03-13%20085633.png)
-
-INSTRUCTIONS:
-- Click the node creation icon. You should see new nodes available (if you don't, restart Godot). You must use a BehaviourTree as the root node, which should have only a single child. This child can be any of the nodes under the BTNode category, which all inherit from the BTNode class.
-- After creating a behavior tree, you must specify who is the owner of the AI (the Agent) and what Blackboard is being used. Blackboards can be put anywhere (given it is outside the tree), and even shared among different trees. The system is flexible enough to allow you to decide how and when to update your blackboard data. For example, you can make a plain Node with a script that handles updating the blackboard, eg. with signal callbacks or even in process(). Or you can do it from anywhere else, even from inside the tree, just make sure to design things in a way you can maintain and keep track of.
-- A Behavior Tree flows executing each of its children, which return some kind of success or failure state. Only those branches following a successful node will be executed.  A BTNode must return either success or failure, and can suspend execution only with a yield() call, after which it will remain in a running state until execution is completed. When a BTNode is in running state, the tree will progressively suspend execution (with the only exeption being BTParallel ) until all of the children complete execution. This is for optimisation purposes.
-- The flow of the tree is defined by the so called composite nodes: BTSequence, BTSelector, BTRandomSelector, BTRandomSequence, BTParallel which all inherit from BTComposite. A sequence is successfull if all the children are successful, while it fails if one of the children fails. The selector is the logical opposite, it succeeds if one children succeeds, and fails if all the children fail. A parallel will run all the children and always succeed regardless, WITHOUT waiting for children to complete execution. The base composite node runs all the children and always succeeds, but it also waits for execution completion.
-- The actions of your AI behavior are carried out in BTLeaf nodes. Add a BTLeaf, then do 'extend script'. Now you can define your own behavior in this script by overriding the _ _tick()_  method. Your actions will go here. Make sure to read the comments in the base script to know the best practices. Also remember BTLeaf shouldn't have children.
-- BTDecorator is used to customise the execution of a child node. They can only have ONE child. 
-- BTConditional is the most common type of decorator. Add a BTConditional and extend the script, then override the _ _pre_tick()_ method to define the conditions under which the child will be executed. Make sure you read the comment cause there is a useful example there. 
-- BTGuards are decorators which can be used to temporarily lock branches. Optionally, you can assign an unlocker, which will override the lock time specified. There is also the option to assign a locker. BTGuards can make your behavior very rich and reactive, as well as optimised, as they avoid unnecessary branching and repetition.
-- Other decorators allow you to loop execution, reverse the result of tick, and so on. There is a lot you can do by customising execution through decorators.
-- Good practice is to use the provided nodes and follow the design pattern of the behavior tree. But since this is a purely code based implementation without any visual editor, you have a lot of control over the design and thus a margin of error. These are just useful scripts that follow some "good practices" but are not bound to them, if not for a couple of basic rules. It is up to you to decide how you design your behavior tree, but keep in mind that if you misuse it you will not benefit from the power of the behavior tree pattern. (for example, you could even use the base BTNode for everything and just extend it everytime, although it would be a mess)
-- You could have a huge behaviour tree, but the best practice is to follow the component philosophy of Godot and make several smaller behaviour trees for each component of your scene. For example, a tree for your movement controller, a tree for your weapon controller, a tree for your pathfinder component, etc.. A behaviour tree can only have one blackboard, but the same blackboard can be used by many trees, so this is particularly handy if you wanna have several trees without also making multiple blackboards. Personally, the reason why I have the blackboard as a decoupled component, is because I wanted to make squads of enemies sharing the same data but behaving independently, so this is a use case for this. Moreover, I usually have several components in my actors, and I wanna use the same database for different tree.
+# GodotBT: Behavior Tree Framework for Godot 4.x
+
+A flexible, extensible behavior tree framework for Godot 4.x that makes it easy to create complex AI behaviors for your games.
+
+## Overview
+
+GodotBT provides a complete behavior tree implementation for the Godot Engine, allowing you to create sophisticated AI behaviors with a clear, modular structure. The framework follows behavior tree design principles with a focus on reusability and separation of concerns.
+
+## Key Features
+
+- **Complete Behavior Tree Implementation**: Core composite nodes, decorators, services, tasks, and conditions
+- **Reusable Behavior Trees**: Define a behavior tree once and use it across multiple agents with their own contexts
+- **Blackboard System**: Flexible data sharing between nodes with typed accessors and change detection
+- **Reactive Conditions**: Trigger behavior changes based on world events with configurable abort scopes
+- **Service System**: Run periodic background tasks with customizable frequency
+- **Context Separation**: Each agent maintains its own execution context with the shared tree
+- **Utility Components**: Helpers like BTTargetKey for simplified movement and targeting operations
+- **Example Implementation**: Includes a complete demo with enemies that can patrol, chase the player, and react to events
+
+## Core Components
+
+### Composite Nodes
+
+- **BTSelector**: Runs child nodes until one succeeds or all fail
+- **BTSequence**: Runs child nodes until one fails or all succeed
+- **BTParallel**: Runs all child nodes simultaneously
+- **BTRandomSelector/BTRandomSequence**: Random execution order versions of selector and sequence
+
+### Decorators
+
+- **BTInverter**: Inverts the result of a node
+- **BTRepeater**: Repeats a node a specified number of times
+- **BTRepeatUntil**: Repeats a node until it returns a specific result
+- **BTAlwaysReturn**: Forces a node to return a specific result
+
+### Conditions
+
+- **BTBlackboardBasedCondition**: Condition based on blackboard values
+- **BTReactiveCondition**: Condition that can trigger aborts
+- **BTCheckNonZeroBBEntry**: Checks if a blackboard value is non-zero/non-empty
+- **BTCompareBBEntries**: Compares two blackboard entries
+
+### Services
+
+- **BTService**: Base class for services that run periodically
+- Custom services in examples like **BTPlayerDetector**, **BTPatrolPathFollower**
+
+### Tasks
+
+- **BTTask**: Base class for leaf nodes that perform actions
+- **BTWait**: Wait for a specified amount of time
+- Example implementations for movement, path finding, and more
+
+## Installation
+
+1. Clone or download this repository
+2. Copy the `addons/godot_bt` folder into your project's `addons` folder
+3. Enable the plugin in Project Settings > Plugins
+
+## Basic Usage
+
+### Creating a Behavior Tree
+
+1. Create a new scene with a root node of type `BehaviorTree`
+2. Add a `BTSelector` or `BTSequence` as the first child
+3. Build your behavior tree by adding more composite nodes and tasks
+4. Save the scene
+
+### Using the Behavior Tree with Multiple Agents
+
+```gdscript
+# Level.gd - Sets up the behavior tree and passes it to agents
+extends Node2D
+
+func _ready():
+    # Find all agents and set their behavior trees
+    for enemy in get_tree().get_nodes_in_group("enemies"):
+        enemy.run_behavior_tree()
+```
+
+```gdscript
+# Enemy.gd - Each agent handles its own context
+extends CharacterBody2D
+
+@export var bt: BehaviorTree
+@export var patrol_path: Node2D
+
+var ctx: BTContext
+
+# Called by the level or manager
+func run_behavior_tree() -> void:
+    if not is_instance_valid(bt):
+        return
+
+    ctx = bt.create_context(self, Blackboard.new())
+
+    # Set up blackboard values for this agent
+    if patrol_path:
+        var patrol_points: Array = []
+        for patrol_pt in patrol_path.get_children():
+            patrol_points.append(patrol_pt.global_position)
+        ctx.blackboard.set_value("patrol_points", patrol_points)
+
+func _physics_process(delta: float) -> void:
+    if is_instance_valid(bt) and ctx:
+        bt.tick(ctx, delta)
+```
+
+## Example Implementation
+
+The included example demonstrates:
+
+1. **Enemy Patrol System**: Enemies follow patrol paths or look in random directions
+2. **Player Detection**: A service that detects the player within a specified range
+3. **Chase Behavior**: Enemies chase the player when detected
+4. **Navigation**: Path finding to navigate around obstacles
+
+To see the example in action, open the `example/TestLevel.tscn` scene.
+
+## Extending the Framework
+
+The GodotBT framework is designed to be highly extensible. You can:
+
+### Create Custom Tasks
+
+```gdscript
+class_name MyCustomTask extends BTTask
+
+@export var _some_parameter: float = 1.0
+
+func _tick(ctx: BTContext) -> BTResult:
+    # Your implementation here
+    if some_condition:
+        return BTResult.SUCCESS
+    else:
+        return BTResult.RUNNING
+```
+
+### Create Custom Conditions
+
+```gdscript
+class_name MyCustomCondition extends BTCondition
+
+func _tick(ctx: BTContext) -> bool:
+    # Your implementation here
+    return some_condition_check
+```
+
+### Create Custom Services
+
+```gdscript
+class_name MyCustomService extends BTService
+
+func _tick(ctx: BTContext) -> void:
+    # Your implementation here
+    ctx.blackboard.set_value("some_key", calculate_some_value())
+```
+
+## License
+
+This project is available under the MIT License.
+
+## Contributing
+
+Contributions are welcome! Feel free to submit pull requests or open issues for bugs and feature requests.