Brick Breaker Internals

Mini Arcade now includes a small core toolkit for Breakout / Arkanoid style games.

This layer is meant for games built around:

  • a bouncing ball

  • paddle-shaped bounce response

  • brick layouts with hit points

  • brick hit / clear gameplay loops

What lives in core

Core built-ins:

  • BounceHit

  • resolve_rect_bounce(...)

  • apply_bounce_hit(...)

  • ViewportBounceBinding

  • ViewportBounceSystem

  • BounceCollisionBinding

  • BounceCollisionSystem

  • PaddleBouncePolicy

  • BrickState

  • BrickField

  • BrickFieldCollisionBinding

  • BrickFieldCollisionSystem

Source module:

  • packages/mini-arcade-core/src/mini_arcade_core/scenes/systems/builtins/brick_breaker.py

Viewport bounce

ViewportBounceSystem handles the common ball-vs-wall case for selected viewport sides.

Typical use:

  • bounce from left, right, and top

  • let bottom pass through for life-loss logic

The system repositions the ball inside the viewport and reflects the relevant velocity component.

Rect bounce collisions

BounceCollisionSystem handles one moving rect against one or more target rects.

resolve_rect_bounce(...) computes:

  • collision axis

  • bounce normal

  • penetration depth

apply_bounce_hit(...) then resolves the overlap and reflects velocity on the chosen axis.

This is intended for:

  • ball vs paddle

  • ball vs moving shield

  • ball vs bumpers

PaddleBouncePolicy

PaddleBouncePolicy reshapes the outgoing ball trajectory based on where it hits the paddle.

It supports:

  • horizontal offset shaping

  • min/max speed

  • speed gain after impact

  • paddle velocity influence

This is the core reusable part of classic paddle-ball gameplay. Exact score, combo, and power-up rules still belong in the game.

BrickField

BrickField is a simple dense brick layout keyed by GridCoord.

Each cell stores a BrickState:

  • hit_points

  • optional payload

The field exposes:

  • alive brick queries

  • brick rect lookup through GridLayout

  • damage application and brick removal

This keeps brick state separate from scene-specific UI or score logic.

BrickFieldCollisionSystem

BrickFieldCollisionSystem reflects a ball from the first hit brick in a field and applies damage to that brick cell.

The binding callback receives:

  • the hit cell

  • the remaining brick state, if any

  • the resolved bounce hit

That gives game code a clean place to:

  • award score

  • spawn drops

  • play sounds

  • track combo/chain rules

What is intentionally not in core

Core does not include a full Arkanoid ruleset.

Still game-specific:

  • score tables

  • lives / restart rules

  • level progression

  • power-up catalogs

  • laser paddles

  • sticky/catch paddles

  • multiball rules

  • enemy waves or bosses

Those should be implemented in game code on top of the reusable helpers above.