Skip to content
dill pixel

Application

The Application class is the entry point for your game. It is responsible for initializing the game, loading assets, and managing the game loop.

The Application class is the entry point for your game. It is responsible for initializing the game, loading assets, and managing the game loop. It extends PIXI’s Application class and implements core functionality through plugins and signals.

Creating an Application

Section titled “Creating an Application”

Creating an application is now a fully automated process. The framework handles the bootstrapping for you, so you can focus on your game’s configuration and logic.

Configuration

Section titled “Configuration”

You configure your application in the dill-pixel.config.ts file. This is where you’ll define core settings, plugins, and, importantly, specify your custom application class.

dill-pixel.config.ts
import { defineConfig } from 'dill-pixel';
import { MyApplication } from './MyApplication';


export default defineConfig({
  /**
   * Core settings
   */
  id: 'MyGame',
  // Point to your custom Application class
  application: MyApplication,
  /**
   * Optional settings
   */
  useLayout: true,
  useSpine: true,
  // The scene to load by default
  defaultScene: 'start',
  // Your Resize settings
  resizeToContainer: true,
  resizer: {
    minWidth: 500,
    minHeight: 768,
    letterbox: false,
    center: false,
  },
  // The default text style to use for all text objects
  defaultTextStyle: {
    fontFamily: 'Arial',
    fontSize: 24,
    fill: 0xffffff,
  },
  // Your custom data
  data: {
    initial: {
      foo: 'bar',
    },
    backupKeys: ['foo'],
  },
  // Your required assets to preload
  assets: {
    preload: {
      bundles: [ 'required'],
    },
    background: {
      bundles: ['audio'],
    },
  },
  // Your Plugins
  plugins: [
    ['matter-physics', { autoLoad: false }],
    // ... other plugins
  ],
  // Your Storage Adapters
  storageAdapters: ['firebase'],
  // your localization settings
  i18n: {
    loadAll: true,
    locales: ['en', 'fr'],
    files: [
      { id: 'en', module: () => import('./src/locales/en') },
      { id: 'fr', module: () => import('./src/locales/fr') },
    ],
  },
   // Your custom GSAP eases
  gsap: {
    eases: {
      custom: (progress: number): number => {
        return 1 - Math.cos((progress * Math.PI) / 2);
      },
      customInOut: (progress: number): number => {
        return progress ** 2 * (3 - 2 * progress); // smoothstep
      },
    },
  },
  // ... and more ...
});

Bootstrapping

Section titled “Bootstrapping”

The entire bootstrapping process is handled by a single import in your src/index.ts file. This special import dynamically loads the framework and starts your application based on your config file.

src/index.ts
import('dill-pixel-runtime');

This will automatically:

  1. Find your dill-pixel.config.ts file.
  2. Instantiate the application class you specified in the config.
  3. Initialize the application with your configuration.
  4. Look for an optional src/main.ts and execute its default export.

Application Logic Entry Point (Optional)

Section titled “Application Logic Entry Point (Optional)”

For any logic that needs to run immediately after the application is created, you can create a src/main.ts file. The framework will automatically execute the default export of this file, passing the created app instance to it.

src/main.ts
import type { MyApplication } from './MyApplication';


export default function main(app: MyApplication) {
  // This code runs right after the app is created.
  console.log('My application is ready!', app);
  // you can access the application instance via `app`
  // if you need to do something specific after the application is created, you can do it here.
}

If you don’t need any post-initialization logic, or if you prefer to handle it within your Application class’s setup method, you can simply omit the src/main.ts file.

Core Features

Section titled “Core Features”

Signals

Section titled “Signals”

The Application provides core signals (defined in ICoreSignals) for various built-in signals. These signals are used to communicate between different parts of the application, and can be accessed via this.app.signals or this.app.signal. These signals are usually aliases for plugins that provide the functionality. E.G. this.app.signals.onSceneChangeStart is just an alias for the SceneManagerPlugin’s onSceneChangeStart signal - this.app.scenes.onSceneChangeStart.connect((detail) => { ... }):

// Listen for scene changes
this.app.signals.onSceneChangeStart.connect((detail) => {
  console.log(`Changing from ${detail.exiting} to ${detail.entering}`);
});


// Listen for window resizing
this.app.signals.onResize.connect((size) => {
  console.log(`Window resized to ${size.width}x${size.height}`);
});

Core Functions

Section titled “Core Functions”

Similarly, the Application provides core functions (defined in ICoreFunctions) for common operations. These functions are used to perform various actions, and can be accessed via this.app.exec or this.app.func. These functions are usually just aliases for the plugins that provide the functionality. E.G. app.exec.loadScene('gameScene') is just an alias for the SceneManagerPlugin’s loadScene function - this.app.scenes.loadScene('gameScene').

// Scene management
app.scenes.loadScene('game');
// also available as `app.exec.loadScene('game')`


// Popup management
app.popups.showPopup('menuPopup');
// also available as `app.exec.loadScene('game')`

Using this.app in Containers and Scenes

Section titled “Using this.app in Containers and Scenes”

Both Container and Scene classes provide access to the Application instance via this.app. This gives you easy access to all Application features:

export class MyScene extends Scene {
  initialize() {
    // Access core functions
    this.app.assets.loadBundles('required');


    // Listen to signals
    this.app.onResize.connect(this.handleResize);


    // Access plugins
    this.app.audio.play('background-music');


    // Manage data
    this.app.data.save('score', 100);
  }
}

Example Implementation

Section titled “Example Implementation”

Here’s a complete example showing how to create a custom Application with the new streamlined process:

import { defineConfig } from 'dill-pixel';
import { MyApplication } from './MyApplication';


export default defineConfig({
    id: 'MyApplication',
    application: MyApplication, // Specify your custom application class
    // ... other config ...
});