core2d 2.10.4 → 2.11.2

package/README.md

@@ -1,54 +1,127 @@
 ![core2d logo](./core2d.jpg)
 
 # About
+
 Core2D is the powerhouse used by [Maragato マラガト](https://maragato.itch.io) apps, among others. It is the evolution of Videogame, which in turn was the evolution of Quick. In its current form, it adopts [JavaScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules), leveraging the full power of [Object-oriented programming](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Object-oriented_programming).
 
 ## Concept
+
 Apps created with Core2D are made of one or more [scenes](src/Scene.mjs), which may contain one or more [sprites](src/Sprite.mjs). These objects have properties that can be customized to shape their behavior. It's that simple.
 
 # Get Started
+
 [Download](https://github.com/dgchrt/core2d-skel/archive/refs/heads/main.zip) or clone/fork the [skeleton project](https://github.com/dgchrt/core2d-skel/) to start building your app. Alternatively, the library can be also installed to your existing/new project:
+
 ```shell
 npm install core2d
 ```
 
 ## Learn
+
 The best way to learn is by doing, and you can see what Core2D is capable of through existing open-sourced apps. Check the [Hall of Fame](#hall-of-fame) below for some source code.
 
 ## Support
+
 Please consider joining the [Discussions](https://github.com/dgchrt/core2d/discussions) for collaboration and support.
 
 # Features
 
+## Scene Management
+
+Core2D facilitates the organization of your app into one or more [scenes](src/Scene.mjs), which can be transitioned between. Each scene can contain multiple [sprites](src/Sprite.mjs), which are the basic building blocks for game objects.
+
+## Sound Management
+
+The engine provides a simple yet powerful sound system that allows for playing sound effects and background music. It also supports fading out the current theme, which is useful for smooth transitions between different music tracks.
+
 ## Collision Detection
+
 Translated to callbacks, to keep update logic clean.
 
 ## Assets Caching
+
 Assets and their transformations are reused automatically to keep a solid performance.
 
+## Transformations
+
+Core2D provides a set of functions to manipulate images, including rotation, flipping, and colorization. These transformations are cached, so they are only applied once per image.
+
+## Tilemap
+
+The `Scene` class provides a `build` method that allows for creating tile-based scenes from a map. This is useful for creating levels in platformers, RPGs, and other genres that use tile-based graphics.
+
 ## User Input
+
 Human interaction is unified via abstractions, so that apps will just work, regardless of the devices in use.
 
 ### Controllers
+
 ![controllers](controller.png)
 
 Gamepads or keyboard. When using a keyboard, sensible defaults (minding accessibility) are used, as seen in [KeyMap.mjs](https://github.com/dgchrt/core2d/blob/main/src/KeyMap.mjs).
 
 ### Pointers
+
 ![pointer](pointer.png)
 
 Mice or touch screen.
 
 ## Virtual Resolution
+
 Internal geometry frees the app logic from displays, i.e. your app can have an internal logic resolution of 800x600, while running on any display size.
 
+# Plugins
+
+Core2D comes with a set of optional plugins that can be used to extend its functionality. These plugins are located in the `src/plugin` directory and can be used by importing them into your project.
+
+- **BaseTile:** A basic tile sprite that can be used with the `Scene.build` method.
+- **ClickableSprite:** A sprite that can be clicked or tapped.
+- **ControllableSprite:** A sprite that can be controlled by a gamepad or keyboard.
+- **CursorSprite:** A sprite that follows the pointer.
+- **Fog:** A simple fog effect.
+- **FontSprite:** A sprite that displays text using a custom font.
+- **JumperSprite:** A sprite that can jump.
+- **RandomRectTransition:** A transition that fills the screen with random rectangles.
+- **Starfield:** A simple starfield effect.
+
 # Contributing
+
 The core of the library (under `src/`) should remain agnostic and lean. Updates to the core library are usually related to technology developments in the platform (web API advances), while staying true to the basic concepts of the library, which are common to all apps.
 
 Opinionated functionality should be implemented in the form of a plugin (under `src/plugin/`). Plugins can add features that are domain driven, such as elements that can be reused by multiple apps, but not necessarily by every app.
 
+## Development Setup
+
+To contribute to Core2D, you'll need to set up your development environment.
+
+1.  **Version Management:**
+    This project uses [asdf](https://asdf-vm.com/) to manage the Node.js version. To install the correct version, run:
+    ```shell
+    asdf install
+    ```
+2.  **Install Dependencies:**
+    ```shell
+    npm install
+    ```
+3.  **Recommended VS Code Extensions:**
+    This project includes a list of recommended VS Code extensions in `.vscode/extensions.json`. When you open the project in VS Code, you should be prompted to install them. These extensions will help you with code formatting and linting.
+4.  **Formatting and Linting:**
+    This project uses [Prettier](https://prettier.io/) for code formatting and [ESLint](https://eslint.org/) for linting. The configuration for these tools is in the `.prettierrc.json` and `eslint.config.js` files, respectively.
+    To format the code, run:
+    ```shell
+    npm run format
+    ```
+    To lint the code, run:
+    ```shell
+    npm run lint
+    ```
+5.  **Git Hooks:**
+    This project uses [husky](https://typicode.github.io/husky/) to manage Git hooks. A `pre-commit` hook is configured to run `npm test` before each commit. This ensures that all tests pass and the code is linted before it's committed. After running `npm install`, the hooks will be automatically configured.
+
 # Hall of Fame
+
 Apps created with Core2D:
+
 - [Asteroids Remake](https://chamun.github.io/asteroids-remake/) ([source](https://github.com/chamun/asteroids-remake))
 - [Cityscape](https://puter.com/app/cityscape) - Single-player arcade survival game
 - [Cucurbita's Halloween](https://www.kongregate.com/games/bbastudios/cucurbitas-halloween)

package/package.json

@@ -1,50 +1,55 @@
 {
-	"name": "core2d",
-	"type": "module",
-	"version": "2.10.4",
-	"description": "Multiplatform 2D interaction engine",
-	"files": [
-		"src"
-	],
-	"scripts": {
-		"lint": "eslint",
-		"prepublishOnly": "git checkout main && git pull --rebase && npm test && git push && git push --tags",
-		"test": "npm run lint && for test in ./test/*.mjs; do node $test; done"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/dgchrt/core2d.git"
-	},
-	"keywords": [
-		"2d",
-		"core",
-		"core2d",
-		"engine",
-		"game",
-		"game-engine",
-		"gamepad",
-		"interaction",
-		"keyboard",
-		"mouse",
-		"multi-platform",
-		"multimedia",
-		"object-oriented",
-		"sprites",
-		"scenes",
-		"touch"
-	],
-	"author": "Diogo Eichert",
-	"license": "MIT",
-	"bugs": {
-		"url": "https://github.com/dgchrt/core2d/issues"
-	},
-	"funding": {
-		"url": "https://github.com/sponsors/dgchrt"
-	},
-	"homepage": "https://dgchrt.github.io/core2d/",
-	"devDependencies": {
-		"@eslint/js": "^9.30.1",
-		"eslint": "^9.30.1",
-		"globals": "^16.3.0"
-	}
+  "name": "core2d",
+  "type": "module",
+  "version": "2.11.2",
+  "description": "Multiplatform 2D interaction engine",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "format": "prettier --write .",
+    "lint": "eslint",
+    "prepublishOnly": "git checkout main && git pull --rebase && npm test && git push && git push --tags",
+    "test": "npm run lint && for test in ./test/*.mjs; do node $test; done",
+    "prepare": "husky"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dgchrt/core2d.git"
+  },
+  "keywords": [
+    "2d",
+    "core",
+    "core2d",
+    "engine",
+    "game",
+    "game-engine",
+    "gamepad",
+    "interaction",
+    "keyboard",
+    "mouse",
+    "multi-platform",
+    "multimedia",
+    "object-oriented",
+    "sprites",
+    "scenes",
+    "touch"
+  ],
+  "author": "Diogo Eichert",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/dgchrt/core2d/issues"
+  },
+  "funding": {
+    "url": "https://github.com/sponsors/dgchrt"
+  },
+  "homepage": "https://dgchrt.github.io/core2d/",
+  "devDependencies": {
+    "@eslint/js": "^9.30.1",
+    "eslint": "^9.30.1",
+    "eslint-config-prettier": "^10.1.5",
+    "globals": "^16.3.0",
+    "husky": "^9.1.7",
+    "prettier": "^3.6.2"
+  }
 }

package/src/ACL.mjs

@@ -3,70 +3,70 @@
 /**
  * Sets up the environment based on its runtime (browser or not).
  */
-if (typeof(global) != "undefined") {
-	global.addEventListener = () => {};
+if (typeof global != "undefined") {
+  global.addEventListener = () => {};
 
-	global.document = {
-		createElement: (name) => {
-			if (name == "canvas") {
-				return {
-					getContext: () => {
-						return {
-							measureText: (text) => {
-								return {
-									width: text.length,
-								};
-							},
-						};
-					},
-				};
-			}
-		},
-		getElementById: (id) => {
-			if (id == "app") {
-				return {
-					focus: () => {},
-					getContext: () => {
-						return {
-							fillRect: () => {},
-						};
-					},
-					height: 400,
-					offsetLeft: 0,
-					offsetTop: 0,
-					style: {},
-					width: 640,
-				};
-			}
+  global.document = {
+    createElement: (name) => {
+      if (name == "canvas") {
+        return {
+          getContext: () => {
+            return {
+              measureText: (text) => {
+                return {
+                  width: text.length,
+                };
+              },
+            };
+          },
+        };
+      }
+    },
+    getElementById: (id) => {
+      if (id == "app") {
+        return {
+          focus: () => {},
+          getContext: () => {
+            return {
+              fillRect: () => {},
+            };
+          },
+          height: 400,
+          offsetLeft: 0,
+          offsetTop: 0,
+          style: {},
+          width: 640,
+        };
+      }
 
-			return {};
-		},
-		getElementsByTagName: () => {
-			return [];
-		}
-	};
+      return {};
+    },
+    getElementsByTagName: () => {
+      return [];
+    },
+  };
 
-	global.localStorage = {};
+  global.localStorage = {};
 
-	/**
-	 * For older Node.js versions.
-	 */
-	if (!global.navigator) {
-		global.navigator = {};
-	}
+  /**
+   * For older Node.js versions.
+   */
+  if (!global.navigator) {
+    global.navigator = {};
+  }
 
-	global.window = {
-		focus: () => {},
-		innerHeight: 600,
-		innerWidth: 800,
-		requestAnimationFrame: () => true
-	};
+  global.window = {
+    focus: () => {},
+    innerHeight: 600,
+    innerWidth: 800,
+    requestAnimationFrame: () => true,
+  };
 }
 
 /**
  * Anti-Corruption Layer, to be used instead of direct API calls.
  */
 export const ACL = {
-	document,
-	window,
+  document,
+  window,
 };

package/src/Animation.mjs

@@ -2,55 +2,92 @@
 
 import { Frame } from "./Frame.mjs";
 
+/**
+ * Represents an animation, which is a sequence of frames.
+ */
 export class Animation {
-	constructor(frames) {
-		this._frames = frames;
-		this._index = 0;
-		this._tick = 0;
-	}
-
-	static fromImages(images, duration) {
-		return new this(images.map(image => new Frame(image, duration)));
-	}
-
-	get image() {
-		return this._frames[this._index].image;
-	}
-
-	get width() {
-		return this._frames[this._index].width;
-	}
-
-	get height() {
-		return this._frames[this._index].height;
-	}
-
-	setFrameIndex(index) {
-		if (index < this._frames.length) {
-			this._index = index;
-			this._tick = 0;
-		}
-	}
-
-	set frameIndex(index) {
-		this.setFrameIndex(index);
-	}
-
-	sync() {
-		const DURATION = this._frames[this._index].duration;
-		let hasLooped = false;
-
-		if (DURATION && ++this._tick >= DURATION) {
-			let index = this._index + 1;
-
-			if (index == this._frames.length) {
-				hasLooped = true;
-				index = 0;
-			}
-
-			this.setFrameIndex(index);
-		}
-
-		return hasLooped;
-	}
+  /**
+   * Creates a new Animation.
+   * @param {Frame[]} frames The frames of the animation.
+   */
+  constructor(frames) {
+    this._frames = frames;
+    this._index = 0;
+    this._tick = 0;
+  }
+
+  /**
+   * Creates a new Animation from a list of images.
+   * @param {HTMLImageElement[]|HTMLCanvasElement[]} images The images of the animation.
+   * @param {number} duration The duration of each frame in ticks.
+   * @returns {Animation} The new animation.
+   */
+  static fromImages(images, duration) {
+    return new this(images.map((image) => new Frame(image, duration)));
+  }
+
+  /**
+   * The image of the current frame.
+   * @type {HTMLImageElement|HTMLCanvasElement}
+   */
+  get image() {
+    return this._frames[this._index].image;
+  }
+
+  /**
+   * The width of the current frame.
+   * @type {number}
+   */
+  get width() {
+    return this._frames[this._index].width;
+  }
+
+  /**
+   * The height of the current frame.
+   * @type {number}
+   */
+  get height() {
+    return this._frames[this._index].height;
+  }
+
+  /**
+   * Sets the index of the current frame.
+   * @param {number} index The index of the frame.
+   */
+  setFrameIndex(index) {
+    if (index < this._frames.length) {
+      this._index = index;
+      this._tick = 0;
+    }
+  }
+
+  /**
+   * The index of the current frame.
+   * @type {number}
+   */
+  set frameIndex(index) {
+    this.setFrameIndex(index);
+  }
+
+  /**
+   * Synchronizes the animation.
+   * @returns {boolean} Whether the animation has looped.
+   */
+  sync() {
+    const DURATION = this._frames[this._index].duration;
+    let hasLooped = false;
+
+    if (DURATION && ++this._tick >= DURATION) {
+      let index = this._index + 1;
+
+      if (index == this._frames.length) {
+        hasLooped = true;
+        index = 0;
+      }
+
+      this.setFrameIndex(index);
+    }
+
+    return hasLooped;
+  }
 }

package/src/Axis.mjs

@@ -2,9 +2,4 @@
 
 import { Static } from "./Static.mjs";
 
-export const Axis = Static.makeEnum([
-	"LEFT_X",
-	"LEFT_Y",
-	"RIGHT_X",
-	"RIGHT_Y",
-]);
+export const Axis = Static.makeEnum(["LEFT_X", "LEFT_Y", "RIGHT_X", "RIGHT_Y"]);

package/src/ButtonLayout.mjs

@@ -3,41 +3,41 @@
 import { Static } from "./Static.mjs";
 
 export const ButtonLayout = {
-	reversed: Static.makeEnum([
-		"B",
-		"A",
-		"Y",
-		"X",
-		"L1",
-		"R1",
-		"L2",
-		"R2",
-		"SELECT",
-		"START",
-		"L3",
-		"R3",
-		"UP",
-		"DOWN",
-		"LEFT",
-		"RIGHT",
-	]),
+  reversed: Static.makeEnum([
+    "B",
+    "A",
+    "Y",
+    "X",
+    "L1",
+    "R1",
+    "L2",
+    "R2",
+    "SELECT",
+    "START",
+    "L3",
+    "R3",
+    "UP",
+    "DOWN",
+    "LEFT",
+    "RIGHT",
+  ]),
 
-	standard: Static.makeEnum([
-		"A",
-		"B",
-		"X",
-		"Y",
-		"L1",
-		"R1",
-		"L2",
-		"R2",
-		"SELECT",
-		"START",
-		"L3",
-		"R3",
-		"UP",
-		"DOWN",
-		"LEFT",
-		"RIGHT",
-	])
+  standard: Static.makeEnum([
+    "A",
+    "B",
+    "X",
+    "Y",
+    "L1",
+    "R1",
+    "L2",
+    "R2",
+    "SELECT",
+    "START",
+    "L3",
+    "R3",
+    "UP",
+    "DOWN",
+    "LEFT",
+    "RIGHT",
+  ]),
 };

package/src/ButtonLayoutMap.mjs

@@ -1,5 +1,5 @@
 "use static";
 
 export const ButtonLayoutMap = {
-	"8bitdo s": "reversed"
+  "8bitdo s": "reversed",
 };