State Manager

class game_state.StateManager(window)

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

Parameters:

window (Surface) – The main game window.

Attributes:
is_running: bool

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

property current_state: State | None

The current state if applied. Will be None otherwise.

Note

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

property global_on_enter: Callable[[State, State | None], None] | None

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

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}"
        )
property global_on_leave: Callable[[State | None, State], None] | None

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

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}"
        )
property global_on_setup: Callable[[State], None] | None

The global on_setup function for all states.

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_setup function-

def global_setup(state: State) -> None:
    print(f"GLOBAL SETUP - Setting up state: {state.state_name}")
property last_state: State | None

The last state object if any. Will be None otherwise

Note

This is a read-only attribute.

property state_map: Dict[str, State]

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

Note

This is a read-only attribute.

change_state(state_name)

Changes the current state and updates the last state. This method executes the on_leave & on_enter state & global listeners.

Parameters:

state_name (str) –

The name of the State you want to switch to.

Raises:
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.

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:
StateError
Raised when the hook function was not found in the state file to be loaded.
Return type:

None

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

Loads the States into the StateManager.

Parameters:

  • states (Type[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:
StateLoadError
Raised when the state has already been loaded.
Only raised when force is set to False.
StateError
Raised when the passed argument(s) is not subclassed from State.
Return type:

None

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

Reloads the specified State. A short hand to StateManager.unload_state & StateManager.load_state.

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
    StateManager.unload_state & StateManager.load_state.

Return type:

State

Returns:

Returns the newly made State instance.

Raises:
StateLoadError
Raised when the state has already been loaded.
Only raised when force is set to False.
unload_state(state_name, force=False, **kwargs)

Unloads the State from the StateManager.

Parameters:

  • state_name (str) –

    The State to be loaded into 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:
StateLoadError
Raised when the state doesn’t exist in the manager to be unloaded.
StateError
Raised when trying to unload an actively running State.
Only raised when force is set to False.