actuators¶

This module contains the base classes for simple and advanced actuators. These classes are the base contract for actuators. If you wish to create your own one, you need to inheritate from one of these base class.

This module contains the simple actuators classes. Simple actuators are movement related one. They allow for predetermined movements patterns.

`Actuator`(parent)	Actuator is the base class for all Actuators.
`Behavioral`(parent)	The behavioral actuator is inheriting from Actuator and is adding a next_action() method.
`RandomActuator`([moveset, parent])	A class that implements a random choice of movement.
`PathActuator`([path, parent])	The path actuator is a subclass of `Actuator`.
`PatrolActuator`([path, parent])	The patrol actuator is a subclass of `PathActuator`.
`UnidirectionalActuator`([direction, parent])	A class that implements a single movement.
`PathFinder`([game, actuated_object, …])	Important This module assume a one step movement.

class pygamelib.actuators.Actuator(parent)¶

Bases: object

Actuator is the base class for all Actuators. It is mainly a contract class with some utility methods.

By default, all actuators are considered movement actuators. So the base class only require next_move() to be implemented.

Parameters:	parent – the item parent.

next_move()¶

That method needs to be implemented by all actuators or a NotImplementedError exception will be raised.

Raises:	NotImplementedError

pause()¶

Set the actuator state to PAUSED.

Example:

mygame.pause()

start()¶

Set the actuator state to RUNNING.

If the actuator state is not RUNNING, actuators’ next_move() function (and all derivatives) should not return anything.

Example:

mygame.start()

stop()¶

Set the actuator state to STOPPED.

Example:

mygame.stop()

class pygamelib.actuators.Behavioral(parent)¶

Bases: pygamelib.actuators.Actuator

The behavioral actuator is inheriting from Actuator and is adding a next_action() method. The actual actions are left to the actuator that implements Behavioral.

Parameters:	parent – the item parent.

next_action()¶

That method needs to be implemented by all behavioral actuators or a NotImplementedError exception will be raised.

Raises:	NotImplementedError

next_move()¶

That method needs to be implemented by all actuators or a NotImplementedError exception will be raised.

Raises:	NotImplementedError

pause()¶

Set the actuator state to PAUSED.

Example:

mygame.pause()

start()¶

Set the actuator state to RUNNING.

If the actuator state is not RUNNING, actuators’ next_move() function (and all derivatives) should not return anything.

Example:

mygame.start()

stop()¶

Set the actuator state to STOPPED.

Example:

mygame.stop()

class pygamelib.actuators.PathActuator(path=None, parent=None)¶

Bases: pygamelib.actuators.Actuator

The path actuator is a subclass of Actuator. The move inside the function next_move depends on path and index. If the state is not running it returns None otherwise it increments the index & then, further compares the index with length of the path. If they both are same then, index is set to value zero and the move is returned back.

Parameters:	path (list) – A list of paths. parent (pygamelib.board_items.BoardItem) – The parent object to actuate.

next_move()¶

Return the movement based on current index

The movement is selected from path if state is RUNNING, otherwise it should return None. When state is RUNNING, the movement is selected before incrementing the index by 1. When the index equal the length of path, the index should return back to 0.

Returns:	The next movement
Return type:	int \| None

Example:

pathactuator.next_move()

pause()¶

Set the actuator state to PAUSED.

Example:

mygame.pause()

set_path(path)¶

Defines a new path

This will also reset the index back to 0.

Parameters:	path (list) – A list of movements.

Example:

pathactuator.set_path([constants.UP,constants.DOWN,constants.LEFT,constants.RIGHT])

start()¶

Set the actuator state to RUNNING.

If the actuator state is not RUNNING, actuators’ next_move() function (and all derivatives) should not return anything.

Example:

mygame.start()

stop()¶

Set the actuator state to STOPPED.

Example:

mygame.stop()

class pygamelib.actuators.PathFinder(game=None, actuated_object=None, circle_waypoints=True, parent=None)¶

Bases: pygamelib.actuators.Behavioral

Important

This module assume a one step movement. If you need more than one step, you will need to sub-class this module and re-implement next_waypoint().

This actuator is a bit different than the simple actuators (SimpleActuators) as it requires the knowledge of both the game object and the actuated object.

The constructor takes the following parameters:

Parameters:

