GHA: Split & package debug symbols for GDExtension editor libs

This reverts commit fe87a87759.

.github/workflows/gdextension.yml

@@ -41,7 +41,7 @@ on:
 # Global Settings
 env:
   SCONS_CACHE_LIMIT: 4096
-  SCONSFLAGS: use_mingw=yes dev_build=no
+  SCONSFLAGS: use_mingw=yes dev_build=no verbose=yes
   EM_VERSION: 3.1.45
   EM_CACHE_FOLDER: "emsdk-cache"
   GODOT_VERSION: 4.3-stable
@@ -61,6 +61,8 @@ jobs:
             platform: linux
             target: template_release
             arch: x86_64
+            debug-symbols: ${{ inputs.debug-symbols }}
+            bin: liblimboai.linux.template_release.x86_64.so
             should-build: true
 
           - name: 🐧 Linux (x86_64, debug)
@@ -68,20 +70,26 @@ jobs:
             platform: linux
             target: editor
             arch: x86_64
+            debug-symbols: true
+            bin: liblimboai.linux.editor.x86_64.so
             should-build: true
 
           - name: 🪟 Windows (x86_64, release)
-            runner: windows-latest
+            runner: ubuntu-latest
             platform: windows
             target: template_release
             arch: x86_64
+            debug-symbols: ${{ inputs.debug-symbols }}
+            bin: liblimboai.windows.template_release.x86_64.dll
             should-build: true
 
           - name: 🪟 Windows (x86_64, debug)
-            runner: windows-latest
+            runner: ubuntu-latest
             platform: windows
             target: editor
             arch: x86_64
+            debug-symbols: true
+            bin: liblimboai.windows.editor.x86_64.dll
             should-build: true
 
           - name: 🍎 macOS (universal, release)
@@ -89,6 +97,8 @@ jobs:
             platform: macos
             target: template_release
             arch: universal
+            debug-symbols: ${{ inputs.debug-symbols }}
+            bin: liblimboai.macos.template_release
             should-build: true
 
           - name: 🍎 macOS (universal, debug)
@@ -96,6 +106,8 @@ jobs:
             platform: macos
             target: editor
             arch: universal
+            debug-symbols: true
+            bin: liblimboai.macos.editor
             should-build: true
 
           - name: 🌐 Web (wasm32, release)
@@ -103,6 +115,8 @@ jobs:
             platform: web
             target: template_release
             arch: wasm32
+            debug-symbols: ${{ inputs.debug-symbols }}
+            bin: liblimboai.web.template_release.wasm32.wasm
             should-build: ${{ !inputs.test-build }}
 
           - name: 🌐 Web (wasm32, debug)
@@ -110,6 +124,8 @@ jobs:
             platform: web
             target: template_debug
             arch: wasm32
+            debug-symbols: ${{ inputs.debug-symbols }}
+            bin: liblimboai.web.template_debug.wasm32.wasm
             should-build: ${{ !inputs.test-build }}
 
           - name: 🤖 Android (arm64, release)
@@ -117,6 +133,8 @@ jobs:
             platform: android
             target: template_release
             arch: arm64
+            debug-symbols: ${{ inputs.debug-symbols }}
+            bin: liblimboai.android.template_release.arm64.so
             should-build: ${{ !inputs.test-build }}
 
           - name: 🤖 Android (arm64, debug)
@@ -124,6 +142,8 @@ jobs:
             platform: android
             target: template_debug
             arch: arm64
+            debug-symbols: ${{ inputs.debug-symbols }}
+            bin: liblimboai.android.template_debug.arm64.so
             should-build: ${{ !inputs.test-build }}
 
           - name: 🤖 Android (arm32, release)
@@ -131,6 +151,8 @@ jobs:
             platform: android
             target: template_release
             arch: arm32
+            debug-symbols: ${{ inputs.debug-symbols }}
+            bin: liblimboai.android.template_release.arm32.so
             should-build: ${{ !inputs.test-build }}
 
           - name: 🤖 Android (arm32, debug)
@@ -138,6 +160,8 @@ jobs:
             platform: android
             target: template_debug
             arch: arm32
