World#

The base class for all of your worlds.

Use world.send_message("name") for simple broadcasts between the world, actors, and docked GUI worlds.

For beginner classes, set world.learning_mode = True. This enables soft conversions for common mistakes in selected public APIs (for example bool-like strings such as "yes"/"no" in some flags, and list positions where tuple positions are expected).

Useful beginner aliases on World include:

  • contains(...) for contains_position(...)

  • broadcast(...) for send_message(...)

  • actors_at(...) for detect_actors(...)

  • set_bg(...), add_bg(...), next_bg() for background helpers

For interactive IDE calls, see Experimentieren aus einer IDE for pause(), invoke(), refresh(), resume(), and versioned object handles.

API Reference#

class miniworlds.worlds.world.World(x=400, y=400)[source]#

Pixel-based scene that owns actors, backgrounds, input, and events.

Positions in a World are pixel coordinates. Actors are placed by their top-left position by default unless their origin is changed.

Notes

Collision checks use sprite masks by default.

Examples

Create and run a world:

    from miniworlds import World
    world = World(300, 200)
    world.run()

Configure a subclass during setup:

    import miniworlds

    class MyWorld(miniworlds.World):
        def on_setup(self):
            self.columns = 300
            self.rows = 200
__init__(x=400, y=400)[source]#

Create a world with the given size.

Parameters:
  • x – Width in pixels, or a (width, height) tuple.

  • y – Height in pixels. Ignored when x is a tuple.

Examples

world = World(400, 300)
square_world = World((200, 200))
act()[source]#

Hook: called once per frame while the world is running.

Overwrite this method in a subclass (or register a function with @world.register) to run code every frame.

The base implementation does nothing, so super().act() is never required in an overwritten act method.

Return type:

None

Examples

class MyWorld(World):
    def act(self):
        if self.frame % 60 == 0:
            self.spawn_enemy()
actors_at(position)[source]#

Student-friendly alias for detect_actors(position).

Return type:

List[Actor]

add_background(source)[source]#

Add a background and make it active.

Return type:

Background

Parameters:

source – Image path or RGB/RGBA color tuple.

Returns:

The newly created Background.

Examples

world.add_background((255, 0, 0))
world.add_background("images/background.png")
add_bg(source)[source]#

Student-friendly alias for add_background(source).

Return type:

Background

property background: Background#

Currently active world background.

Examples

world.background = (30, 30, 30)
world.background = "images/sky.png"
current = world.background
Type:

Background

broadcast(message, data=None)[source]#

Student-friendly alias for send_message(message, data).

Return type:

None

property columns: int#

Width of the visible world area in pixels.

Examples

world.columns = 640
Type:

int

contains(pos)[source]#

Return whether a position lies inside the world.

This is a short alias for contains_position().

contains_position(pos)[source]#

Return whether a position lies inside the world.

Parameters:

pos – Position as (x, y).

Returns:

True if the position is inside the world.

Examples

if world.contains_position(actor.center):
    actor.move()
contains_rect(rect)[source]#

Return whether a rectangle is fully inside the world.

Parameters:

rect – Rectangle as (x, y, width, height) or pygame.Rect.

Returns:

True if the whole rectangle is inside the world.

Examples

if world.contains_rect(actor.rect):
    actor.move()
contains_rect_any(rect)[source]#

Return whether any part of a rectangle is inside the world.

Parameters:

rect – Rectangle as (x, y, width, height) or pygame.Rect.

Returns:

True if at least one part of the rectangle is inside the world.

Examples

if not world.contains_rect_any(actor.rect):
    actor.remove()
property debug: bool#

Whether to draw a compact runtime debug overlay.

Examples

world.debug = True
Type:

bool

detect_actors(position)[source]#

Return all actors at a world position.

Return type:

List[Actor]

Parameters:

position – World position as (x, y).

Returns:

Actors found at the position.

Examples

actors = world.detect_actors(player.position)
for actor in actors:
    if isinstance(actor, Coin):
        actor.remove()
dialog#
direction_to(pos1, pos2)[source]#

Return the Miniworlds direction from one position to another.

Return type:

float

Parameters:
  • pos1 – Start position as (x, y).

  • pos2 – Target position as (x, y).

