Actor

Contents

Actor#

class miniworlds.actors.actor.Actor(position=(0, 0), *args, **kwargs)[source]#

Actors are objects on your world. Actors can move around the world and have sensors to detect other actors.

The appearance of a actor is determined by its costume.

Examples

Create a actor:

from miniworlds import *

world = World()
world.size = (100,60)
Actor(position=(10, 10))

world.run()

Output:

Create a actor

Create a actor with an image:

from miniworlds import *

world = World(100,60)
actor = Actor((10, 10))
actor.add_costume("images/player.png")

world.run()

Output:

Create a Actor with image
import miniworlds

class MyActor(miniworlds.Actor):

    def on_setup(self):
        self.add_costume("images/player.png")

world = World(100,60)
my_actor = MyActor(position = (40,130))
world.run()

Output:

Create a actor

Create a Actor at current mouse position:

from miniworlds import *

world = World()

@world.register
def act(self):
    Actor(self.get_mouse_position())

world.run()
Create a actor at mouse position

See also

  • See: Actor

  • See: Shapes

  • See: TextActors and NumberActors

Public Data Attributes:

actor_count

class_image

origin

collision_type

collision_type specifies how collisions should be checked:

is_blockable

A actor with the property is_blockable cannot move through actors with the property is_blocking.

is_blocking

A actor with the property is_blockable cannot move through actors with the property is_blocking.

layer

Defines the layer on which the actor is drawn if several actors overlap.

last_position

Actor position in last frame

last_direction

costume_count

Returns number of costumes of actor, 0 if actor has no costume

is_flipped

When a actor is mirrored, it is mirrored across the y-axis.

costume

Gets the costume of actor

costumes

Gets the costume manager

orientation

direction

Directions are handled exactly as in the Scratch programming language, see: Scratch Wiki

direction_at_unit_circle

Gets the direction as value in unit circle (0° right, 90° top, 180° left...)

dirty

If actor is dirty, it will be repainted.

size

Size of the actor

width

The width of the actor in pixels.

height

The height of the actor in pixels.

x

The x-value of a actor

y

The y-value of a actor

class_name

topleft_x

x-value of actor topleft-position

topleft_y

x-value of actor topleft-position

topleft

local_center

x-value of actor center-position inside the current camera-screen

center_x

x-value of actor center-position

center_y

y-value of actor center-position

center

is_rotatable

Defines if the costume of a actor should be rotatable.

static

Should actor react to events? You can turn this option off for additional performance boost.

fill_color

The fill color of actor as rgba value, e.g. (255, 0, 0) for red.

color

The fill color of actor as rgba value, e.g. (255, 0, 0) for red.

is_filled

Is actor filled with color?

border_color

border color of actor.

stroke_color

border color of actor.

border

The border-size of actor.

visible

You can make this sprite disappear without removing it from the group assign 0 for invisible and 1 for visible

rect

The surrounding Rectangle as pygame.Rect.

world

image

The image of the actor:

position_manager

sensor_manager

costume_manager

position

The position of the actor as Position(x, y)

is_display_initialized

actor_id

children

speed

ask

Inherited from DirtySprite

visible

You can make this sprite disappear without removing it from the group assign 0 for invisible and 1 for visible

layer

Layer property can only be set before the sprite is added to a group, after that it is read only and a sprite's layer in a group should be set via the group's change_layer() method.

Inherited from Sprite

layer

Dynamic, read only property for protected _layer attribute.

Public Methods:

__init__([position])

switch_origin(value)

create_on_world(world)

Creates a actor to a specific world

from_topleft(topleft_position, *args, **kwargs)

Creates a actor with center at center_position

from_center(center_position, *args, **kwargs)

Creates a actor with center at center_position

flip_x()

Flips the actor by 180° degrees.

add_costume([source])

Adds a new costume to actor.

add_costumes(sources)

Adds multiple costumes

remove_costume([source])

Removes a costume from actor

switch_costume(source)

Switches the costume of actor

set_costume(costume)

reset_costumes()

set_background_color(color)

next_costume()

Switches to the next costume of actor

turn_left([degrees])

Turns actor by degrees degrees left :rtype: int

turn_right([degrees])

Turns actor by degrees degrees right

set_direction(direction)

Actor points in given direction.

point_towards_position(destination)

Actor points towards a given position

point_towards_actor(other)

Actor points towards another actor.

set_size(value)

scale_width(value)

scale_height(value)

move([distance])

Moves actor distance steps in current direction

move_vector(vector)

Moves actor in direction defined by the vector

move_up([distance])

move_down([distance])

move_left([distance])

move_right([distance])

move_back(distance)

undo_move()

Undo the last move.

move_towards(target)

move_in_direction(direction[, distance])

Moves actor distance steps into a direction or towards a position

move_to(position)

Moves actor distance to a specific world_posiition

remove([kill])

Removes this actor from world

before_remove()

bounce_from_border(borders)

The actor "bounces" from a border.

detect_all([actors, direction, distance])

Detects if actors are on actor position.

detect(*args, **kwargs)

Detects if actors are on actor position.

detect_borders([distance])

Detects borders :rtype: List

detect_left_border()