+            debug-symbols: ${{ inputs.debug-symbols }}
+            bin: liblimboai.android.template_debug.arm32.so
             should-build: ${{ !inputs.test-build }}
 
           - name: 🤖 Android (x86_64, release)
@@ -145,6 +169,8 @@ jobs:
             platform: android
             target: template_release
             arch: x86_64
+            debug-symbols: ${{ inputs.debug-symbols }}
+            bin: liblimboai.android.template_release.x86_64.so
             should-build: ${{ !inputs.test-build }}
 
           - name: 🤖 Android (x86_64, debug)
@@ -152,6 +178,8 @@ jobs:
             platform: android
             target: template_debug
             arch: x86_64
+            debug-symbols: ${{ inputs.debug-symbols }}
+            bin: liblimboai.android.template_debug.x86_64.so
             should-build: ${{ !inputs.test-build }}
 
           - name: 🤖 Android (x86_32, release)
@@ -159,6 +187,8 @@ jobs:
             platform: android
             target: template_release
             arch: x86_32
+            debug-symbols: ${{ inputs.debug-symbols }}
+            bin: liblimboai.android.template_release.x86_32.so
             should-build: ${{ !inputs.test-build }}
 
           - name: 🤖 Android (x86_32, debug)
@@ -166,6 +196,8 @@ jobs:
             platform: android
             target: template_debug
             arch: x86_32
+            debug-symbols: ${{ inputs.debug-symbols }}
+            bin: liblimboai.android.template_debug.x86_32.so
             should-build: ${{ !inputs.test-build }}
 
           - name: 🍏 iOS (arm64, release)
@@ -173,6 +205,8 @@ jobs:
             platform: ios
             target: template_release
             arch: arm64
+            debug-symbols: ${{ inputs.debug-symbols }}
+            bin: liblimboai.ios.template_release.arm64.dylib
             should-build: ${{ !inputs.test-build }}
 
           - name: 🍏 iOS (arm64, debug)
@@ -180,6 +214,8 @@ jobs:
             platform: ios
             target: template_debug
             arch: arm64
+            debug-symbols: ${{ inputs.debug-symbols }}
+            bin: liblimboai.ios.template_debug.arm64.dylib
             should-build: ${{ !inputs.test-build }}
 
           - name: 🍏 iOS (simulator, release)
@@ -187,7 +223,9 @@ jobs:
             platform: ios
             target: template_release
             arch: universal
+            debug-symbols: ${{ inputs.debug-symbols }}
             scons-flags: ios_simulator=yes
+            bin: liblimboai.ios.template_release.universal.simulator.dylib
             should-build: ${{ !inputs.test-build }}
 
           - name: 🍏 iOS (simulator, debug)
@@ -195,15 +233,14 @@ jobs:
             platform: ios
             target: template_debug
             arch: universal
+            debug-symbols: ${{ inputs.debug-symbols }}
             scons-flags: ios_simulator=yes
+            bin: liblimboai.ios.template_debug.universal.simulator.dylib
             should-build: ${{ !inputs.test-build }}
 
         exclude:
           - { opts: { should-build: false } }
 
-    env:
-      BIN: liblimboai.${{matrix.opts.platform}}.${{matrix.opts.target}}.${{matrix.opts.arch}}
-
     steps:
       - name: Clone LimboAI module
         uses: actions/checkout@v4
@@ -280,30 +317,65 @@ jobs:
           ndk-version: r23c
           link-to-sdk: true
 
-      - name: Set up MSVC problem matcher on Windows
-        if: matrix.opts.platform == 'windows'
-        uses: ammaraskar/msvc-problem-matcher@master
-
       - name: Set up scons cache
         if: inputs.test-build # ! Only cache test/PR builds
         uses: actions/cache@v4
         with:
           path: ${{github.workspace}}/.scons_cache/
-          key: ${{env.BIN}}-${{inputs.debug-symbols}}-${{inputs.godot-cpp-ref}}-${{inputs.limboai-ref}}-${{env.LIMBOAI_VERSION}}
+          key: ${{matrix.opts.bin}}-${{matrix.opts.debug-symbols}}-${{inputs.godot-cpp-ref}}-${{inputs.limboai-ref}}-${{env.LIMBOAI_VERSION}}
           restore-keys: |
