behavior_tree 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 31f5019e142143d5a29316f05bbd5a5763631041b6bcbba15a453c91dd0d149f
+  data.tar.gz: 6b4f1de6262f8837974101a42ed0f101559a9d9e5de8b5e1645a8d082a3d57c7
+SHA512:
+  metadata.gz: c0e4a9526e181ac5f3f3d9f2e789ac288f7ba5a45cdcb68b2b9a54f315d02d911802f7aa1b7ca3d74bd5f4b5ed2a33802e925215bdd1b6a0c495177f40ff5b41
+  data.tar.gz: d0a55cad6cecf95ae803bb83c5b00f99575a002508d5bd909129cc580382d5aaf23c5123d01be15c05069fc846386df8a3fd010adb46fa21a7ac46a6b494273d

data/lib/behavior_tree.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Load all files from lib.
+Dir[File.join(__dir__, '../', 'lib', 'behavior_tree', '**', '*.rb')].sort.each { |file| require file }

data/lib/behavior_tree/builder.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative './concerns/dsl/spell_checker'
+require_relative './concerns/dsl/initial_config'
+
+module BehaviorTree
+  # DSL for building a tree.
+  class Builder
+    @node_type_mapping = {}
+    class << self
+      include Dsl::SpellChecker
+      include Dsl::InitialConfig
+
+      def build(&block)
+        # Stack of lists. When a method like 'sequence' is executed, the resulting
+        # sequence object will be stored in the last list. Then, the whole list will
+        # be retrieved as the node children.
+        @stack = []
+
+        stack_children_from_block(block)
+        tree_main_nodes = @stack.pop
+
+        raise DSLStandardError, 'Tree main node should be a single node' if tree_main_nodes.count > 1
+
+        raise 'Tree structure is incorrect. Probably a problem with the library.' unless @stack.empty?
+
+        BehaviorTree::Tree.new tree_main_nodes.first
+      end
+
+      # Don't validate class_name, because in some situations the user wants it to be evaluated
+      # in runtime.
+      def register(node_name, class_name, children: :none)
+        valid_children_values = %i[none single multiple]
+        raise "Children value must be in: #{valid_children_values}" unless valid_children_values.include?(children)
+
+        node_name = node_name.to_sym
+        raise RegisterDSLNodeAlreadyExistsError, node_name if @node_type_mapping.key?(node_name)
+
+        @node_type_mapping[node_name] = {
+          class:    class_name,
+          children: children
+        }
+      end
+
+      def register_alias(original, alias_key)
+        unless @node_type_mapping.key?(original)
+          raise "Cannot register alias for '#{original}', since it doesn't exist."
+        end
+        raise RegisterDSLNodeAlreadyExistsError, alias_key if @node_type_mapping.key?(alias_key)
+        raise 'Alias key cannot be empty' if alias_key.to_s.empty?
+
+        @node_type_mapping[original][:alias] = alias_key
+        @node_type_mapping[alias_key] = @node_type_mapping[original].dup
+        @node_type_mapping[alias_key][:alias] = original
+      end
+
+      private
+
+      def stack(obj)
+        @stack.last << obj
+      end
+
+      # Execute @stack.pop after executing this method to
+      # extract what was pushed.
+      def stack_children_from_block(block)
+        @stack << []
+        instance_eval(&block)
+      end
+
+      def chain(node)
+        unless node.is_a?(NodeBase)
+          raise DSLStandardError, "The 'chain' keyword must be used to chain a node or subtree, not a #{node.class}"
+        end
+
+        stack node
+      end
+
+      def respond_to_missing?(method_name, _include_private)
+        @node_type_mapping.key? method_name
+      end
+
+      # Convert a class name with namespace into a constant.
+      # It returns the class itself if it's already a class.
+      # @param class_name [String]
+      # @return [Class]
+      def constantize(class_name)
+        return class_name if class_name.is_a?(Class)
+
+        class_name.split('::').compact.inject(Object) { |o, c| o.const_get c }
+      rescue NameError
+        nil
+      end
+
+      def dynamic_method_with_children(node_class, children, args, block)
+        stack_children_from_block(block)
+        final_args = [@stack.pop] + args # @stack.pop is already an Array
+        final_args.flatten! unless children == :multiple
+        stack node_class.new(*final_args)
+      end
+
+      def dynamic_method_leaf(node_class, args, block)
+        stack node_class.new(*args, &block)
+      end
+
+      def method_missing(name, *args, &block)
+        # Find by name or alias.
+        node_class_name = @node_type_mapping.dig name, :class
+
+        node_class = constantize(node_class_name)
+
+        raise_node_type_not_exists name if node_class.nil?
+
+        children = @node_type_mapping.dig(name.to_sym, :children)
+
+        # Nodes that have children are executed differently from leaf nodes.
+        if children == :none
+          dynamic_method_leaf(node_class, args, block)
+        else
+          dynamic_method_with_children(node_class, children, args, block)
+        end
+      end
+    end
+
+    BehaviorTree::Builder.initial_config
+  end
+end

