Pygame

https://www.pygame.org/docs/
Admin
Pygame is a cross-platform set of Python modules designed for writing video games and multimedia...
Tokens:181,587
Snippets:1,626
Trust Score:9.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Main Game Loop Setup

Source: https://www.pygame.org/docs/tut/chimp.py.html

Initializes the display, background, and game objects before starting the main execution loop.

```python
def main():
    """this function is called when the program starts.
    it initializes everything it needs, then runs in
    a loop until the function returns."""
    # Initialize Everything
    pg.init()
    screen = pg.display.set_mode((1280, 480), pg.SCALED)
    pg.display.set_caption("Monkey Fever")
    pg.mouse.set_visible(False)

    # Create The Background
    background = pg.Surface(screen.get_size())
    background = background.convert()
    background.fill((170, 238, 187))

    # Put Text On The Background, Centered
    if pg.font:
        font = pg.font.Font(None, 64)
        text = font.render("Pummel The Chimp, And Win $$$", True, (10, 10, 10))
        textpos = text.get_rect(centerx=background.get_width() / 2, y=10)
        background.blit(text, textpos)

    # Display The Background
    screen.blit(background, (0, 0))
    pg.display.flip()

    # Prepare Game Objects
    whiff_sound = load_sound("whiff.wav")
    punch_sound = load_sound("punch.wav")
    chimp = Chimp()
    fist = Fist()
    allsprites = pg.sprite.RenderPlain((chimp, fist))
    clock = pg.time.Clock()
```

--------------------------------

### Locate and Execute Pygame Examples in Python

Source: https://www.pygame.org/docs/ref/examples.html

Use the Python interpreter to find the installation path of an example or execute its main() function directly.

```python
>>> import pygame.examples.scaletest
>>> pygame.examples.scaletest.__file__
'/usr/lib/python2.6/site-packages/pygame/examples/scaletest.py'
```

```python
>>> import pygame.examples.scaletest
>>> pygame.examples.scaletest.main()
```

--------------------------------

### Run Pygame Examples via Command Line

Source: https://www.pygame.org/docs/ref/examples.html

Use the python -m flag to execute example programs directly from the terminal.

```bash
python -m pygame.examples.<example name> <example arguments>
```

```bash
python -m pygame.examples.scaletest someimage.png
```

--------------------------------

### Complete Pygame Example

Source: https://www.pygame.org/docs/tut/MoveIt.html

This snippet shows the full integration of Pygame elements including display setup, image loading, object creation, event handling, and the main game loop for rendering and input processing. It requires a GameObject class and assumes image files are present.

```python
>>> screen = pygame.display.set_mode((640, 480))
>>> clock = pygame.time.Clock()            #get a pygame clock object
>>> player = pygame.image.load('player.bmp').convert()
>>> entity = pygame.image.load('alien1.bmp').convert()
>>> background = pygame.image.load('background.bmp').convert()
>>> screen.blit(background, (0, 0))
>>> objects = []
>>> p = GameObject(player, 10, 3)          #create the player object
>>> for x in range(10):                    #create 10 objects</i>
...     o = GameObject(entity, x*40, x)
...     objects.append(o)
>>> while True:
...     screen.blit(background, p.pos, p.pos)
...     for o in objects:
...         screen.blit(background, o.pos, o.pos)
...     keys = pygame.key.get_pressed()
...     if keys[pygame.K_UP]:
...         p.move(up=True)
...     if keys[pygame.K_DOWN]:
...         p.move(down=True)
...     if keys[pygame.K_LEFT]:
...         p.move(left=True)
...     if keys[pygame.K_RIGHT]:
...         p.move(right=True)
...     for event in pygame.event.get():
...         if event.type == pygame.QUIT:
...             sys.exit()
...     screen.blit(p.image, p.pos)
...     for o in objects:
...         o.move()
...         screen.blit(o.image, o.pos)
...     pygame.display.update()
...     clock.tick(60)

```

--------------------------------

### Translate Keyboard to MIDI Notes

Source: https://www.pygame.org/docs/ref/examples.html

This example demonstrates how to translate keyboard events into MIDI notes. It includes a basic button widget and state machine implementation. Requires a virtual MIDI patch cord to connect with input examples.

```python
import pygame

# ... (rest of the code for output example)

```

--------------------------------

### midi.main

Source: https://www.pygame.org/docs/ref/examples.html

Runs a MIDI example for input, output, or device listing.

```APIDOC
## midi.main

### Description
Executes a MIDI example based on the specified mode.

### Method
Function Call

### Parameters
#### Arguments
- **mode** (string) - Optional - 'output' for keyboard output, 'input' for event logger, 'list' for devices (default 'output')
- **device_id** (integer) - Optional - MIDI device number (default None)
```

--------------------------------

### Pygame Examples

Source: https://www.pygame.org/docs/genindex.html

List of example modules available in Pygame.

```APIDOC
## camera.main Function

### Description
Main function for the camera example.

### Module
pygame.examples.camera
```

```APIDOC
## chimp.main Function

### Description
Main function for the chimp example.

### Module
pygame.examples.chimp
```

```APIDOC
## cursors.main Function

### Description
Main function for the cursors example.

### Module
pygame.examples.cursors
```

```APIDOC
## eventlist.main Function

### Description
Main function for the eventlist example.

### Module
pygame.examples.eventlist
```

--------------------------------

### Execute Specific Pygame Example Modules

Source: https://www.pygame.org/docs/ref/examples.html

