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(...)forcontains_position(...)broadcast(...)forsend_message(...)actors_at(...)fordetect_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:
Examples
class MyWorld(World): def act(self): if self.frame % 60 == 0: self.spawn_enemy()
- add_background(source)[source]#
Add a background and make it active.
- Return type:
- 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")
- property background: Background#
Currently active world background.
Examples
world.background = (30, 30, 30) world.background = "images/sky.png" current = world.background
- Type:
- broadcast(message, data=None)[source]#
Student-friendly alias for send_message(message, data).
- Return type:
- property columns: int#
Width of the visible world area in pixels.
Examples
world.columns = 640
- Type:
- 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:
- detect_actors(position)[source]#
Return all actors at a world position.
- Return type:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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 onworld.cameraand 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:
- on_setup()[source]#
Hook for initial world setup.
Override this in subclasses or register a function with @world.register.
- Return type:
Examples
@world.register def on_setup(self): self.background = (0, 0, 0) Actor((20, 20))
- 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:
- 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:
- Parameters:
exit_code – Process exit code.
Examples
world.quit()
- refresh()[source]#
Render current state without advancing animation, timers, or physics.
- Return type:
- remove_background(background=None)[source]#
Remove a background.
- Return type:
- 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()
- 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:
- 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:
- 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:
- 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_columns(value)[source]#
Set the visible world width in pixels.
- Return type:
- Parameters:
value – New width in pixels.
Examples
world.set_columns(640)
- set_rows(value)[source]#
Set the visible world height in pixels.
- Return type:
- 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)
- step(frames=1)[source]#
Advance a paused world by exactly
framessimulation frames.The world stays paused afterwards (“Act” in a stepping IDE). The frames are executed by the mainloop, one per loop iteration.
- Return type:
- stop(frames=0)[source]#
Stop world updates immediately or after a number of frames.
- Return type:
- 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:
- 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:
- 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:
- Parameters:
position – World position as (x, y).
- Returns:
Pixel position as (x, y).
Examples
pixel = world.to_pixel(actor.position)
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.