Scenes

Dill Pixel uses a scene management system to manage different scenes in your game. 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 animateIn and animateOut methods that will fade all of our scenes in and out:

src/scenes/BaseScene.ts

import { COLOR_SLATE } from '@/utils/Constants';
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
 */
export default class BaseScene extends Scene<MyApplication> {
  constructor() {
    super();
    this.alpha = 0;
    this.addColoredBackground(COLOR_SLATE);
  }
}

Creating a Scene

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

src/scenes/StartScene.ts

import BaseScene from '@/scenes/BaseScene';
import { FONT_KUMBH_SANS } from '@/utils/Constants';
import { FlexContainer } from 'dill-pixel';

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

export default class StartScene extends BaseScene {
  private _layout: FlexContainer;

  initialize() {
    // a temporary layout container
    this._layout = this.add.flexContainer({
      flexDirection: 'column',
      gap: 25,
      alignItems: 'center',
      justifyContent: 'center',
    });

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

    // from src/assets.json
    this._layout.add.sprite({ asset: 'jar.png', scale: 0.25 });

    const startButton = this._layout.add.button({
      sheet: 'ui',
      scale: 0.5,
      cursor: 'pointer',
      textures: {
        default: 'btn/blue',
        hover: 'btn/red',
        active: 'btn/green',
      },
    });

    startButton.add.text({
      text: 'Start',
      style: { fontFamily: FONT_KUMBH_SANS, fontWeight: 'bold', fill: 0xffffff, align: 'center', fontSize: 60 },
      resolution: 2,
      anchor: 0.5,
    });

    this.addSignalConnection(
      startButton.onClick.connect(() => {
        this.app.exec.loadScene({ id: 'game', method: 'exitEnter' });
      }),
    );
  }

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

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

  start() {}
}

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)
};

Switching Between Scenes

To switch between scenes, use the transitionTo method on the game instance:

// 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');