game (pygamelib.engine.Game) – A reference to the instanciated game engine.
actuated_object (pygamelib.board_items.BoardItem) – The object to actuate. Deprecated in favor of parent. Only kept for backward compatibility.
parent (pygamelib.board_items.BoardItem) – The parent object to actuate.
circle_waypoints (bool) – If True the next_waypoint() method is going to circle between the waypoints (when the last is visited, go back to the first)

add_waypoint(row, column)¶

Add a waypoint to the list of waypoints.

Waypoints are used one after the other on a FIFO basis (First In, First Out).

If not destination (i.e destination == (None, None)) have been set yet, that method sets it.

Parameters:	row (int) – The “row” part of the waypoint’s coordinate. column – The “column” part of the waypoint’s coordinate.
Raises:	PglInvalidTypeException – If any of the parameters is not an int.

Example:

pf = PathFinder(game=mygame, actuated_object=npc1)
pf.add_waypoint(3,5)
pf.add_waypoint(12,15)

clear_waypoints()¶

Empty the waypoints stack.

Example:

pf.clear_waypoints()

current_path()¶

This method simply return a copy of the current path of the actuator.

The current path is to be understood as: the list of positions still remaining. All positions that have already been gone through are removed from the stack.

Important

A copy of the path is returned for every call to that function so be wary of the performances impact.

Example:

mykillernpc.actuator = PathFinder(
                        game=mygame,
                        actuated_object=mykillernpc
                    )
mykillernpc.actuator.set_destination(
                        mygame.player.pos[0],
                        mygame.player.pos[1]
                    )
mykillernpc.actuator.find_path()
for i in mykillernpc.actuator.current_path():
    print(i)

current_waypoint()¶

Return the currently active waypoint.

If no waypoint have been added, this function return None.

Returns:	Either a None tuple or the current waypoint.
Return type:	A None tuple or a tuple of integer.

Example:

(row,column) = pf.current_waypoint()
pf.set_destination(row,column)

find_path()¶

Find a path to the destination.

Destination (PathFinder.destination) has to be set beforehand. This method implements a Breadth First Search algorithm (Wikipedia) to find the shortest path to destination.

Example:

mykillernpc.actuator = PathFinder(
        game=mygame, actuated_object=mykillernpc
    )
mykillernpc.actuator.set_destination(
        mygame.player.pos[0], mygame.player.pos[1]
    )
mykillernpc.actuator.find_path()

Warning

PathFinder.destination is a tuple! Please use PathFinder.set_destination(x,y) to avoid problems.

next_action()¶

That method needs to be implemented by all behavioral actuators or a NotImplementedError exception will be raised.

Raises:	NotImplementedError

next_move()¶

This method return the next move calculated by this actuator.

In the case of this PathFinder actuator, next move does the following:

If the destination is not set return NO_DIR (see constants) - If the destination is set, but the path is empty and actuated object’s position is different from destination: call find_path()

Look at the current waypoint, if the actuated object is not at that position return a direction from the constants module. The direction is calculated from the difference betwen actuated object’s position and waypoint’s position.

If the actuated object is at the waypoint position, then call next_waypoint(), set the destination and return a direction. In this case, also call find_path().

In any case, if there is no more waypoints in the path this method returns NO_DIR (see constants)

Example:

seeker = NPC(model=Sprites.SKULL)
seeker.actuator = PathFinder(game=mygame,actuated_object=seeker)
while True:
    seeker.actuator.set_destination(mygame.player.pos[0],mygame.player.pos[1])
    # next_move() will call find_path() for us.
    next_move = seeker.actuator.next_move()
    if next_move == constants.NO_DIR:
        seeker.actuator.set_destination(mygame.player.pos[0],mygame.player.pos[1])
    else:
        mygame.current_board().move(seeker,next_move,1)

next_waypoint()¶

Return the next active waypoint.

If no waypoint have been added, this function return None. If there is no more waypoint in the stack:

if PathFinder.circle_waypoints is True this function reset the waypoints stack and return the first one.
else, return None.

Returns:	Either a None tuple or the next waypoint.
Return type:	A None tuple or a tuple of integer.

Example:

pf.circle_waypoints = True
(row,column) = pf.next_waypoint()
pf.set_destination(row,column)

pause()¶

Set the actuator state to PAUSED.

Example:

mygame.pause()

remove_waypoint(row, column)¶

Remove a waypoint from the stack.

This method removes the first occurrence of a waypoint in the stack.

