xpgzero 1.2.6

A zero-boilerplate 2D games framework

xpgzero is a unified and extended version of Pygame Zero that incorporates the original code written by Daniel Pope and adds functionality from the pgzhelper library.

The library maintains the simple and clear syntax of the original Pygame Zero, making it ideal for teaching programming and creating 2D games. At the same time, it expands the basic capabilities:

1. Preservation of Original Simplicity: All core hooks (draw, update), objects (Actor, Rect, keyboard), and built-in modules (screen, clock, music, sounds) work exactly as they do in classic Pygame Zero.

2. Additional Methods for Actor (from pgzhelper): Actors gain new properties and methods that simplify game creation:

   • flip_x / flip_y for mirroring sprites.
   • scale for resizing.
   • Movement methods: move_forward(), move_towards(), point_towards().
   • Animation support via images, next_image(), animate().

3. Advanced Collision Detection Methods (from pgzhelper): In addition to standard rectangular collisions, more precise methods become available:

   • Pixel-perfect collisions (collide_pixel).
   • Oriented Bounding Box (OBB) collisions.
   • Circle collisions.

4. Additional Utilities (from pgzhelper): Functions for screen management (set_fullscreen, toggle_fullscreen) and mouse cursor control (hide_mouse, show_mouse).

Thus, xpgzero can be considered "Pygame Zero Pro" — a library that takes the best from Daniel Pope's original project and supplements it with tools for creating more complex games without losing ease of use.

---

List of xpgzero Classes and Methods

Classes and Built-in Objects

• screen: The main object for drawing everything the player sees.

  • screen.surface: The Pygame Surface (screen buffer) for low-level operations.
  • screen.clear(): Clears the screen, filling it with black.
  • screen.fill(color): Fills the entire screen with the specified solid color.
  • screen.blit(image, pos): Draws an image on the screen at the specified position.
  • screen.blit_gradient(start, stop, dir=0): Fills the entire screen with a gradient from color start to stop (dir=0 vertical, dir=1 horizontal).
  • screen.draw.line(start, end, color): Draws a line from point start to point end.
  • screen.draw.circle(pos, radius, color): Draws the outline of a circle.
  • screen.draw.filled_circle(pos, radius, color): Draws a filled circle.
  • screen.draw.ellipse(rect, color): Draws the outline of an ellipse inscribed in the rectangle rect.
  • screen.draw.filled_ellipse(rect, color): Draws a filled ellipse inscribed in the rectangle rect.
  • screen.draw.arc(rect, start_angle, end_angle, color): Draws an elliptical arc from start_angle to end_angle (angles in degrees).
  • screen.draw.filled_arc(rect, start_angle, end_angle, color, steps=60, mode=0): Draws a filled elliptical arc (mode 0 = chord, 1 = sector).
  • screen.draw.polygon(points, color): Draws the outline of a polygon using the list of points.
  • screen.draw.filled_polygon(points, color): Draws a filled polygon using the list of points.
  • screen.draw.rect(rect, color): Draws the outline of a rectangle (Rect object).
  • screen.draw.filled_rect(rect, color): Draws a filled rectangle.
  • screen.draw.text(text, **kwargs): Draws text with extended formatting options.
  • screen.draw.textbox(text, rect, **kwargs): Draws text, fitting it into the specified rectangle.

• Rect: A class for working with rectangles (coordinates, size, collisions).

• Actor: A class for managing game objects (sprites).

  • Actor(image, pos): Creates a new actor with an image and position.
  • actor.draw(): Draws the actor on the screen.
  • actor.x, actor.y: The actor's coordinates.
  • actor.colliderect(other_actor): Checks for a collision with another actor.

• images: An object for accessing loaded images.

  • images.name: Returns the Surface of the loaded image name.
  • surface.get_width(): Returns the image's width in pixels.
  • surface.get_height(): Returns the image's height in pixels.
  • surface.get_size(): Returns the image's size as a tuple (width, height).
  • surface.get_rect(): Returns a Rect object for this image.