Individual example modules can be run by calling their respective main() functions.

```python
aliens.main()
```

```python
stars.main()
```

```python
chimp.main()
```

```python
moveit.main()
```

```python
fonty.main()
```

```python
freetype_misc.main()
```

```python
vgrade.main()
```

```python
eventlist.main()
```

```python
arraydemo.main(arraytype=None)
```

```python
sound.main(file_path=None)
```

--------------------------------

### Translate MIDI Input to Pygame Events

Source: https://www.pygame.org/docs/ref/examples.html

This example shows how to translate MIDI input into Pygame events. It can be run as a separate process and connected to the output example using a virtual MIDI patch cord.

```python
import pygame

# ... (rest of the code for input example)

```

--------------------------------

### scaletest.main

Source: https://www.pygame.org/docs/ref/examples.html

Provides an interactive smoothscale example to resize images on the screen.

```APIDOC
## scaletest.main

### Description
An interactive smoothscale example that resizes an image on the screen using arrow keys.

### Method
Function Call

### Parameters
#### Arguments
- **imagefile** (string) - Required - File name of source image
- **convert_alpha** (boolean) - Optional - Use convert_alpha() on the surface (default False)
- **run_speed_test** (boolean) - Optional - Perform a background timing test (default True)
```

--------------------------------

### NumPy Array Slicing Examples

Source: https://www.pygame.org/docs/tut/SurfarrayIntro.html

Demonstrates basic array creation and slicing operations using NumPy syntax.

```python
>>> c = arange(10)                         #like range, but makes an array
>>> c                                      #show the array
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
>>> c[1:6:2]                               #slice odd values from 1 to 6
array([1, 3, 5])
>>> c[4::4]                                #slice every 4th val starting at 4
array([4, 8])
>>> c[8:1:-1]                              #slice 1 to 8, reversed
array([8, 7, 6, 5, 4, 3, 2])
```

--------------------------------

### Configure Camera Controls

Source: https://www.pygame.org/docs/tut/CameraIntro.html

Adjusts hardware settings like image flipping after the camera has started.

```python
cam.set_controls(hflip = True, vflip = False)
print camera.get_controls()
```

--------------------------------

### Initialize Pygame and Set Up Display

Source: https://www.pygame.org/docs/ref/draw.html

Basic setup for a Pygame application, including initialization and display window creation.

```python
import pygame
from math import pi

# Initialize pygame
pygame.init()

# Set the height and width of the screen
size = [400, 300]
screen = pygame.display.set_mode(size)

pygame.display.set_caption("Example code for the draw module")
```

--------------------------------

### Get Joystick GUID

Source: https://www.pygame.org/docs/ref/joystick.html

Returns the GUID (Globally Unique Identifier) string for the joystick. This GUID uniquely identifies the specific hardware of the joystick device.

```python
joystick.get_guid()
```

--------------------------------

### Queueing Music Files

Source: https://www.pygame.org/docs/ref/music.html

Example demonstrating how to queue a second music file to play after the current one finishes.

```python
pygame.mixer.music.load('bach.ogg')
pygame.mixer.music.play(5)        # Plays six times, not five!
pygame.mixer.music.queue('mozart.ogg')
```

--------------------------------

### Example: Creating and Switching Cursors

Source: https://www.pygame.org/docs/ref/cursors.html

Demonstrates creating system, bitmap, and color cursors, and switching between them on mouse click. Includes Pygame initialization and event loop.

```python
# pygame setup
import pygame as pg

pg.init()
screen = pg.display.set_mode([600, 400])
pg.display.set_caption("Example code for the cursors module")

# create a system cursor
system = pg.cursors.Cursor(pg.SYSTEM_CURSOR_NO)

# create bitmap cursors
bitmap_1 = pg.cursors.Cursor(*pg.cursors.arrow)
bitmap_2 = pg.cursors.Cursor(
    (24, 24), (0, 0), *pg.cursors.compile(pg.cursors.thickarrow_strings)
)

# create a color cursor
surf = pg.Surface((40, 40)) # you could also load an image 
surf.fill((120, 50, 50))        # and use that as your surface
color = pg.cursors.Cursor((20, 20), surf)

cursors = [system, bitmap_1, bitmap_2, color]
cursor_index = 0

pg.mouse.set_cursor(cursors[cursor_index])

clock = pg.time.Clock()
going = True
while going:
    clock.tick(60)
    screen.fill((0, 75, 30))
    pg.display.flip()

    for event in pg.event.get():
        if event.type == pg.QUIT or (event.type == pg.KEYDOWN and event.key == pg.K_ESCAPE):
            going = False

        # if the mouse is clicked it will switch to a new cursor
        if event.type == pg.MOUSEBUTTONDOWN:
            cursor_index += 1
            cursor_index %= len(cursors)
            pg.mouse.set_cursor(cursors[cursor_index])

pg.quit()

```

--------------------------------

### GET /render

Source: https://www.pygame.org/docs/ref/freetype.html

Renders text to a new Surface and returns the surface along with its bounding rectangle.

```APIDOC
## GET /render

### Description
Returns a new Surface with the text rendered in the specified foreground color. If a background color is provided, the surface is filled with it; otherwise, it is transparent.

### Parameters
#### Query Parameters
- **text** (string) - Required - The text to render.
- **fgcolor** (color) - Optional - Foreground color.
- **bgcolor** (color) - Optional - Background color.
- **style** (int) - Optional - Font style.
- **rotation** (int) - Optional - Rotation angle.
- **size** (int) - Optional - Point size.

### Response
#### Success Response (200)
- **surface** (Surface) - The rendered text surface.
- **rect** (Rect) - The bounding rectangle of the rendered text.
```