data/lib/behavior_tree/concerns/dsl/dsl.yml

@@ -0,0 +1,45 @@
+dsl:
+  nodes:
+    -
+      keyword:    re_try
+      class_name: BehaviorTree::Decorators::Retry
+      children:   single
+    -
+      keyword:    inverter
+      class_name: BehaviorTree::Decorators::Inverter
+      children:   single
+    -
+      keyword:    repeater
+      class_name: BehaviorTree::Decorators::Repeater
+      children:   single
+    -
+      keyword:    force_failure
+      class_name: BehaviorTree::Decorators::ForceFailure
+      children:   single
+    -
+      keyword:    force_success
+      class_name: BehaviorTree::Decorators::ForceSuccess
+      children:   single
+    -
+      keyword:    condition
+      class_name: BehaviorTree::Decorators::Condition
+      children:   single
+    -
+      keyword:    sequence
+      class_name: BehaviorTree::Sequence
+      children:   multiple
+    -
+      keyword:    selector
+      class_name: BehaviorTree::Selector
+      children:   multiple
+    -
+      keyword:    task
+      class_name: BehaviorTree::TaskBase
+      children:   none
+  aliases:
+    sequence:  seq
+    selector:  sel
+    repeater:  rep
+    inverter:  inv
+    condition: cond
+    task:      t

data/lib/behavior_tree/concerns/dsl/initial_config.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module BehaviorTree
+  module Dsl
+    # Executes the initial registration of nodes.
+    module InitialConfig
+      def dsl_config
+        @dsl_config ||= YAML.load_file(File.join(__dir__, 'dsl.yml'))['dsl']
+      end
+
+      def initial_config
+        dsl_config['nodes'].each do |node|
+          BehaviorTree::Builder.register(
+            node['keyword'].to_sym,
+            node['class_name'],
+            children: node['children'].to_sym
+          )
+        end
+
+        dsl_config['aliases'].each do |k, v|
+          BehaviorTree::Builder.register_alias(k.to_sym, v.to_sym)
+        end
+      end
+    end
+  end
+end

data/lib/behavior_tree/concerns/dsl/spell_checker.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module BehaviorTree
+  module Dsl
+    # Helpers for spellchecking, and correcting user input in the DSL builder.
+    module SpellChecker
+      def raise_node_type_not_exists(missing_method)
+        suggestion = most_similar_name missing_method
+        method_alias = @node_type_mapping.dig suggestion, :alias
+        raise NodeTypeDoesNotExistError.new(missing_method, suggestion, method_alias)
+      end
+
+      def most_similar_name(name)
+        return nil if (defined? DidYouMean).nil?
+
+        DidYouMean::SpellChecker.new(dictionary: @node_type_mapping.keys)
+                                .correct(name)&.first
+      end
+    end
+  end
+end

data/lib/behavior_tree/concerns/node_iterators/all_nodes.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module BehaviorTree
+  module NodeIterators
+    # Iterates all nodes, without skipping or re-ordering.
+    module AllNodes
+      def all_nodes
+        @children.each
+      end
+    end
+  end
+end

data/lib/behavior_tree/concerns/node_iterators/prioritize_running.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module BehaviorTree
+  module NodeIterators
+    # If there's at least one node with 'running' status, then iterate starting from there, in order.
+    # Else, iterate all nodes.
+    module PrioritizeRunning
+      def prioritize_running
+        idx = @children.find_index { |child| child.status.running? }.to_i
+
+        Enumerator.new do |y|
+          @children[idx..].each do |child|
+            y << child
+          end
+        end
+      end
+    end
+  end
+end

