angry-pixel 1.2.17 → 2.0.1

package/README.md

@@ -1,148 +1,168 @@
-# Introduction
+# Angry Pixel Engine
 
-## What is Angry Pixel?
+## What is Angry Pixel Engine?
 
-Angry Pixel is a 2D engine for browser games written in Typescript.
+It is a 2D engine for browser games written in Typescript.
 
 Main features:
 
--   Sprites and animations
--   Tilemaps (csv and Tiled)
+-   Entity-Component-System based architecture
 -   WebGL rendering
--   Polygonal collisions and static physics resolution
--   Input (keyboard, mouse, gamepad, touch)
--   Scene-Object-Component based architecture
+-   Sprite-based graphics and frame-by-frame animations
+-   Text rendering based on bitmap fonts
+-   Shadow/Lights rendering
+-   Polygonal collisions and static/dynamic physical responses
+-   Keyboard, mouse, gamepad and touch screen input support
+-   Dependency Injection
 
 ## Getting Started
 
+Let's create a scene where the Angry Pixel logo bounces off the edges of the screen in a DVD screensaver fashion.
+
 ### Installation
 
 ```bash
 npm i angry-pixel
 ```
 
+or
+
+```bash
+yarn add angry-pixel
+```
+
 ### Initialize
 
-Create and configure a new Game instance.
+First we create an instance of the Game class:
 
 ```typescript
 import { Game, GameConfig } from "angry-pixel";
 
 const config: GameConfig = {
-    containerNode: document.getElementById("app"),
-    gameWidth: 1920,
-    gameHeight: 1080,
+    containerNode: document.querySelector("#app"),
+    width: 1920,
+    height: 1080,
     canvasColor: "#00D9D9",
 };
 
-// create the game
 const game = new Game(config);
 ```
 
 ### Create a Scene
 
-Crear la clase MainScene que extiende Scene and load an image that will be used as a Sprite.
+Then we will create the MainScene class, which extends the Scene base class. This class represents a scene in our game, and has three main functions:
+
+-   To load assets.
+-   To create the initial entities.
+-   To know which are the necessary systems.
+
+For the moment we only implement the function loadAssets to load an image that we will use later:
 
 ```typescript
 import { Scene } from "angry-pixel";
 
 class MainScene extends Scene {
-    protected init(): void {
+    // within this method we load the assets
+    public loadAssets(): void {
         this.assetManager.loadImage("logo.png");
     }
 }
 ```
 
-Add the scene to the game.
+And we add this scene to our game:
 
 ```typescript
-const config: GameConfig = {
-    containerNode: document.getElementById("app"),
-    gameWidth: 1920,
-    gameHeight: 1080,
-    canvasColor: "#00D9D9",
-};
+// arguments: the scene class, the scene name, and true because is the opening scene
+game.addScene(MainScene, "MainScene", true);
+```
 
-// create the game
-const game = new Game(config);
-// add scene
-game.addScene(MainScene, "MainScene");
+### Create a Component
+
+Then we will create the MoveAndBounce component which has the necessary attributes to define the movement of our entity.
+
+```typescript
+import { Vector2 } from "angry-pixel";
+
+class MoveAndBounce {
+    boundaries: number[] = [476, -476, 896, -896]; // top, bottom, left, right
+    direction: Vector2 = new Vector2(1, 1); // the direction in wich the entity will move
+    speed: number = 200; // pixels per second
+}
 ```
 
-### Create a Game Object
+### Create a System
 
-Create the Logo class extending GameObject and add the image using the native SpriteRenderer component.
+Once we have created our component, we will need a system that executes the business logic. Extending the base class GameSystem, we will create our MoveAndBounceSystem, which, using the EntityManager, obtains all the entities that have the MoveAndBounce component, and executes the business logic necessary for the entity to move by bouncing on the edges of the screen:
 
 ```typescript
-import { GameObject, Sprite, SpriteRenderer } from "angry-pixel";
+import { GameSystem, Transform } from "angry-pixel";
 
-class Logo extends GameObject {
-    protected init(): void {
-        this.addComponent(SpriteRenderer, {
-            sprite: new Sprite({
-                image: this.assetManager.getImage("logo.png"),
-            }),
+class MoveAndBounceSystem extends GameSystem {
+    public onUpdate(): void {
+        this.entityManager.search(MoveAndBounce).forEach(({ component, entity }) => {
+            const transform = this.entityManager.getComponent(entity, Transform);
+            const { boundaries, direction, speed } = component;
+
+            if (transform.position.y >= boundaries[0] || transform.position.y <= boundaries[1]) {
+                direction.y *= -1;
+            }
+
+            if (transform.position.x >= boundaries[2] || transform.position.x <= boundaries[3]) {
+                direction.x *= -1;
+            }
+
+            transform.position.x += direction.x * speed * this.timeManager.deltaTime;
+            transform.position.y += direction.y * speed * this.timeManager.deltaTime;
         });
     }
 }
 ```
 
