|
| 1 | +--- |
| 2 | +sidebar_position: 1 |
| 3 | +title: Engine |
| 4 | +--- |
| 5 | + |
| 6 | +## Initializing the Creation Engine |
| 7 | + |
| 8 | +To initialize the engine, you need to create an instance of the CreationEngine class and call its init method. This method sets up the PixiJS application, initializes the screen manager, and loads the necessary assets. |
| 9 | + |
| 10 | +```ts |
| 11 | +import { CreationEngine } from './engine/engine'; |
| 12 | + |
| 13 | +const engine = new CreationEngine(); |
| 14 | + |
| 15 | +(async () => { |
| 16 | + await engine.init({ |
| 17 | + background: '#1E1E1E', |
| 18 | + resizeOptions: { minWidth: 768, minHeight: 1024, letterbox: false }, |
| 19 | + }); |
| 20 | +})(); |
| 21 | +``` |
| 22 | + |
| 23 | +## Handling Resizing |
| 24 | + |
| 25 | +The engine automatically handles resizing of the application. The resize behavior can be customized by passing options to the init method. |
| 26 | + |
| 27 | +```ts |
| 28 | +await engine.init({ |
| 29 | + resizeOptions: { minWidth: 768, minHeight: 1024, letterbox: false }, |
| 30 | +}); |
| 31 | +``` |
| 32 | + |
| 33 | +- **minWidth**: The minimum width of the application. If the window width is less than this value, the application will scale down to fit the window, but will report a logical width of this value. |
| 34 | +- **minHeight**: The minimum height of the application. If the window height is less than this value, the application will scale down to fit the window, but will report a logical height of this value. |
| 35 | +- **letterbox**: If true, the canvas will be letterboxed to maintain the aspect ratio of the application. If false, the canvas will be stretched to fill the window. |
| 36 | + |
| 37 | +## Navigation & Screens |
| 38 | + |
| 39 | +The engine provides a screen manager that allows you to manage different screens in your application. Each screen is a PixiJS Container that implements the Screen interface. |
| 40 | + |
| 41 | +```ts |
| 42 | +import { Container } from 'pixi.js'; |
| 43 | +import { Screen } from './engine/navigation'; |
| 44 | + |
| 45 | +export class MyScreen extends Container implements Screen { |
| 46 | + /** Show the screen */ |
| 47 | + show?(): Promise<void>; |
| 48 | + /** Hide the screen */ |
| 49 | + hide?(): Promise<void>; |
| 50 | + /** Pause the screen */ |
| 51 | + pause?(): Promise<void>; |
| 52 | + /** Resume the screen */ |
| 53 | + resume?(): Promise<void>; |
| 54 | + /** Prepare screen, before showing */ |
| 55 | + prepare?(): void; |
| 56 | + /** Reset screen, after hidden */ |
| 57 | + reset?(): void; |
| 58 | + /** Update the screen, passing delta time/step */ |
| 59 | + update?(time: Ticker): void; |
| 60 | + /** Resize the screen */ |
| 61 | + resize?(width: number, height: number): void; |
| 62 | + /** Blur the screen */ |
| 63 | + blur?(): void; |
| 64 | + /** Focus the screen */ |
| 65 | + focus?(): void; |
| 66 | +} |
| 67 | +``` |
| 68 | + |
| 69 | +To show different screens in your app, you can use the `showScreen` method of the Navigation class. This method hides the current screen and presents a new screen. |
| 70 | + |
| 71 | +```ts |
| 72 | +import { MainScreen } from './app/screens/main/MainScreen'; |
| 73 | +import { LoadScreen } from './app/screens/LoadScreen'; |
| 74 | + |
| 75 | +await engine.navigation.showScreen(LoadScreen); |
| 76 | +await engine.navigation.showScreen(MainScreen); |
| 77 | +``` |
| 78 | + |
| 79 | +### Popup Screens |
| 80 | + |
| 81 | +You can also show popup screens on top of the current screen. Popup screens are displayed in a separate layer above the main screen. |
| 82 | + |
| 83 | +```ts |
| 84 | +import { PauseScreen } from './app/screens/PauseScreen'; |
| 85 | + |
| 86 | +await engine.navigation.presentPopup(PauseScreen); |
| 87 | +``` |
| 88 | + |
| 89 | +equally you can hide the popup screen using the `dismissPopup` method. |
| 90 | + |
| 91 | +```ts |
| 92 | +await engine.navigation.dismissPopup(); |
| 93 | +``` |
| 94 | + |
| 95 | +### Asset Loading |
| 96 | + |
| 97 | +Using AssetPack you can define bundles of assets for your application. These bundles can be loaded individually to avoid loading all assets at once. |
| 98 | +Typically you would define a bundle for each screen in your application, and load them as needed. |
| 99 | + |
| 100 | +To help with this a screen can implements a `static assetBundles: string[]` property that defines the bundles required for that screen. The engine will automatically load these bundles when the screen is shown. |
| 101 | + |
| 102 | +```ts |
| 103 | +export class MainScreen extends Container { |
| 104 | + /** Assets bundles required by this screen */ |
| 105 | + public static assetBundles = ["main"]; |
| 106 | + |
| 107 | +} |
| 108 | +``` |
| 109 | + |
| 110 | +## Audio |
| 111 | + |
| 112 | +The engine includes built-in support for managing background music (bgm) and sound effects (sfx). You can control audio playback using the `audio` property on the `CreationEngine`. |
| 113 | + |
| 114 | +```ts |
| 115 | +// Play background music |
| 116 | +engine.audio.bgm.play('background-music.mp3', { volume: 0.5 }); |
| 117 | + |
| 118 | +// Play sound effect |
| 119 | +engine.audio.sfx.play('explosion.mp3', { volume: 0.8 }); |
| 120 | +``` |
| 121 | + |
| 122 | +### Background Music (bgm) |
| 123 | +Handles music background, playing only one audio file in loop at time, and fade/stop the music if a new one is requested. Also provide volume control for music background only, leaving other sounds volumes unchanged. |
| 124 | + |
| 125 | +### Sound Effects (sfx) |
| 126 | +Handles short sound special effects, mainly for having its own volume settings. The volume control is only a workaround to make it work only with this type of sound, with a limitation of not controlling volume of currently playing instances - only the new ones will have their volume changed. But because most of sound effects are short sounds, this is generally fine. |
| 127 | + |
| 128 | +### Global Volume |
| 129 | +While you can control the volume of each audio type, you can also control the global volume of all audio the exposed global volume functions |
| 130 | + |
| 131 | +```ts |
| 132 | +engine.audio.setMasterVolume(0.5); |
| 133 | +const volume = engine.audio.getMasterVolume(); |
| 134 | +``` |
| 135 | + |
| 136 | +## Utility Functions |
| 137 | + |
| 138 | +The engine provides several utility functions for common tasks, such as calculating distances, interpolating values, and generating random numbers. |
| 139 | + |
| 140 | +This is not an exhaustive list, but here are some examples: |
| 141 | + |
| 142 | +```ts |
| 143 | +import { getDistance, lerp, clamp } from './engine/utils/maths'; |
| 144 | +import { randomInt, randomFloat } from './engine/utils/random'; |
| 145 | + |
| 146 | +const distance = getDistance(0, 0, 10, 10); |
| 147 | +const interpolatedValue = lerp(0, 10, 0.5); |
| 148 | +const clampedValue = clamp(15, 0, 10); |
| 149 | + |
| 150 | +const randValue = randomInt(0, 10); |
| 151 | +const randFloat = randomFloat(0, 10); |
| 152 | +``` |
0 commit comments