--------------------------------

### Example of redundant code commenting

Source: https://www.pygame.org/docs/tut/MakeGames.html

Avoid adding comments that explain obvious operations, as shown in this example.

```python
player1.score += scoreup        # Add scoreup to player1 score

```

--------------------------------

### Camera Initialization and Configuration

Source: https://www.pygame.org/docs/ref/camera.html

Details on how to load and initialize a camera device with specified dimensions and format.

```APIDOC
## Camera Loading and Initialization

### Description
Loads a camera device. On Linux, the device is typically something like "/dev/video0". Default width and height are 640 by 480. Format is the desired colorspace of the output, useful for computer vision purposes. The default is `RGB`.

Supported formats:
- `RGB` - Red, Green, Blue
- `YUV` - Luma, Blue Chrominance, Red Chrominance
- `HSV` - Hue, Saturation, Value

### Parameters
#### Path Parameters
- **device** (string) - Required - The path to the camera device (e.g., "/dev/video0").

#### Query Parameters
- **width** (int) - Optional - The desired width of the camera feed. Defaults to 640.
- **height** (int) - Optional - The desired height of the camera feed. Defaults to 480.
- **format** (string) - Optional - The desired colorspace format (e.g., "RGB", "YUV", "HSV"). Defaults to "RGB".
```

--------------------------------

### Pygame Module Get Functions

Source: https://www.pygame.org/docs/genindex.html

General 'get' functions available at the top level of the Pygame module.

```APIDOC
## GET /pygame

### Description
Provides access to general Pygame module information and initialization status.

### Method
GET

### Endpoint
/pygame

### Parameters
#### Query Parameters
- **get_error()** (function) - Gets the last error message from Pygame.
- **get_init()** (function) - Checks if Pygame has been initialized.

### Response
#### Success Response (200)
- **last_error** (string) - The last error message encountered.
- **initialized_state** (boolean) - True if Pygame is initialized, False otherwise.

### Response Example
```json
{
  "last_error": "",
  "initialized_state": true
}
```
```

--------------------------------

### Configure default MIDI devices via environment variables

Source: https://www.pygame.org/docs/ref/midi.html

Sets the default input or output device using environment variables on Windows.

```batch
set PM_RECOMMENDED_INPUT_DEVICE=1
or
set PM_RECOMMENDED_OUTPUT_DEVICE=1
```

--------------------------------

### spritecollide() Example Usage

Source: https://www.pygame.org/docs/ref/sprite.html

Example demonstrating how to use spritecollide to detect collisions between a player sprite and a list of block sprites, with an option to remove hit blocks.

```python
# See if the Sprite block has collided with anything in the Group block_list
# The True flag will remove the sprite in block_list
blocks_hit_list = pygame.sprite.spritecollide(player, block_list, True)
```

--------------------------------

### Initialize Game Objects

Source: https://www.pygame.org/docs/tut/ChimpLineByLine.html

Loads sound assets, instantiates sprite classes, and creates a RenderPlain group for drawing.

```python
whiff_sound = load_sound("whiff.wav")
punch_sound = load_sound("punch.wav")
chimp = Chimp()
fist = Fist()
allsprites = pg.sprite.RenderPlain((chimp, fist))
clock = pg.time.Clock()
```

--------------------------------

### Group clear() Method with Callback Example

Source: https://www.pygame.org/docs/ref/sprite.html

Erases Sprites drawn in the last Group.draw() call by filling their areas with a background. The background can be a Surface or a callback function, as shown in the example for filling with solid red.

```python
Erases the Sprites used in the last `Group.draw()` call. The destination Surface is cleared by filling the drawn Sprite positions with the background.
The background is usually a Surface image the same dimensions as the destination Surface. However, it can also be a callback function that takes two arguments; the destination Surface and an area to clear. The background callback function will be called several times each clear.
Here is an example callback that will clear the Sprites with solid red:
```
def clear_callback(surf, rect):
    color = 255, 0, 0
    surf.fill(color, rect)

```
```

--------------------------------

### Initialize Display Window

Source: https://www.pygame.org/docs/tut/MoveIt.html

Creates a 640x480 pixel window with an automatically selected color depth and pixel format.

```python
>>> screen = pygame.display.set_mode((640, 480))
```

--------------------------------

### Initialize Pygame Resources

Source: https://www.pygame.org/docs/tut/chimp.py.html

Functions for loading images and sounds from a data directory, with fallback handling for missing modules.

```python
def load_image(name, colorkey=None, scale=1):
    fullname = os.path.join(data_dir, name)
    image = pg.image.load(fullname)
    image = image.convert()

    size = image.get_size()
    size = (size[0] * scale, size[1] * scale)
    image = pg.transform.scale(image, size)

    if colorkey is not None:
        if colorkey == -1:
            colorkey = image.get_at((0, 0))
        image.set_colorkey(colorkey, pg.RLEACCEL)
    return image, image.get_rect()


def load_sound(name):
    class NoneSound:
        def play(self):
            pass

    if not pg.mixer or not pg.mixer.get_init():
        return NoneSound()

    fullname = os.path.join(data_dir, name)
    sound = pg.mixer.Sound(fullname)

    return sound
```

--------------------------------

### GET /display/screensaver

Source: https://www.pygame.org/docs/ref/display.html

