feat: RewindableState signals (#494)

Co-authored-by: Tamás Gálffy <ezittgtx@gmail.com>

Author: RickyYCheng

addons/netfox.extras/plugin.cfg

@@ -3,5 +3,5 @@
 name="netfox.extras"
 description="Game-specific utilities for Netfox"
 author="Tamas Galffy and contributors"
-version="1.32.3"
+version="1.33.0"
 script="netfox-extras.gd"

addons/netfox.extras/state-machine/rewindable-state-machine.gd

@@ -50,8 +50,11 @@ static var _logger: _NetfoxLogger = _NetfoxLogger.for_extras("RewindableStateMac
 var _state_object: RewindableState = null
 var _previous_state_object: RewindableState = null
 var _available_states: Dictionary = {}
+var _prevent_transition: bool = false
+var _prevent_callable: Callable = func(): _prevent_transition = true
 
-## Transition to a new state specified by [param new_state_name].
+## Transition to a new state specified by [param new_state_name] and return
+## true.
 ##
 ## Finds the given state by name and transitions to it if possible. The new
 ## state's [method RewindableState.can_enter] callback decides if it can be
@@ -63,42 +66,67 @@ var _available_states: Dictionary = {}
 ## [br][br]
 ## Does nothing if transitioning to the currently active state. Emits a warning
 ## and does nothing when transitioning to an unknown state.
-func transition(new_state_name: StringName) -> void:
+func transition(new_state_name: StringName) -> bool:
+	# Check if target state is valid
 	if state == new_state_name:
-		return
+		return false
 
 	if not _available_states.has(new_state_name):
 		_logger.warning("Attempted to transition from state '%s' into unknown state '%s'", [state, new_state_name])
-		return
+		return false
 
+	var from_state = _state_object
 	var new_state: RewindableState = _available_states[new_state_name]
-	if _state_object:
+	_prevent_transition = false
+
+	# Validate transition
+	if from_state:
 		if !new_state.can_enter(_state_object):
-			return
+			return false
+		
+		# Emit exit signal, allow handlers to prevent transition
+		_state_object.on_exit.emit(new_state, NetworkRollback.tick, _prevent_callable)
+		if _prevent_transition: return false
+
+	new_state.on_enter.emit(from_state, NetworkRollback.tick, _prevent_callable)
+	if _prevent_transition: return false
+	
+	# Transition valid, run callbacks
+	if is_instance_valid(from_state):
+		from_state.exit(new_state, NetworkRollback.tick)
+	new_state.enter(from_state, NetworkRollback.tick)
+
+	# Set new state
+	_state_object = new_state
+	on_state_changed.emit(from_state, new_state)
 
-		_state_object.exit(new_state, NetworkRollback.tick)
+	return true
 
-	var _previous_state: RewindableState = _state_object
-	_state_object = new_state
-	on_state_changed.emit(_previous_state, new_state)
-	_state_object.enter(_previous_state, NetworkRollback.tick)
+## Update the internal cache of known states
+## [br][br]
+## Automatically called on ready and when a child node is added or removed. Call
+## manually to force an update.
+func update_states() -> void:
+	_available_states.clear()
+	
+	for child in find_children("*", "RewindableState", false):
+		_available_states[child.name] = child
 
 func _notification(what: int):
 	# Use notification instead of _ready, so users can write their own _ready
 	# callback without having to call super()
 	if Engine.is_editor_hint(): return
 
-	if what == NOTIFICATION_ENTER_TREE:
-		# Gather known states if we haven't yet
-		if _available_states.is_empty():
-			for child in find_children("*", "RewindableState", false):
-				_available_states[child.name] = child
-
-		# Compare states after tick loop
-		NetworkTime.after_tick_loop.connect(_after_tick_loop)
-	elif what == NOTIFICATION_EXIT_TREE:
-		# Disconnect handlers
-		NetworkTime.after_tick_loop.disconnect(_after_tick_loop)
+	match what:
+		NOTIFICATION_CHILD_ORDER_CHANGED:
+			update_states()
+		NOTIFICATION_ENTER_TREE:
+			# Compare states after tick loop
+			NetworkTime.after_tick_loop.connect(_after_tick_loop)
+			update_states()
+		NOTIFICATION_EXIT_TREE:
+			# Disconnect handlers
+			NetworkTime.after_tick_loop.disconnect(_after_tick_loop)
 
 func _get_configuration_warnings():
 	const MISSING_SYNCHRONIZER_ERROR := \
@@ -133,13 +161,17 @@ func _get_configuration_warnings():
 func _rollback_tick(delta: float, tick: int, is_fresh: bool) -> void:
 	if _state_object:
 		_state_object.tick(delta, tick, is_fresh)
+		_state_object.on_tick.emit(delta, tick, is_fresh)
 
 func _after_tick_loop():
 	if _state_object != _previous_state_object:
 		on_display_state_changed.emit(_previous_state_object, _state_object)
 
 		if _previous_state_object:
+			_previous_state_object.on_display_exit.emit(_state_object, NetworkTime.tick)
 			_previous_state_object.display_exit(_state_object, NetworkTime.tick)
+
+		_state_object.on_display_enter.emit(_previous_state_object, NetworkTime.tick)
 		_state_object.display_enter(_previous_state_object, NetworkTime.tick)
 
 		_previous_state_object = _state_object

addons/netfox.extras/state-machine/rewindable-state.gd

@@ -12,6 +12,21 @@ class_name RewindableState
 ##
 ## @tutorial(RewindableStateMachine Guide): https://foxssake.github.io/netfox/latest/netfox.extras/guides/rewindable-state-machine/
 
+## Emitted when entering the state
+signal on_enter(previous_state: RewindableState, tick: int, prevent: Callable)
+ 
+## Emitted on every rollback tick while the state is active
+signal on_tick(delta: float, tick: int, is_fresh: bool)
+ 
+## Emitted when exiting the state
+signal on_exit(next_state: RewindableState, tick: int, prevent: Callable)
+
+## Emitted before displaying this state
+signal on_display_enter(previous_state: RewindableState, tick: int)
+
+## Emitted before displaying another state
+signal on_display_exit(next_state: RewindableState, tick: int)
+
 ## The [RewindableStateMachine] this state belongs to.
 ## [br][br]
 ## [i]read-only[/i]

addons/netfox.internals/plugin.cfg

@@ -3,5 +3,5 @@
 name="netfox.internals"
 description="Shared internals for netfox addons"
 author="Tamas Galffy and contributors"
-version="1.32.3"
+version="1.33.0"
 script="plugin.gd"

addons/netfox.noray/plugin.cfg

@@ -3,5 +3,5 @@
 name="netfox.noray"
 description="Bulletproof your connectivity with noray integration for netfox"
 author="Tamas Galffy and contributors"
-version="1.32.3"
+version="1.33.0"
 script="netfox-noray.gd"

addons/netfox/plugin.cfg

@@ -3,5 +3,5 @@
 name="netfox"
 description="Shared internals for netfox addons"
 author="Tamas Galffy and contributors"
-version="1.32.3"
+version="1.33.0"
 script="netfox.gd"

addons/vest/mocks/vest-mock-generator.gd

@@ -39,9 +39,10 @@ func generate_mock_source(script: Script) -> String:
 
 		var arg_def_string := ", ".join(arg_defs)
 
+		# TODO(vest): Handle method name shadowing param name
 		mock_source.append(
 			("func %s(%s):\n" +
-			"\treturn __vest_mock_handler._handle(%s, [%s])\n\n") %
+			"\treturn __vest_mock_handler._handle(self.%s, [%s])\n\n") %
 			[method_name, arg_def_string, method_name, arg_def_string]
 		)
 

docs/netfox.extras/guides/rewindable-state-machine.md

@@ -35,14 +35,24 @@ RewindableStateMachine.
 
 States react to the game world using the following callbacks:
 
-* `tick(delta, tick, is_fresh)` is called for every rollback tick.
-* `enter(previous_state, tick)` is called when entering the state.
-* `exit(next_state, tick)` is called when exiting the state.
-* `can_enter(previous_state)` is called before entering the state. The state is
-  only entered if this method returns true.
-* `display_enter(previous_state, tick)` is called before displaying the state.
-* `display_exit(next_state, tick)` is called before displaying a different
-  state.
+`tick(delta, tick, is_fresh)`
+: Called for every rollback tick the state is active.
+
+`enter(previous_state, tick)`
+: Called when entering the state.
+
+`exit(next_state, tick)`
+: Called when exiting the state.
+
+`can_enter(previous_state)`
+: Called before entering the state. The state is only entered if this method
+  returns true.
+
+`display_enter(previous_state, tick)`
+: Called before displaying the state.
+
+`display_exit(next_state, tick)`
+: Called before displaying a different state.
 
 You can override any of these callbacks to implement your custom behaviors.
 
@@ -69,6 +79,28 @@ machine](../assets/rewindable-state-children.png)
 
 States must be added as children under a RewindableStateMachine to work.
 