-            ${{env.BIN}}-${{inputs.debug-symbols}}-${{inputs.godot-cpp-ref}}-${{inputs.limboai-ref}}-${{env.LIMBOAI_VERSION}}
-            ${{env.BIN}}-${{inputs.debug-symbols}}-${{inputs.godot-cpp-ref}}-${{inputs.limboai-ref}}
-            ${{env.BIN}}-${{inputs.debug-symbols}}-${{inputs.godot-cpp-ref}}
+            ${{matrix.opts.bin}}-${{matrix.opts.debug-symbols}}-${{inputs.godot-cpp-ref}}-${{inputs.limboai-ref}}-${{env.LIMBOAI_VERSION}}
+            ${{matrix.opts.bin}}-${{matrix.opts.debug-symbols}}-${{inputs.godot-cpp-ref}}-${{inputs.limboai-ref}}
+            ${{matrix.opts.bin}}-${{matrix.opts.debug-symbols}}-${{inputs.godot-cpp-ref}}
+
+      - name: Set up MinGW
+        if: matrix.opts.platform == 'windows'
+        run: |
+          sudo apt update
+          sudo apt install g++-mingw-w64-x86-64-posix
 
       - name: Compilation
         shell: bash
         env:
           SCONS_CACHE: ${{github.workspace}}/.scons_cache/
-          DEBUG_FLAGS: ${{ inputs.debug-symbols && 'debug_symbols=yes symbols_visibility=visible' || 'debug_symbols=no' }}
+          DEBUG_FLAGS: ${{ matrix.opts.debug-symbols && 'debug_symbols=yes symbols_visibility=visible' || 'debug_symbols=no' }}
         run: |
           PATH=${GITHUB_WORKSPACE}/buildroot/bin:$PATH
           scons platform=${{matrix.opts.platform}} target=${{matrix.opts.target}} arch=${{matrix.opts.arch}} ${{env.DEBUG_FLAGS}} ${{matrix.opts.scons-flags}} ${{env.SCONSFLAGS}}
 
+      - name: Split debug symbols (Linux)
+        if: matrix.opts.debug-symbols && matrix.opts.platform == 'linux'
+        shell: bash
+        run: |
+          cd demo/addons/limboai/bin/
+          objcopy --only-keep-debug ${{matrix.opts.bin}} ${{matrix.opts.bin}}.debug
+          objcopy --add-gnu-debuglink ${{matrix.opts.bin}}.debug ${{matrix.opts.bin}}
+          strip --strip-debug ${{matrix.opts.bin}}
+          readelf --debug-dump=links ${{matrix.opts.bin}}
+          nm ${{matrix.opts.bin}}
+
+      - name: Split debug symbols (Windows)
+        if: matrix.opts.debug-symbols && matrix.opts.platform == 'windows'
+        shell: bash
+        run: |
+          cd demo/addons/limboai/bin/
+          x86_64-w64-mingw32-objcopy --only-keep-debug ${{matrix.opts.bin}} ${{matrix.opts.bin}}.debug
+          x86_64-w64-mingw32-objcopy --add-gnu-debuglink ${{matrix.opts.bin}}.debug ${{matrix.opts.bin}}
+          x86_64-w64-mingw32-strip --strip-debug ${{matrix.opts.bin}}
+          x86_64-w64-mingw32-nm ${{matrix.opts.bin}}
+
+      - name: Split debug symbols (macOS & iOS)
+        if: matrix.opts.debug-symbols && (matrix.opts.platform == 'macos' || matrix.opts.platform == 'ios')
+        shell: bash
+        run: |
+          cd demo/addons/limboai/bin/
+          if [ "${{matrix.opts.platform}}" == "macos" ]; then
+            cd liblimboai.*.framework/
+          fi
+          dsymutil ${{matrix.opts.bin}}
+          strip -x ${{matrix.opts.bin}}
+          nm ${{matrix.opts.bin}}
+
       - name: Prepare artifact
         shell: bash
         run: |
