Description

The idea here is to have a simple change that even a beginning user can make to their pygame script to enable a range of 'live' debugging information and warnings. It would replace import pygame and add debugging, diagnostic and warning information.

Credit to @Starbuck5 for the original idea, I'm just writing it up from discord discussion.

Example script:

import pygame.debug
import pygame.gfxdraw

pygame.init()


display_surf = pygame.display.set_mode(
    (800, 600), flags=pygame.SCALED | pygame.HWSURFACE, vsync=1
)
pygame.display.set_caption("Test")

clock = pygame.time.Clock()

while True:
    clock.tick(60)

    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            pygame.quit()

    display_surf.fill("black")

    pygame.gfxdraw.aacircle(display_surf, 100, 100, 50, pygame.Color("white"))
    pygame.display.flip()

Example output (exact message format not relevant):

pygame-ce 2.5.0.dev3 (SDL 2.30.3, Python 3.11.1) - try pygame.print_debug_info() for more environment details

WARNING: flag pygame.HWSURFACE is deprecated and no longer does anything.
WARNING: using vsync together with a frame limit in clock.tick() is not recommended.
WARNING: pygame.gfxdraw.aacircle() is now superseded by pygame.draw.aacircle().

Whereas with the standard import pygame at the top we would default to a 'release' mode with nothing printed to the console by pygame-ce.

I hope this idea could resolve a bunch of stalled issues and longstanding debates regarding what warnings are too much and what we should or should not be printing to the console. The slight caveat is reducing user awareness of things like deprecation warnings so perhaps there could be some debate about what should remain in 'standard/release' mode and what would be hidden under pgyame.debug

This simple change could be added to our beginner tutorials and some documentation example code snippets (perhaps with an explanatory comment). We could also advise it to users asking questions on reddit, discord and in issues here (a quick change to the bug report template) as a good first step when helping to diagnose problems.

What is incorporated into import pygame.debug could evolve over time and I think a basic implementation that moved, say the support prompt over to it would be enough to get started and resolve this issue.