+## Using signals instead of classes
+
+*RewindableState* nodes also emit signals during their lifetime. This enables
+an alternate style of implementing states, by connecting handlers to different
+signals. This can be useful if you want to keep all your logic in a single
+script, among others.
+
+Each of these signals correspond to a callback explained above:
+
+* `on_enter()` → `enter()`
+* `on_tick()` → `tick()`
+* `on_exit()` → `exit()`
+* `on_display_enter()` → `display_enter()`
+* `on_display_exit()` → `display_exit()`
+
+## Adding states
+
+Once implemented, add the state nodes as children of the
+*RewindableStateMachine* in the Scene Tree. When doing this programmatically,
+make sure to set the state's `owner` to the target *RewindableStateMachine*.
+Without the owner set, the *RewindableStateMachine* won't recognize the state.
+
 ## Display State vs State
 
 There's two sets of callbacks for state transition - `enter()`/`exit()` and
@@ -109,10 +141,10 @@ P is Idle
 
 This will trigger the following state changes:
 
-* Tick@1: Idle -> Moving
-* Tick@3: Moving -> Jumping
-* Tick@5: Jumping -> Moving
-* Tick@8: Moving -> Idle
+* Tick@1: Idle → Moving
+* Tick@3: Moving → Jumping
+* Tick@5: Jumping → Moving
+* Tick@8: Moving → Idle
 
 For each of the above, the `on_state_changed` signal will be emitted, and the
 `enter()`/`exit()` callbacks will be triggered.