Returns:

Direction angle in degrees.

Examples

mouse_position = world.mouse.get_position()
actor.direction = world.direction_to(actor.center, mouse_position)
static distance_to(pos1, pos2)[source]#

Return the Euclidean distance between two positions.

Return type:

float

Parameters:
  • pos1 – First position as (x, y).

  • pos2 – Second position as (x, y).

Returns:

Distance between both positions.

Examples

distance = World.distance_to((0, 0), (3, 4))
property fps: int#

Frames per second of the render loop.

This controls redraw frequency. Logic frequency can be tuned independently via world.tick_rate.

Example

world.fps = 24 world.tick_rate = 2

get_actors_from_pixel(pixel)[source]#

Return all actors under a screen pixel.

Return type:

List[Actor]

Parameters:

pixel – Screen pixel as (x, y).

Returns:

Actors whose screen rectangle overlaps the pixel.

Examples

@world.register
def on_mouse_left(self, position):
    for actor in self.get_actors_from_pixel(position):
        actor.hide()
get_background()[source]#

Return the active background.

Return type:

Background

Returns:

The current Background.

Examples

bg = world.get_background()
bg.fill_color = (0, 0, 0)
get_from_pixel(position)[source]#

Convert a screen pixel position to a world position.

Return type:

Optional[Tuple[float, float]]

Parameters:

position – Pixel position as (x, y).

Returns:

World position, or None if the pixel is outside the world.

Examples

@world.register
def on_mouse_left(self, position):
    world_position = self.get_from_pixel(position)
    if world_position:
        Actor(world_position)
property has_background: bool#

Whether the world has at least one background.

Examples

if world.has_background:
    world.next_bg()
Type:

bool

invoke(callback, *args, **kwargs)[source]#

Call synchronously in the runtime thread and refresh, staying paused.

Returns the callback result; exceptions propagate without rolling back mutations. The host must dispatch this on the SDL/mainloop thread.

is_in_world(position)[source]#

Return whether a position lies inside the world.

Return type:

bool

Parameters:

position – Position as (x, y).

Returns:

True if the position is inside the world.

Examples

if world.is_in_world((100, 100)):
    print("inside")
property is_paused: bool#

Whether the world is frozen for interactive experimentation.

property layout#

Backward-compatible docking API for older example code.

The actual layout manager remains internal on world._layout. Public docking helpers continue to live on world.camera and are exposed here as a compatibility alias for existing teaching material.

property learning_mode: bool#

Whether beginner-friendly conversions and hints are enabled.

Examples

world.learning_mode = True
Type:

bool

next_bg()[source]#

Student-friendly alias to switch to the next background.

Return type:

Background

on_setup()[source]#

Hook for initial world setup.

Override this in subclasses or register a function with @world.register.

Return type:

None

Examples

@world.register
def on_setup(self):
    self.background = (0, 0, 0)
    Actor((20, 20))
pause()[source]#

Freeze simulation and game events, including before the first frame.

Return type:

None

play_sound(path, volume=100)[source]#

Student-friendly alias for sound.play(path, volume).

Students often try world.play_sound(…) first, so this alias exists for discoverability. Prefer world.sound.play(…).

Return type:

None

Parameters:
  • path – Path to the sound.

  • volume – Volume between 0 and 100.

quit(exit_code=0)[source]#

Quit the application and close the game window.

Return type:

None

Parameters:

exit_code – Process exit code.

Examples

world.quit()
refresh()[source]#

Render current state without advancing animation, timers, or physics.

Return type:

None

remove_background(background=None)[source]#

Remove a background.

Return type:

None

Parameters:

background – Background index or Appearance. If omitted, the last background is removed.

Examples

world.remove_background()
world.remove_background(0)
reset()[source]#

Reset the world to its initial state.

Examples

@player.register
def on_detecting_actor(self, other):
    if isinstance(other, Enemy):
        self.world.reset()
resume()[source]#

Leave experiment mode and resume normal simulation.

Return type:

None

property rows: int#

Height of the visible world area in pixels.

Examples

world.rows = 480
Type:

int