Checks if the screensaver is allowed to run.

```APIDOC
## GET /display/screensaver

### Description
Returns whether the screensaver is allowed to run whilst the app is running.

### Method
GET

### Response
#### Success Response (200)
- **allowed** (bool) - True if allowed, False otherwise.
```

--------------------------------

### Initialize Camera with Colorspaces

Source: https://www.pygame.org/docs/tut/CameraIntro.html

Initialize a camera instance with specific colorspace support. RGB, YUV, and HSV are supported, with YUV and HSV being preferred for computer vision tasks.

```python
self.cam = pygame.camera.Camera(self.clist[0], self.size, "RGB")
```

```python
self.cam = pygame.camera.Camera(self.clist[0], self.size, "YUV")
```

```python
self.cam = pygame.camera.Camera(self.clist[0], self.size, "HSV")
```

--------------------------------

### GET /display/num_displays

Source: https://www.pygame.org/docs/ref/display.html

Returns the number of available displays.

```APIDOC
## GET /display/num_displays

### Description
Returns the number of available displays as an integer.

### Method
GET

### Response
#### Success Response (200)
- **count** (int) - The number of available displays.
```

--------------------------------

### headless_no_windows_needed.main

Source: https://www.pygame.org/docs/ref/examples.html

Demonstrates how to use pygame for image processing on headless servers without a windowing system.

```APIDOC
## headless_no_windows_needed.main

### Description
Writes an image file that is a smoothscaled copy of an input file, suitable for headless environments.

### Method
Function Call

### Parameters
#### Arguments
- **fin** (string) - Required - Name of an input image file
- **fout** (string) - Required - Name of the output file to create/overwrite
- **w** (integer) - Required - Width of the rescaled image
- **h** (integer) - Required - Height of the rescaled image
```

--------------------------------

### Color Class Initialization

Source: https://www.pygame.org/docs/ref/color.html

Describes how to instantiate a new Color object using various supported formats.

```APIDOC
## Color Initialization

### Description
Creates a new Color object. Supports multiple input formats including individual RGBA components, color names, hex strings, and tuples.

### Parameters
#### Request Body
- **r** (int) - Required - Red value (0-255)
- **g** (int) - Required - Green value (0-255)
- **b** (int) - Required - Blue value (0-255)
- **a** (int) - Optional - Alpha value (0-255), default 255
- **color_value** (Color/str/int/tuple/list) - Optional - Alternative input format (e.g., 'red', '#rrggbbaa', 0xrrggbbaa, (R, G, B, A))

### Response
#### Success Response (200)
- **Color** (Object) - A newly created Color object.
```

--------------------------------

### pygame.mixer.music.get_pos

Source: https://www.pygame.org/docs/ref/music.html

Gets the number of milliseconds that the music has been playing for.

```APIDOC
## get_pos()

### Description
Gets the number of milliseconds that the music has been playing for. Does not account for starting position offsets.

### Response
- **time** (int) - The number of milliseconds the music has been playing.
```

--------------------------------

### get_track_start

Source: https://www.pygame.org/docs/ref/cdrom.html

Returns the start time of a specific track.

```APIDOC
## GET /get_track_start

### Parameters
#### Query Parameters
- **track** (int) - Required - The track number (starts at 0).

### Response
#### Success Response (200)
- **seconds** (float) - The absolute time in seconds where the track starts.
```

--------------------------------

### pygame.scrap.get_types()

Source: https://www.pygame.org/docs/ref/scrap.html

Gets a list of the available clipboard data types.

```APIDOC
## Get Available Clipboard Types

### Method
`pygame.scrap.get_types()`

### Description
Gets a list of string identifiers for the data types currently available on the clipboard. Each identifier can be used with `pygame.scrap.get()` to retrieve the corresponding clipboard content.

### Returns
- `list`: A list of strings representing the available clipboard data types. Returns an empty list if there is no data in the clipboard.

### Example
```python
for t in pygame.scrap.get_types():
    if "text" in t:
        # There is some content with the word "text" in its type string.
        print(pygame.scrap.get(t))
```
```

--------------------------------

### Initialize Screen List

Source: https://www.pygame.org/docs/tut/MoveIt.html

Create a Python list to represent the screen and fill it with initial values. This serves as a foundational step before drawing.

```python
>>> screen = [1, 1, 2, 2, 2, 1]
>>> print(screen)
[1, 1, 2, 2, 2, 1]
```

--------------------------------

### GET /display/window_size

Source: https://www.pygame.org/docs/ref/display.html

Returns the current size of the window or screen.

```APIDOC
## GET /display/window_size

### Description
Returns the size of the window initialized with set_mode().

### Method
GET

### Response
#### Success Response (200)
- **size** (tuple) - The width and height of the window.
```

--------------------------------

### Initialize Background and Screen with Lists

Source: https://www.pygame.org/docs/tut/MoveIt.html

This code initializes a background list and a screen list, then copies the background to the screen. It then places a player character (represented by 8) at a specific position on the screen.

```python
>>> background = [1, 1, 2, 2, 2, 1]
>>> screen = [0]*6                         #a new blank screen
>>> for i in range(6):
...     screen[i] = background[i]
>>> print(screen)
[1, 1, 2, 2, 2, 1]
>>> playerpos = 3
>>> screen[playerpos] = 8
>>> print(screen)
[1, 1, 2, 8, 2, 1]
```

--------------------------------

### GET /get_count

Source: https://www.pygame.org/docs/ref/midi.html