Does the actor touch the left border?

detect_right_border()

Does the actor touch the right border?

detect_top_border()

Does the actor touch the lower border?

detecting_bottom_border()

Does the actor touch the lower border?

detect_color([color])

Detects colors in world-background at actor center-position

detect_color_at([direction, distance])

Detects colors in world-background at actor-position

detect_actors_at([direction, distance, actors])

Detects a actor in given direction and distance.

detect_actor_at([direction, distance, actors])

detect_actors_in_front([actors, distance])

detect_actor_in_front([actors, distance])

detect_point(position)

Is the actor colliding with a specific (global) point?

detect_pixel(position)

Is the actor colliding with a pixel?

detect_rect(rect)

Is the actor colliding with a static rect?

detect_world()

Is the actor colliding with a static rect?

bounce_from_actor(other)

animate([speed])

animate_costume(costume[, speed])

animate_loop([speed])

Animates a costume with a looping animation

stop_animation()

Stops current animation.

send_message(message)

Sends a message to world.

on_key_down(key)

on_key_down is called one time when a key is pressed down.

on_key_pressed(key)

on_key_pressed is called when while key is pressed.

on_key_up(key)

on_mouse_over(position)

on_mouse_over is called, when mouse is moved over actor :type position: :param position: The mouse position

on_mouse_leave(position)

on_mouse_over is called, when mouse is moved over actor :type position: :param position: The mouse position

on_mouse_left(position)

on_mouse_left is called when left mouse button was pressed.

on_mouse_right(position)

Method is called when right mouse button was pressed.

on_mouse_motion(position)

Method is called when mouse moves.

on_mouse_left_released(position)

Method is called when left mouse key is released.

on_mouse_right_released(position)

Method is called when right mouse key is released.

on_clicked_left(position)

The mouse is on top of a actor and mouse was clicked.

on_clicked_right(position)

The mouse is on top of a actor and mouse was clicked.

on_detecting_world()

on_detecting_world is called, when actor is on the world

on_not_detecting_world()

on_detecting_world is called, when actor is on the world

on_detecting_actor(actor)

on_detect_actor is called, when actor is detects a actor on same position

on_detecting_borders(borders)

on_detecting_border is called, when actor is near a border

fill(value)

Set fill color for borders and lines

hide()

Hides a actor (the actor will be invisible)

show()

Displays a actor ( an invisible actor will be visible)

register(method[, force, name])

This method is used for the @register decorator.

register_message(*args, **kwargs)

This method is used for the @register_message decorator.

register_sensor(*args, **kwargs)

This method is used for the @register_sensor decorator.

get_local_rect()

__str__()

Return str(self).

set_world(new_world)

new_costume()

get_costume_class()

set_position(value)

get_distance_to(obj)

Gets the distance to another actor or a position

on_shape_change()

Inherited from DirtySprite

__init__(*groups)

__repr__()

Return repr(self).

Inherited from Sprite

__init__(*groups)

add(*groups)

add the sprite to groups

remove(*groups)

remove the sprite from groups

add_internal(group)

For adding this sprite to a group internally.

remove_internal(group)

For removing this sprite from a group internally.

update(*args, **kwargs)

method to control sprite behavior

kill()

remove the Sprite from all Groups

groups()

list of Groups that contain this Sprite

alive()

does the sprite belong to any groups

__repr__()

Return repr(self).

Private Data Attributes:

_world

_sensor_manager

_position_manager

_costume_manager

_collision_type

_layer

_is_acting

Private Methods:

_validate_arguments(position, *args, **kwargs)

Inherited from DirtySprite

_set_visible(val)

set the visible value (0 or 1) and makes the sprite dirty

_get_visible()

return the visible value of that sprite


actor_count: int = 0#
add_costume(source=None)[source]#

Adds a new costume to actor. The costume can be switched with self.switch_costume(index)

Return type:

Costume

Parameters:

source – Path to the first image of new costume or Tuple with color-value

Examples

Add first costume from image:

from miniworlds import *

world = World((100,60))
actor = Actor((10,10))
costume = actor.add_costume("images/player.png")

world.run()

Output:

Create Actor with image as costume

Add first costume from color:

from miniworlds import *

world = World((100,60))
actor = Actor((10,10))
costume = actor.add_costume((255,255,0))

world.run()

Output:

Create Actor with image as costume

Create two costumes and switch between costumes

from miniworlds import *

world = World((100,60))
actor = Actor((10,10))
world.speed = 30
costume1 = actor.add_costume((255,255,0))
costume2 = actor.add_costume((255,0,255))
@actor.register
def act(self):
    if self.costume == costume1:
        self.switch_costume(costume2)
    else:
        self.switch_costume(costume1)

world.run()

Output:

Create multiple costumes and switch between costumes
Returns:

The new costume.

add_costumes(sources)[source]#

Adds multiple costumes

Return type:

Costume

animate(speed=10)[source]#
animate_costume(costume, speed=10)[source]#
animate_loop(speed=10)[source]#

Animates a costume with a looping animation

Switches through all costume-images every speed-frame.

Examples

from miniworlds import *

