Refactor web globals for pygbag WebAssembly compilation

[Copilot]

Pygbag requires all global variables declared at module level before asyncio.run(main()) for optimal WebAssembly compilation. Previously, 65 globals were scattered across web/aggravation_web.py with some initialized inside the run() function.

Changes

web/main.py

• Declared all globals at module level before asyncio.run(main()):
  • Constants: BOARD_TEMPLATE, FPS, WINDOWWIDTH, color definitions, etc.
  • Player state: P1END, P2END, P3END, P4END
  • Pygame objects: Pre-declared as None (FPSCLOCK, DISPLAYSURF, BASICFONT, button surfaces/rects)

web/aggravation_web.py

• Removed module-level global declarations
• Import pattern:

  # Read-only constants imported directly for convenience
  from __main__ import (
      BOARD_TEMPLATE, FPS, WINDOWWIDTH, WINDOWHEIGHT,
      GRAY, WHITE, RED, P1COLOR, PLAYER_COLORS, ...
  )
  
  # Mutable globals accessed via __main__ module
  import __main__
  
  def run():
      __main__.FPSCLOCK = pygame.time.Clock()
      __main__.DISPLAYSURF = pygame.display.set_mode(...)
      # References use __main__.DISPLAYSURF.blit(...)

This follows the pygbag recommended pattern: single source of truth for globals in entry point, initialized upfront for efficient WebAssembly compilation.

Original prompt

Summary

Per pygbag's documentation and best practices, all global variables should be declared at once at the module level in the main.py entry point file, before asyncio.run(main()) is called. This improves WebAssembly compilation performance and ensures globals are efficiently initialized upfront.

Currently, the aggravation web version has its globals scattered:

• Many globals are declared at the module level in web/aggravation_web.py (lines 50-123): BOARD_TEMPLATE, PLAYER_COLORS, P1END-P4END, FPS, WINDOWWIDTH, WINDOWHEIGHT, REVEALSPEED, SIMSPEED, BOXSIZE, GAPSIZE, BOARDWIDTH, BOARDHEIGHT, BASICFONTSIZE, BLANK, SPOT, XMARGIN, YMARGIN, all color constants (GRAY, NAVYBLUE, WHITE, RED, GREEN, BLUE, YELLOW, ORANGE, PURPLE, CYAN, BLACK), UI color aliases (BUTTONCOLOR, BUTTONTEXTCOLOR, MESSAGECOLOR, TILECOLOR, TEXTCOLOR, BGCOLOR, LIGHTBGCOLOR, BOXCOLOR, HIGHLIGHTCOLOR), and player colors (P1COLOR, P2COLOR, P3COLOR, P4COLOR).
• Additional globals are initialized inside the run() function with global declarations (lines 207-210): FPSCLOCK, DISPLAYSURF, BASICFONT, ROLL_SURF, ROLL_RECT, ROLL1_SURF, ROLL1_RECT, EXIT_SURF, EXIT_RECT, OPTION_SURF, OPTION_RECT, CLEAR_SURF, CLEAR_RECT, ROLL6_SURF, ROLL6_RECT, PLAYERROR_SURF, PLAYERROR_RECT, CLEARERROR_SURF, CLEARERROR_RECT, TEST_SURF, TEST_RECT.
• The current web/main.py is minimal (only imports asyncio and aggravation_web, calls run()).

Changes Required

1. web/main.py — Declare all globals at module level

Restructure web/main.py to follow the pygbag pattern. All global variables that are currently in web/aggravation_web.py at module level (lines 50-123) should be moved into web/main.py and declared before asyncio.run(main()). Specifically:

• Move all constant declarations to main.py: BOARD_TEMPLATE, FPS, WINDOWWIDTH, WINDOWHEIGHT, REVEALSPEED, SIMSPEED, BOXSIZE, GAPSIZE, BOARDWIDTH, BOARDHEIGHT, BASICFONTSIZE, BLANK, SPOT, XMARGIN, YMARGIN
• Move all color definitions: GRAY, NAVYBLUE, WHITE, RED, GREEN, BLUE, YELLOW, ORANGE, PURPLE, CYAN, BLACK
• Move all UI color aliases: BUTTONCOLOR, BUTTONTEXTCOLOR, MESSAGECOLOR, TILECOLOR, TEXTCOLOR, BGCOLOR, LIGHTBGCOLOR, BOXCOLOR, HIGHLIGHTCOLOR
• Move player colors: P1COLOR, P2COLOR, P3COLOR, P4COLOR, PLAYER_COLORS
• Move player end trackers: P1END, P2END, P3END, P4END
• Pre-declare pygame surface/rect globals as None so they exist at module scope: FPSCLOCK, DISPLAYSURF, BASICFONT, ROLL_SURF, ROLL_RECT, ROLL1_SURF, ROLL1_RECT, EXIT_SURF, EXIT_RECT, OPTION_SURF, OPTION_RECT, CLEAR_SURF, CLEAR_RECT, ROLL6_SURF, ROLL6_RECT, PLAYERROR_SURF, PLAYERROR_RECT, CLEARERROR_SURF, CLEARERROR_RECT, TEST_SURF, TEST_RECT

The file should follow this structure:

"""
Pygbag Entry Point for Aggravation Web Version
...
"""
import asyncio

# === Try to declare all globals at once to facilitate compilation (pygbag best practice) ===

# Board template
BOARD_TEMPLATE = [...]

# Game constants
FPS = 30
WINDOWWIDTH = 640
# ... etc ...

# Color definitions
GRAY = (100, 100, 100)
# ... etc ...

# Pre-declare pygame globals (initialized in run())
FPSCLOCK = None
DISPLAYSURF = None
BASICFONT = None
ROLL_SURF = None
ROLL_RECT = None
# ... etc ...

import aggravation_web

async def main():
    """Main async entry point for Pygbag."""
    await aggravation_web.run()

# This must be the last line
asyncio.run(main())

2. web/aggravation_web.py — Import globals from main instead of declaring them

• Remove all the global variable declarations from the module level (lines 50-123) that were moved to main.py
• Instead, import them from __main__ or use a shared module pattern. The simplest approach: import the globals from main module. Since pygbag loads main.py as __main__, use: from __main__ import * or explicitly import each needed global.
• Alternatively, keep a clean approach: create the variables in main.py and have aggravation_web.py import them with import __main__ and reference them as __main__.VARIABLE_NAME, OR simply from __main__ import BOARD_TEMPLATE, FPS, WINDOWWIDTH, ... etc.
• The global declarations inside run() (lines 207-210) should still use global keyword since those variables (FPSCLOCK, DISPLAYSURF, etc.) need to be written to at module scope, but now they should reference the pre-declared None values from main.py.
• Make sure the game still functions correctly — all references to these globals throughout aggravation_web.py must still resolve properly.

Important Notes

• Do NOT modify game_engine.py or aggravation.py — only change web/main.py and web/aggravation_web.py
• Ensure all existing tests still pass
• The asyncio.run(main()) call MUST remain the last line in `web/mai...

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.