• sounds: An object for working with sounds.

  • sounds.name.play(): Plays the sound name once.
  • sounds.name.play(loops): Plays the sound with the specified number of loops.
  • sounds.name.stop(): Stops the sound playback.
  • sounds.name.get_length(): Returns the duration of the sound in seconds.

• music: An object for controlling music (streaming playback).

  • music.play(name): Plays the music file name (loops indefinitely).
  • music.play_once(name): Plays the music file once.
  • music.queue(name): Queues a music file to play after the current one.
  • music.stop(): Stops the music.
  • music.pause(): Pauses the music.
  • music.unpause(): Resumes music playback after a pause.
  • music.is_playing(): Checks if music is playing (and not paused).
  • music.fadeout(duration): Gradually decreases the volume to 0 over duration seconds.
  • music.set_volume(volume): Sets the volume (0.0 - 1.0).
  • music.get_volume(): Returns the current volume.

• clock: An object for scheduling events in the future.

  • clock.schedule(callback, delay): Calls a function once after delay seconds.
  • clock.schedule_unique(callback, delay): Same as schedule, but cancels previous calls to the same function.
  • clock.schedule_interval(callback, interval): Calls a function every interval seconds.
  • clock.unschedule(callback): Cancels scheduled calls of a function.
  • clock.each_tick(callback): Schedules a function to be called on every tick (frame).

• keyboard: An object for checking the state of keys.

  • keyboard.key_name: Returns True if the key key_name (e.g., keyboard.a) is pressed, otherwise False.

Event Handling Functions

• draw(): Automatically called to redraw the contents of the game window; takes no arguments.
• update(): Called ~60 times per second to update the game logic; takes no arguments for frame-rate independent logic.
• update(dt): Called ~60 times per second, receiving the time (dt) in seconds since the previous frame.
• on_mouse_down(): Called when a mouse button is pressed; can accept pos and/or button arguments.
• on_mouse_up(): Called when a mouse button is released; can accept pos and/or button arguments.
• on_mouse_move(): Called when the mouse moves; can accept pos, rel (offset), and/or buttons arguments.
• on_key_down(): Called when a key is pressed; can accept key, mod (modifiers), and/or unicode arguments.
• on_key_up(): Called when a key is released; can accept key and/or mod arguments.
• on_music_end(): Called after a music track finishes playing (not called for looping tracks).

Actor Properties (Attributes)

Core Properties

• image: A string with the name of the actor's current image (without extension).
• x: The actor's X coordinate (floating-point).
• y: The actor's Y coordinate (floating-point).
• pos: A tuple (x, y) for accessing both coordinates simultaneously.
• angle: The actor's rotation angle in degrees (clockwise).
• anchor: Defines the actor's anchor point (e.g., ('center', 'center')).

Positional Properties (Rectangle Points)

• left: The X coordinate of the actor's left edge.
• right: The X coordinate of the actor's right edge.
• top: The Y coordinate of the actor's top edge.
• bottom: The Y coordinate of the actor's bottom edge.
• topleft: A tuple (left, top) for the top-left corner.
• topright: A tuple (right, top) for the top-right corner.
• bottomleft: A tuple (left, bottom) for the bottom-left corner.
• bottomright: A tuple (right, bottom) for the bottom-right corner.
• midtop: A tuple (center_x, top) for the middle of the top side.
• midleft: A tuple (left, center_y) for the middle of the left side.
• midright: A tuple (right, center_y) for the middle of the right side.
• midbottom: A tuple (center_x, bottom) for the middle of the bottom side.
• center: A tuple (center_x, center_y) for the actor's center.
• center_x: The X coordinate of the actor's center.
• center_y: The Y coordinate of the actor's center.

Size Properties

• width: The actor's width in pixels.
• height: The actor's height in pixels.
• size: A tuple (width, height) for accessing dimensions simultaneously.