world = World(columns=280, rows=100)
robo = Actor(position=(0, 0))
robo.costume.add_images(["images/1.png", "images/2.png","images/3.png","images/4.png"])
robo.size = (99, 99)
robo.animate_loop()
world.run()
Parameters:

speed (int, optional) – Every speed frame, the image is switched. Defaults to 10.

before_remove()[source]#
property border#

The border-size of actor.

The value is 0, if actor has no border.

Note

You can also set border with costume.border or you can set the border with world.default_border

Examples

Set border of actor:

from miniworlds import *

world = World(210,80)
world.default_border_color = (0,0, 255)
world.default_border = 1

t = Actor((10,10)) # default-border and color from world
t.add_costume("images/player.png")

t2 = Actor ((60, 10)) # overwrites default border values
t2.add_costume("images/player.png")
t2.border_color = (0,255, 0)
t2.border = 5

t3 = Actor ((110, 10)) # removes border
t3.add_costume("images/player.png")
t3.border = None

world.run()

Output:

Set borders
property border_color#

border color of actor.

The border-color is a rgba value, for example (255, 0, 0) for red, (0, 255, 0) for green and (255, 0, 0, 100).

If the color-value has 4 values, the last value defines the transparency:
  • 0: Full transparent,

  • 255: No transparency

Note

You must also set Actor.border to a value > 0

Aliases: Actor.stroke_color

Examples

See Actor.border

bounce_from_actor(other)[source]#
bounce_from_border(borders)[source]#

The actor “bounces” from a border.

The direction is set according to the principle input angle = output angle. :rtype: Actor

Note

You must check for borders first!

Parameters:

borders – A list of borders as strings e.g. [“left”, “right”]

Examples

from miniworlds import *
import random

world = World(150, 150)
actor = Actor((50,50))
actor.add_costume("images/ball.png")
actor.direction = 10

@actor.register
def act(self):
    self.move()
    borders = self.detecting_borders()
    if borders:
        self.bounce_from_border(borders)

world.run()

Output:

Returns:

The actor

property center: Tuple[float, float]#
property center_x: float#

x-value of actor center-position

property center_y: float#

y-value of actor center-position

class_image: str = ''#
property class_name: str#
property collision_type: str#

collision_type specifies how collisions should be checked:

  • default: tile for Tiledworlds, ‘mask’ for Pixelworlds

  • tile: Are actors on the same tile? (only TiledWorld)

  • rect: Are actors colliding when checking their bounding - boxes? (Only PixelWorld)

  • static-rect: Are actors colliding when checking circle with radius = bounding-box-radius.(Only PixelWorld)

  • circle: Are actors colliding when checking circle with radius = bounding-box-radius.(Only PixelWorld)

  • mask: Are actors colliding when checking if their image masks are overlapping.

property color#

The fill color of actor as rgba value, e.g. (255, 0, 0) for red.

