botaccount
/
limboai
mirror of https://github.com/limbonaut/limboai.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #241 from limbonaut/hsm-transition-guards 

`LimboHSM`: Ability to specify per-transition guard function
This commit is contained in:
Serhii Snitsaruk 2024-11-01 07:49:20 -07:00 committed by GitHub
parent 6de8b9e4c4 a5d59a0a51
commit 423c4ce7a4
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 72 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
doc/source/classes/class_limbohsm.rst
View File

@ -45,27 +45,27 @@ Methods
.. table:: .. table::
:widths: auto :widths: auto
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`add_transition<class_LimboHSM_method_add_transition>`\ (\ from_state\: :ref:`LimboState<class_LimboState>`, to_state\: :ref:`LimboState<class_LimboState>`, event\: ``StringName``\ ) | | |void| | :ref:`add_transition<class_LimboHSM_method_add_transition>`\ (\ from_state\: :ref:`LimboState<class_LimboState>`, to_state\: :ref:`LimboState<class_LimboState>`, event\: ``StringName``, guard\: ``Callable`` = Callable()\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`change_active_state<class_LimboHSM_method_change_active_state>`\ (\ state\: :ref:`LimboState<class_LimboState>`\ ) | | |void| | :ref:`change_active_state<class_LimboHSM_method_change_active_state>`\ (\ state\: :ref:`LimboState<class_LimboState>`\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`LimboState<class_LimboState>` | :ref:`get_active_state<class_LimboHSM_method_get_active_state>`\ (\ ) |const| | | :ref:`LimboState<class_LimboState>` | :ref:`get_active_state<class_LimboHSM_method_get_active_state>`\ (\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`LimboState<class_LimboState>` | :ref:`get_leaf_state<class_LimboHSM_method_get_leaf_state>`\ (\ ) |const| | | :ref:`LimboState<class_LimboState>` | :ref:`get_leaf_state<class_LimboHSM_method_get_leaf_state>`\ (\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`LimboState<class_LimboState>` | :ref:`get_previous_active_state<class_LimboHSM_method_get_previous_active_state>`\ (\ ) |const| | | :ref:`LimboState<class_LimboState>` | :ref:`get_previous_active_state<class_LimboHSM_method_get_previous_active_state>`\ (\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``bool`` | :ref:`has_transition<class_LimboHSM_method_has_transition>`\ (\ from_state\: :ref:`LimboState<class_LimboState>`, event\: ``StringName``\ ) |const| | | ``bool`` | :ref:`has_transition<class_LimboHSM_method_has_transition>`\ (\ from_state\: :ref:`LimboState<class_LimboState>`, event\: ``StringName``\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`initialize<class_LimboHSM_method_initialize>`\ (\ agent\: ``Node``, parent_scope\: :ref:`Blackboard<class_Blackboard>` = null\ ) | | |void| | :ref:`initialize<class_LimboHSM_method_initialize>`\ (\ agent\: ``Node``, parent_scope\: :ref:`Blackboard<class_Blackboard>` = null\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`remove_transition<class_LimboHSM_method_remove_transition>`\ (\ from_state\: :ref:`LimboState<class_LimboState>`, event\: ``StringName``\ ) | | |void| | :ref:`remove_transition<class_LimboHSM_method_remove_transition>`\ (\ from_state\: :ref:`LimboState<class_LimboState>`, event\: ``StringName``\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`set_active<class_LimboHSM_method_set_active>`\ (\ active\: ``bool``\ ) | | |void| | :ref:`set_active<class_LimboHSM_method_set_active>`\ (\ active\: ``bool``\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`update<class_LimboHSM_method_update>`\ (\ delta\: ``float``\ ) | | |void| | :ref:`update<class_LimboHSM_method_update>`\ (\ delta\: ``float``\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. rst-class:: classref-section-separator .. rst-class:: classref-section-separator
@ -191,9 +191,16 @@ Method Descriptions
.. rst-class:: classref-method .. rst-class:: classref-method
|void| **add_transition**\ (\ from_state\: :ref:`LimboState<class_LimboState>`, to_state\: :ref:`LimboState<class_LimboState>`, event\: ``StringName``\ ) :ref:`🔗<class_LimboHSM_method_add_transition>` |void| **add_transition**\ (\ from_state\: :ref:`LimboState<class_LimboState>`, to_state\: :ref:`LimboState<class_LimboState>`, event\: ``StringName``, guard\: ``Callable`` = Callable()\ ) :ref:`🔗<class_LimboHSM_method_add_transition>`
Establishes a transition from one state to another when ``event`` is dispatched. Both ``from_state`` and ``to_state`` must be immediate children of this state. Establishes a transition from one state to another when ``event`` is dispatched. Both ``from_state`` and ``to_state`` must be immediate children of this **LimboHSM**.
Optionally, a ``guard`` function can be specified, which must return a boolean value. If the guard function returns ``false``, the transition will not occur. The guard function is called immediately before the transition is considered. For a state-wide guard function, check out :ref:`LimboState.set_guard<class_LimboState_method_set_guard>`.
::
func my_guard() -> bool:
return is_some_condition_met()
.. rst-class:: classref-item-separator .. rst-class:: classref-item-separator

8
doc_classes/LimboHSM.xml
View File

@ -14,8 +14,14 @@
<param index="0" name="from_state" type="LimboState" /> <param index="0" name="from_state" type="LimboState" />
<param index="1" name="to_state" type="LimboState" /> <param index="1" name="to_state" type="LimboState" />
<param index="2" name="event" type="StringName" /> <param index="2" name="event" type="StringName" />
<param index="3" name="guard" type="Callable" default="Callable()" />
<description> <description>
Establishes a transition from one state to another when [param event] is dispatched. Both [param from_state] and [param to_state] must be immediate children of this state. Establishes a transition from one state to another when [param event] is dispatched. Both [param from_state] and [param to_state] must be immediate children of this [LimboHSM].
Optionally, a [param guard] function can be specified, which must return a boolean value. If the guard function returns [code]false[/code], the transition will not occur. The guard function is called immediately before the transition is considered. For a state-wide guard function, check out [method LimboState.set_guard].
[codeblock]
func my_guard() -&gt; bool:
return is_some_condition_met()
[/codeblock]
</description> </description>
</method> </method>
<method name="change_active_state"> <method name="change_active_state">

17
hsm/limbo_hsm.cpp
View File

@ -100,7 +100,7 @@ void LimboHSM::update(double p_delta) {
} }
} }
void LimboHSM::add_transition(LimboState *p_from_state, LimboState *p_to_state, const StringName &p_event) { void LimboHSM::add_transition(LimboState *p_from_state, LimboState *p_to_state, const StringName &p_event, const Callable &p_guard) {
ERR_FAIL_COND_MSG(p_from_state != nullptr && p_from_state->get_parent() != this, "LimboHSM: Unable to add a transition from a state that is not an immediate child of mine."); ERR_FAIL_COND_MSG(p_from_state != nullptr && p_from_state->get_parent() != this, "LimboHSM: Unable to add a transition from a state that is not an immediate child of mine.");
ERR_FAIL_COND_MSG(p_to_state == nullptr, "LimboHSM: Unable to add a transition to a null state."); ERR_FAIL_COND_MSG(p_to_state == nullptr, "LimboHSM: Unable to add a transition to a null state.");
ERR_FAIL_COND_MSG(p_to_state->get_parent() != this, "LimboHSM: Unable to add a transition to a state that is not an immediate child of mine."); ERR_FAIL_COND_MSG(p_to_state->get_parent() != this, "LimboHSM: Unable to add a transition to a state that is not an immediate child of mine.");
@ -108,8 +108,13 @@ void LimboHSM::add_transition(LimboState *p_from_state, LimboState *p_to_state,
TransitionKey key = Transition::make_key(p_from_state, p_event); TransitionKey key = Transition::make_key(p_from_state, p_event);
ERR_FAIL_COND_MSG(transitions.has(key), "LimboHSM: Unable to add another transition with the same event and origin."); ERR_FAIL_COND_MSG(transitions.has(key), "LimboHSM: Unable to add another transition with the same event and origin.");
// Note: Explicit casting needed for GDExtension. // Note: Explicit ObjectID casting needed for GDExtension.
transitions[key] = { p_from_state != nullptr ? ObjectID(p_from_state->get_instance_id()) : ObjectID(), ObjectID(p_to_state->get_instance_id()), p_event }; transitions[key] = {
p_from_state != nullptr ? ObjectID(p_from_state->get_instance_id()) : ObjectID(),
ObjectID(p_to_state->get_instance_id()),
p_event,
p_guard
};
} }
void LimboHSM::remove_transition(LimboState *p_from_state, const StringName &p_event) { void LimboHSM::remove_transition(LimboState *p_from_state, const StringName &p_event) {
@ -166,13 +171,13 @@ bool LimboHSM::_dispatch(const StringName &p_event, const Variant &p_cargo) {
Transition transition; Transition transition;
_get_transition(active_state, p_event, transition); _get_transition(active_state, p_event, transition);
if (transition.is_valid()) { if (transition.is_valid() && transition.is_allowed()) {
to_state = Object::cast_to<LimboState>(ObjectDB::get_instance(transition.to_state)); to_state = Object::cast_to<LimboState>(ObjectDB::get_instance(transition.to_state));
} }
if (to_state == nullptr) { if (to_state == nullptr) {
// Get ANYSTATE transition. // Get ANYSTATE transition.
_get_transition(nullptr, p_event, transition); _get_transition(nullptr, p_event, transition);
if (transition.is_valid()) { if (transition.is_valid() && transition.is_allowed()) {
to_state = Object::cast_to<LimboState>(ObjectDB::get_instance(transition.to_state)); to_state = Object::cast_to<LimboState>(ObjectDB::get_instance(transition.to_state));
if (to_state == active_state) { if (to_state == active_state) {
// Transitions to self are not allowed with ANYSTATE. // Transitions to self are not allowed with ANYSTATE.
@ -300,7 +305,7 @@ void LimboHSM::_bind_methods() {
ClassDB::bind_method(D_METHOD("get_leaf_state"), &LimboHSM::get_leaf_state); ClassDB::bind_method(D_METHOD("get_leaf_state"), &LimboHSM::get_leaf_state);
ClassDB::bind_method(D_METHOD("set_active", "active"), &LimboHSM::set_active); ClassDB::bind_method(D_METHOD("set_active", "active"), &LimboHSM::set_active);
ClassDB::bind_method(D_METHOD("update", "delta"), &LimboHSM::update); ClassDB::bind_method(D_METHOD("update", "delta"), &LimboHSM::update);
ClassDB::bind_method(D_METHOD("add_transition", "from_state", "to_state", "event"), &LimboHSM::add_transition); ClassDB::bind_method(D_METHOD("add_transition", "from_state", "to_state", "event", "guard"), &LimboHSM::add_transition, DEFVAL(Callable()));
ClassDB::bind_method(D_METHOD("remove_transition", "from_state", "event"), &LimboHSM::remove_transition); ClassDB::bind_method(D_METHOD("remove_transition", "from_state", "event"), &LimboHSM::remove_transition);
ClassDB::bind_method(D_METHOD("has_transition", "from_state", "event"), &LimboHSM::has_transition); ClassDB::bind_method(D_METHOD("has_transition", "from_state", "event"), &LimboHSM::has_transition);
ClassDB::bind_method(D_METHOD("anystate"), &LimboHSM::anystate); ClassDB::bind_method(D_METHOD("anystate"), &LimboHSM::anystate);

5
hsm/limbo_hsm.h
View File

@ -39,9 +39,12 @@ private:
ObjectID from_state; ObjectID from_state;
ObjectID to_state; ObjectID to_state;
StringName event; StringName event;
Callable guard;
inline bool is_valid() const { return to_state != ObjectID(); } inline bool is_valid() const { return to_state != ObjectID(); }
inline bool is_allowed() const { return guard.is_null() || guard.call(); }
static _FORCE_INLINE_ TransitionKey make_key(LimboState *p_from_state, const StringName &p_event) { static _FORCE_INLINE_ TransitionKey make_key(LimboState *p_from_state, const StringName &p_event) {
return TransitionKey( return TransitionKey(
p_from_state != nullptr ? uint64_t(p_from_state->get_instance_id()) : 0, p_from_state != nullptr ? uint64_t(p_from_state->get_instance_id()) : 0,
@ -93,7 +96,7 @@ public:
void update(double p_delta); void update(double p_delta);
void add_transition(LimboState *p_from_state, LimboState *p_to_state, const StringName &p_event); void add_transition(LimboState *p_from_state, LimboState *p_to_state, const StringName &p_event, const Callable &p_guard = Callable());
void remove_transition(LimboState *p_from_state, const StringName &p_event); void remove_transition(LimboState *p_from_state, const StringName &p_event);
bool has_transition(LimboState *p_from_state, const StringName &p_event) const { return transitions.has(Transition::make_key(p_from_state, p_event)); } bool has_transition(LimboState *p_from_state, const StringName &p_event) const { return transitions.has(Transition::make_key(p_from_state, p_event)); }

21
tests/test_hsm.h
View File

@ -215,7 +215,7 @@ TEST_CASE("[Modules][LimboAI] HSM") {
CHECK(beta_updates->num_callbacks == 0); CHECK(beta_updates->num_callbacks == 0);
CHECK(beta_exits->num_callbacks == 1); // * exited CHECK(beta_exits->num_callbacks == 1); // * exited
} }
SUBCASE("Test transition with guard") { SUBCASE("Test transition with state-wide guard") {
Ref<TestGuard> guard = memnew(TestGuard); Ref<TestGuard> guard = memnew(TestGuard);
state_beta->set_guard(callable_mp(guard.ptr(), &TestGuard::can_enter)); state_beta->set_guard(callable_mp(guard.ptr(), &TestGuard::can_enter));
@ -234,6 +234,25 @@ TEST_CASE("[Modules][LimboAI] HSM") {
CHECK(beta_entries->num_callbacks == 0); CHECK(beta_entries->num_callbacks == 0);
} }
} }
SUBCASE("Test transition with transition-scoped guard") {
Ref<TestGuard> guard = memnew(TestGuard);
hsm->add_transition(state_alpha, state_beta, "guarded_transition", callable_mp(guard.ptr(), &TestGuard::can_enter));
SUBCASE("When entry is permitted") {
guard->permitted_to_enter = true;
hsm->dispatch("guarded_transition");
CHECK(hsm->get_active_state() == state_beta);
CHECK(alpha_exits->num_callbacks == 1);
CHECK(beta_entries->num_callbacks == 1);
}
SUBCASE("When entry is not permitted") {
guard->permitted_to_enter = false;
hsm->dispatch("guarded_transition");
CHECK(hsm->get_active_state() == state_alpha);
CHECK(alpha_exits->num_callbacks == 0);
CHECK(beta_entries->num_callbacks == 0);
}
}
SUBCASE("When there is no transition for given event") { SUBCASE("When there is no transition for given event") {
hsm->dispatch("not_found"); hsm->dispatch("not_found");
CHECK(alpha_exits->num_callbacks == 0); CHECK(alpha_exits->num_callbacks == 0);