Retrieves the number of available MIDI devices.

```APIDOC
## GET /get_count

### Description
Gets the number of available MIDI devices. Device IDs range from 0 to count - 1.

### Response
#### Success Response (200)
- **num_devices** (int) - The total count of available MIDI devices.
```

--------------------------------

### pygame.camera.init

Source: https://www.pygame.org/docs/ref/camera.html

Initializes the camera module with an optional backend.

```APIDOC
## pygame.camera.init()

### Description
Starts up the camera module, choosing the best webcam backend available for the system.

### Parameters
#### Query Parameters
- **backend** (str) - Optional - The name of the backend to use, overriding the default choice.
```

--------------------------------

### pygame.mixer.music.set_pos

Source: https://www.pygame.org/docs/ref/music.html

Sets the position in the music file where playback will start.

```APIDOC
## set_pos(pos)

### Description
Sets the position in the music file where playback will start. The meaning of 'pos' depends on the music format.

### Parameters
#### Request Body
- **pos** (float) - Required - The position to start playback from.
```

--------------------------------

### POST /Sound/play

Source: https://www.pygame.org/docs/ref/mixer.html

Begins playback of the Sound on an available Channel.

```APIDOC
## POST /Sound/play

### Description
Begin playback of the Sound on an available Channel.

### Parameters
#### Request Body
- **loops** (int) - Optional - Number of times to repeat after the first play. Default is 0.
- **maxtime** (int) - Optional - Stop playback after given milliseconds.
- **fade_ms** (int) - Optional - Fade in time in milliseconds.
```

--------------------------------

### pygame.mixer.init()

Source: https://www.pygame.org/docs/ref/mixer.html

Initializes the mixer module for sound loading and playback with configurable audio parameters.

```APIDOC
## pygame.mixer.init()

### Description
Initialize the mixer module for Sound loading and playback. The default arguments can be overridden to provide specific audio mixing.

### Parameters
#### Query Parameters
- **frequency** (int) - Optional - The audio playback rate (default: 44100).
- **size** (int) - Optional - Number of bits used for each audio sample (default: -16).
- **channels** (int) - Optional - Number of channels (1 for mono, 2 for stereo, 4 or 6 supported) (default: 2).
- **buffer** (int) - Optional - Number of internal samples used in the sound mixer (default: 512).
- **devicename** (string) - Optional - Name of the audio device.
- **allowedchanges** (int) - Optional - Constants to allow changes to frequency, format, or channels (default: AUDIO_ALLOW_FREQUENCY_CHANGE | AUDIO_ALLOW_CHANNELS_CHANGE).

### Response
#### Success Response (200)
- **None** (None) - Returns None upon successful initialization.
```

--------------------------------

### Initialize Pygame Rect objects

Source: https://www.pygame.org/docs/tut/newbieguide.html

Demonstrates various ways to instantiate a Rect object or define a rectstyle sequence.

```python
rect = pygame.Rect(10, 20, 30, 30)
rect = pygame.Rect((10, 20, 30, 30))
rect = pygame.Rect((10, 20), (30, 30))
rect = (10, 20, 30, 30)
rect = ((10, 20, 30, 30))
```

--------------------------------

### GET /get_palette

Source: https://www.pygame.org/docs/ref/surface.html

Retrieves the color index palette for an 8-bit Surface.

```APIDOC
## GET /get_palette

### Description
Return a list of up to 256 color elements that represent the indexed colors used in an 8-bit Surface.

### Method
GET

### Endpoint
get_palette()

### Response
#### Success Response (200)
- **palette** (list) - A list of Color instances.
```

--------------------------------

### GET /display/caption

Source: https://www.pygame.org/docs/ref/display.html

Retrieves the current window caption title and icontitle.

```APIDOC
## GET /display/caption

### Description
Returns the title and icontitle for the display window. In pygame 2.x these will always be the same value.

### Method
GET

### Response
#### Success Response (200)
- **title** (string) - The current window title.
- **icontitle** (string) - The current window icontitle.
```

--------------------------------

### Color Initialization Examples

Source: https://www.pygame.org/docs/ref/color.html

Demonstrates various ways to initialize a Color object using RGBA values, color names, HTML color strings, hex numbers, integers, and tuples/lists of integers. The alpha value defaults to 255 if not provided.

```python
Color(255, 255, 255, 255)
```

```python
Color(0, 64, 64, 64)
```

```python
Color(255, 255, 255, 255) % Color(64, 64, 64, 0)
```

```python
Color('red')
```

```python
Color('#FF0000')
```

```python
Color('#FF000080')
```

```python
Color('0xFF0000')
```

```python
Color('0xFF000080')
```

```python
Color(0xFF0000)
```

```python
Color(0xFF000080)
```

```python
Color((255, 0, 0))
```

```python
Color((255, 0, 0, 128))
```

```python
Color([255, 0, 0])
```

```python
Color([255, 0, 0, 128])
```

--------------------------------

### GET /get_metrics

Source: https://www.pygame.org/docs/ref/freetype.html

Retrieves the glyph metrics for each character in the provided text.

```APIDOC
## GET /get_metrics

### Description
Returns the glyph metrics for each character in the specified text as a list of tuples.

### Parameters
#### Query Parameters
- **text** (string) - Required - The text to retrieve metrics for.
- **size** (int) - Optional - The point size to use for calculations.

### Response
#### Success Response (200)
- **metrics** (list) - A list of tuples containing (min_x, max_x, min_y, max_y, horizontal_advance_x, horizontal_advance_y).
```

