Current Version: 1.2.0

DX Ball is a modern arcade paddle-and-ball game built with Python and pygame-ce. Keep the ball alive, score points on each return, collect random boosts, and push for the highest score in each mode.

Intro screen with 3 tutorial slides explaining welcome, mechanics, and controls for new players

Five game modes with separate records:

Countdown timer in every run with time bonuses for successful paddle returns

Boost-combo multiplier system based on consecutive positive boost pickups

Time booster pickup appears more frequently and adds extra seconds instantly

Temporary paddle-size effects: wider paddle and shortener both expire after a duration

Booster and multiplier pacing are tuned per mode for distinct gameplay identity

Boost pickups use clearer symbols for faster recognition during gameplay

In-game boost guide panel classifies positive and challenge boosts

Level progression system in Gauntlet mode: level-up thresholds, speed ramp, and rewards

Pause system with Resume, Restart, Sound toggle, Visuals toggle, Main Menu confirmation, and Quit confirmation

Settings organized by sections:

Boost system with varied sizes and effects

Separate hit sounds for paddle and boost interactions

Dark and light themes

Per-mode high score tracking

Hidden score storage with signature validation

Keyboard gameplay and mouse interaction for menus

Control the paddle to keep the ball in play.

Earn points every time the ball hits the paddle.

Lose a life if the ball falls below the paddle.

Keep an eye on the timer. Every paddle hit adds a small time bonus.

Consecutive paddle hits increase multiplier, which also increases time gained per hit.

The run ends when all lives are lost or time runs out.

Boost items spawn randomly. Hitting a boost can trigger bonus score, extra life, slower ball speed, wider paddle, or score multipliers. Boost items can also grant time, temporarily widen the paddle, or temporarily shrink it for added challenge.

Keyboard: Space/Enter to advance, Esc to go to menu

Mouse: Click "Next", "Start Game", or "Skip"/"Back" buttons

Keyboard: Up/Down, Enter, S, Esc

Mouse: Click for mode selection and action buttons

Move paddle: Left/Right arrows or A/D

Pause: P or Esc (while run is active)

Restart after game over: Space

Return to menu after game over: Enter

Resume run

Restart run

Toggle sound

Toggle visuals

Return to main menu with confirmation prompt

Quit run with confirmation prompt

For a clearer mental model of the project, the codebase is grouped by responsibility:

Entry point and bootstrap: main.py, game/app.py

Game rules and simulation: game/engine.py

Data models and shared state: game/models.py

Configuration and player settings: game/config.py, game/settings.py

Mode balance and presets: game/modes.py

Rendering and input handling: game/ui.py, game/ui_theme.py

Audio playback: game/ui_audio.py

Score storage and validation: game/records.py

The runtime flow is:

main.py launches the app.

game/app.py loads config, settings, and records.

game/ui.py owns screens, input, and drawing.

game/engine.py updates physics, boosts, scoring, and time.

game/models.py carries the shared game state between layers.

If you want the code grouped differently, see docs/code-classification.md.

Python 3.10+

Note:

Startup now reloads core runtime modules automatically, so code edits are picked up when launching from long-lived Python sessions (for example repeated runs from an interactive environment).

Score records are stored in a hidden internal folder.

Records are validated with signatures to reduce casual score tampering.

High scores are maintained separately per game mode.

Default hidden files used at runtime:

.bin/.score_records.csv

.bin/boost_hit.wav

.bin/paddle_hit.wav

Python

pygame-ce

MIT License

Copyright (c) 2026 Md. Faizal Alvi Sarker (GitHub: AlviAdor)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.