Scenes

In Dill Pixel, a Scene is a container that contains a game’s assets, logic, and UI. For example, a simple game might have Title, Game, and GameOver scenes. Let’s see how we would include those in our game and switch between them.

Creating a Base Scene

To create a new scene, create a new file in the src/scenes directory. For example, let’s create a BaseScene that all of our other game scenes will extend. This first scene should extend dill pixel’s Scene class and for now we’ll just add custom enter and exit methods that will fade all of our scenes in and out:

src/scenes/BaseScene.ts

import { Scene } from 'dill-pixel';

// include this scene in the bundle
export const dynamic = false;

// make it inactive in the scene list (debug mode)
export const active = false;

/**
 * Base scene
 * this is a nice way to make a scene that can be extended by other scenes
 * it casts the scene to the application type,
 * so you can access the application's properties and methods in all scenes extending this one
 * it also allows you to add custom logic to the scene that can be shared across scenes
 * commented out is an example of how you can use enter / exit animations
 */
export default class Base extends Scene {
  constructor() {
    super();
    this.addColoredBackground(0xffffff);

    // // for enter / exit animations you could start the scene with 0 opacity, and fade in / out
    // this.alpha = 0;
  }

  // // enter / exit animations (basic)
  // async enter() {
  // // fade in on enter
  //   return this.animate({ alpha: 1, duration: 1, ease: 'sine.out' });
  // }

  // async exit() {
  // // fade out on exit
  //   return this.animate({ alpha: 0, duration: 0.5, ease: 'sine.in' });
  // }
}

Creating a Scene

Next, let’s create a StartScene that extends our BaseScene:

src/scenes/Start.ts

import { FlexContainer } from 'dill-pixel';
import Base from './Base';

export const id = 'start';
export const debug = {
  label: 'Start Scene',
};

export default class Start extends Base {
  private container: FlexContainer;

  initialize() {
    // a layout container
    this.container = this.add.flexContainer({
      label: 'Main Container',
      bindToAppSize: true,
      layout: {
        flexDirection: 'column',
        alignItems: 'center',
        justifyContent: 'center',
        gap: 25,
      },
    });

    // some title text
    this.container.add.text({
      text: 'Hello Dill Pixel',
      resolution: 2,
      style: { fontFamily: 'Kumbh Sans', fontWeight: 'bold', fill: 0xffffff },
    });

    // from src/assets.json
    this.container.add.sprite({
      asset: 'jar.png',
      scale: 0.25,
      anchor: 0.5,
      layout: { applySizeDirectly: true },
    });
  }

  start() {
    // start the scene's jobs here
  }

  resize() {
    // the layout container binds to the app size,
    // but we still need to center it
    this.container.position.set(-this.app.size.width * 0.5, -this.app.size.height * 0.5);
  }
}

Configuring Scenes

Scenes in the ./src/scenes directory will be automatically registered with the game.

You can configure how your scene is loaded by modifying a few custom exports in your scene file:

export const id = 'game'; // the scene's id. If not provided, the file name will be used
export const dynamic = false; // if true, the scene will be loaded dynamically
export const active = false; // if true, the scene will be active in the scene list

export const debug = {
  label: 'Game', // the scene's label. If not provided, the id will be used
  group: 'Game', // the scene's group in the debug panel (optional)
};

Strongly-typing Scene exports

To get autocompletion and type-checking for your scene exports, you can use the helper types exported from dill-pixel. This is especially useful for assets and plugins where you can get autocompletion for bundle names and plugin IDs.

Here’s how you can type your exports:

src/scenes/MyScene.ts

import type { SceneAssets, ScenePlugins, SceneDebug } from 'dill-pixel';

export const id = 'my-scene';

// will autocomplete with object properties and available bundle names
export const assets: SceneAssets = {
  preload: {
    bundles: ['game'],
  },
  autoUnload: true,
};

// will autocomplete with available plugin ids
export const plugins: ScenePlugins = ['my-plugin'];

// will autocomplete with debug object properties
export const debug: SceneDebug = {
  group: 'My Game',
  label: 'My Awesome Scene',
};

Note

You can also use the SceneConfig type to type all exports at once, but typing them individually is often cleaner.

import type { SceneConfig } from 'dill-pixel';

export const assets: SceneConfig['assets'] = { /* ... */ };
export const plugins: SceneConfig['plugins'] = [ /* ... */ ];
export const debug: SceneConfig['debug'] = { /* ... */ };

Switching Between Scenes

To switch between scenes, use the loadScene method on the app:

// From within the Application.ts file
this.loadScene('game'); // reference by the scene's id

// From outside of the Applicatiqon.ts file, and not within a scene,
// you can call the app's loadScene method directly
app.exec.loadScene('game'); // reference by the scene's id

// From within a scene (or any container with an Application instance)
this.app.exec.loadScene('game');