core2d 2.10.3 → 2.11.1

package/README.md

@@ -1,54 +1,128 @@
 ![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,15 +1,17 @@
 {
 	"name": "core2d",
 	"type": "module",
-	"version": "2.10.3",
+	"version": "2.11.1",
 	"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"
+		"test": "npm run lint && for test in ./test/*.mjs; do node $test; done",
+		"prepare": "husky"
 	},
 	"repository": {
 		"type": "git",
@@ -45,6 +47,9 @@
 	"devDependencies": {
 		"@eslint/js": "^9.30.1",
 		"eslint": "^9.30.1",
-		"globals": "^16.3.0"
+		"eslint-config-prettier": "^10.1.5",
+		"globals": "^16.3.0",
+		"husky": "^9.1.7",
+		"prettier": "^3.6.2"
 	}
 }

package/src/ACL.mjs

@@ -3,7 +3,7 @@
 /**
  * Sets up the environment based on its runtime (browser or not).
  */
-if (typeof(global) != "undefined") {
+if (typeof global != "undefined") {
 	global.addEventListener = () => {};
 
 	global.document = {
@@ -43,7 +43,7 @@ if (typeof(global) != "undefined") {
 		},
 		getElementsByTagName: () => {
 			return [];
-		}
+		},
 	};
 
 	global.localStorage = {};
@@ -59,7 +59,7 @@ if (typeof(global) != "undefined") {
 		focus: () => {},
 		innerHeight: 600,
 		innerWidth: 800,
-		requestAnimationFrame: () => true
+		requestAnimationFrame: () => true,
 	};
 }
 

package/src/Animation.mjs

@@ -2,29 +2,58 @@
 
 import { Frame } from "./Frame.mjs";
 
+/**
+ * Represents an animation, which is a sequence of frames.
+ */
 export class Animation {
+	/**
+	 * 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)));
+		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;
@@ -32,10 +61,18 @@ export class Animation {
 		}
 	}
 
+	/**
+	 * 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;

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

@@ -39,5 +39,5 @@ export const ButtonLayout = {
 		"DOWN",
 		"LEFT",
 		"RIGHT",
-	])
+	]),
 };

package/src/ButtonLayoutMap.mjs

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

package/src/Controller.mjs

@@ -2,8 +2,18 @@
 
 import { Command } from "./Command.mjs";
 
+/**
+ * Represents a controller, which can be a gamepad or a keyboard.
+ */
 export class Controller {
+	/**
+	 * Creates a new Controller.
+	 */
 	constructor() {
+		/**
+		 * The tolerance for the command sequence.
+		 * @type {number}
+		 */
 		this.tolerance = 0;
 		this._active = {};
 		this._device = null;
@@ -12,9 +22,17 @@ export class Controller {
 		this._tick = 0;
 	}
 
+	/**
+	 * Checks if a sequence of commands was performed.
+	 * @param {Command[]} commands The sequence of commands.
+	 * @returns {boolean} Whether the sequence of commands was performed.
+	 */
 	didPerform(commands) {
 		for (let i = 1; i <= commands.length; ++i) {
-			if (this._sequence[this._sequence.length - i] != commands[commands.length - i]) {
+			if (
+				this._sequence[this._sequence.length - i] !=
+				commands[commands.length - i]
+			) {
 				return false;
 			}
 		}
@@ -23,18 +41,35 @@ export class Controller {
 		return true;
 	}
 
+	/**
+	 * Checks if a command is being held down.
+	 * @param {Command} command The command to check.
+	 * @returns {boolean} Whether the command is being held down.
+	 */
 	keyDown(command) {
 		return this._active[command];
 	}
 
+	/**
+	 * Checks if a command was just pushed.
+	 * @param {Command} command The command to check.
+	 * @returns {boolean} Whether the command was just pushed.
+	 */
 	keyPush(command) {
 		return this._active[command] && !this._hold[command];
 	}
 
+	/**
+	 * Sets the device of the controller.
+	 * @param {object} device The device.
+	 */
 	setDevice(device) {
 		this._device = device;
 	}
 
+	/**
+	 * Updates the controller.
+	 */
 	update() {
 		if (!this._device) {
 			return;

package/src/Core2D.mjs

@@ -1,5 +1,6 @@
 "use strict";
 
+import { Animation } from "./Animation.mjs";
 import { Engine } from "./Engine.mjs";
 import { Frame } from "./Frame.mjs";
 import { Point } from "./Point.mjs";
@@ -7,128 +8,276 @@ import { Rect } from "./Rect.mjs";
 import { Scene } from "./Scene.mjs";
 import { Sprite } from "./Sprite.mjs";
 
+/**
+ * The main class of the Core2D library.
+ */
 export class Core2D {
+	/**
+	 * Initializes the engine.
+	 * @param {Scene} scene The initial scene.
+	 */
 	static init(scene) {
 		Engine.init(scene);
 	}
 
+	/**
+	 * Whether the current frame is an even frame.
+	 * @type {boolean}
+	 */
 	static get everyOther() {
 		return Engine.everyOther;
 	}
 
+	/**
+	 * Adds a controller device.
+	 * @param {object} device The controller device.
+	 */
 	static addControllerDevice(device) {
 		Engine.addControllerDevice(device);
 	}
 
+	/**
+	 * Clears the canvas.
+	 */
 	static clear() {
 		Engine.clear();
 	}
 
+	/**
+	 * Colorizes an image.
+	 * @param {HTMLImageElement|HTMLCanvasElement} image The image to colorize.
+	 * @param {string} fillStyle The color to use.
+	 * @returns {HTMLCanvasElement} The colorized image.
+	 */
 	static colorize(image, fillStyle) {
 		return Engine.colorize(image, fillStyle);
 	}
 
+	/**
+	 * Fades out the current theme.
+	 */
 	static fadeOut() {
 		Engine.fadeOut();
 	}
 
+	/**
+	 * Flips an image vertically.
+	 * @param {string} id The ID of the image to flip.
+	 * @returns {HTMLCanvasElement} The flipped image.
+	 */
 	static flip(id) {
 		return Engine.flip(id);
 	}
 
+	/**
+	 * Gets a controller.
+	 * @param {number} id The ID of the controller.
+	 * @returns {Controller} The controller.
+	 */
 	static getController(id) {
 		return Engine.getController(id);
 	}
 
+	/**
+	 * Gets a pointer.
+	 * @param {number} id The ID of the pointer.
+	 * @returns {Pointer} The pointer.
+	 */
 	static getPointer(id) {
 		return Engine.getPointer(id);
 	}
 
+	/**
+	 * Gets an image.
+	 * @param {string} id The ID of the image.
+	 * @param {boolean} isMirror Whether to mirror the image.
+	 * @param {boolean} isFlip Whether to flip the image.
+	 * @returns {HTMLImageElement|HTMLCanvasElement} The image.
+	 */
 	static image(id, isMirror, isFlip) {
 		return Engine.image(id, isMirror, isFlip);
 	}
 
+	/**
+	 * Loads data from local storage.
+	 * @param {string} namespace The namespace to use.
+	 * @returns {object} The loaded data.
+	 */
 	static load(namespace) {
 		return Engine.load(namespace);
 	}
 
+	/**
+	 * Mirrors an image horizontally.
+	 * @param {string} id The ID of the image to mirror.
+	 * @returns {HTMLCanvasElement} The mirrored image.
+	 */
 	static mirror(id) {
 		return Engine.mirror(id);
 	}
 
+	/**
+	 * Mutes or unmutes the sound.
+	 */
 	static mute() {
 		Engine.mute();
 	}
 
+	/**
+	 * Paints a renderable object.
+	 * @param {object} renderable The renderable object.
+	 * @param {number} index The layer index.
+	 */
 	static paint(renderable, index) {
 		Engine.paint(renderable, index);
 	}
 
+	/**
+	 * Plays a sound.
+	 * @param {string} id The ID of the sound to play.
+	 * @param {number} volume The volume to play the sound at.
+	 */
 	static play(id, volume) {
 		Engine.play(id, volume);
 	}
 
+	/**
+	 * Plays a theme.
+	 * @param {string} name The name of the theme to play.
+	 */
 	static playTheme(name) {
 		Engine.playTheme(name);
 	}
 
+	/**
+	 * Generates a random number.
+	 * @param {number} max The maximum value.
+	 * @returns {number} The random number.
+	 */
 	static random(max) {
 		return Engine.random(max);
 	}
 
+	/**
+	 * Rotates an image.
+	 * @param {HTMLImageElement|HTMLCanvasElement} image The image to rotate.
+	 * @param {number} degrees The number of degrees to rotate the image.
+	 * @returns {HTMLCanvasElement} The rotated image.
+	 */
 	static rotate(image, degrees) {
 		return Engine.rotate(image, degrees);
 	}
 
+	/**
+	 * Saves data to local storage.
+	 * @param {object} data The data to save.
+	 * @param {string} namespace The namespace to use.
+	 */
 	static save(data, namespace) {
 		Engine.save(data, namespace);
 	}
 
+	/**
+	 * Sets whether to automatically scale the canvas.
+	 * @param {boolean} autoScale Whether to automatically scale the canvas.
+	 */
 	static setAutoScale(autoScale) {
 		Engine.setAutoScale(autoScale);
 	}
 
+	/**
+	 * Sets the frame time.
+	 * @param {number} frameTime The frame time in milliseconds.
+	 */
 	static setFrameTime(frameTime) {
 		Engine.setFrameTime(frameTime);
 	}
 
+	/**
+	 * Sets whether to use full screen.
+	 * @param {boolean} fullScreen Whether to use full screen.
+	 */
 	static setFullScreen(fullScreen) {
 		Engine.setFullScreen(fullScreen);
 	}
 
+	/**
+	 * Sets whether to keep the aspect ratio when scaling the canvas.
+	 * @param {boolean} keepAspect Whether to keep the aspect ratio.
+	 */
 	static setKeepAspect(keepAspect) {
 		Engine.setKeepAspect(keepAspect);
 	}
 
+	/**
+	 * Sets the name of the game.
+	 * @param {string} name The name of the game.
+	 */
 	static setName(name) {
 		Engine.setName(name);
 	}
 
+	/**
+	 * Stops the current theme.
+	 */
 	static stopTheme() {
 		Engine.stopTheme();
 	}
 
-	// factories
+	/**
+	 * Creates a new Animation.
+	 * @param {Frame[]} frames The frames of the animation.
+	 * @returns {Animation} The new animation.
+	 */
 	static animation(frames) {
 		return new Animation(frames);
 	}
 
+	/**
+	 * Creates a new Frame.
+	 * @param {HTMLImageElement|HTMLCanvasElement} image The image of the frame.
+	 * @param {number} duration The duration of the frame in ticks.
+	 * @returns {Frame} The new frame.
+	 */
 	static frame(image, duration) {
 		return new Frame(image, duration);
 	}
 
+	/**
+	 * Creates a new Point.
+	 * @param {number} x The x-coordinate of the point.
+	 * @param {number} y The y-coordinate of the point.
+	 * @returns {Point} The new point.
+	 */
 	static point(x, y) {
 		return new Point(x, y);
 	}
 
+	/**
+	 * Creates a new Rect.
+	 * @param {number} x The x-coordinate of the rectangle.
+	 * @param {number} y The y-coordinate of the rectangle.
+	 * @param {number} width The width of the rectangle.
+	 * @param {number} height The height of the rectangle.
+	 * @returns {Rect} The new rectangle.
+	 */
 	static rect(x, y, width, height) {
 		return new Rect(x, y, width, height);
 	}
 
+	/**
+	 * Creates a new Scene.
+	 * @returns {Scene} The new scene.
+	 */
 	static scene() {
 		return new Scene();
 	}
 
+	/**
+	 * Creates a new Sprite.
+	 * @param {Scene} scene The scene of the sprite.
+	 * @returns {Sprite} The new sprite.
+	 */
 	static sprite(scene) {
 		return new Sprite(scene);
 	}