data/lib/behavior_tree/concerns/tree_structure/algorithms.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module BehaviorTree
+  module TreeStructure
+    # Basic tree algorithms.
+    module Algorithms
+      def repeated_nodes
+        visited = Set.new
+        repeated_nodes = Set.new
+
+        dfs = ->(node) {
+          break repeated_nodes << node if visited.include?(node)
+
+          visited << node
+
+          node.children.each(&dfs)
+        }
+
+        dfs.(chainable_node)
+
+        repeated_nodes
+      end
+
+      def uniq_nodes?
+        repeated_nodes.empty?
+      end
+
+      def cycle?
+        current_path = Set.new
+
+        dfs = ->(node) {
+          break true if current_path.include?(node)
+
+          current_path << node
+          result = node.children.any?(&dfs)
+          current_path.delete node
+
+          result
+        }
+
+        dfs.(chainable_node)
+      end
+
+      def each_node(traversal_type = TRAVERSAL_TYPES.first, &block)
+        return enum_for(:each_node, traversal_type) unless block_given?
+
+        raise ArgumentError, "Traversal type must be in: #{TRAVERSAL_TYPES}" unless TRAVERSAL_TYPES.any?(traversal_type)
+
+        send("#{traversal_type}_node_yielder", &block)
+        nil
+      end
+
+      private
+
+      def breadth_node_yielder
+        queue = [[chainable_node, 0, self]]
+        idx = 0
+        depth = 0
+        until queue.empty?
+          node, depth, parent_node = queue.shift # Remove first
+          # Enqueue node with depth and parent.
+          queue.concat(node.children.map { |child| [child, depth + 1, node] })
+          yield(node, depth, idx, parent_node)
+          idx += 1
+        end
+      end
+
+      def depth_postorder_node_yielder
+        idx = 0
+
+        dfs = ->(node, depth, parent_node) {
+          node.children.each { |child| dfs.(child, depth + 1, node) }
+          yield(node, depth, idx, parent_node)
+          idx += 1
+        }
+
+        dfs.(chainable_node, 0, self)
+      end
+
+      def depth_preorder_node_yielder
+        idx = 0
+
+        dfs = ->(node, depth, parent_node) {
+          yield(node, depth, idx, parent_node)
+          idx += 1
+          node.children.each { |child| dfs.(child, depth + 1, node) }
+        }
+
+        dfs.(chainable_node, 0, self)
+      end
+
+      TRAVERSAL_TYPES = %i[depth_postorder depth_preorder breadth].freeze
+    end
+  end
+end

data/lib/behavior_tree/concerns/tree_structure/printer.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'colorized_string'
+
+module BehaviorTree
+  module TreeStructure
+    # Algorithm to print tree.
+    module Printer
+      def print
+        puts '∅' # Style for the root node.
+        tree_lines.each { |line| puts line }
+        puts ''
+        puts cycle_string
+        puts uniq_nodes_string
+        puts size_string
+      end
+
+      private
+
+      def tree_lines
+        # Store which depth values must continue to display a vertical line.
+        vertical_lines_continues = Set.new
+
+        each_node(:depth_preorder).map do |node, depth, _global_idx, parent_node|
+          # Parent's last child?
+          last_child = node == parent_node.children.last
+
+          last_child ? vertical_lines_continues.delete(depth) : vertical_lines_continues << depth
+
+          space = (0...depth).map { |d| vertical_lines_continues.include?(d) ? '│ ' : '  ' }.join
+          connector = last_child ? '└─' : '├─'
+
+          "#{space}#{connector}#{class_simple_name(node)} #{status_string(node)} #{tick_count_string(node)}"
+        end
+      end
+
+      def size_string
+        "Tree has #{size - 1} nodes."
+      end
+
+      def cycle_string
+        "Cycles: #{bool_yes_no(cycle?)}."
+      end
+
+      def uniq_nodes_string
+        "All nodes are unique object refs: #{bool_yes_no(uniq_nodes?)}."
+      end
+
+      def bool_yes_no(bool)
+        bool ? 'yes' : 'no'
+      end
+
+      def status_string(node)
+        if node.status.success?
+          ColorizedString['success'].colorize(:blue)
+        elsif node.status.running?
+          ColorizedString['running'].colorize(:light_green)
+        elsif node.status.failure?
+          ColorizedString['failure'].colorize(:red)
+        end
+      end
+
+      def tick_count_string(node)
+        count = node.tick_count
+        color = count.zero? ? :light_red : :light_black
+        ColorizedString["(#{node.tick_count} ticks)"].colorize(color)
+      end
+
+      # Copied from Rails' ActiveSupport.
+      def snake_case(str)
+        str.gsub(/::/, '/')
+           .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+           .tr('-', '_')
+           .downcase
+      end
+
+      def class_simple_name(node)
+        snake_case(node.class.name.split('::').last)
+      end
+    end
+  end
+end