When fill_color is set to a color, the attribute is_filled of costume (See: :py:attr:.appearances.appearance.Appearance.is_filled`) is set to True.

Note

Aliases: Actor.color

Warning

If you fill a costume with an image, the image will be completely overwritten, even if fill_color is transparent.

This behaviour may change in later releases!

Examples:

from miniworlds import *

world = World(200,80)
world.default_fill_color = (0,0, 255)

t = Actor()

t2 = Actor((40,0))
t2.is_filled = (0, 255, 0)

t3 = Actor((80, 0))
t3.fill_colorimport miniworlds.actors.actor as actor

= (255, 0, 0)

t4 = Actor((120, 0)) t4.add_costume((0,0,0)) t4.fill_color = (255, 255, 0)

t5 = Actor((160, 0)) t5.add_costume(“images/player.png”) t5.fill_color = (255, 255, 0, 100) # image is overwritten

t6 = Circle((0, 40), 20) t6.position = t6.center t6.fill_color = (255, 255, 255)

t7 = Ellipse((40, 40), 40, 40) t7.fill_color = (255, 0, 255)

world.run()

Output:

Set borders
property costume: Costume#

Gets the costume of actor

property costume_count: int#

Returns number of costumes of actor, 0 if actor has no costume

Examples

Add costume and count costumes

from miniworlds import *
world = World()
actor = Actor()
assert actor.costume_count == 0
actor.add_costume((255,0,0,0))
assert actor.costume_count == 1
world.run()
Returns:

_description_

Return type:

int

property costume_manager#
property costumes: CostumesManager#

Gets the costume manager

The costume manager can be iterated to get all costumes

classmethod create_on_world(world)[source]#

Creates a actor to a specific world

overwritten in subclasses

detect(*args, **kwargs)[source]#

Detects if actors are on actor position. Returns the first found actor. :rtype: Optional[Actor]

_images/detecting_actor.png
Parameters:
  • actors – filter by actor type. Enter a class_name of actors to look for heredirection: int = 0, distance: int = 0

  • direction – The direction in which actors should be detected.

  • distance – The distance in which actors should be detected (Start-Point is actor.center)

Returns:

First actor found by Sensor

Examples

The green robot pushes the yellow robot:

from miniworlds import *

world = TiledWorld(8,3)
actor = Actor((1,1))
actor.add_costume("images/robo_green.png")
actor.orientation = -90
actor.direction = 90

actor2 = Actor((4,1))
actor2.add_costume("images/robo_yellow.png")
actor2.orientation = -90
actor2.direction = -90

@actor.register
def act(self):
    self.move()
    actor = self.detecting_actor()
    if actor:
        actor.move_right()
world.run()

Output:

detect_actor_at(direction=None, distance=0, actors=None)[source]#
Return type:

Actor

detect_actor_in_front(actors=None, distance=1)[source]#
Return type:

Actor

detect_actors_at(direction=None, distance=0, actors=None)[source]#

Detects a actor in given direction and distance.

Examples

from miniworlds import *
world = World()
wall=Rectangle((200,0))
wall.size = (20, 400)

for i in range(7):
    actor = Circle((10,i*60 + 20))
    actor.range = i * 10
    @actor.register
    def act(self):
        if not self.detect_actors_at(self.direction, self.range):
            self.direction = "right"
            self.move()

world.run()
Parameters:
  • direction – The direction in which actors should be detected.

  • distance – The distance in which actors should be detected (Start-Point is actor.center)

Return type:

list

Returns:

A list of actors

detect_actors_in_front(actors=None, distance=1)[source]#
Return type:

list

detect_all(actors=None, direction=0, distance=0)[source]#

Detects if actors are on actor position. Returns a list of actors. :rtype: List[Actor]

_images/detecting_actors.png
Parameters:
  • actors – filter by actor type. Enter a class_name of actors to look for here

  • direction – The direction in which actors should be detected.

  • distance – The distance in which actors should be detected (Start-Point is actor.center)

Returns:

All actors found by Sensor

detect_borders(distance=0)[source]#

Detects borders :rtype: List

_images/detecting_borders.png
Parameters:

distance – Specifies the distance in front of the actuator to which the sensors reacts.

Returns:

True if border was found.

detect_color(color=None)[source]#

Detects colors in world-background at actor center-position

Return type:

bool

Parameters:

color – color as tuple

Returns:

True, if color was found

detect_color_at(direction=None, distance=0)[source]#

Detects colors in world-background at actor-position

Return type:

Union[Tuple, List]

Parameters:
  • direction – Specifies the direction where the sensors is searching.

  • distance – Specifies the distance in front of the actuator to which the sensors reacts.

Returns:

All colors found by Sensor

detect_left_border()[source]#

Does the actor touch the left border?

Return type:

bool

Returns:

True if border was found.

detect_pixel(position)[source]#

Is the actor colliding with a pixel?

Return type:

bool

Returns:

True if pixel is below actor

detect_point(position)[source]#

Is the actor colliding with a specific (global) point?

Return type:

bool

Warning

If your want to check if an actor detects a specific pixel, use detect_pixel

Returns:

True if point is below actor

detect_rect(rect)[source]#

Is the actor colliding with a static rect?

detect_right_border()[source]#

Does the actor touch the right border?

Return type:

bool

Returns:

True if border was found.

detect_top_border()[source]#

Does the actor touch the lower border?

Return type:

bool

Returns:

True if border was found.

detect_world()[source]#

Is the actor colliding with a static rect?

detecting_bottom_border()[source]#

Does the actor touch the lower border?

Return type:

bool

Returns:

True if border was found.

property direction: int#

Directions are handled exactly as in the Scratch programming language, see: Scratch Wiki

The default direction is . All actors are looking "up"

Move on world

Values for Direction

  • or "up": up

  • 90° or "right": Move right

  • -90° or "left": Move left

  • 180° or "down": Move down

  • "forward": Current direction

Sets direction of the actor.

You can use an integer or a string to describe the direction

Options
  • 0, "up" - Look up

  • 90, "right", - Look right

  • -90, "left", - Look left

  • -180, 180, "down" - Look down

../_images/direction.png

Examples

Move in a direction with WASD-Keys

def on_key_down(self, keys):
    if "W" in keys:
        self.direction = "up"
    elif "S" in keys:
        self.direction = "down"
    elif "A" in keys:
        self.direction = "left"
    elif "D" in keys:
        self.direction = "right"
    self.move()

Move 45°:

from miniworlds import *

world = World(100, 100)
c = Circle ((50,50), 10)

@c.register
def act(self):
    c.direction = 45
    c.move()

world.run()

Move -45°:

from miniworlds import *

world = World(100, 100)
c = Circle ((50,50), 10)

@c.register
def act(self):
    c.direction = -45
    c.move()

world.run()
property direction_at_unit_circle: int#

Gets the direction as value in unit circle (0° right, 90° top, 180° left…)

property dirty: int#

If actor is dirty, it will be repainted.

Returns:

1 if actor is dirty/0 otherwise

Return type:

int

fill(value)[source]#

Set fill color for borders and lines

property fill_color#

The fill color of actor as rgba value, e.g. (255, 0, 0) for red.

When fill_color is set to a color, the attribute is_filled of costume (See: :py:attr:.appearances.appearance.Appearance.is_filled`) is set to True.

Note

Aliases: Actor.color

Warning

If you fill a costume with an image, the image will be completely overwritten, even if fill_color is transparent.

This behaviour may change in later releases!

