systems/cull_viewport_builtin

Goal

See how CullOutOfViewportSystem automatically removes entities that leave the visible area, and watch a spawn counter track creation vs culling.

Why this tutorial exists

In many games, projectiles, particles, or enemies that leave the screen should be cleaned up. The built-in CullOutOfViewportSystem:

  • checks each entity’s transform against the viewport bounds

  • removes entities that are fully outside the viewport

  • fires callbacks or increments counters for monitoring

This example continuously spawns entities that move in random directions and displays real-time spawn and cull counters.

Source map

  • Settings profile: examples/settings/systems/cull_viewport_builtin.yml

  • Example builder: examples/catalog/systems/cull_viewport_builtin/main.py

  • Scene: examples/catalog/systems/cull_viewport_builtin/scenes/scene.py

  • Shared runner: examples/_shared/runner.py

What to verify

You should see:

  1. coloured rectangles spawning from the centre and drifting outward

  2. entities disappearing as they leave the viewport edge

  3. a panel showing spawned / culled / active counts

  4. active count stays bounded (culling keeps up with spawning)

Behavior checks:

  • resizing the window changes the effective cull boundary

  • entities touching the edge are not culled — only fully outside ones

  • the active count stabilizes after a few seconds

Run

mini-arcade run --example systems/cull_viewport_builtin
mini-arcade run --example systems/cull_viewport_builtin --pass-through --backend pygame
mini-arcade run --example systems/cull_viewport_builtin --pass-through --backend native

Common mistakes

  • Culling entities that should wrap around (use viewport wrapping instead).

  • Setting the cull margin to 0 — entities flicker at the exact edge.

  • Forgetting that the system uses virtual coordinates, not pixel coordinates.

Next step