tuxemon.state module

class tuxemon.state.State[source]

Bases: object

This is a prototype class for States.

All states should inherit from it. No direct instances of this class should be created. Update must be overloaded in the child class.

Overview of Methods:

resume - Called each time state is updated for first time
update - Called each frame while state is active
process_event - Called when there is a new input event
pause - Called when state is no longer active
shutdown - Called before state is destroyed

animate(*targets, **kwargs)[source]

Animate something in this state.

Animations are processed even while state is inactive.

Parameters:

targets (Any) – Targets of the Animation.
kwargs (Any) – Attributes and their final value.

Returns:

Resulting animation.

Return type:

Animation

draw(surface)[source]

Render the state to the surface passed. Must be overloaded in children.

Do not change the state of any game entities. Every draw should be the same for a given game time. Any game changes should be done during update.

Parameters:: surface (Surface) – Surface to be rendered onto.
Return type:: None

force_draw = False

load_sprite(filename, **kwargs)[source]

Load a sprite and add it to this state.

Parameters:

filename (str) – Filename, relative to the resources folder.
kwargs (Any) – Keyword arguments to pass to the Rect constructor. Can be any value used by Rect, or layer.

Returns:

Loaded sprite.

Return type:

Sprite

property name: str

pause()[source]

Called when state is pushed back in the stack, allowed to pause.

This will be called: * after update when state is pushed back * before being shutdown

After being called, state will no longer receive player input. Could be called several times over lifetime of state.

Example uses: stopping music, sounds, fading out, making state graphics dim, etc.

Return type:: None

process_event(event)[source]

Handles player input events.

This function is only called when the player provides input such as pressing a key or clicking the mouse.

Since this is part of a chain of event handlers, the return value from this method becomes input for the next one. Returning None signifies that this method has dealt with an event and wants it exclusively. Return the event and others can use it as well.

You should return None if you have handled input here.

Parameters:: event (PlayerInput) – Player input event.
Returns:: None if the event should not be passed to the next handlers. Otherwise, return the input event.
Return type:: PlayerInput | None

rect = <rect(0, 0, 1280, 720)>

remove_animations_of(target)[source]

Given and object, remove any animations that it is used with.

Parameters:: target (Any) – Object whose animations should be removed.
Return type:: None

resume()[source]

Called before update when state is newly in focus.

This will be called: * after startup and before next update * after a pop operation which causes this state to be in focus

After being called, state will begin to receive player input. Could be called several times over lifetime of state.

Example uses: starting music, open menu, starting animations, timers, etc.

Return type:: None

shutdown()[source]

Called when state is removed from stack and will be destroyed.

This will be called: * after update when state is popped

Make sure to release any references to objects that may cause cyclical dependencies.

Return type:: None

startup(**kwargs)[source]

DEPRECATED - Use __init__ instead.

Called when scene is added to the state stack.

This will be called: * after state is pushed and before next update * just once during the life of a state

Example uses: loading images, configuration, sounds, etc.

Parameters:: kwargs (Any) – Configuration options.
Return type:: None

task(*args, **kwargs)[source]

Create a task for this state.

Tasks are processed even while state is inactive. If you want to pass positional arguments, use functools.partial.

Parameters:

args (Any) – Function to be called.
kwargs (Any) – Keyword parameters passed to the task.

Returns:

The created task.

Return type:

Task

transparent = False

update(time_delta)[source]

Time update function for state. Must be overloaded in children.

Parameters:: time_delta (float) – Amount of time in fractional seconds since last update.
Return type:: None

class tuxemon.state.StateManager(package, on_state_change=None)[source]

Bases: object

Allows game states to be managed like a queue.

Parameters:

package (str) – Name of package to search for states.
on_state_change (Optional[Callable[[], None]]) – Optional callback to be executed when top state changes.

property active_states: Sequence[State]

Sequence of states that are active.

Returns:: List of active states.

auto_state_discovery()[source]

Scan a folder, load states found in it, and register them.

TODO: this functionality duplicates the plugin code.

Return type:: None

static collect_states_from_module(import_name)[source]

Given a module, return all classes in it that are a game state.

Abstract Base Classes, those whose metaclass is abc.ABCMeta, will not be included in the state dictionary.

Parameters:: import_name (str) – Name of module
Yields:: Each game state class.
Return type:: Generator[Type[State], None, None]

collect_states_from_path(folder)[source]

Load states from disk, but do not register it.

Parameters:: folder (str) – Folder to load from.
Yields:: Each game state class.
Return type:: Generator[Type[State], None, None]

property current_state: State | None

Return the currently running state, if any.

Returns:: Currently running state.

get_queued_state_by_name(state_name)[source]

Query the queued state stack for a state by the name supplied.

Parameters:: state_name (str) – Name of a state.
Returns:: State with that name, if one exist. None otherwise.
Return type:: Tuple[str, Mapping[str, Any]]

get_state_by_name(state_name: str) → State[source]

get_state_by_name(state_name: Type[StateType]) → StateType

Query the state stack for a state by the name supplied.

Parameters:: state_name – Name of a state.
Returns:: State with that name, if one exist. None otherwise.

pop_state(state=None)[source]

Pop some state.

The default state is the current one. The previously running state will resume, unless there is a queued state, then that state will be become the new current state, not the previous.

Parameters:: state (State | None) – The state to remove from stack. Use None (or omit) for current state.
Return type:: None

push_state(state_name: str, **kwargs: Any) → State[source]

push_state(state_name: StateType, **kwargs: Any) → StateType

Pause currently running state and start new one.

Parameters:

state_name – Name of state to start.
kwargs – Arguments to pass to the __init__ method of the new state.

Returns:

Instanced state.

query_all_states()[source]

Return a dictionary of all loaded states.

Keys are state names, values are State classes.

Returns:: Dictionary of all loaded states.
Return type:: Mapping[str, Type[State]]

queue_state(state_name, **kwargs)[source]

Queue a state to be pushed after the top state is popped or replaced.

Use this to chain execution of states, without causing a state to get instanced before it is on top of the stack.

Parameters:

state_name (str) – Name of state to start.
kwargs (Any) – Arguments to pass to the __init__ method of the new state.

Return type:

None

property queued_states: Sequence[Tuple[str, Mapping[str, Any]]]

Sequence of states that are queued.

Returns:: List of queued states

register_state(state)[source]

Add a state class.

Parameters:: state (Type[State]) – The state to add.
Return type:: None

remove_state(state)[source]

Remove state by passing a reference to it

Parameters:: state (State) – State to remove
Return type:: None

replace_state(state_name: str, **kwargs: Any) → State[source]

replace_state(state_name: StateType, **kwargs: Any) → StateType

Replace the currently running state with a new one.

This is essentially, just a push_state, followed by pop_state(running_state). This cannot be used to replace states in the middle of the stack.

Parameters:

state_name – Name of state to start.
kwargs – Arguments to pass to the __init__ method of the new state.

Returns:

Instanced state.

update(time_delta)[source]

Run update on all active states, which doing some internal housekeeping.

WIP. This may change at some point, especially handling of paused states.

Parameters:: time_delta (float) – Amount of time passed since last frame.
Return type:: None