Actor Methods

• Actor(image, pos=None, **kwargs): Constructor, creates a new actor with the specified image.
• draw(): Draws the actor on the screen at its current position.
• distance_to(target): Returns the distance (in pixels) from this actor to another actor or a point.
• angle_to(target): Returns the angle (in degrees) to another actor or point.
• colliderect(other): Checks if this actor's rectangle intersects with another actor or a Rect object.
• collidepoint(x, y): Checks if the point with coordinates (x, y) is inside the actor's rectangle.
• collidelist(list): Checks for a collision with any actor in a list, returns the index of the first found.
• collidelistall(list): Checks for collisions with actors in a list, returns a list of indices of all found.
• get_rect(): Returns a Rect object representing the actor's current rectangle.

Extensions for Actor (Methods and Properties provided by pgzhelper)

• Actor.flip_x / Actor.flip_y: A property (True/False) that flips the actor's image horizontally or vertically.
• Actor.scale: A property (floating-point number) for scaling the actor (e.g., 0.5 will halve the size).
• Actor.move_forward(distance): Moves the actor forward by the specified distance relative to its angle (angle).
• Actor.move_back(distance): Moves the actor backward by the specified distance relative to its angle (angle).
• Actor.move_left(distance): Moves the actor left by the specified distance relative to its angle (angle).
• Actor.move_right(distance): Moves the actor right by the specified distance relative to its angle (angle).
• Actor.direction: A property (angle in degrees) for storing a movement direction that does not rotate the actor's image itself.
• Actor.move_in_direction(distance): Moves the actor by the specified distance in the direction set by the direction property.
• Actor.distance_to(target): Returns the distance (in pixels) from the actor to another actor or a point (extended version).
• Actor.direction_to(target): Returns the angle (in degrees) from the actor to another actor or point.
• Actor.move_towards(target, distance): Moves the actor the specified distance towards a target (without rotating the image).
• Actor.point_towards(target): Points the actor (changes its angle) towards a target.
• Actor.images: A property that accepts a list of image name strings for animation.
• Actor.next_image(): Switches the actor's image to the next one in the images list.
• Actor.fps: A property that sets the animation speed (frames per second) for the animate() method.
• Actor.animate(): Automatically cycles the actor's images at the speed set by fps.
• Actor.get_rect(): Returns the actor's Rect object (useful for drawing borders around the actor).

Collision Detection

• Actor.collidepoint_pixel(point): Checks if a point hits a non-transparent pixel of the actor (pixel-perfect).
• Actor.collide_pixel(other_actor): Checks for collision between the non-transparent pixels of two actors.
• Actor.collidelist_pixel(actor_list): Finds the first pixel-perfect collision with an actor from a list.
• Actor.collidelistall_pixel(actor_list): Returns a list of indices of all actors from the list that have a pixel-perfect collision.
• Actor.obb_collidepoint(point): Checks for collision of a point with the actor's Oriented Bounding Box (OBB) (fast, good for rotated objects).
• Actor.obb_collidepoints(point_list): Checks for collision of the oriented bounding box with any point from a list.
• Actor.circle_collidepoint(radius, point): Checks for collision of a point with a circle of a given radius around the actor.
• Actor.circle_collidepoints(radius, point_list): Checks for collision of a circle of a given radius with any point from a list.
• Collide.circle_line(circle, line): Checks for collision between a circle and a line.
• Collide.obb_points(obb_rect, points): Checks for collision between an oriented bounding box and a set of points.

Utility Functions

• set_fullscreen(): Switches the game to fullscreen mode.
• set_windowed(): Switches the game to windowed mode.
• toggle_fullscreen(): Toggles the current display mode (windowed/fullscreen).
• hide_mouse(): Hides the mouse cursor.
• show_mouse(): Shows the mouse cursor.
• distance_to(a, b): Calculates the distance between two points or actors.
• direction_to(a, b): Calculates the direction from point a to point b.