State Manager¶

class game_state.StateManager(*, bound_state_type=<class 'game_state.sync_machine.state.State'>, **kwargs)¶

The State Manager used for managing multiple State(s).

Parameters:

bound_state_type (type[State]) –

The base state class which all states inherits from.
**kwargs (Any) –

The keyword arguments to bind to bound_state_type.

Attributes:

is_running: bool: Added in version 2.0.

A bool for controlling the game loop. True by default.

property current_state: S | None¶

The current state if applied. Will be None otherwise.

Type:: State | None

Changed in version 2.0:

Changed from method to property.

Note

This is a read-only attribute. To change states use change_state() instead.

property last_state: S | None¶

The last state object if any. Will be None otherwise

Type:: State | None

Changed in version 2.0:

Changed from method to property.

Note

This is a read-only attribute.

property lazy_state_map: Dict[str, Tuple[Type[S], List[StateArgs] | None]]¶

A dictionary copy of all the added lazy state names mapped to their respective type and state args.

Type:: dict[str, tuple[type[State], None | list[StateArgs]]]

Added in version 2.2.

Note

This is a read-only attribute.

Note

Once the lazy state has been fully initialized, it will be removed from the lazy state map.

property state_map: Dict[str, S]¶

A dictionary copy of all the state names mapped to their respective instance.

Type:: dict[str, State]

Changed in version 2.0:

Changed from method to property.

Added in version 1.0.

Note

This is a read-only attribute.

property global_on_enter: Callable[[S, S | None], None] | None¶

The global on_enter listener called right before a state’s on_enter listener.

Type:: None | Callable[[State, Optional[State]], None]

Changed in version 2.0.3:

Global listeners can accept None now.

Added in version 2.0.

Note

This has to be assigned before changing the states.

The first argument passed to the function is the current state and the second is the previous state which may be None.

Example for a global_on_enter function-

def global_on_enter(
    current_state: State, previous_state: None | State
) -> None:
    if previous_state:
        print(
            f"GLOBAL ENTER - Entering {current_state.state_name} from {previous_state.state_name}"
        )


your_manager_instance.global_on_enter = global_on_enter

property global_on_leave: Callable[[S | None, S], None] | None¶

The global on_leave listener called right before a state’s on_leave listener.

Type:: None | Callable[[Optional[State], State], None]

Changed in version 2.0.3:

Global listeners can accept None now.

Added in version 2.0.

Note

This has to be assigned before changing the states.

The first argument passed to the function is the current state which may be None and the second is the next state to take place.

Example for a global_on_leave function-

def global_on_leave(
    current_state: None | State, next_state: State
) -> None:
    if current_state:
        print(
            f"GLOBAL LEAVE - Leaving {current_state.state_name} to {next_state.state_name}"
        )


your_manager_instance.global_on_leave = global_on_leave

property global_on_load: Callable[[S, bool], None] | None¶

The global State.on_load() function for all states.

Type:: None | Callable[[State, bool], None]

Added in version 2.3.

Note

This has to be assigned before loading the states into the manager.

The first argument passed to the function is the current state which has been setup.

Example for a global_on_load function-

def global_on_load(state: State, reload: bool) -> None:
    print(f"GLOBAL LOAD - Loading up state: {state.state_name}")
    if reload:
        print("The state is being reloaded.")
    else:
        print("The state is not being reloaded.")


your_manager_instance.global_on_load = global_on_load

property global_on_unload: Callable[[S, bool], None] | None¶

The global State.on_unload() function for all states.

Type:: None | Callable[[State, bool], None]

Added in version 2.3.

Note

This has to be assigned before loading the states into the manager.

The first argument passed to the function is the current state which has been setup.

Example for a global_on_unload function-

def global_on_unload(state: State, reload: bool) -> None:
    print(f"GLOBAL UNLOAD - Loading up state: {state.state_name}")
    if reload:
        print("The state is being reloaded.")
    else:
        print("The state is not being reloaded.")