@@ -313,18 +385,30 @@ jobs:
           cp {README,LICENSE,LOGO_LICENSE}.md out/addons/limboai/
           cp -R demo/demo/ out/demo/
           cp demo/LICENSE_ASSETS.md out/demo/
-          rm -f out/addons/limboai/bin/*.{exp,lib,pdb}
+          rm -f out/addons/limboai/bin/*.{exp,lib}
           echo "${LIMBOAI_VERSION}" > out/addons/limboai/version.txt
           echo "---"
           ls -R out/
 
       - name: Upload artifact
         uses: actions/upload-artifact@v4
-        env:
-          NAME: tmp-gdextension.${{matrix.opts.platform}}.${{matrix.opts.target}}.${{matrix.opts.arch}}
         with:
-          name: ${{ env.NAME }}
-          path: out/*
+          name: tmp-gdextension.${{matrix.opts.platform}}.${{matrix.opts.target}}.${{matrix.opts.arch}}
+          path: |
+            out/*
+            !out/**/*.debug
+            !out/**/*.pdb
+            !out/**/*.dSYM
+
+      - name: Upload debug symbols
+        if: matrix.opts.debug-symbols
+        uses: actions/upload-artifact@v4
+        with:
+          name: tmp-gdextension-symbols.${{matrix.opts.platform}}.${{matrix.opts.target}}.${{matrix.opts.arch}}
+          path: |
+            out/**/*.debug
+            out/**/*.pdb
+            out/**/*.dSYM
 
   package-extension:
     name: 📦 Package extension
@@ -339,6 +423,13 @@ jobs:
           pattern: tmp-gdextension.*
           delete-merged: true
 
+      - name: Merge debug symbols artifacts
+        uses: actions/upload-artifact/merge@v4
+        with:
+          name: ${{needs.gdextension.outputs.name-prefix}}.debug-symbols
+          pattern: tmp-gdextension-symbols.*
+          delete-merged: true
+
       - name: Download artifact
         uses: actions/download-artifact@v4
         with:

README.md

@@ -121,7 +121,8 @@ LimboAI can be used as either a C++ module or as a GDExtension shared library. G
 
 ## Contributing
 
