Metadata-Version: 2.4
Name: xpgzero
Version: 1.2.6
Summary: A zero-boilerplate 2D games framework
Author-email: Daniel Pope <mauve@mauveweb.co.uk>
Project-URL: Homepage, http://pypi.python.org/pypi/xpgzero
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Education
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: COPYING
License-File: AUTHORS
Requires-Dist: pygame<3.0,>=2.0
Requires-Dist: pgzhelper-rw
Requires-Dist: numpy
Provides-Extra: legacy
Requires-Dist: enum34; python_version < "3.4" and extra == "legacy"
Dynamic: license-file

**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`.