Examples:

from miniworlds import *

world = World(200,80)
world.default_fill_color = (0,0, 255)

t = Actor()

t2 = Actor((40,0))
t2.is_filled = (0, 255, 0)

t3 = Actor((80, 0))
t3.fill_colorimport miniworlds.actors.actor as actor

= (255, 0, 0)

t4 = Actor((120, 0)) t4.add_costume((0,0,0)) t4.fill_color = (255, 255, 0)

t5 = Actor((160, 0)) t5.add_costume(“images/player.png”) t5.fill_color = (255, 255, 0, 100) # image is overwritten

t6 = Circle((0, 40), 20) t6.position = t6.center t6.fill_color = (255, 255, 255)

t7 = Ellipse((40, 40), 40, 40) t7.fill_color = (255, 0, 255)

world.run()

Output:

Set borders
flip_x()[source]#

Flips the actor by 180° degrees. The costume is flipped and the actor’s direction changed by 180 degrees. :rtype: int

../_images/flip_x.png

Examples

Flip a actor in Example flipthefish.py

from miniworlds import *

world=TiledWorld()
world.columns = 4
world.rows = 1
world.add_background("images/water.png")
fish = Actor()
fish.border = 1
fish.add_costume("images/fish.png")
fish.direction = "right"
fish.orientation = -90
@fish.register
def act(self):
    self.move()

@fish.register
def on_not_detecting_world(self):
    self.move_back()
    self.flip_x()

world.run()

Output:

classmethod from_center(center_position, *args, **kwargs)[source]#

Creates a actor with center at center_position

Arg`s:

center_position: Center of actor

classmethod from_topleft(topleft_position, *args, **kwargs)[source]#

Creates a actor with center at center_position

Arg`s:

center_position: Center of actor

get_costume_class()[source]#
Return type:

type[Costume]

get_distance_to(obj)[source]#

Gets the distance to another actor or a position

Return type:

float

Parameters:

obj – Actor or Position

Returns:

The distance between actor (measured from actor.center) to actor or position.

Return type:

float

get_local_rect()[source]#
Return type:

Rect

property height#

The height of the actor in pixels.

When the height of a actor is changed, the width is scaled proportionally.

Examples

Create a actor and scale width/height proportionally:

from miniworlds import *

world = World(800,400)

def create_actor(x, y):
t = Actor()
t.position = (x, y)
t.add_costume("images/alien1.png")
t.border = 1
return t

t0 = create_actor(0,0)
t1 = create_actor(50,0)
t1.height = 400
t2 = create_actor(300,0)
t2.width = 180

world.run()
Textured image
hide()[source]#

Hides a actor (the actor will be invisible)

property image: Surface#

The image of the actor:

Warning

Warning: You should not directly draw on the image (with pygame functions) as the image will be reloaded during animations

property is_blockable#

A actor with the property is_blockable cannot move through actors with the property is_blocking.

property is_blocking#

A actor with the property is_blockable cannot move through actors with the property is_blocking.

property is_filled#

Is actor filled with color?

property is_flipped: bool#

When a actor is mirrored, it is mirrored across the y-axis. You can use this property in 2D platformer games to change the direction of actor.

Note

It may be necessary to set is_rotatable = True

Examples

Flip a costume after 100 frames.

from miniworlds import *

world = World(100,100)
actor = Actor()
actor.add_costume("images/alien1.png")
actor.height= 400
actor.width = 100
actor.is_rotatable = False
@actor.register
def act(self):
    if self.world.frame % 100 == 0:
        if self.is_flipped:
            self.is_flipped = False
        else:
            self.is_flipped = True
world.run()

Output:

Returns:

True, if actor is flipped

property is_rotatable: bool#

Defines if the costume of a actor should be rotatable. The actor can still be rotated with the direction property, but its costume won’t be changed

Note

You can also use actor.costume.is_rotatable

Examples

Create a rotatable and a not rotatable actor

from miniworlds import *
world = World()

t1 = Actor((100,100))
t1.add_costume("images/alien1.png")

t2 = Actor((200,200))
t2.add_costume("images/alien1.png")
t2.is_rotatable = False

@t1.register
def act(self):
    self.move()
    self.direction += 1

@t2.register
def act(self):
    self.move()
    self.direction += 1

world.run()

Output:

property last_direction: int#
property last_position: Tuple[float, float]#

Actor position in last frame

Can be used to track changes.

property layer: int#

Defines the layer on which the actor is drawn if several actors overlap.

property local_center: Tuple[float, float]#

x-value of actor center-position inside the current camera-screen

move(distance=0)[source]#

Moves actor distance steps in current direction

../_images/move.png
Parameters:

distance – Number of steps to move. If distance = 0, the actor speed will be used.

Returns:

The moved actor

Examples

if actor is on the world, move forward:

class Robot(Actor):

    def act(self):
        if self.detecting_world():
            self.move()
move_back(distance)[source]#
move_down(distance=1)[source]#
move_in_direction(direction, distance=1)[source]#

Moves actor distance steps into a direction or towards a position

../_images/move_in_direction.png
Options
  • 0, “up” - Look up

  • 90, “right”, - Look right

  • -90, “left”, - Look left

  • -180, 180, “down” - Look down