data/lib/behavior_tree/concerns/validations/proc_or_block.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module BehaviorTree
+  module Validations
+    # Validates that only one (procedure or block) is present. None present is also valid.
+    module ProcOrBlock
+      private
+
+      def validate_proc!(procedure, block)
+        return if block.nil? && procedure.nil?
+        return if block.is_a?(Proc) ^ procedure.is_a?(Proc)
+
+        raise ArgumentError, 'Pass a lambda/proc or block to a condition decorator, but not both'
+      end
+    end
+  end
+end

data/lib/behavior_tree/concerns/validations/single_child.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module BehaviorTree
+  module Validations
+    # Validates that a node has a single node child.
+    module SingleChild
+      private
+
+      def validate_single_child!(child)
+        raise InvalidLeafNodeError if child.nil?
+        return if child.is_a?(NodeBase)
+
+        err = "This node can only have a #{NodeBase.name} object as a child. Attempted to assign #{child.class}."
+        raise TypeError, err
+      end
+    end
+  end
+end

data/lib/behavior_tree/control_nodes/control_node_base.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative '../node_base'
+require_relative '../concerns/node_iterators/prioritize_running'
+require_relative '../concerns/node_iterators/all_nodes'
+
+module BehaviorTree
+  # A node that has children (abstract class).
+  class ControlNodeBase < NodeBase
+    include NodeIterators::PrioritizeRunning
+    include NodeIterators::AllNodes
+
+    def initialize(children = [])
+      raise IncorrectTraversalStrategyError, nil.class if traversal_strategy.nil?
+      raise IncorrectTraversalStrategyError, traversal_strategy unless respond_to?(traversal_strategy, true)
+
+      super()
+      @children = children
+    end
+
+    def <<(child)
+      @children << child
+      @children.flatten! # Accepts array of children too.
+      @children.map!(&:chainable_node)
+    end
+
+    def halt!
+      validate_non_leaf!
+
+      super
+
+      @children.each(&:halt!)
+    end
+
+    protected
+
+    def on_tick
+      raise NotImplementedError, 'Must implement control logic'
+    end
+
+    def validate_non_leaf!
+      raise InvalidLeafNodeError if @children.empty?
+    end
+
+    def tick_each_children(&block)
+      return enum_for(:tick_each_children) unless block_given?
+
+      validate_non_leaf!
+
+      Enumerator.new do |y|
+        enum = send(traversal_strategy)
+        validate_enum!(enum)
+
+        enum.each do |child|
+          child.tick!
+          y << child
+        end
+      end.each(&block)
+    end
+
+    private
+
+    def traversal_strategy
+      self.class.traversal_strategy
+    end
+
+    # Keep it simple, because it's executed everytime it ticks.
+    def validate_enum!(enum)
+      raise IncorrectTraversalStrategyError, enum unless enum.respond_to? :each
+    end
+
+    class << self
+      def traversal_strategy
+        @traversal_strategy ||= ancestors.find do |constant|
+          next if constant == self
+          next unless constant.is_a? Class
+          next unless constant.respond_to? :traversal_strategy
+          next if constant.traversal_strategy.nil?
+
+          break constant.traversal_strategy
+        end
+      end
+
+      private
+
+      def children_traversal_strategy(traversal_strategy)
+        @traversal_strategy = traversal_strategy
+      end
+    end
+
+    children_traversal_strategy :prioritize_running
+  end
+end

data/lib/behavior_tree/control_nodes/selector.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative './control_node_base'
+
+module BehaviorTree
+  # A selector node.
+  class Selector < ControlNodeBase
+    def on_tick
+      tick_each_children do |child|
+        return status.running! if child.status.running?
+
+        # Both self and children have the status set to success.
+        return halt! if child.status.success?
+      end
+
+      # Halt, but set success only to children, not to self.
+      # Self status must be overriden to failure.
+      halt!
+      status.failure!
+    end
+  end
+end

