From 35a2cbac56937eeb6cc9c757d7bee9bf9d34a24c Mon Sep 17 00:00:00 2001 From: namelessvoid Date: Mon, 16 Dec 2024 21:46:56 +0100 Subject: [PATCH] Re-arrange documentation --- .../accessing-nodes.rst | 0 doc/source/behavior-trees/create-tree.rst | 10 ++ .../custom-tasks.rst | 48 +++++++++- doc/source/behavior-trees/debugging.rst | 8 ++ .../introduction.rst | 0 .../using-blackboard.rst | 0 .../featured-classes.rst | 0 doc/source/getting-started/c-sharp.rst | 44 --------- .../getting-started/getting-limboai.rst | 48 ++++++++++ .../create-hsm.rst} | 4 +- doc/source/index.rst | 91 +++++-------------- 11 files changed, 138 insertions(+), 115 deletions(-) rename doc/source/{getting-started => behavior-trees}/accessing-nodes.rst (100%) create mode 100644 doc/source/behavior-trees/create-tree.rst rename doc/source/{getting-started => behavior-trees}/custom-tasks.rst (83%) create mode 100644 doc/source/behavior-trees/debugging.rst rename doc/source/{getting-started => behavior-trees}/introduction.rst (100%) rename doc/source/{getting-started => behavior-trees}/using-blackboard.rst (100%) rename doc/source/{getting-started => classes}/featured-classes.rst (100%) create mode 100644 doc/source/getting-started/getting-limboai.rst rename doc/source/{getting-started/hsm.rst => hierarchical-state-machines/create-hsm.rst} (99%) diff --git a/doc/source/getting-started/accessing-nodes.rst b/doc/source/behavior-trees/accessing-nodes.rst similarity index 100% rename from doc/source/getting-started/accessing-nodes.rst rename to doc/source/behavior-trees/accessing-nodes.rst diff --git a/doc/source/behavior-trees/create-tree.rst b/doc/source/behavior-trees/create-tree.rst new file mode 100644 index 0000000..175dec1 --- /dev/null +++ b/doc/source/behavior-trees/create-tree.rst @@ -0,0 +1,10 @@ +.. _create_tree:: + +Creating your own Behavior Trees +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Make a scene file for your agent, or open an existing scene. +2. Add a :ref:`BTPlayer` node to your scene. +3. Select :ref:`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. diff --git a/doc/source/getting-started/custom-tasks.rst b/doc/source/behavior-trees/custom-tasks.rst similarity index 83% rename from doc/source/getting-started/custom-tasks.rst rename to doc/source/behavior-trees/custom-tasks.rst index f1da51f..c9ae8f8 100644 --- a/doc/source/getting-started/custom-tasks.rst +++ b/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(); + } + } + diff --git a/doc/source/behavior-trees/debugging.rst b/doc/source/behavior-trees/debugging.rst new file mode 100644 index 0000000..d92e095 --- /dev/null +++ b/doc/source/behavior-trees/debugging.rst @@ -0,0 +1,8 @@ +.. _debugging: + +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. diff --git a/doc/source/getting-started/introduction.rst b/doc/source/behavior-trees/introduction.rst similarity index 100% rename from doc/source/getting-started/introduction.rst rename to doc/source/behavior-trees/introduction.rst diff --git a/doc/source/getting-started/using-blackboard.rst b/doc/source/behavior-trees/using-blackboard.rst similarity index 100% rename from doc/source/getting-started/using-blackboard.rst rename to doc/source/behavior-trees/using-blackboard.rst diff --git a/doc/source/getting-started/featured-classes.rst b/doc/source/classes/featured-classes.rst similarity index 100% rename from doc/source/getting-started/featured-classes.rst rename to doc/source/classes/featured-classes.rst diff --git a/doc/source/getting-started/c-sharp.rst b/doc/source/getting-started/c-sharp.rst index 7af00c5..8d83571 100644 --- a/doc/source/getting-started/c-sharp.rst +++ b/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 `. - -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(); - } - } - diff --git a/doc/source/getting-started/getting-limboai.rst b/doc/source/getting-started/getting-limboai.rst new file mode 100644 index 0000000..c1cc8a0 --- /dev/null +++ b/doc/source/getting-started/getting-limboai.rst @@ -0,0 +1,48 @@ +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 is the most feature-full and 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. 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. + +Get 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. + + **🛈 See also:** `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 `_ page, +and in the Asset Library (coming soon!). + +Installation instructions: + +1. In `GitHub 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. diff --git a/doc/source/getting-started/hsm.rst b/doc/source/hierarchical-state-machines/create-hsm.rst similarity index 99% rename from doc/source/getting-started/hsm.rst rename to doc/source/hierarchical-state-machines/create-hsm.rst index 6a8a5c9..c16595d 100644 --- a/doc/source/getting-started/hsm.rst +++ b/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`. diff --git a/doc/source/index.rst b/doc/source/index.rst index 9fc7db4..6cbd948 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -18,73 +18,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 `_ 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 `_, 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` node to your scene. -3. Select :ref:`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 + +.. 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 + behavior-trees/debugging + +.. toctree:: + :hidden: + :maxdepth: 1 + :caption: Hierarchical State MachineS + + hierarchical-state-machines/create-hsm .. toctree:: :hidden: @@ -92,11 +55,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.