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

API Reference

class miniworlds.worlds.world.World(x=400, y=400)

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)

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))

actors_at(position)

Student-friendly alias for detect_actors(position).

Return type:

List[Actor]

add_background(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)

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)

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)

Return whether a position lies inside the world.

This is a short alias for contains_position().

contains_position(pos)

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)

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)

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)

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)

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)

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)

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()

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)

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

is_in_world(position)

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 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()

Student-friendly alias to switch to the next background.

Return type:

Background

on_setup()

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))

quit(exit_code=0)

Quit the application and close the game window.

Return type:

None

Parameters:

exit_code – Process exit code.

Examples

world.quit()

remove_background(background=None)

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()

Reset the world to its initial state.

Examples

@player.register
def on_detecting_actor(self, other):
    if isinstance(other, Enemy):
        self.world.reset()

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)

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.

Examples

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

send_message(message, data=None)

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)

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)

Student-friendly alias for set_background(source).

Return type:

Background

set_columns(value)

Set the visible world width in pixels.

Return type:

None

Parameters:

value – New width in pixels.

Examples

world.set_columns(640)

set_rows(value)

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()

Start or resume world updates.

Return type:

None

Examples

world.start()

stop(frames=0)

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)

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)

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)

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)

exception miniworlds.base.exceptions.OriginException(actor, value=None)