Events

Events flow from the Manager into the active scene, then down to entities and GUI widgets. You can intercept them at several points.

Scene event order

When a scene receives an event, propagation stops as soon as event.consumed is set:

1. do_early_handle_event(self, event) — earliest scene hook
2. early_actions — scene early ActionContainer
3. Player input is skipped while a transition is running
4. VIDEORESIZE may resize the camera (when fullscreen and not SCALED)
5. Each entity via entity.process_event(event) (includes scene.root and the GUI tree)
6. handle_event(self, event) — main scene hook
7. actions — scene ActionContainer

class MyScene(bf.Scene):
    def do_early_handle_event(self, event):
        if event.type == pygame.KEYDOWN and event.key == pygame.K_ESCAPE:
            # handle before entities see it
            event.consumed = True

    def handle_event(self, event):
        if event.type == pygame.KEYDOWN and event.key == pygame.K_p:
            self.toggle_pause()

Entity event order

For each entity:

1. process_actions(event) — entity actions, if any
2. handle_event(event) — override for custom logic

GUI interactive widgets extend this with focus, hover, click, and custom handlers.

Consuming events

Set event.consumed = True (or use an Action with set_consume_event(True)) to stop further propagation.

Related hooks

Scene lifecycle (not event-based, but often used together):

• do_when_added — scene linked to manager
• do_update(dt) — per-frame logic after entities update
• do_on_enter / do_on_exit — stack enter/exit
• do_on_enter_early / do_on_exit_early — earlier enter/exit