-Add the object to the scene.
+Once the system is created, we can add it to the scene
 
 ```typescript
+import { Scene } from "angry-pixel";
+
 class MainScene extends Scene {
-    protected init(): void {
+    // in this attribute we load the systems of the scene
+    public systems: SystemType<System>[] = [MoveAndBounceSystem];
+
+    public loadAssets(): void {
         this.assetManager.loadImage("logo.png");
-        this.addGameObject(Logo);
     }
 }
 ```
 
-### Create a Component
+### Create the entities
 
-Create the MoveAndBounce class that extends Component and contains the logic for object movement, using the native Transform component (natively included in the GameObject), vectors and delta time.
+Finally, we need two entities, one that represents our logo, which we want to move, and another one that represents the camera of our game. To do this we will create the entities in the following way:
 
 ```typescript
-import { Component, Transform, Vector2 } from "angry-pixel";
-
-class MoveAndBounce extends Component {
-    private transform: Transform;
-    private direction: Vector2;
-    private speed: number;
+import { Camera, Component, Scene, SpriteRenderer, Transform } from "angry-pixel";
 
-    protected init(): void {
-        this.transform = this.gameObject.transform;
-        this.direction = new Vector2(1, 1);
-        this.speed = 200; // pixels per second
-    }
+class MainScene extends Scene {
+    public systems: SystemType<System>[] = [MoveAndBounceSystem];
 
-    // this method is called once per frame
-    protected update(): void {
-        if (this.transform.position.y >= 476 || this.transform.position.y <= -476) {
-            this.direction.y *= -1;
-        }
-        if (this.transform.position.x >= 896 || this.transform.position.x <= -896) {
-            this.direction.x *= -1;
-        }
-
-        this.transform.position.x += this.direction.x * this.speed * this.timeManager.deltaTime;
-        this.transform.position.y += this.direction.y * this.speed * this.timeManager.deltaTime;
+    public loadAssets(): void {
+        this.assetManager.loadImage("logo.png");
     }
-}
-```
 
-Add the component to the object.
-
-```typescript
-class Logo extends GameObject {
-    protected init(): void {
-        this.addComponent(SpriteRenderer, {
-            sprite: new Sprite({
+    // within this method we create the entities
+    public setup(): void {
+        // camera
+        const cameraArchetype: Component[] = [new Transform(), new Camera({ layers: ["Logo"] })];
+        this.entityManager.createEntity(cameraArchetype);
+
+        // logo
+        const logoArchetype: Component[] = [
+            new Transform(),
+            new SpriteRenderer({
+                layer: "Logo",
                 image: this.assetManager.getImage("logo.png"),
             }),
-        });
-
-        this.addComponent(MoveAndBounce);
+            new MoveAndBounce(),
+        ];
+        this.entityManager.createEntity(logoArchetype);
     }
 }
 ```
@@ -150,21 +170,13 @@ class Logo extends GameObject {
 ### Run the game
 
 ```typescript
-const config: GameConfig = {
-    containerNode: document.getElementById("app"),
-    gameWidth: 1920,
-    gameHeight: 1080,
-    canvasColor: "#00D9D9",
-};
-
-// create the game
-const game = new Game(config);
-// add scene
-game.addScene(MainScene, "MainScene");
-// run the game
 game.run();
 ```
 
 ### Check this example live
 
-➡️ [https://angrypixel.gg/angry-pixel-logo-bounce](https://angrypixel.gg/angry-pixel-logo-bounce)
+🎮 [https://angrypixel.gg/angry-pixel-logo-bounce](https://angrypixel.gg/angry-pixel-logo-bounce)
+
+## API DOCS
+
+🔎 [https://angrypixel.gg/engine/api-docs](https://angrypixel.gg/engine/api-docs)