--------------------------------

### Get Mask Size

Source: https://www.pygame.org/docs/ref/mask.html

Retrieves the dimensions (width and height) of the mask.

```python
mask.get_size()
```

--------------------------------

### Initialize Display Surface in Pygame

Source: https://www.pygame.org/docs/tut/newbieguide.html

Creates the main window or screen for display. This 'display surface' is what the user sees.

```python
pygame.display.set_mode()
```

--------------------------------

### Pygame Overlay Get Functions

Source: https://www.pygame.org/docs/genindex.html

Functions for retrieving information about Pygame overlays.

```APIDOC
## GET /pygame/overlay

### Description
Retrieves information about Pygame overlay objects.

### Method
GET

### Endpoint
/pygame/overlay

### Parameters
#### Path Parameters
- **overlay_id** (string) - Required - The unique identifier for the Overlay object.

#### Query Parameters
- **get_hardware()** (function) - Gets hardware information related to the overlay.

### Response
#### Success Response (200)
- **hardware_info** (object) - Information about the overlay's hardware.

### Response Example
```json
{
  "hardware_info": {"renderer": "OpenGL", "version": "4.6"}
}
```
```

--------------------------------

### Pygame sndarray/surfarray Get Functions

Source: https://www.pygame.org/docs/genindex.html

Functions for retrieving array information from surfaces.

```APIDOC
## GET /pygame/array

### Description
Retrieves information about array representations of Pygame surfaces.

### Method
GET

### Endpoint
/pygame/array

### Parameters
#### Query Parameters
- **get_arraytype()** (function) - Gets the current array type of a surface.
- **get_arraytypes()** (function) - Gets all available array types for a surface.

### Response
#### Success Response (200)
- **array_type** (string) - The current array type (e.g., 'f2', 'u16').
- **available_array_types** (list) - A list of supported array types.

### Response Example
```json
{
  "array_type": "f2",
  "available_array_types": ["f2", "u16", "u8"]
}
```
```

--------------------------------

### Load a sound file with safety checks

Source: https://www.pygame.org/docs/tut/ChimpLineByLine.html

Loads a sound file and returns a dummy object if the mixer is not initialized to prevent runtime errors.

```python
def load_sound(name):
    class NoneSound:
        def play(self):
            pass

    if not pg.mixer or not pg.mixer.get_init():
        return NoneSound()

    fullname = os.path.join(data_dir, name)
    sound = pg.mixer.Sound(fullname)

    return sound
```

--------------------------------

### Load an image with scaling and colorkey

Source: https://www.pygame.org/docs/tut/ChimpLineByLine.html

Loads an image from a data directory, converts it for display performance, scales it, and optionally sets a transparency colorkey.

```python
def load_image(name, colorkey=None, scale=1):
    fullname = os.path.join(data_dir, name)
    image = pg.image.load(fullname)

    size = image.get_size()
    size = (size[0] * scale, size[1] * scale)
    image = pg.transform.scale(image, size)

    image = image.convert()
    if colorkey is not None:
        if colorkey == -1:
            colorkey = image.get_at((0, 0))
        image.set_colorkey(colorkey, pg.RLEACCEL)
    return image, image.get_rect()
```

--------------------------------

### Pygame Sound Get Functions

Source: https://www.pygame.org/docs/genindex.html

Functions for retrieving information about Pygame sounds.

```APIDOC
## GET /pygame/sound

### Description
Retrieves information about Pygame sound objects, such as their length.

### Method
GET

### Endpoint
/pygame/sound

### Parameters
#### Path Parameters
- **sound_id** (string) - Required - The unique identifier for the Sound object.

#### Query Parameters
- **get_length()** (function) - Gets the length of the sound in seconds.
- **get_num_channels()** (function) - Gets the number of channels used by the sound.

### Response
#### Success Response (200)
- **sound_length** (float) - The length of the sound in seconds.
- **num_channels** (integer) - The number of channels used by the sound.

### Response Example
```json
{
  "sound_length": 2.5,
  "num_channels": 2
}
```
```

--------------------------------

### Pygame Mouse Get Functions

Source: https://www.pygame.org/docs/genindex.html

Functions for retrieving information about the mouse state.

```APIDOC
## GET /pygame/mouse

### Description
Retrieves information about the current state of the mouse.

### Method
GET

### Endpoint
/pygame/mouse

### Parameters
#### Query Parameters
- **get_cursor()** (function) - Gets the current mouse cursor.
- **get_focused()** (function) - Checks if the mouse focus is on the window.

### Response
#### Success Response (200)
- **cursor_data** (object) - Information about the current mouse cursor.
- **focused_state** (boolean) - True if the mouse focus is on the window, False otherwise.

### Response Example
```json
{
  "cursor_data": {"hotspot": [0, 0], "size": [32, 32]},
  "focused_state": true
}
```
```

--------------------------------

### Pygame Key Get Functions

Source: https://www.pygame.org/docs/genindex.html

Functions for retrieving information about keyboard state.

```APIDOC
## GET /pygame/key

### Description
Retrieves information about the current state of the keyboard.

### Method
GET

### Endpoint
/pygame/key

### Parameters
#### Query Parameters
- **get_focused()** (function) - Checks if the keyboard focus is on the window.
- **get_mods()** (function) - Gets the current state of the modifier keys (Shift, Ctrl, Alt, etc.).

### Response
#### Success Response (200)
- **focused_state** (boolean) - True if the keyboard focus is on the window, False otherwise.
- **modifier_keys** (integer) - A bitmask representing the state of modifier keys.

### Response Example
```json
{
  "focused_state": true,
  "modifier_keys": 1  // Represents the Shift key being pressed
}
```
```