test/netfox.extras/rewindable-state-machine.test.gd

@@ -0,0 +1,135 @@
+extends VestTest
+
+func get_suite_name() -> String:
+	return "RewindableStateMachine"
+
+var state_machine: RewindableStateMachine
+var first_state: RewindableState
+var other_state: RewindableState
+
+func before_case(__):
+	state_machine = RewindableStateMachine.new()
+	first_state = mock(RewindableState)
+	other_state = mock(RewindableState)
+	
+	# Setup mock answers
+	when(first_state.can_enter).then_return(true)
+	when(first_state.enter).then_answer(func(__): pass)
+	when(first_state.exit).then_answer(func(__): pass)
+	when(first_state.tick).then_answer(func(__): pass)
+	when(first_state.display_enter).then_answer(func(__): pass)
+	when(first_state.display_exit).then_answer(func(__): pass)
+	
+	when(other_state.can_enter).then_return(true)
+	when(other_state.enter).then_answer(func(__): pass)
+	when(other_state.exit).then_answer(func(__): pass)
+	when(other_state.tick).then_answer(func(__): pass)
+	when(other_state.display_enter).then_answer(func(__): pass)
+	when(other_state.display_exit).then_answer(func(__): pass)
+	
+	# Set state names
+	first_state.name = "First State"
+	other_state.name = "Other State"
+	
+	# Add states as children - RSM will pick them up when added
+	# **NOTE**: Make sure to set owner if spawning states manually, otherwise
+	# RSM won't pick them up
+	state_machine.add_child(first_state); first_state.owner = state_machine
+	state_machine.add_child(other_state); other_state.owner = state_machine
+	
+	# TODO(vest): TestingSceneTree
+	await Vest._scene_tree.process_frame
+	Vest._scene_tree.root.add_child(state_machine, true)
+
+func test_should_start_empty():
+	expect_empty(state_machine.state)
+
+func test_should_notify_new_state_on_enter():
+	capture_signal(first_state.on_enter, 3)
+	
+	# Enter first state
+	state_machine.transition("First State")
+	
+	# Check for event
+	expect_not_empty(get_signal_emissions(first_state.on_enter))
+	expect_empty(get_calls_of(first_state.can_enter))
+	expect_equal(get_calls_of(first_state.enter), [[null, 0]])
+
+func test_on_enter_should_prevent_transition():
+	other_state.on_enter.connect(
+		func(_new_state, _tick, prevent):
+			prevent.call()
+	)
+	
+	# Enter first state
+	state_machine.transition("First State")
+	
+	# Try to enter second state
+	expect_false(state_machine.transition("Other State"), "Transition should have failed!")
+	expect_equal(state_machine.state, "First State")
+
+func test_on_exit_should_prevent_transition():
+	first_state.on_exit.connect(
+		func(_new_state, _tick, prevent):
+			prevent.call()
+	)
+	
+	# Enter first state
+	state_machine.transition("First State")
+	
+	# Try to enter second state
+	expect_false(state_machine.transition("Other State"), "Transition should have failed!")
+	expect_equal(state_machine.state, "First State")
+
+func test_can_enter_should_prevent_transition():
+	state_machine.state = "First State"
+	
+	# Register a more specific answer so the mock will use that
+	when(other_state.can_enter)\
+		.with_args([first_state])\
+		.then_return(func(__): return false)
+	
+	# Try to enter second state
+	expect_false(state_machine.transition("Other State"), "Transition should have failed!")
+	expect_equal(state_machine.state, "First State")
+
+func test_should_call_tick():
+	capture_signal(first_state.on_tick, 3)
+
+	# Set state
+	state_machine.transition("First State")
+
+	# Run a rollback tick
+	state_machine._rollback_tick(0.16, 0, true)
+	
+	# Tick should have been called
+	expect_equal(get_calls_of(first_state.tick), [[0.16, 0, true]], "Wrong method call!")
+	expect_equal(get_signal_emissions(first_state.on_tick), [[0.16, 0, true]], "Wrong signal!")
+
+func test_should_notify_display_state():
+	state_machine.state = "First State"
+	
+	capture_signal(first_state.on_display_enter, 2)
+	capture_signal(first_state.on_display_exit, 2)
+	capture_signal(other_state.on_display_enter, 2)
+	
+	# First loop, display enters First State
+	NetworkMocks.in_network_tick_loop(func():
+		state_machine.transition("First State")
+	)
+	expect_not_empty(get_signal_emissions(first_state.on_display_enter))
+	expect_not_empty(get_calls_of(first_state.display_enter))
+	
+	# Second loop, display enters Other State
+	NetworkMocks.in_network_tick_loop(func():
+		state_machine.transition("Other State")
+	)
+	
+	expect_not_empty(get_signal_emissions(first_state.on_display_exit))
+	expect_not_empty(get_signal_emissions(other_state.on_display_enter))
+
+	expect_not_empty(get_calls_of(first_state.display_exit))
+	expect_not_empty(get_calls_of(other_state.display_enter))
+
+func after_case(__):
+	state_machine.queue_free()

test/netfox.extras/rewindable-state-machine.test.gd.uid

@@ -0,0 +1 @@
+uid://cykemuvhqeq2r