data/lib/behavior_tree/control_nodes/sequence.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module BehaviorTree
+  # A sequence node.
+  class Sequence < ControlNodeBase
+    def on_tick
+      tick_each_children do |child|
+        return status.running! if child.status.running?
+
+        if child.status.failure?
+          halt!
+
+          # Halt, but set success only to children, not to self.
+          # Self status must be overriden to failure.
+          status.failure!
+          return
+        end
+      end
+
+      # Both self and children have the status set to success.
+      halt!
+    end
+  end
+end

data/lib/behavior_tree/decorator_nodes/condition.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative './decorator_base'
+require_relative '../concerns/validations/proc_or_block'
+
+module BehaviorTree
+  module Decorators
+    # Applies a condition that will decide whether to tick the decorated node or not.
+    class Condition < DecoratorBase
+      include Validations::ProcOrBlock
+
+      def initialize(child, procedure = nil, &block)
+        validate_proc!(procedure, block)
+
+        super(child)
+
+        @conditional_block = block_given? ? block : procedure
+      end
+
+      protected
+
+      def should_tick?
+        return false unless @conditional_block.is_a?(Proc)
+
+        if @conditional_block.lambda?
+          args = [@context, self].take @conditional_block.arity
+          @conditional_block.(*args)
+        else
+          instance_eval(&@conditional_block)
+        end
+      end
+
+      def status_map
+        if @tick_prevented
+          status.failure!
+        else
+          self.status = child.status
+        end
+      end
+
+      private
+
+      attr_reader :context
+    end
+  end
+end

data/lib/behavior_tree/decorator_nodes/decorator_base.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative '../single_child_node'
+
+module BehaviorTree
+  module Decorators
+    # Base class for a decorator node.
+    class DecoratorBase < SingleChildNodeBase
+      def on_tick
+        super
+        decorate
+      end
+
+      def ensure_after_tick
+        status_map
+      end
+
+      def halt!
+        super
+
+        status_map
+      end
+
+      protected
+
+      # Decorate behavior. Retry, repeat, etc.
+      # Leave empty if there's no extra behavior to add.
+      # Default behavior is to do nothing additional.
+      # @return [void]
+      def decorate; end
+
+      # This method must change the self node status in function
+      # of the child status. The default behavior is to copy its status.
+      # @return [void]
+      def status_map
+        self.status = child.status
+      end
+    end
+  end
+end

data/lib/behavior_tree/decorator_nodes/force_failure.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module BehaviorTree
+  module Decorators
+    # Returns always failure when the child is not running.
+    class ForceFailure < DecoratorBase
+      protected
+
+      def status_map
+        return status.running! if child.status.running?
+
+        status.failure!
+      end
+    end
+  end
+end

data/lib/behavior_tree/decorator_nodes/force_success.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module BehaviorTree
+  module Decorators
+    # Returns always success when the child is not running.
+    class ForceSuccess < DecoratorBase
+      protected
+
+      def status_map
+        return status.running! if child.status.running?
+
+        status.success!
+      end
+    end
+  end
+end

data/lib/behavior_tree/decorator_nodes/inverter.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative './decorator_base'
+
+module BehaviorTree
+  module Decorators
+    # Returns the inverted child status.
+    class Inverter < DecoratorBase
+      protected
+
+      def status_map
+        return status.running! if child.status.running?
+        return status.failure! if child.status.success?
+        return status.success! if child.status.failure?
+      end
+    end
+  end
+end

data/lib/behavior_tree/decorator_nodes/repeat_times_base.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module BehaviorTree
+  module Decorators
+    # While the node status is <repeat_while>, tick it again up to N times.
+    # Interrupt the loop when the <repeat_while> condition fails.
+    # If the child returns running, this node returns running too.
+    # The count is resetted when the loop is interrupted or finished.
+    # N is the total times to be ticked, and it includes the initial tick (the
+    # original tick that all nodes have in common).
+    class RepeatTimesBase < DecoratorBase
+      def initialize(child, max)
+        validate_max!(max)
+        super(child)
+
+        @max = max
+        reset_remaining_attempts
+      end
+
+      def decorate
+        while repeat_while || child.status.running?
+          break if child.status.running?
+
+          @remaining_attempts -= 1
+          break unless @remaining_attempts.positive?
+
+          child.tick!
+          break if child.status.running?
+        end
+      end
+
+      def ensure_after_tick
+        status_map
+      end
+
+      protected
+
+      def repeat_while
+        raise NotImplementedError
+      end
+
+      private
+
+      def reset_remaining_attempts
+        @remaining_attempts = @max
+      end
+
+      def validate_max!(max)
+        return if max.is_a?(Integer) && max.positive?
+
+        raise ArgumentError, 'Number of repetitions must be a positive integer.'
+      end
+    end
+
+    private_constant :RepeatTimesBase
+  end
+end