--------------------------------

### POST /note_on

Source: https://www.pygame.org/docs/ref/midi.html

Turns a MIDI note on in the output stream.

```APIDOC
## POST /note_on

### Description
Turns a MIDI note on in the output stream. The note must already be off for this to work correctly.

### Parameters
#### Request Body
- **note** (int) - Required - The MIDI note number to turn on.
- **velocity** (int) - Optional - The velocity of the note.
- **channel** (int) - Optional - The MIDI channel (default 0).
```

--------------------------------

### pygame.sndarray.get_arraytype() (DEPRECATED)

Source: https://www.pygame.org/docs/ref/sndarray.html

Gets the currently active array type. Raises DeprecationWarning.

```APIDOC
## pygame.sndarray.get_arraytype()

### Description
Gets the currently active array type.

### Method
`get_arraytype () -> str`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **str** - The currently active array type (e.g., 'numpy').
```

--------------------------------

### Module Initialization

Source: https://www.pygame.org/docs/ref/midi.html

Functions to initialize, uninitialize, and check the status of the MIDI module.

```APIDOC
## pygame.midi.init()

### Description
Initializes the pygame.midi module. Must be called before using the module.

### Method
Function Call

### Response
- **None** (None) - Returns None.

---

## pygame.midi.quit()

### Description
Uninitializes the pygame.midi module.

### Method
Function Call

---

## pygame.midi.get_init()

### Description
Returns the initialization state of the module.

### Method
Function Call

### Response
- **initialized** (bool) - True if initialized, False otherwise.
```

--------------------------------

### GET /controller/mapping

Source: https://www.pygame.org/docs/ref/sdl2_controller.html

Retrieves the current button, hat, and axis mapping for the controller.

```APIDOC
## GET /controller/mapping

### Description
Returns a dictionary containing the current mapping of the controller buttons, hats, and axes.

### Method
GET

### Response
#### Success Response (200)
- **mapping** (dict) - A dictionary representing the current controller configuration.

#### Response Example
{
  "a": "b0",
  "y": "b3"
}
```

--------------------------------

### Basic Pygame Game Loop

Source: https://www.pygame.org/docs/index.html

Sets up a basic Pygame window, handles events, updates the display, and limits the frame rate. Use this as a starting point for Pygame applications.

```python
# Example file showing a basic pygame "game loop"
import pygame

# pygame setup
pygame.init()
screen = pygame.display.set_mode((1280, 720))
clock = pygame.time.Clock()
running = True

while running:
    # poll for events
    # pygame.QUIT event means the user clicked X to close your window
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    # fill the screen with a color to wipe away anything from last frame
    screen.fill("purple")

    # RENDER YOUR GAME HERE

    # flip() the display to put your work on screen
    pygame.display.flip()

    clock.tick(60)  # limits FPS to 60

pygame.quit()

```

--------------------------------

### Pygame Camera Get Functions

Source: https://www.pygame.org/docs/genindex.html

Functions for retrieving information from a Pygame camera.

```APIDOC
## GET /pygame/camera

### Description
Retrieves information and image data from a Pygame camera.

### Method
GET

### Endpoint
/pygame/camera

### Parameters
#### Path Parameters
- **camera_id** (string) - Required - The unique identifier for the Camera object.

#### Query Parameters
- **get_controls()** (function) - Gets the control settings of the camera.
- **get_image()** (function) - Captures and returns an image from the camera.

### Response
#### Success Response (200)
- **controls** (object) - An object containing camera control settings.
- **image_data** (object) - The captured image data.

### Response Example
```json
{
  "controls": {"brightness": 0.5, "contrast": 0.5},
  "image_data": {"width": 640, "height": 480, "format": "RGB", "pixels": "..."}
}
```
```

--------------------------------

### Pygame Mask Get Functions

Source: https://www.pygame.org/docs/genindex.html

Functions for retrieving information about Pygame masks.

```APIDOC
## GET /pygame/mask

### Description
Retrieves information about Pygame mask objects, such as bounding rectangles.

### Method
GET

### Endpoint
/pygame/mask

### Parameters
#### Path Parameters
- **mask_id** (string) - Required - The unique identifier for the Mask object.

#### Query Parameters
- **get_at()** (function) - Gets the value at a specific point in the mask.
- **get_bounding_rects()** (function) - Gets the bounding rectangles of the mask.

### Response
#### Success Response (200)
- **mask_value** (integer) - The value at the specified point (0 or 1).
- **bounding_rectangles** (list) - A list of bounding rectangle objects.

### Response Example
```json
{
  "mask_value": 1,
  "bounding_rectangles": [{"x": 10, "y": 10, "w": 5, "h": 5}]
}
```
```

--------------------------------

### Load an image from a file

Source: https://www.pygame.org/docs/ref/image.html

Use os.path.join for cross-platform file path compatibility when loading images into a Surface.

```python
asurf = pygame.image.load(os.path.join('data', 'bla.png'))
```

--------------------------------

### Initialize Pygame Camera

Source: https://www.pygame.org/docs/tut/CameraIntro.html

The camera module is optional and requires manual initialization after importing.

```python
import pygame
import pygame.camera
from pygame.locals import *

pygame.init()
pygame.camera.init()
```

--------------------------------