../_images/direction.png
Parameters:
  • direction – Direction as angle

  • distance – Detects obj “distance” steps in front of current actor.

Returns:

The actor itself

move_left(distance=1)[source]#
move_right(distance=1)[source]#
move_to(position)[source]#

Moves actor distance to a specific world_posiition

Parameters:
  • position – The position to which the actor should move. The position can be a 2-tuple (x, y)

  • world_position (which will be converted to a)

../_images/move_to.png
Returns:

The actor itself

Examples

move to (3, 2) on mouse_click

def on_clicked_left(self, position):
    self.move_to((3,2))
move_towards(target)[source]#
move_up(distance=1)[source]#
move_vector(vector)[source]#

Moves actor in direction defined by the vector

Returns:

The moved actor

new_costume()[source]#
next_costume()[source]#

Switches to the next costume of actor

Returns:

The new costume

on_clicked_left(position)[source]#

The mouse is on top of a actor and mouse was clicked.

Examples

Registering a on_click event:

actor = miniworlds.Actor((2,2))

@actor.register
def on_clicked_left(self, position):
    print("clicked" + str(position))
Parameters:

position (tuple) – Actual mouse position as tuple (x,y)

Raises:

NotImplementedOrRegisteredError – The error is raised when method is not overwritten or registered.

on_clicked_right(position)[source]#

The mouse is on top of a actor and mouse was clicked.

Examples

Registering a on_click event:

actor = miniworlds.Actor((2,2))

@actor.register
def on_clicked_right(self, position):
    print("clicked" + str(position))
Parameters:

position (tuple) – Actual mouse position as tuple (x,y)

Raises:

NotImplementedOrRegisteredError – The error is raised when method is not overwritten or registered.

on_detecting_actor(actor)[source]#

on_detect_actor is called, when actor is detects a actor on same position

Parameters:

actor (Actor) – The found actor

Examples

Register detect_actor event

@player.register
def on_detect_actor(self, actor):
    print("Player 1: detecting actor:")
    if actor == player2:
    print("Am i detecting player2?" + str(actor == player2))
Raises:

NotImplementedOrRegisteredError – The error is raised when method is not overwritten or registered.

on_detecting_borders(borders)[source]#

on_detecting_border is called, when actor is near a border

Parameters:

borders (List) – A list of strings with found borders, e.g.: [‘left’, ‘top’]

Examples

Register on_detecting_border_event:

@player.register
def on_detecting_borders(self, borders):
    print("Player 4: detecting borders:")
    print("Borders are here!", str(borders))
Raises:

NotImplementedOrRegisteredError – The error is raised when method is not overwritten or registered.

on_detecting_world()[source]#

on_detecting_world is called, when actor is on the world

Examples

Register on_detecting_world method:

@player.register
    def on_detecting_world(self):
        print("Player 3: I'm on the world:")
Raises:

NotImplementedOrRegisteredError – The error is raised when method is not overwritten or registered.

on_key_down(key)[source]#

on_key_down is called one time when a key is pressed down.

Note

Instead of on_key_down you can use on_key_down_letter, e.g. on_key_down_a or on_key_down_w , if you want to handle an on_key_down event for a specific letter.

Examples

Register a key_down event:

actor1 = miniworlds.Actor(position = (2, 2) )
actor1.add_costume((100,0,100,100))

@actor1.register
def on_key_down(self, key):
    print(key)

Register on_key_down_a event

actor1 = miniworlds.Actor(position = (2, 2) )
actor1.add_costume((100,0,100,100))

@actor1.register
def on_key_down_a(self):
    print("a")
Parameters:

key (list) – The typed key as list (e.g. [‘A’, ‘a’]) containing both uppercase and lowercase of typed letter.

Raises:

NotImplementedOrRegisteredError – The error is raised when method is not overwritten or registered.

on_key_pressed(key)[source]#

on_key_pressed is called when while key is pressed. If you hold the key, on_key_pressed is repeatedly called again and again until the key is released.

Note

Like on_key_down the method can be called in the variant on_key_pressed_[letter] (e.g. on_key_pressed_w(self)).

Examples

Register on_key_pressed event:

actor1 = miniworlds.Actor(position = (2, 2) )
actor1.add_costume((100,0,100,100))

@actor1.register
def on_key_pressed(self, key):
    print("pressed", key)

@actor1.register
def on_key_pressed_s(self):
    print("pressed s")
Parameters:
  • key (list) – The typed key as list (e.g. [‘C’, ‘c’, ‘D’, ‘d’]) containing both uppercase and lowercase

  • letter. (of typed)

Raises:

NotImplementedOrRegisteredError – The error is raised when method is not overwritten or registered.

on_key_up(key)[source]#
on_mouse_leave(position)[source]#

on_mouse_over is called, when mouse is moved over actor :type position: :param position: The mouse position

on_mouse_left(position)[source]#

on_mouse_left is called when left mouse button was pressed. You must register or implement this method as an event.

Note

The event is triggered, when mouse-left was clicked, even when the current mouse position is not related to actor position.