run(fullscreen=False, fit_desktop=False, replit=False, event=None, data=None, video_driver=None)[source]#

Start the Miniworlds main loop.

Call this once at the end of a Miniworlds program.

Return type:

None

Parameters:
  • fullscreen – Whether to launch in fullscreen mode.

  • fit_desktop – Whether to adapt the window to the desktop.

  • replit – Whether to use Replit-specific display adjustments.

  • event – Optional event name to queue at startup.

  • data – Optional data to include with the startup event.

  • video_driver – Force an SDL video driver, for example “x11” or “wayland”. Use it if the window stays black, e.g. on some Linux systems. It has the same effect as starting the program with the environment variable SDL_VIDEODRIVER, which also works. Ignored in the browser.

Examples

world = World(800, 600)
world.run()

Force the X11 driver:

world.run(video_driver="x11")
send_message(message, data=None)[source]#

Broadcast a message to the world and its actors.

The message is dispatched through the event system and can be handled by registered message handlers.

Return type:

None

Parameters:
  • message – Message name.

  • data – Optional payload for message-specific handlers.

Examples

world.send_message("game_over")

@world.register
def on_message(self, message):
    if message == "game_over":
        self.stop()
set_background(source)[source]#

Replace the active background.

Return type:

Background

Parameters:

source – Image path or RGB/RGBA color tuple.

Returns:

The new active Background.

Examples

world.set_background("images/sky.png")
world.set_background((30, 30, 30))
set_bg(source)[source]#

Student-friendly alias for set_background(source).

Return type:

Background

set_columns(value)[source]#

Set the visible world width in pixels.

Return type:

None

Parameters:

value – New width in pixels.

Examples

world.set_columns(640)
set_rows(value)[source]#

Set the visible world height in pixels.

Return type:

None

Parameters:

value – New height in pixels.

Examples

world.set_rows(480)
property size: Tuple[int, int]#

World size as (width, height) in pixels.

Examples

width, height = world.size
world.size = (800, 600)
Type:

tuple[int, int]

start()[source]#

Start or resume world updates.

Return type:

None

Examples

world.start()
step(frames=1)[source]#

Advance a paused world by exactly frames simulation frames.

The world stays paused afterwards (“Act” in a stepping IDE). The frames are executed by the mainloop, one per loop iteration.

Return type:

None

stop(frames=0)[source]#

Stop world updates immediately or after a number of frames.

Return type:

None

Parameters:

frames – Frames to wait before stopping. 0 stops immediately.

Examples

world.stop()
world.stop(frames=5)
switch_background(background)[source]#

Switch to another background.

Pass an index, an existing appearance, or -1 for the next background.

Return type:

Background

Parameters:

background – Background index, Appearance, or -1.

Returns:

The new active Background.

Examples

world.add_background("images/day.png")
world.add_background("images/night.png")
world.switch_background(1)
world.switch_background(-1)
switch_world(new_world, reset=False)[source]#

Switch the active scene to another world.

Return type:

None

Parameters:
  • new_world – The world that should become active.

  • reset – If True, the new world is reset before it starts.

property tick_rate: int#

How often world logic runs relative to the frame loop.

A value of 1 runs game logic every frame. A value of 30 runs it every 30th frame.

Example

from miniworlds import World

world = World(120, 210) world.fps = 60 world.tick_rate = 3 world.run()

to_pixel(position)[source]#

Convert a world position to a screen pixel position.

Return type:

Tuple[float, float]

Parameters:

position – World position as (x, y).

Returns:

Pixel position as (x, y).

Examples

pixel = world.to_pixel(actor.position)
property world_size_x: int#

Horizontal world size in pixels.

Examples

world.world_size_x = 800
print(world.world_size_x)
Type:

int

property world_size_y: int#

Vertical world size in pixels.

Examples

world.world_size_y = 600
print(world.world_size_y)
Type:

int

Exceptions#

These exceptions are exported by miniworlds for code that wants to catch specific Miniworlds errors. They are documented here but intentionally do not have their own navigation entry.

exception miniworlds.base.exceptions.CostumeOutOfBoundsError(actor, costume_count, costume_number)[source]#
exception miniworlds.base.exceptions.OriginException(actor, value=None)[source]#