data/lib/behavior_tree/decorator_nodes/repeater.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative './repeat_times_base'
+
+module BehaviorTree
+  module Decorators
+    # Repeat N times while child has success status.
+    class Repeater < RepeatTimesBase
+      protected
+
+      def repeat_while
+        child.status.success?
+      end
+    end
+  end
+end

data/lib/behavior_tree/decorator_nodes/retry.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module BehaviorTree
+  module Decorators
+    # Repeat N times while child has failure status.
+    class Retry < RepeatTimesBase
+      protected
+
+      def repeat_while
+        child.status.failure?
+      end
+    end
+  end
+end

data/lib/behavior_tree/errors.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module BehaviorTree
+  # Exception for when the children traversal strategy is incorrect.
+  class IncorrectTraversalStrategyError < StandardError
+    def initialize(value)
+      err = [
+        "Strategy for iterating children nodes must return an object which has an 'each' method.",
+        "Attempted to use strategy: #{value}."
+      ]
+      super err.join ' '
+    end
+  end
+
+  # Exception raised when the main node of a tree is of invalid type.
+  class InvalidTreeMainNodeError < StandardError
+    def initialize(node_type)
+      super "Cannot chain #{node_type} to the root node of a tree. Valid types are: #{Tree::CHILD_VALID_CLASSES}."
+    end
+  end
+
+  # Exception for control nodes without children.
+  class InvalidLeafNodeError < StandardError
+    def initialize
+      super 'This node cannot be a leaf node.'
+    end
+  end
+
+  # Exception for when a node has an incorrect status value.
+  class IncorrectStatusValueError < StandardError
+    def initialize(value)
+      super "Incorrect status value. A node cannot have '#{value}' status."
+    end
+  end
+
+  # Exception for incorrect node type when using the DSL builder.
+  class NodeTypeDoesNotExistError < StandardError
+    def initialize(missing_method, suggestion, method_alias)
+      suggestion = suggestion.to_s
+      method_alias = method_alias.to_s
+
+      err = ["Node type '#{missing_method}' does not exist."]
+      unless suggestion.empty?
+        alias_text = method_alias.empty? ? '' : " (alias of #{method_alias})"
+        err << "Did you mean '#{suggestion}'#{alias_text}?"
+      end
+
+      super err.join ' '
+    end
+  end
+
+  # Exception for misuse of the DSL builder.
+  class DSLStandardError < StandardError
+    def initialize(message)
+      super "Cannot build tree (DSL Builder): #{message}"
+    end
+  end
+
+  # Exception for when trying to register a DSL keyword that already exists.
+  class RegisterDSLNodeAlreadyExistsError < StandardError
+    def initialize(node_type)
+      super "Cannot register node '#{node_type}', it already exists."
+    end
+  end
+end