You can use Actor.detect_pixel() to check, if the mouse_position is inside the actor.

Examples

A circle will be moved, if you click on circle.

from miniworlds import *

world = World(120,40)
circle = Circle((20, 20))
circle.direction = 90

@circle.register
def on_mouse_left(self, mouse_pos):
    if self.detect_pixel(mouse_pos):
        self.move()

world.run()
Parameters:

position (tuple) – Actual mouse position as tuple (x,y)

Raises:

NotImplementedOrRegisteredError – The error is raised when method is not overwritten or registered.

on_mouse_left_released(position)[source]#

Method is called when left mouse key is released.

Examples

You can use on_mouse_left_release to implement a drag_and_drop event

from miniworlds import *

world = World(200, 200)
circle = Circle((30, 30), 60)
circle.direction = 90
circle.dragged = False

@circle.register
def on_mouse_left(self, mouse_pos):
    if self.detect_pixel(mouse_pos):
        self.dragged = True

@circle.register
def on_mouse_left_released(self, mouse_pos):
    if not world.is_mouse_pressed():
        self.dragged = False
        self.center = mouse_pos

world.run()

Output:

Parameters:

position (tuple) – Actual mouse position as tuple (x,y)

Raises:

NotImplementedOrRegisteredError – The error is raised when method is not overwritten or registered.

on_mouse_motion(position)[source]#

Method is called when mouse moves. You must register or implement this method as an event.

Note

The event is triggered, when mouse is moved, even when the current mouse position is not related to actor position.

You can use Actor.detect_pixel() to check, if the mouse_position is inside the actor.

Examples

A circle will be moved, if you click on circle.

from miniworlds import *

world = World(120,40)
circle = Circle((20, 20))
circle.direction = 90

@circle.register
def on_mouse_motion(self, mouse_pos):
    if self.detect_pixel(mouse_pos):
        self.move()

world.run()
Parameters:

position (tuple) – Actual mouse position as tuple (x,y)

Raises:

NotImplementedOrRegisteredError – The error is raised when method is not overwritten or registered.

on_mouse_over(position)[source]#

on_mouse_over is called, when mouse is moved over actor :type position: :param position: The mouse position

on_mouse_right(position)[source]#

Method is called when right mouse button was pressed. You must register or implement this method as an event.

Note

The event is triggered, when mouse was clicked,even when the current mouse position is not related to actor position.

You can use Actor.detect_pixel() to check, if the mouse_position is inside the actor.

Examples

See: Actor.on_mouse_left().

Parameters:

position (tuple) – Actual mouse position as tuple (x,y)

Raises:

NotImplementedOrRegisteredError – The error is raised when method is not overwritten or registered.

on_mouse_right_released(position)[source]#

Method is called when right mouse key is released. See Actor.on_mouse_left_released().

Parameters:

position (tuple) – Actual mouse position as tuple (x,y)

Raises:

NotImplementedOrRegisteredError – The error is raised when method is not overwritten or registered.

on_not_detecting_world()[source]#

on_detecting_world is called, when actor is on the world

Examples

Register on_detecting_world method:

@player.register
    def on_detecting_world(self):
        print("Player 3: I'm on the world:")
Raises:

NotImplementedOrRegisteredError – The error is raised when method is not overwritten or registered.

on_shape_change()[source]#
property orientation: float#
property origin#
point_towards_actor(other)[source]#

Actor points towards another actor.

Return type:

int

Parameters:

other – The other actor

Returns:

The new direction

point_towards_position(destination)[source]#

Actor points towards a given position

Return type:

Union[int, float]

Parameters:

destination – The position to which the actor should pointing

Returns:

The new direction

Examples

Point towards mouse_position:

def act(self):
    mouse = self.world.get_mouse_position()
if mouse:
    self.point_towards_position(mouse)
self.move()
property position: Tuple[float, float]#

The position of the actor as Position(x, y)

property position_manager#
property rect: Rect#

The surrounding Rectangle as pygame.Rect. The rect coordinates describes the local coordinates and depend on the camera view.

Warning

If the actor is rotated, the rect vertices are not the vertices of the actor image.

register(method, force=False, name=None)[source]#

This method is used for the @register decorator. It adds a method to an object

Parameters:
  • method (callable) – The method which should be added to the actor

  • force – Should register forced, even if method is not handling a valid event?

  • name – Registers method with specific name

register_message(*args, **kwargs)[source]#

This method is used for the @register_message decorator.

It adds a method to an object and reacts to on_message events

Parameters:
  • method (callable) – The method which should be added to the actor

  • force – Should register forced, even if method is not handling a valid event?

  • name – Registers method with specific name

register_sensor(*args, **kwargs)[source]#

This method is used for the @register_sensor decorator.

It adds a method to an object and reacts to on_detect_[class] events

Parameters:
  • method (callable) – The method which should be added to the actor

  • force – Should register forced, even if method is not handling a valid event?

  • name – Registers method with specific name

remove(kill=True)[source]#

Removes this actor from world

Examples: :rtype: defaultdict

Removes robots in thecrash.py :

def act(self):
    self.move()
    other = self.detecting_actor(distance = 0, actor_type=Robot)