your_manager_instance.global_on_unload = global_on_unload

change_state(state_name)¶

Changes the current state and updates the last state. This method executes the State.on_leave() & State.on_enter() state & global listeners (global_on_leave() & global_on_enter())

Added in version 1.0.

Parameters:

state_name (str) –

The name of the state you want to switch to.

Raises:

game_state.errors.StateError: Raised when the state name doesn’t exist in the manager.

Return type:

None

connect_state_hook(path, **kwargs)¶

Calls the hook function of the state file.

Added in version 1.0.

Parameters:

path (str) –

The path to the state file containing the hook function to be called.
**kwargs (Any) –

The keyword arguments to be passed to the hook function.

Raises:

game_state.errors.StateError: Raised when the hook function was not found in the state file to be loaded.

Return type:

None

add_lazy_states(*lazy_states, force=False, state_args=None)¶

Lazily adds the States into the StateManager. Unlike load_states(), it only initializes the state when required i.e. when change_state() switches to the lazy state.

Added in version 2.2.

Parameters:

lazy_states (State) –

The states to be loaded into the manager as lazy states.
force (bool) –

Default False.

Loads the state regardless of whether the state has already been loaded or not

without raising any internal error.

Warning

If set to True it may lead to unexpected behavior.
state_args (Optional[Iterable[StateArgs]]) –

The data to be passed to the subclassed states upon their initialization in the manager.

Raises:

game_state.errors.StateLoadError: Raised when the state has already been loaded.

Only raised when force is set to False.

Return type:

None

load_states(*states, force=False, state_args=None)¶

Loads the States into the StateManager.

Changed in version 2.1:

Method now accepts state_args.

Added in version 1.0.

Parameters:

states (State) –

The States to be loaded into the manager.
force (bool) –

Default False.

Loads the state regardless of whether the state has already been loaded or not

without raising any internal error.

Warning

If set to True it may lead to unexpected behavior.
state_args (Optional[Iterable[StateArgs]]) –

The data to be passed to the subclassed states upon their initialization in the manager.

Raises:

game_state.errors.StateLoadError: Raised when the state has already been loaded.

Only raised when force is set to False.

Return type:

None

reload_state(state_name, force=False, **kwargs)¶

Reloads the specified state. A short hand to unload_state() & load_states().

Added in version 1.0.

Parameters:

state_name (str) –

The state name to be reloaded.
force (bool) –

Default False.

Reloads the state even if it’s an actively running state without

raising any internal error.

Warning

If set to True it may lead to unexpected behavior.
**kwargs (Any) –

The keyword arguments to be passed to the unload_state() & load_states().

Return type:

State

Returns:

Returns the newly made State instance.

Raises:

game_state.errors.StateLoadError: Raised when the state has already been loaded.

Only raised when force is set to False.

remove_lazy_state(state_name)¶

Removes the specified lazy state from the StateManager. This will silently fail if the lazy state has been loaded to the manager, which in case you will have to unload via unload_state().

Added in version 2.2.

Parameters:

state_name (str) –

The state to be removed from the manager.

Return type:

None | Tuple[Type[State], Optional[List[StateArgs]]]

Returns:

Either returns None if the lazy state was not found or it returns a
tuple with the first element being the lazy state and the second being
the StateArgs if any were passed.

unload_state(state_name, force=False, **kwargs)¶

Unloads the specified state from the StateManager.

Added in version 1.0.

Parameters:

state_name (str) –

The state name to be unloaded from the manager.
force (bool) –

Default False.

Unloads the state even if it’s an actively running state without raising any internal error.

Warning

If set to True it may lead to unexpected behavior.
**kwargs (Any) –

The keyword arguments to be passed on to the raised errors.

Return type:

Type[State]

Returns:

The State class of the deleted state name.

Raises:

game_state.errors.StateLoadError: Raised when the state doesn’t exist in the manager to be unloaded.
game_state.errors.StateError: Raised when trying to unload an actively running state.

Only raised when force is set to False.