data/lib/behavior_tree/node_base.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative './concerns/tree_structure/algorithms'
+
+module BehaviorTree
+  # A node (abstract class).
+  class NodeBase
+    include TreeStructure::Algorithms
+    attr_reader :status, :tick_count, :ticks_running, :arbitrary_storage
+
+    def initialize
+      @status = NodeStatus.new NodeStatus::SUCCESS
+      @tick_count = 0
+      @ticks_running = 0
+      @context = nil
+
+      @status.subscribe { |prev, curr| on_status_change(prev, curr) }
+
+      @arbitrary_storage = {}
+    end
+
+    def context=(context)
+      @context = context
+
+      # Propagate context.
+      children.each do |child|
+        child.context = context
+      end
+    end
+
+    def size
+      1 + children.map(&:size).sum
+    end
+
+    def tick!
+      @tick_count += 1
+      @tick_prevented = !should_tick?
+
+      unless @tick_prevented
+        status.running!
+        on_tick
+        @ticks_running += 1
+      end
+
+      ensure_after_tick
+
+      # NOTE: Make sure this method returns nil. Since 'ensure_after_tick' might return
+      #       the node status, it generates some error in IRB (unknown cause).
+      #
+      #       This error can be replicated by pasting a valid status object in IRB, such as by doing:
+      #       BehaviorTree.const_get(:NodeStatus).new(:__running__) # Valid, but IRB crashes.
+      nil
+    end
+
+    def children
+      if @children.is_a?(Array)
+        @children
+      elsif @child.is_a?(NodeBase)
+        [@child]
+      else
+        []
+      end
+    end
+
+    def chainable_node
+      self
+    end
+
+    def []=(key, value)
+      @arbitrary_storage[key] = value
+    end
+
+    def [](key)
+      @arbitrary_storage[key]
+    end
+
+    def status=(other_status)
+      status.running! if other_status.running?
+      status.failure! if other_status.failure?
+      status.success! if other_status.success?
+    end
+
+    def halt!
+      status.success!
+    end
+
+    protected
+
+    # If this value is false, @tick_prevented will be set to true, which can be handled in other
+    # tick callbacks.
+    def should_tick?
+      true
+    end
+
+    def on_tick; end
+
+    def ensure_after_tick; end
+
+    def on_started_running; end
+
+    def on_finished_running; end
+
+    private
+
+    # Always prev != curr (states that are set to the same aren't notified).
+    # The fact that it's set to 0 means that setting to running must be done before
+    # increasing the counts (so that @ticks_running becomes 1 after the whole tick lifecycle).
+    def on_status_change(prev, curr)
+      if prev == NodeStatus::RUNNING
+        on_finished_running
+      elsif curr == NodeStatus::RUNNING
+        @ticks_running = 0
+        on_started_running
+      end
+    end
+  end
+
+  private_constant :NodeBase
+end

data/lib/behavior_tree/node_status.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module BehaviorTree
+  # Status for nodes.
+  class NodeStatus
+    SUCCESS = :__success__
+    RUNNING = :__running__
+    FAILURE = :__failure__
+
+    def initialize(value)
+      set(value)
+    end
+
+    def set(value)
+      return if value == @value
+      raise IncorrectStatusValueError, value unless [SUCCESS, RUNNING, FAILURE].include?(value)
+
+      prev = @value
+
+      @value = value
+
+      # NOTE: Make sure to notify after having set the @value above, so that the new status is already set.
+      @subscriber&.(prev, value)
+    end
+
+    def subscribe(&subscriber)
+      @subscriber = subscriber
+    end
+
+    def ==(other)
+      to_sym == other.to_sym
+    end
+
+    def inspect
+      to_sym
+    end
+
+    def to_sym
+      return :success if success?
+      return :running if running?
+      return :failure if failure?
+    end
+
+    def success!
+      set(SUCCESS)
+    end
+
+    def running!
+      set(RUNNING)
+    end
+
+    def failure!
+      set(FAILURE)
+    end
+
+    def success?
+      @value == SUCCESS
+    end
+
+    def running?
+      @value == RUNNING
+    end
+
+    def failure?
+      @value == FAILURE
+    end
+  end
+
+  private_constant :NodeStatus
+end

data/lib/behavior_tree/single_child_node.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative './node_base'
+require_relative './concerns/validations/single_child'
+
+module BehaviorTree
+  # A node that has a single child (abstract class).
+  class SingleChildNodeBase < NodeBase
+    include Validations::SingleChild
+    attr_reader :child
+
+    def initialize(child)
+      validate_single_child! child
+      super()
+      @child = child.chainable_node
+    end
+
+    def on_tick
+      @child.tick!
+    end
+
+    def halt!
+      super
+      @child.halt!
+    end
+  end
+
+  private_constant :SingleChildNodeBase
+end

data/lib/behavior_tree/tasks/nop.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative './task_base'
+
+module BehaviorTree
+  # An empty task that does not do anything.
+  # It requires N ticks to complete.
+  # It can be set to end with failure.
+  class Nop < TaskBase
+    def initialize(necessary_ticks = 1, completes_with_failure: false)
+      raise ArgumentError, 'Should need at least one tick' if necessary_ticks < 1
+
+      super()
+      @necessary_ticks = necessary_ticks
+      @completes_with_status = completes_with_failure ? NodeStatus::FAILURE : NodeStatus::SUCCESS
+      reset_remaining_attempts
+    end
+
+    def on_tick
+      @remaining_ticks -= 1
+      return if @remaining_ticks.positive?
+
+      status.set @completes_with_status
+      reset_remaining_attempts
+    end
+
+    def halt!
+      super
+      reset_remaining_attempts
+    end
+
+    private
+
+    def reset_remaining_attempts
+      @remaining_ticks = @necessary_ticks
+    end
+  end
+end

