aadit-n3rdy/smart_asteroids

Purpose and entry points

Smart Asteroids is a local Python/Pygame game where a player-controlled rocket fights asteroids whose movement behavior is driven by neural networks and improved through genetic evolution. The runnable entry point is main.py, with application startup likely delegated to src/main.py.

Game orchestration and state control

The central runtime loop and game-wide coordination live in src/core/game.py. It manages frame updates, input dispatch, entity lifecycles, collision/game-over conditions, and transitions between menu, active play, and paused/game-over states. State definitions or state-machine support are separated in src/core/game_states.py.

Player and combat entities

Gameplay actors are isolated under src/entities/:

• src/entities/rocket.py implements mouse-aimed player movement, thrust, and firing.

• src/entities/bullet.py represents player projectiles and their update/collision lifetime.

• src/entities/asteroid.py owns asteroid movement and likely exposes the inputs/fitness signals used by AI evolution.

The game loop is the boundary that creates, updates, renders, and removes these entities.

Neural-network-controlled asteroid behavior

src/utils/neural_network.py provides the model representation or inference/math used to map game observations into asteroid actions. Asteroids in src/entities/asteroid.py consume these networks during frame updates; the game supplies the world context needed for decisions, such as player position or survival/combat outcomes. numpy is a material dependency for this numerical layer.

Evolution framework

Evolution is deliberately modular:

• src/evolution/base.py defines the common evolution-strategy contract.

• src/evolution/factory.py selects an implementation from configuration.

• src/evolution/crossover_evolution.py creates offspring from high-performing parents.

• src/evolution/tournament_evolution.py selects candidates through tournament competition.

At generation boundaries, asteroid fitness/performance feeds the selected strategy; it returns new neural-network genomes/models for the next asteroid population. This keeps selection/reproduction independent of game rendering and core entity control.

Configuration and strategy boundary

src/utils/constants.py contains shared simulation settings, including the EVOLUTION_STRATEGY selector. The factory in src/evolution/factory.py is the architectural seam between fixed game orchestration and interchangeable genetic algorithms: adding a strategy should require implementing the base interface and registering it with the factory rather than changing entity logic.

UI, assets, and runtime dependencies

Pygame-ce provides the window, event loop, rendering, audio-capable runtime primitives, and input handling. pygame-gui supports structured UI screens:

• src/ui/main_menu.py

• src/ui/user_guide.py

Theme assets are externalized in assets/themes/main_menu_theme.json, assets/themes/pause_menu_theme.json, and assets/themes/game_over_theme.json; images and fonts are loaded from assets/images and assets/fonts. UI screens control transitions back into the core game/state layer rather than owning simulation logic.