StateMachine Functions - Grisgram/gml-raptor GitHub Wiki

/// @function	 StateMachine(_owner) constructor
/// @description Create a new state machine with a specified owner and an optional list of 
/// 		 predefined states.
/// @param {instance} _owner  The owner of the StateMachine. MUST be an object instance!
/// @param {State...} states  Any number (up to 15) of State(...) instances that define the states

/// @function 	events_enabled()
/// @description Invoked by the StateMachine when it needs to know, whether it should react
///		 on input events like key strokes or mouse clicks.
///		 The default implementation disables events if we are behind a popup or a 
///		 MessageBox is currently open.
///		 override/redefine if you need another condition
///		 ATTENTION! If you redeclare this, do it always in a with(states) {...} bracket
///		 in the create event of the object redefining it, otherwise you won't have access 
///		 to the state machine's variables, like the owner.
/// @returns {bool} true/false Shall the StateMachine react on input events?
events_enabled = function() {
    with(owner)
	return !__LAYER_OR_OBJECT_HIDDEN && !__HIDDEN_BEHIND_POPUP;
}

/// @function		set_events_enabled_func(func)
/// @description	Assigns a new events_enabled function to this state machine.
///			This is a chainable convenience function, you can also assign a
///			new events_enabled function by simply overriding (redefining)
///			the .events_enabled member of this state machine directly.
/// @param {func} func	The function to assign as events_enabled evaluator

/// @function		clear_states()
/// @description	Removes all known states, sets active_state = undefined and optionally 
///			resets the data variable.
///			NOTE: The on_leave callback of any active state will NOT be invoked!
///			This reset is instant.
/// @param {bool}	reset_data	Default true. The data variable will be reset also.

/// @description	Enter an animation lock state for a specified animation.
///			Locking to an animation means, no state changes are allowed until
///			this animation is finished.
///			With the second parameter you can set whether state changes shall be
///			buffered and executed when the animation ends.
///			NOTE: Only the LAST state change will be set. All intermediate changes
///			are ignored, as only the last makes sense (as it's the most recent one).
/// @param {Animation} _animation		The animation to wait for to finish.
/// @param {bool} _buffer_state_change  Optional. if true, the last set_state will be set 
///						when the animation finishes.

/// @function		add_state(_name, _on_enter = undefined, _on_step = undefined, _on_leave = undefined)
/// @description	Defines a new state for the StateMachine.
///			NOTE: If a state with that name already exists, it is overwritten!
/// @param {func} _on_enter  Optional. Callback to invoke when this state gets entered
/// @param {func} step       Optional. Callback to invoke every frame while in this state
/// @param {func} _on_leave  Optional. Callback to invoke when this state shall be left

/// @function		 add_state_shared(_state)
/// @description	 Adds a shared state to the StateMachine. 
///			 NOTE: If a state with that name already exists, it is overwritten!
/// @param {State} state The shared state to add

/// @function set_state(name, enter_override = undefined, leave_override = undefined)
/// @description	Transition to a new state. If the specified state does not exist,
///			an error is logged and the object stays in the current state.
/// @param {func} enter_override  Optional. Replace the original on_enter for this transition with something else
/// @param {func} leave_override  Optional. Replace the original on_leave for this transition with something else

/// @function 		delete_state(_name)
/// @description	Delete a state from the StateMachine.
///			If the object is currently in this state, the delete request is silently ignored.
/// @param {string} 	_name  The name of the state to delete.

/// @function 		has_active_state()
/// @description	Check whether the StateMachine is currently in a valid state
/// @returns {bool} 	true/false Is the object in a valid state?

/// @function 		active_state_name()
/// @description	Get the name of the active state
/// @returns {string} 	The name of the active state or undefined if there is none.

/// @function get_state(name)
/// @description	Get the state instance with the given name
/// @returns {State} 	The requested state or undefined if there is none.

/// @function get_active_state()
/// @description	Get the state instance of the currently active state
/// @returns {State} 	The requested state or undefined if there is none.

/// @function rename_state(old_name, new_name)
/// @description	Rename an existing state.
///			Useful to rename event states if you redefine keys or similar reasons.
///			NOTE: If the state to rename does not exist, the rename request is silently ignored.
/// @param {string} old_name   The current name of the state
/// @param {string} new_name   The new name to assign.

/// @function		state_exists(name)
/// @description	Check whether the specified state exists
/// @param {string} name   The name of the state to check
/// @returns {bool} true/false State exists?

/// @function		set_allow_re_enter_state(allow)
/// @description	Set whether re-entering the same state is allowed (Default = false).
///			If you set this to true, a set_state with the name of the current state
///			will cause the on_leave of the current state followed by on_enter of
///			the same to be invoked.
/// @param {bool}	allow  Set to true if re-entering the current state is allowed (Default = false)

/// @function set_on_destroy(func)
/// @description	Set a callback function to be invoked when this StateMachine is destroyed.
///			Use this if you need to destroy/free resources allocated in the data of the
///			StateMachine (like ds_lists or ds_maps).
/// @param {func} 	func	Function to invoke when this StateMachine is destroyed.

/// @function destroy()
/// @description	Destroy this StateMachine. The on_destroy callback will be invoked, if one is set.