if other:
    explosion = Explosion(position=self.position)
    self.remove()
    other.remove()
remove_costume(source=None)[source]#

Removes a costume from actor

Parameters:

source – The index of the new costume or costume-object. Defaults to actual costume

reset_costumes()[source]#
scale_height(value)[source]#
scale_width(value)[source]#
send_message(message)[source]#

Sends a message to world.

The message can be received with the on_message-event

Examples

Send and receive messages:

from miniworlds import *

world = World()

actor1 = Actor((2, 2))
actor1.add_costume((100,0,100,100))

@actor1.register
def on_message(self, message):
    print("Received message:" + message)

actor2 = Actor((100,100))
actor2.send_message("Hello from actor2")

@actor2.register
def on_key_down_s(self):
    self.send_message("Hello")
world.run()
Parameters:

message (str) – A string containing the message.

property sensor_manager#
set_background_color(color)[source]#
set_costume(costume)[source]#
set_direction(direction)[source]#

Actor points in given direction.

You can use a integer or a string to describe the direction

Return type:

float

Parameters:

string (The direction as integer or)

Options
  • 0, "up" - Look up

  • 90, "right", - Look right

  • -90, "left", - Look left

  • -180, 180, "down" - Look down

../_images/direction.png

Examples

Move in a direction with WASD-Keys

def on_key_down(self, keys):
    if "W" in keys:
        self.direction = "up"
    elif "S" in keys:
        self.direction = "down"
    elif "A" in keys:
        self.direction = "left"
    elif "D" in keys:
        self.direction = "right"
    self.move()
set_position(value)[source]#
set_size(value)[source]#
set_world(new_world)[source]#
Return type:

Actor

show()[source]#

Displays a actor ( an invisible actor will be visible)

property size: tuple#

Size of the actor

property static#

Should actor react to events? You can turn this option off for additional performance boost.

stop_animation()[source]#

Stops current animation. Costume is_animated is set to False

Examples

from miniworlds import *

world = World(columns=280, rows=100)
robo = Actor(position=(0, 0))
robo.costume.add_images(["images/1.png", "images/2.png","images/3.png","images/4.png"])
robo.size = (99, 99)
robo.animate_loop()
@timer(frames = 100)
def stop():
    robo.stop_animation()
world.run()
property stroke_color#

border color of actor.

The border-color is a rgba value, for example (255, 0, 0) for red, (0, 255, 0) for green and (255, 0, 0, 100).

If the color-value has 4 values, the last value defines the transparency:
  • 0: Full transparent,

  • 255: No transparency

Note

You must also set Actor.border to a value > 0

Aliases: Actor.stroke_color

Examples

See Actor.border

switch_costume(source)[source]#

Switches the costume of actor

Return type:

Costume

Parameters:

source – Number of costume or Costume object

Examples

Switch a costume:

from miniworlds import *

world = World(100,60)
t = Actor()
costume =t1.add_costume("images/1.png")
t.add_costume("images/2.png")
t.switch_costume(1)

@timer(frames = 40)
def switch():
    t1.switch_costume(0)

world.run()
Returns:

The new costume

switch_origin(value)[source]#
property topleft: Tuple[float, float]#
property topleft_x: float#

x-value of actor topleft-position

property topleft_y: float#

x-value of actor topleft-position

turn_left(degrees=90)[source]#

Turns actor by degrees degrees left :rtype: int

../_images/turn_left.png
Options:
  • You can set the value actor.is_rotatable = False if you don’t want the actor to be rotated.

Examples

from miniworlds import *

world = World(100, 100)
t = Actor()
t.add_costume("images/arrow.png")
t.size = (100,100)

@t.register
def act(self):
    t.turn_left(1)

world.run()

Output:

Parameters:

degrees – degrees in left direction

Returns:

New direction

turn_right(degrees=90)[source]#

Turns actor by degrees degrees right

../_images/turn_right.png

Examples

from miniworlds import *

world = World(100, 100)
t = Actor()
t.add_costume("images/arrow.png")
t.size = (100,100)

@t.register
def act(self):
    t.turn_left(1)

world.run()

Output:

Options:
  • You can set the value actor.is_rotatable = False if you don’t want the actor to be rotated.

Parameters:

degrees – degrees in left direction

Returns:

New direction

undo_move()[source]#

Undo the last move. Moves the actor to the last position and resets direction.

../_images/move_back.png
Returns:

The moved actor

Examples

move_back when field is blocked:

def on_detecting_wall(self, wall):
    self.undo_move()
property visible#

You can make this sprite disappear without removing it from the group assign 0 for invisible and 1 for visible

property width#

The width of the actor in pixels.

When the width of a actor is changed, the height is scaled proportionally.

Examples

Create a actor and scale width/height proportionally:

from miniworlds import *

world = World(800,400)

def create_actor(x, y):
t = Actor()
t.position = (x, y)
t.add_costume("images/alien1.png")
t.border = 1
return t

t0 = create_actor(0,0)
t1 = create_actor(50,0)
t1.height = 400
t2 = create_actor(300,0)
t2.width = 180

world.run()
Textured image
property world#
property x: float#

The x-value of a actor

property y: float#

The y-value of a actor