### Pygame CDROM Get Functions

Source: https://www.pygame.org/docs/genindex.html

Functions for retrieving information about the CD-ROM drive.

```APIDOC
## GET /pygame/cdrom

### Description
Retrieves information about the CD-ROM drive, such as its status and capabilities.

### Method
GET

### Endpoint
/pygame/cdrom

### Parameters
#### Path Parameters
- **cdrom_id** (string) - Required - The unique identifier for the CD-ROM drive.

#### Query Parameters
- **get_all()** (function) - Gets a list of all CD-ROM drives.
- **get_busy()** (function) - Checks if the CD-ROM drive is busy.
- **get_current()** (function) - Gets the current CD-ROM drive.
- **get_empty()** (function) - Checks if the CD-ROM drive is empty.
- **get_id()** (function) - Gets the ID of the CD-ROM drive.
- **get_init()** (function) - Checks if the cdrom module is initialized.
- **get_name()** (function) - Gets the name of the CD-ROM drive.

### Response
#### Success Response (200)
- **all_cdroms** (list) - A list of all CD-ROM drive identifiers.
- **busy_state** (boolean) - True if the CD-ROM drive is busy, False otherwise.
- **current_cdrom** (string) - The identifier of the current CD-ROM drive.
- **is_empty** (boolean) - True if the drive is empty, False otherwise.
- **cdrom_id_value** (integer) - The ID of the CD-ROM drive.
- **initialized_state** (boolean) - True if the cdrom module is initialized.
- **cdrom_name** (string) - The name of the CD-ROM drive.

### Response Example
```json
{
  "all_cdroms": ["/dev/cdrom", "/dev/sr0"],
  "busy_state": false,
  "current_cdrom": "/dev/cdrom",
  "is_empty": false,
  "cdrom_id_value": 0,
  "initialized_state": true,
  "cdrom_name": "HL-DT-ST DVDRAM GH24NSC0"
}
```
```

--------------------------------

### Joystick Hat Controls

Source: https://www.pygame.org/docs/ref/joystick.html

Functions to get information and state of joystick hats.

```APIDOC
## Joystick Hat Controls

### Description
Functions to get information and state of joystick hats.

### get_hat(hat_number)

Returns the current position of a joystick hat. The position is given as two values representing the `x` and `y` position for the hat. `(0, 0)` means centered. A value of `-1` means left/down and a value of `1` means right/up: so `(-1, 0)` means left; `(1, 0)` means right; `(0, 1)` means up; `(1, 1)` means upper-right; etc.

#### Parameters
- **hat_number** (int) - Required - The index of the hat to query. Must be an integer from `0` to `get_numhats() - 1`.

### Hat Event Data

- The `pygame.JOYHATMOTION` event is generated when the hat changes position. The `position` attribute for the event contains a pair of values that are either `-1`, `0`, or `1`.
- This value is digital, `i.e.`, each coordinate can be `-1`, `0` or `1` but never in-between.
```

--------------------------------

### Create and display a black surface array

Source: https://www.pygame.org/docs/tut/SurfarrayIntro.html

Initializes a 2D array of zeros and displays it using the surfdemo_show helper function.

```python
allblack = N.zeros((128, 128))
surfdemo_show(allblack, 'allblack')
```

--------------------------------

### POST /write

Source: https://www.pygame.org/docs/ref/midi.html

Writes a list of MIDI data to the output.

```APIDOC
## POST /write

### Description
Writes a series of MIDI information in the form of a list.

### Parameters
#### Request Body
- **data** (list) - Required - The data to write, formatted as [[[status, data1=0, data2=0, ...], timestamp], ...].
```

--------------------------------

### Joystick Button Controls

Source: https://www.pygame.org/docs/ref/joystick.html

Functions to get information and state of joystick buttons.

```APIDOC
## Joystick Button Controls

### Description
Functions to get information and state of joystick buttons.

### get_button(button_index)

Returns the current state of a joystick button.

#### Parameters
- **button_index** (int) - Required - The index of the button to query. Must be an integer from `0` to `get_numbuttons() - 1`.

### Button Event Data

- Buttons generate `pygame.JOYBUTTONDOWN` and `pygame.JOYBUTTONUP` events when pressed and released.
```

--------------------------------

### Controller Initialization and Management

Source: https://www.pygame.org/docs/ref/sdl2_controller.html

Functions for initializing, quitting, and checking the status of the controller module.

```APIDOC
## Pygame _sdl2 Controller Module Functions

### init()

Initialize the controller module.

- **Returns**: None

### quit()

Uninitialize the controller module.

- **Returns**: None

### get_init()

Returns True if the controller module is initialized.

- **Returns**: bool

### set_eventstate(state)

Sets the current state of events related to controllers.

- **Parameters**:
  - **state** (bool) - True to enable events, False to disable.
- **Returns**: None

### get_eventstate()

Gets the current state of events related to controllers.

- **Returns**: bool - True if events are posted, False otherwise.

### get_count()

Get the number of joysticks connected.

- **Returns**: int - The number of connected joysticks.

### is_controller(index)

Check if the given joystick is supported by the game controller interface.

- **Parameters**:
  - **index** (int) - The index of the joystick to check.
- **Returns**: bool - True if the joystick is a supported controller, False otherwise.

### name_forindex(index)

Get the name of the controller.

- **Parameters**:
  - **index** (int) - The index of the controller.
- **Returns**: str or None - The name of the controller, or None if invalid.
```
Tokens:
Raw