-Contributions are welcome! Please open issues for bug reports, feature requests, or code changes. Keep the minor versions backward-compatible when submitting pull requests.
+Contributions are welcome! Please open issues for bug reports, feature requests, or code changes.
+For detailed guidelines on contributing to code or documentation, check out our [Contributing](https://limboai.readthedocs.io/en/latest/getting-started/contributing.html) page.
 
 If you have an idea for a behavior tree task or a feature that could be useful in a variety of projects, open an issue to discuss it.
 

bt/tasks/decorators/bt_new_scope.cpp

@@ -35,7 +35,7 @@ void BTNewScope::_set_parent_scope_plan_from_bt() {
 	ERR_FAIL_NULL(get_blackboard_plan());
 	Ref<BehaviorTree> bt = get_root()->editor_get_behavior_tree();
 	ERR_FAIL_NULL(bt);
-	get_blackboard_plan()->set_parent_scope_plan_provider(callable_mp(bt.ptr(), &BehaviorTree::get_blackboard_plan));
+	get_blackboard_plan()->set_parent_scope_plan_provider(Callable(bt.ptr(), "get_blackboard_plan"));
 }
 #endif // TOOLS_ENABLED
 

doc/source/.readthedocs.yaml

@@ -32,4 +32,6 @@ sphinx:
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
   install:
-    - requirements: doc/source/requirements.txt
+    - requirements: doc/source/requirements.txt
+
+formats: all

doc/source/behavior-trees/create-tree.rst

@@ -0,0 +1,24 @@
+.. _create_tree::
+
+Creating Behavior Trees
+=======================
+
+This chapter describes how to create and debug behavior trees.
+
+Add a Behavior Tree to an agent
+-------------------------------
+
+Follow these steps to add a behavior tree to a new or existing agent:
+
+1. Make a scene file for your agent, or open an existing scene.
+2. Add a :ref:`BTPlayer<class_BTPlayer>` node to your scene.
+3. Select :ref:`BTPlayer<class_BTPlayer>`, and create a new behavior tree in the inspector.
+4. Optionally, you can save the behavior tree to a file using the property's context menu.
+5. Click the behavior tree property to open it in the LimboAI editor.
+
+Debugging Behavior Trees
+------------------------
+
+In Godot Engine, follow to "Bottom Panel > Debugger > LimboAI" tab. With the LimboAI debugger,
+you can inspect any currently active behavior tree within the running project. The debugger can be detached
+from the main editor window, which can be particularly useful if you have a HiDPI or a secondary display.

doc/source/behavior-trees/custom-tasks.rst

@@ -1,7 +1,7 @@
 .. _custom_tasks:
 
-Creating custom tasks in GDScript
-=================================
+Creating custom tasks
+=====================
 
 By default, user tasks should be placed in the ``res://ai/tasks``
 directory. You can set an alternative location for user tasks in the
@@ -145,3 +145,47 @@ Example 2: InRange condition
            return SUCCESS
        else:
            return FAILURE
+
+.. _creating_tasks_in_c
+
+Creating tasks in C#
+--------------------
+
+You can use the following script template for custom tasks:
+
+.. code:: csharp
+
+    using Godot;
+    using System;
+
+    [Tool]
+    public partial class _CLASS_ : _BASE_
+    {
+        public override string _GenerateName()
+        {
+            return "_CLASS_";
+        }
+
+        public override void _Setup()
+        {
+        }
+
+        public override void _Enter()
+        {
+        }
+
+        public override void _Exit()
+        {
+        }
+
+        public override Status _Tick(double delta)
+        {
+            return Status.Success;
+        }
+
+        public override string[] _GetConfigurationWarnings()
+        {
+            return Array.Empty<string>();
+        }
+    }
+

doc/source/getting-started/c-sharp.rst

@@ -21,47 +21,3 @@ Each provided build comes with a GodotSharp folder, which has packages under
 Regarding GDExtension, I can only confirm success with the module version and C#.
 Unfortunately, I haven't had any luck with the GDExtension version yet.
 If you've had success with GDExtension, please let me know via Discord or email.
-
-Creating custom tasks in C#
----------------------------
-
-   **🛈 Note:** For more information, check out :ref:`creating custom tasks in GDScript <custom_tasks>`.
-
-You can use the following script template for custom tasks:
-
-.. code:: csharp
-
-    using Godot;
-    using System;
-
-    [Tool]
-    public partial class _CLASS_ : _BASE_
-    {
-        public override string _GenerateName()
-        {
-            return "_CLASS_";
-        }
-
-        public override void _Setup()
-        {
-        }
-
-        public override void _Enter()
-        {
-        }
-
-        public override void _Exit()
-        {
-        }
-
-        public override Status _Tick(double delta)
-        {
-            return Status.Success;
-        }
-
-        public override string[] _GetConfigurationWarnings()
-        {
-            return Array.Empty<string>();
-        }
-    }
-

doc/source/getting-started/contributing.rst

@@ -0,0 +1,70 @@
+.. _contributing:
+
+Contributing
+============
+
+We target the latest stable version of the Godot Engine for development until a
+third beta or a release candidate of an upcoming Godot release becomes available.
+If you want to contribute to the project, please ensure that you are using the
+corresponding Godot version.
+
+We follow the `Godot code style guidelines <https://docs.godotengine.org/en/stable/contributing/development/code_style_guidelines.html#doc-code-style-guidelines>`_.
+Please use ``clang-format`` to maintain consistent styling. You can install
+``pre-commit`` hooks for Git using ``pre-commit install`` to automate this process.
+
+Please keep the minor versions backward-compatible when submitting pull requests.
+
+We support building LimboAI as a module for the Godot Engine and as a GDExtension library.
+Make sure your contribution is compatible with both. Our CI workflow will verify
+that your changes can be compiled in both configurations.
+
+Compiling as module of the Godot Engine
+---------------------------------------
+
+1. Clone the Godot Engine repository.
+2. Switch to the latest stable tag.
+3. Clone the LimboAI repository into the ``modules/limboai`` directory.
+
+.. code-block:: bash
+
+   git clone https://github.com/godotengine/godot.git
+   git checkout 4.3-stable  # Replace "4.3-stable" with the latest stable tag
+   git clone https://github.com/limbonaut/limboai modules/limboai
+
+Consult the `Godot Engine documentation <https://docs.godotengine.org/en/stable/contributing/development/compiling/index.html>`_
+for detailed instructions on building the engine.
+
+**Unit tests** can be compiled using the ``tests=yes`` build option. To execute them,
+run the compiled Godot binary with the ``--test --tc="*[LimboAI]*"`` command-line options.
+
+Compiling as GDExtension library
+--------------------------------
+
+You'll need the SCons build tool and a C++ compiler. See also `Compiling <https://docs.godotengine.org/en/stable/contributing/development/compiling/index.html>`_.
+Run ``scons target=editor`` to build the plugin library for your current platform.
+
+- SCons will automatically clone the ``godot-cpp`` repository if it doesn't already exist in the ``limboai/godot-cpp`` directory.
+- By default, built targets are placed in the demo project: ``demo/addons/limboai/bin/``.
+
+Check ``scons -h`` for other options and targets.
+
+Contributing to the documentation
+---------------------------------
+
+Online documentation is created using `Sphinx <https://www.sphinx-doc.org/en/master/>`_.
+Source files are located in the ``doc/source`` directory in RST format and can
+be built locally with ``sphinx-build``. See the
+`Sphinx documentation <https://www.sphinx-doc.org/en/master/tutorial/getting-started.html>`_
+for more details.
+
+Class documentation resides in XML files within the ``doc_classes/`` directory.
+If you create a new class or modify an existing one, you can run the compiled
+Godot binary with the ``--doctool`` option in the root of the Godot source code
+to generate the missing XML files or sections within those files in the class documentation.
+After editing the XML files, please run the compiled editor binary with the ``--doctool``
+option again to update and tidy up the XML files.
+
+Sphinx RST files for the class documentation are generated from
+XML files using the Godot script ``make_rst.py`` and stored in the ``doc/source/classes`` directory.
+This process is performed using our own script ``gdextension/update_rst.sh``. RST files
+in ``doc/source/classes`` should not be edited manually.

doc/source/getting-started/gdextension.rst

@@ -1,31 +0,0 @@
-.. _gdextension:
-
-Using GDExtension
-=================
-
-    **🛈 See also:** `What is GDExtension? <https://docs.godotengine.org/en/stable/tutorials/scripting/gdextension/what_is_gdextension.html#what-is-gdextension>`_
-
-LimboAI can be used as either a C++ module or as a GDExtension shared library.
-The module version is the most feature-full and slightly more performant, but
-it requires using custom engine builds including the export templates.
-
-    **🛈 Note:** Precompiled builds are available on the official
-    `LimboAI GitHub <https://github.com/limbonaut/limboai#getting-limboai>`_ page.
-
-GDExtension version is more convenient to use, as you don't need a custom engine
-build. You can simply download the extension and put it inside your project.
-However, it has certain limitations, described in detail in the next section.
-
-Whichever you choose to use, remember, your project will stay compatible with
-both and you can transition from one to the other any time.
-
-
-Limitations of the GDExtension version
---------------------------------------
-
-GDExtension is the most convenient way of using the LimboAI plugin, but it comes
-with certain limitations.
-
-* Built-in documentation is not available. The plugin will open online documentation instead when requested.
-* Documentation tooltips are not available.
-* Handy :ref:`class_BBParam` property editor is not available in the extension due to dependencies on the engine classes that are not available in the Godot API.

doc/source/getting-started/getting-limboai.rst

@@ -0,0 +1,46 @@
+Getting LimboAI
+===============
+
+LimboAI can be used as either a C++ module or as a GDExtension shared library.
+There are some differences between the two. In short, GDExtension version is more
+convenient to use but somewhat limited in features. The module version provides better editor
+experience and is slightly more performant, but it requires using custom engine builds including the export templates.
+Whichever you choose to use, your project will stay compatible with both and you can switch from one to
+the other any time.
+
+Choose the version you'd like to use. If you're unsure, start with the GDExtension version.
+You can change your decision at any time - both versions are fully compatible.
+
+Get GDExtension version
+------------------------
+
+GDExtension is the most convenient way of using the LimboAI plugin, but it comes
+with certain limitations:
+
+* Documentation tooltips are not available.
+* Handy :ref:`class_BBParam` property editor is not available in the extension due to dependencies on the engine classes that are not available in the Godot API.
+
+    **🛈 See also:** `What is GDExtension? <https://docs.godotengine.org/en/stable/tutorials/scripting/gdextension/what_is_gdextension.html#what-is-gdextension>`_
+
+Installation instructions:
+
+1. Make sure you're using the latest stable version of the Godot editor.
+2. Create a new project for your experiments with LimboAI.
+3. In Godot, click AssetLib tab at the top of the screen and search for LimboAI. Download it. LimboAI plugin will be downloaded with the demo project files. Don't mind the errors printed at this point, this is due to the extension library not being loaded just yet.
+4. Reload your project with `Project -> Reload project`. There shouldn't be any errors printed now.
+5. In the project files, locate a scene file called `showcase.tscn` and run it. It's the demo's entry point.
+
+Get module version
+-------------------
+
+Precompiled builds are available on the official
+`LimboAI GitHub <https://github.com/limbonaut/limboai#getting-limboai>`_ page,
+and in the Asset Library (coming soon!).
+
+Installation instructions:
+
+1. In `GitHub releases <https://github.com/limbonaut/limboai/releases/>`_, download the latest pre-compiled release build for your platform.
+2. Download the demo project archive from the same release.
+3. Extract the pre-compiled editor and the demo project files.
+4. Launch the pre-compiled editor binary, import and open the demo project.
+5. Run the project.

doc/source/hierarchical-state-machines/create-hsm.rst

@@ -1,8 +1,8 @@
 .. _hsm:
 
 
-State Machines
-==============
+Create State Machines
+=====================
 
 This guide will show how to set up and use a state machine using :ref:`LimboHSM<class_LimboHSM>`.
 
@@ -197,7 +197,7 @@ Let's illustrate this with a practical code example:
     func _idle_update(delta: float) -> void:
         var dir: Vector2 = Input.get_vector(
             &"ui_left", &"ui_right", &"ui_up", &"ui_down")
-        if dir.is_zero_approx():
+        if not dir.is_zero_approx():
             hsm.dispatch(&"movement_started")
 
 

doc/source/index.rst

@@ -1,9 +1,6 @@
 LimboAI Documentation
 =====================
 
-About
------
-
 **LimboAI** is an open-source C++ module for **Godot Engine 4** providing a combination of
 **Behavior Trees** and **State Machines** for crafting your game’s AI. It comes with a
 behavior tree editor, built-in documentation, visual debugger, and more! While
@@ -18,73 +15,36 @@ of agents in a game (e.g., characters, enemies, entities). They are designed to
 make it easier to create complex and highly modular behaviors for your games.
 To learn more about behavior trees, check out :ref:`introduction`.
 
-
-Getting LimboAI
----------------
-
-Precompiled builds are available on the official
-`LimboAI GitHub <https://github.com/limbonaut/limboai#getting-limboai>`_ page,
-and in the Asset Library (coming soon!).
-
-LimboAI can be used as either a C++ module or as a GDExtension shared library.
-There are some differences between the two. In short, GDExtension version is more
-convenient to use but somewhat limited in features. Whichever you choose to use,
-your project will stay compatible with both and you can switch from one to
-the other any time. For more information on this topic, see :ref:`gdextension`.
-
-   **🛈 Note:** Class reference is available in the side bar.
-
-
-First steps
------------
-
-Choose the version you'd like to use. The module version provides better editor
-experience and performance, while the GDExtension version is more convenient to use.
-If you're unsure, start with the GDExtension version.
-You can change your decision at any time - both versions are fully compatible.
-For more information, see :ref:`gdextension`.
-
-With GDExtension version
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-1. Make sure you're using the latest stable version of the Godot editor.
-2. Create a new project for your experiments with LimboAI.
-3. In Godot, click AssetLib tab at the top of the screen and search for LimboAI. Download it. LimboAI plugin will be downloaded with the demo project files. Don't mind the errors printed at this point, this is due to the extension library not being loaded just yet.
-4. Reload your project with `Project -> Reload project`. There shouldn't be any errors printed now.
-5. In the project files, locate a scene file called `showcase.tscn` and run it. It's the demo's entry point.
-
-With module version
-~~~~~~~~~~~~~~~~~~~
-
-1. In `GitHub releases <https://github.com/limbonaut/limboai/releases/>`_, download the latest pre-compiled release build for your platform.
-2. Download the demo project archive from the same release.
-3. Extract the pre-compiled editor and the demo project files.
-4. Launch the pre-compiled editor binary, import and open the demo project.
-5. Run the project.
-
-Creating your own behavior trees
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-1. Make a scene file for your agent, or open an existing scene.
-2. Add a :ref:`BTPlayer<class_BTPlayer>` node to your scene.
-3. Select :ref:`BTPlayer<class_BTPlayer>`, and create a new behavior tree in the inspector.
-4. Optionally, you can save the behavior tree to a file using the property's context menu.
-5. Click the behavior tree property to open it in the LimboAI editor.
-
+**Hierarchical State Machines** are finite state machines that allow any state to host their own
+sub-state machine. This allows you to tackle your AI's state and transition complexity by breaking down
+one big state machine into multiple smaller ones.
 
 .. toctree::
    :hidden:
    :maxdepth: 1
    :caption: Getting started
 
-   getting-started/introduction
-   getting-started/custom-tasks
-   getting-started/using-blackboard
-   getting-started/accessing-nodes
-   getting-started/hsm
-   getting-started/gdextension
+   getting-started/getting-limboai
    getting-started/c-sharp
-   getting-started/featured-classes
+   getting-started/contributing
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: Behavior Trees
+
+   behavior-trees/introduction
+   behavior-trees/create-tree
+   behavior-trees/custom-tasks
+   behavior-trees/using-blackboard
+   behavior-trees/accessing-nodes
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: Hierarchical State MachineS
+
+   hierarchical-state-machines/create-hsm
 
 .. toctree::
    :hidden:
@@ -92,11 +52,5 @@ Creating your own behavior trees
    :caption: Class reference
    :glob:
 
+   classes/featured-classes
    classes/class_*
-
-Debugging behavior trees
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-In Godot Engine, follow to "Bottom Panel > Debugger > LimboAI" tab. With the LimboAI debugger,
-you can inspect any currently active behavior tree within the running project. The debugger can be detached
-from the main editor window, which can be particularly useful if you have a HiDPI or a secondary display.

hsm/limbo_state.cpp

@@ -24,7 +24,7 @@ void LimboState::set_blackboard_plan(const Ref<BlackboardPlan> &p_plan) {
 	blackboard_plan = p_plan;
 
 	if (Engine::get_singleton()->is_editor_hint() && blackboard_plan.is_valid()) {
-		blackboard_plan->set_parent_scope_plan_provider(callable_mp(this, &LimboState::_get_parent_scope_plan));
+		blackboard_plan->set_parent_scope_plan_provider(Callable(this, "_get_parent_scope_plan"));
 	}
 
 	_update_blackboard_plan();
@@ -213,6 +213,8 @@ void LimboState::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_blackboard_plan", "plan"), &LimboState::set_blackboard_plan);
 	ClassDB::bind_method(D_METHOD("get_blackboard_plan"), &LimboState::get_blackboard_plan);
 
+	ClassDB::bind_method(D_METHOD("_get_parent_scope_plan"), &LimboState::_get_parent_scope_plan);
+
 	GDVIRTUAL_BIND(_setup);
 	GDVIRTUAL_BIND(_enter);
 	GDVIRTUAL_BIND(_exit);