data/lib/behavior_tree/tasks/task_base.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative '../node_base'
+require_relative '../concerns/validations/proc_or_block'
+
+module BehaviorTree
+  # A task (leaf) node.
+  class TaskBase < NodeBase
+    include Validations::ProcOrBlock
+
+    def initialize(procedure = nil, &block)
+      validate_proc!(procedure, block)
+
+      super()
+
+      @task_block = block_given? ? block : procedure
+    end
+
+    def on_tick
+      raise 'Node should be set to running' unless status.running?
+      return unless @task_block.is_a?(Proc)
+
+      if @task_block.lambda?
+        args = [@context, self].take @task_block.arity
+        @task_block.(*args)
+      else
+        instance_eval(&@task_block)
+      end
+    end
+
+    private
+
+    attr_reader :context
+  end
+
+  Task = TaskBase
+end

data/lib/behavior_tree/tree.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module BehaviorTree
+  # Root node of the tree.
+  # This is the class that must be instantiated by the user.
+  class Tree < SingleChildNodeBase
+    include TreeStructure::Algorithms
+    include TreeStructure::Printer
+    attr_reader :context
+
+    CHILD_VALID_CLASSES = [
+      Decorators::DecoratorBase, ControlNodeBase, TaskBase
+    ].freeze
+
+    def initialize(child)
+      super(child) if child.nil? # Cannot be leaf, raise error.
+
+      if CHILD_VALID_CLASSES.any? { |node_class| child.is_a?(NodeBase) && child.chainable_node.is_a?(node_class) }
+        super(child)
+        return
+      end
+
+      raise InvalidTreeMainNodeError, child.class
+    end
+
+    def chainable_node
+      @child
+    end
+
+    def ensure_after_tick
+      # Copy the main node status to self.
+      self.status = child.status
+    end
+  end
+end

data/lib/behavior_tree/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BehaviorTree
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: behavior_tree
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Felo Vilches
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-07-15 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- felovilches@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- "./lib/behavior_tree.rb"
+- "./lib/behavior_tree/builder.rb"
+- "./lib/behavior_tree/concerns/dsl/dsl.yml"
+- "./lib/behavior_tree/concerns/dsl/initial_config.rb"
+- "./lib/behavior_tree/concerns/dsl/spell_checker.rb"
+- "./lib/behavior_tree/concerns/node_iterators/all_nodes.rb"
+- "./lib/behavior_tree/concerns/node_iterators/prioritize_running.rb"
+- "./lib/behavior_tree/concerns/tree_structure/algorithms.rb"
+- "./lib/behavior_tree/concerns/tree_structure/printer.rb"
+- "./lib/behavior_tree/concerns/validations/proc_or_block.rb"
+- "./lib/behavior_tree/concerns/validations/single_child.rb"
+- "./lib/behavior_tree/control_nodes/control_node_base.rb"
+- "./lib/behavior_tree/control_nodes/selector.rb"
+- "./lib/behavior_tree/control_nodes/sequence.rb"
+- "./lib/behavior_tree/decorator_nodes/condition.rb"
+- "./lib/behavior_tree/decorator_nodes/decorator_base.rb"
+- "./lib/behavior_tree/decorator_nodes/force_failure.rb"
+- "./lib/behavior_tree/decorator_nodes/force_success.rb"
+- "./lib/behavior_tree/decorator_nodes/inverter.rb"
+- "./lib/behavior_tree/decorator_nodes/repeat_times_base.rb"
+- "./lib/behavior_tree/decorator_nodes/repeater.rb"
+- "./lib/behavior_tree/decorator_nodes/retry.rb"
+- "./lib/behavior_tree/errors.rb"
+- "./lib/behavior_tree/node_base.rb"
+- "./lib/behavior_tree/node_status.rb"
+- "./lib/behavior_tree/single_child_node.rb"
+- "./lib/behavior_tree/tasks/nop.rb"
+- "./lib/behavior_tree/tasks/task_base.rb"
+- "./lib/behavior_tree/tree.rb"
+- "./lib/behavior_tree/version.rb"
+homepage: https://github.com/FeloVilches/Ruby-Behavior-Tree
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: Behavior Tree (AI) library for Ruby.
+test_files: []