If the waypoint cannot be found, it raises a ValueError exception. If the row and column parameters are not int, an PglInvalidTypeException is raised.

Parameters:	row (int) – The “row” part of the waypoint’s coordinate. column – The “column” part of the waypoint’s coordinate.
Raises:	PglInvalidTypeException – If any of the parameters is not an int. ValueError – If the waypoint is not found in the stack.

Example:

method()

set_destination(row=0, column=0)¶

Set the targeted destination.

Parameters:	row (int) – “row” coordinate on the board grid column (int) – “column” coordinate on the board grid
Raises:	PglInvalidTypeException – if row or column are not int.

Example:

mykillernpc.actuator.set_destination(
    mygame.player.pos[0], mygame.player.pos[1]
)

start()¶

Set the actuator state to RUNNING.

If the actuator state is not RUNNING, actuators’ next_move() function (and all derivatives) should not return anything.

Example:

mygame.start()

stop()¶

Set the actuator state to STOPPED.

Example:

mygame.stop()

class pygamelib.actuators.PatrolActuator(path=None, parent=None)¶

Bases: pygamelib.actuators.PathActuator

The patrol actuator is a subclass of PathActuator. The move inside the function next_move depends on path and index and the mode. Once it reaches the end of the move list it will start cycling back to the beggining of the list. Once it reaches the beggining it will start moving forwards If the state is not running it returns None otherwise it increments the index & then, further compares the index with length of the path. If they both are same then, index is set to value zero and the move is returned back.

Parameters:	path (list) – A list of directions.

next_move()¶

Return the movement based on current index

The movement is selected from path if state is RUNNING, otherwise it should return None. When state is RUNNING, the movement is selected before incrementing the index by 1. When the index equals the length of path, the index should return back to 0 and the path list should be reversed before the next call.

Returns:	The next movement
Return type:	int \| None

Example:

patrolactuator.next_move()

pause()¶

Set the actuator state to PAUSED.

Example:

mygame.pause()

set_path(path)¶

Defines a new path

This will also reset the index back to 0.

Parameters:	path (list) – A list of movements.

Example:

pathactuator.set_path([constants.UP,constants.DOWN,constants.LEFT,constants.RIGHT])

start()¶

Set the actuator state to RUNNING.

If the actuator state is not RUNNING, actuators’ next_move() function (and all derivatives) should not return anything.

Example:

mygame.start()

stop()¶

Set the actuator state to STOPPED.

Example:

mygame.stop()

class pygamelib.actuators.RandomActuator(moveset=None, parent=None)¶

Bases: pygamelib.actuators.Actuator

A class that implements a random choice of movement.

The random actuator is a subclass of Actuator. It is simply implementing a random choice in a predefined move set.

Parameters:	moveset (list) – A list of movements. parent (pygamelib.board_items.BoardItem) – The parent object to actuate.

next_move()¶

Return a randomly selected movement

The movement is randomly selected from moveset if state is RUNNING, otherwise it should return None.

Returns:	The next movement
Return type:	int \| None

Example:

randomactuator.next_move()

pause()¶

Set the actuator state to PAUSED.

Example:

mygame.pause()

start()¶

Set the actuator state to RUNNING.

If the actuator state is not RUNNING, actuators’ next_move() function (and all derivatives) should not return anything.

Example:

mygame.start()

stop()¶

Set the actuator state to STOPPED.

Example:

mygame.stop()

class pygamelib.actuators.UnidirectionalActuator(direction=10000100, parent=None)¶

Bases: pygamelib.actuators.Actuator

A class that implements a single movement.

The unidirectional actuator is a subclass of Actuator. It is simply implementing a mono directional movement. It is primarily target at projectiles.

Parameters:	direction (int) – A single direction from the Constants module. parent (pygamelib.board_items.BoardItem) – The parent object to actuate.

next_move()¶

Return the direction.

The movement is always direction if state is RUNNING, otherwise it returns None.

Returns:	The next movement
Return type:	int \| None

Example:

unidirectional_actuator.next_move()

pause()¶

Set the actuator state to PAUSED.

Example:

mygame.pause()

start()¶

Set the actuator state to RUNNING.

If the actuator state is not RUNNING, actuators’ next_move() function (and all derivatives) should not return anything.

Example:

mygame.start()

stop()¶

Set the actuator state to STOPPED.

Example:

mygame.stop()