Skip to main content
Version: Dev

Scenes

Scenes are a fundamental part of your game. They keep everything neatly organized.

Why Scenes?​

As an example, picture a game with a title screen and a settings menu. Without scenes, the game loop would contain code for both of those screens.

After a while, you might add a game screen, a pause menu, etc. At this point your game loop would be very busy from all the different code needed to handle all those different screens.

So as a good developer, you'd think to shorten and simplify your code by making functions or classes that encapsulate the logic of each scene to keep the game loop neat and clean. That's basically what scenes do!

Basics​

Entities and Camera​

Each scene manages a flat list of entities and a single camera (scene.camera). Draw order is controlled by each Drawable's render_order — lower values are drawn first.

Every scene also creates a GUI root (scene.root) and adds it as an entity automatically. Add game objects with scene.add(...), and add widgets to the GUI tree with scene.root.add(...).

class MyScene(bf.Scene):
    def do_when_added(self):
        self.add(player, enemy)          # game entities
        self.root.add(score_label)       # GUI widgets

How to use a Scene​

To customize a scene, inherit the Scene class:

class MyScene(bf.Scene):...

Important methods:

  • do_when_added(self) is called once when the scene is linked with the Manager. Initialize variables and entities here. The manager attribute is available from this point on.
  • do_update(self, dt: float) is called every frame. dt is the time elapsed since the last frame (in seconds).
  • do_on_enter(self) is called every time the scene becomes the top of the stack.
  • do_on_exit(self) is called every time the scene leaves the top of the stack.
  • do_on_enter_early(self) / do_on_exit_early(self) run earlier in enter/exit transitions.
  • add(self, *entities: bf.Entity) queues one or more entities to be added (applied on the next flush).
  • remove(self, *entities: bf.Entity) queues one or more entities to be removed.
  • set_clear_color(self, color) sets the camera clear color (background).
  • get_by_tags(self, *tags) returns the first entity matching all given tags, or None.
  • get_all_by_tags(self, *tags) returns all entities matching all given tags.
  • get_by_uid(self, uid) looks up an entity by unique id.
Check the sources

Check the source code on GitHub to see all the methods available to you.