@starktma/minecraft-utils 1.1.0 → 1.2.1

package/README.md

@@ -0,0 +1,77 @@
+# Database Management in Minecraft: TypeScript Edition
+
+PropertyDatabase is a TypeScript-based database management system designed for use within Minecraft. The system consists of two main classes: `DatabaseManager` and `SimpleDatabase`, which handle JSON database operations in the Minecraft world.
+
+## Features
+
+- **Entity & World Targeting**: Ability to target either an entity or the Minecraft world for storing data.
+- **JSON Database Operations**: Supports basic CRUD (Create, Read, Update, Delete) operations for JSON databases.
+- **Custom Object Management**: Facilitates storing and managing custom objects with unique IDs.
+
+## Installation
+
+1. Ensure you have the Minecraft server set up with the appropriate scripting API support.
+2. Install the PropertyDatabase module `@starktma/minecraft-utils` using your preferred method (e.g., npm, yarn).
+3. Place the PropertyDatabase module in your server's script directory or in the assets/javascript directory if you're using Anvil.
+
+## Usage
+
+### DatabaseManager Class
+
+Handles JSON databases in Minecraft's world properties. Can target an entity or the world itself.
+
+#### Methods:
+
+- `hasJSONDatabase(databaseName: string)`: Checks if a database exists.
+- `addJSONDatabase(databaseName: string, database: object)`: Adds a new database.
+- `removeJSONDatabase(databaseName: string)`: Removes a database.
+- `getJSONDatabase(databaseName: string)`: Retrieves a database.
+
+### SimpleDatabase Class
+
+A base class for managing databases of custom objects.
+
+#### Methods:
+
+- `addObject(object: SimpleObject)`: Adds a new object to the database.
+- `updateObject(object: SimpleObject)`: Updates an existing object.
+- `hasObject(id: string)`: Checks if an object exists.
+- `getObject(id: string)`: Retrieves an object by ID.
+- `removeObject(id: string)`: Removes an object.
+- `getAllObjects()`: Retrieves all objects.
+- `eraseAllObjects()`: Clears the database.
+- `forEach(callback: Function)`: Iterates over objects.
+
+### SimpleObject Interface
+
+A basic interface for objects managed by `SimpleDatabase`. Must include an `id` property.
+
+## NOTE
+
+The `DatabaseManager` class is designed to handle JSON databases in Minecraft's world properties and cannot be used directly. Its main job is to convert your database to string formats that can be stored on dynamic properties and back.
+
+The `DatabaseManager` class is responsible for deconstructing and reconstructing the database from JSON strings to work around the dynamic property size limits in Minecraft [`32767`].
+
+The `SimpleDatabase` class uses the `DatabaseManager` to manage custom objects. It provides methods to add, update, retrieve, and remove objects, as well as to iterate over all objects in the database.
+
+The `SimpleDatabase` is intended to be inherited by custom object classes. It requires an `id` property to uniquely identify each object and can be extended with additional properties as needed.
+
+The `SimpleObject` interface defines the structure of objects that can be managed by `SimpleDatabase`. It includes an `id` property, which is essential for identifying objects within the database, and can be extended with additional properties to structure your own database objects.
+
+## Examples
+
+### Creating a Custom Database
+
+```typescript
+class MyDatabase extends SimpleDatabase {
+	constructor() {
+		super("my_database");
+	}
+
+	addObject(object: MyObject) {
+		super.addObject(object);
+	}
+
+	// Additional custom methods...
+}
+```

package/dist/database/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/database/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS,sBAAsB,CAAC"}

package/dist/database/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/database/database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAgB,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AA0I5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,cAAc,CAAC,CAAC,SAAS,YAAY;IACjD,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,OAAO,CAAM;IAErB,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC;IAE/B;;;;OAIG;IACH,SAAS,aAAa,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS;IAYvE;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAIpB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAIjB;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI;IAK1B;;;;OAIG;IACH,YAAY,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI;IAO7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAIpC;;;OAGG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAK9B;;;OAGG;IACH,aAAa,IAAI,CAAC,EAAE;IAIpB;;OAEG;IACH,eAAe,IAAI,IAAI;IAKvB;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;CAGtE"}

package/dist/database/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/database/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC"}

package/dist/database/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/database/interfaces.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAC;CACX"}

package/dist/math/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/math/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CAIhF;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAmBlG;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG9C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,SAAS,GAAE,MAAY,GAAG,OAAO,CAEvF;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAExE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/math/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CAIhF;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,GAAE,OAAe,GAAG,GAAG,GAAG,IAAI,CAsB9E;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG9C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,SAAS,GAAE,MAAY,GAAG,OAAO,CAEvF;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAExE"}

package/dist/minecraft/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/minecraft/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAS,MAAM,mBAAmB,CAAC;AAG1E,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,KAAK,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,WA4BnG;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,OAAO,EAAE,GAAG,QAO3E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAEtD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/minecraft/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,MAAM,EACN,MAAM,EACN,KAAK,EACL,OAAO,EAEP,iBAAiB,EACjB,OAAO,EAOP,MAAM,mBAAmB,CAAC;AAG3B,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,KAAK,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,WA4BnG;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,OAAO,EAAE,GAAG,QAO3E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,GAAE,MAAU,GAAG,OAAO,CAUjG;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAQ1F;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAapF;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAwC1D;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,GAAE,OAAe,GAAG,MAAM,CAuD3F"}

package/dist/player-event/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/player-event/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,MAAM,EAEN,yBAAyB,EACzB,wBAAwB,EAGxB,SAAS,EACT,MAAM,mBAAmB,CAAC;AAE3B,KAAK,aAAa,CAAC,CAAC,GAAG,YAAY,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,CAAC;AAC3D,KAAK,eAAe,GAAG,kBAAkB,GAAG,MAAM,CAAC;AAEnD,aAAK,kBAAkB;IACtB,IAAI,SAAS;IACb,SAAS,cAAc;IACvB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,UAAU,eAAe;IACzB,SAAS,cAAc;IACvB,QAAQ,aAAa;CACrB;AAED,cAAM,UAAU,CAAC,CAAC,GAAG,YAAY;IAChC,OAAO,CAAC,SAAS,CAAkD;;IASnE,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC;IAOxC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC;IAQpD,GAAG,CAAC,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC;CASrD;AAED,cAAM,YAAY;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,SAAK;IACd,QAAQ,SAAK;IACb,SAAS,SAAK;gBAEF,MAAM,EAAE,MAAM;IAK1B,IAAI,mBAAmB,IACoD,yBAAyB,CACnG;IAED,IAAI,kBAAkB,IACoD,wBAAwB,CACjG;IAED,eAAe,IAAI,SAAS,GAAG,SAAS;IAIxC,KAAK;IAML,IAAI;CAmBJ;AAED,cAAM,aAAa,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY;IACxD,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,MAAM,CAAoC;IAElD,SAAS;IAwBT,SAAS,CAAC,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC;IAIhD,SAAS,CAAC,EAAE,EAAE,MAAM;IAIpB,YAAY,CAAC,EAAE,EAAE,MAAM;IAIvB,SAAS,CAAC,MAAM,EAAE,MAAM;IAKxB,cAAc,CAAC,OAAO,EAAE,MAAM;;;IAM9B,SAAS,CAAC,OAAO,EAAE,MAAM;IAIzB,IAAI;CAWJ;AAED,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,aAAa,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@starktma/minecraft-utils",
-	"version": "1.1.0",
+	"version": "1.2.1",
 	"description": "",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -23,6 +23,14 @@
 		"./minecraft": {
 			"import": "./dist/minecraft/index.js",
 			"types": "./dist/minecraft/index.d.ts"
+		},
+		"./database": {
+			"import": "./dist/database/index.js",
+			"types": "./dist/database/index.d.ts"
+		},
+		"./player-events": {
+			"import": "./dist/player-event/index.js",
+			"types": "./dist/player-event/index.d.ts"
 		}
 	},
 	"publishConfig": {

package/src/database/constants.ts

@@ -0,0 +1 @@
+export const NAMESPACE = 'inventory-manager';

package/src/database/database.ts

@@ -0,0 +1,271 @@
+import { Entity, world, World } from "@minecraft/server";
+import { SimpleObject } from "./interfaces";
+
+//@ts-ignore
+import { NAMESPACE } from "./constants";
+
+/**
+ * DatabaseManager is a class that manages databases stored in Minecraft's world properties.
+ * Currently only supports JSON databases.
+ */
+class DatabaseManager {
+	private static readonly DYNAMIC_PROP_MAX_LENGTH = 32767;
+	private static readonly CHUNK_KEY = "__SPLIT__";
+
+	private target: Entity | World;
+
+	constructor(target: Entity | undefined) {
+		if (target instanceof Entity) {
+			this.target = target;
+		} else {
+			this.target = world;
+		}
+	}
+
+	/**
+	 * Checks if a JSON database with the given name exists.
+	 * @param databaseName The name of the database.
+	 * @returns True if the database exists, false otherwise.
+	 */
+	hasJSONDatabase(databaseName: string) {
+		return this.target.getDynamicProperty(NAMESPACE + ":" + databaseName) !== undefined;
+	}
+
+	/**
+	 * Adds a new JSON database with the given name and data.
+	 * @param databaseName The name of the database.
+	 * @param database The data to be stored in the database.
+	 */
+	addJSONDatabase(databaseName: string, database: object) {
+		const propertyName = `${NAMESPACE}:${databaseName}`;
+		const jsonString = JSON.stringify(database);
+		const existingProp = this.target.getDynamicProperty(propertyName) as string | undefined;
+		let existingChunks = 0;
+
+		if (existingProp) {
+			try {
+				const propObj = JSON.parse(existingProp);
+				if (propObj && typeof propObj === "object" && DatabaseManager.CHUNK_KEY in propObj) {
+					existingChunks = propObj[DatabaseManager.CHUNK_KEY];
+				}
+			} catch {}
+		}
+		if (jsonString.length <= DatabaseManager.DYNAMIC_PROP_MAX_LENGTH || jsonString.length === 0) {
+			if (existingChunks > 0) {
+				for (let i = 0; i < existingChunks; i++) {
+					const partName = `${propertyName}_${i}`;
+					this.target.setDynamicProperty(partName, undefined);
+				}
+			}
+			this.target.setDynamicProperty(propertyName, jsonString);
+		} else {
+			const chunkSize = DatabaseManager.DYNAMIC_PROP_MAX_LENGTH;
+			const chunkCount = Math.ceil(jsonString.length / chunkSize);
+			if (existingChunks > 0) {
+				for (let i = 0; i < existingChunks; i++) {
+					const oldPartName = `${propertyName}_${i}`;
+					this.target.setDynamicProperty(oldPartName, undefined);
+				}
+			}
+			for (let i = 0; i < chunkCount; i++) {
+				const start = i * chunkSize;
+				const end = start + chunkSize;
+				const chunk = jsonString.slice(start, end);
+				const partName = `${propertyName}_${i}`;
+				this.target.setDynamicProperty(partName, chunk);
+			}
+			const meta = { [DatabaseManager.CHUNK_KEY]: chunkCount };
+			this.target.setDynamicProperty(propertyName, JSON.stringify(meta));
+		}
+	}
+
+	/**
+	 * Removes a JSON database with the given name.
+	 * @param databaseName The name of the database.
+	 */
+	removeJSONDatabase(databaseName: string) {
+		const propertyName = `${NAMESPACE}:${databaseName}`;
+		const propString = this.target.getDynamicProperty(propertyName) as string | undefined;
+		if (propString !== undefined) {
+			try {
+				const propObj = JSON.parse(propString);
+				if (propObj && typeof propObj === "object" && DatabaseManager.CHUNK_KEY in propObj) {
+					const chunkCount = propObj[DatabaseManager.CHUNK_KEY];
+					for (let i = 0; i < chunkCount; i++) {
+						const partName = `${propertyName}_${i}`;
+						this.target.setDynamicProperty(partName, undefined);
+					}
+				}
+			} catch {}
+			this.target.setDynamicProperty(propertyName, undefined);
+		}
+	}
+
+	/**
+	 * Retrieves a JSON database with the given name.
+	 * @param databaseName The name of the database.
+	 * @returns The data stored in the database.
+	 * @throws An error if the database does not exist.
+	 */
+	getJSONDatabase(databaseName: string) {
+		const propertyName = `${NAMESPACE}:${databaseName}`;
+		const propString = this.target.getDynamicProperty(propertyName) as string | undefined;
+		if (propString === undefined) {
+			throw new Error("Database does not exist");
+		}
+		try {
+			const propObj = JSON.parse(propString);
+			if (propObj && typeof propObj === "object" && DatabaseManager.CHUNK_KEY in propObj) {
+				const chunkCount: number = propObj[DatabaseManager.CHUNK_KEY];
+				let combined = "";
+				for (let i = 0; i < chunkCount; i++) {
+					const partName = `${propertyName}_${i}`;
+					const part = this.target.getDynamicProperty(partName) as string | undefined;
+					if (typeof part === "string") {
+						combined += part;
+					} else {
+						combined += "";
+					}
+				}
+				return JSON.parse(combined);
+			} else {
+				return JSON.parse(propString);
+			}
+		} catch {
+			throw new Error("Failed to parse database JSON");
+		}
+	}
+}
+
+/**
+ * SimpleDatabase is a base class for databases that store custom objects with an id property.
+ * It provides methods for adding, updating, removing and retrieving objects from the database.
+ * A singleton pattern is used to ensure that only one instance of the database exists.
+ *
+ * @example
+ * class MyDatabase extends SimpleDatabase<PlayerObject> {
+ * 	protected static instance: MyDatabase;
+ * 	constructor() {
+ * 		super("myDatabase", undefined);
+ * 	}
+ *
+ * 	static getInstance(): MyDatabase {
+ * 		if (!MyDatabase.instance) {
+ * 			MyDatabase.instance = new MyDatabase();
+ * 		}
+ * 		return MyDatabase.instance;
+ * 	}
+ */
+export class SimpleDatabase<T extends SimpleObject> {
+	private mainDB: DatabaseManager;
+	private localDB: T[];
+
+	protected databaseName: string;
+
+	/**
+	 * The constructor initializes the local database and syncs it with the main database.
+	 * @param databaseName The name of the database.
+	 * @param target The target entity to store the database in. If undefined, the database is stored in the world.
+	 */
+	protected constructor(databaseName: string, target?: Entity | undefined) {
+		this.mainDB = new DatabaseManager(target);
+		this.databaseName = databaseName;
+
+		if (this.mainDB.hasJSONDatabase(this.databaseName)) {
+			this.localDB = this.getMainDB();
+		} else {
+			this.localDB = [];
+			this.updateMainDB();
+		}
+	}
+
+	/**
+	 * Updates the main database with the local database.
+	 * This method is called automatically when an object is added, updated or removed.
+	 * @private
+	 */
+	private updateMainDB() {
+		this.mainDB.addJSONDatabase(this.databaseName, this.localDB);
+	}
+
+	/**
+	 * Retrieves the main database.
+	 * @private
+	 * @returns The main database.
+	 */
+	private getMainDB() {
+		return this.mainDB.getJSONDatabase(this.databaseName);
+	}
+
+	/**
+	 * Adds an object to the local database and updates the main database.
+	 * @param object The object to be added.
+	 */
+	addObject(object: T): void {
+		this.localDB.push(object);
+		this.updateMainDB();
+	}
+
+	/**
+	 * Updates an object in the local database and the main database.
+	 * If the object does not exist, it is added.
+	 * @param object The object to be updated.
+	 */
+	updateObject(object: T): void {
+		if (this.hasObject(object.id)) {
+			this.removeObject(object.id);
+		}
+		this.addObject(object);
+	}
+
+	/**
+	 * Checks if an object with the given id exists in the local database.
+	 * @param id The id of the object.
+	 * @returns True if the object exists, false otherwise.
+	 */
+	hasObject(id: string): boolean {
+		return this.localDB.map((object) => object.id).includes(id);
+	}
+
+	/**
+	 * Retrieves an object with the given id from the local database.
+	 * @param id The id of the object.
+	 * @returns The object if it exists, undefined otherwise.
+	 */
+	getObject(id: string): T | undefined {
+		return this.localDB.filter((object) => object.id === id)[0];
+	}
+
+	/**
+	 * Removes an object with the given id from the local database and updates the main database.
+	 * @param id The id of the object.
+	 */
+	removeObject(id: string): void {
+		this.localDB = this.localDB.filter((object) => object.id !== id);
+		this.updateMainDB();
+	}
+
+	/**
+	 * Retrieves all objects from the local database.
+	 * @returns An array of all objects in the local database.
+	 */
+	getAllObjects(): T[] {
+		return this.localDB;
+	}
+
+	/**
+	 * Removes all objects from the local database and updates the main database.
+	 */
+	eraseAllObjects(): void {
+		this.localDB = [];
+		this.updateMainDB();
+	}
+
+	/**
+	 * Iterates over all objects in the local database.
+	 * @param callback The function to be called for each object.
+	 */
+	forEach(callback: (object: SimpleObject, index: number) => void): void {
+		this.localDB.forEach((object, index) => callback(object, index));
+	}
+}

package/src/database/index.ts

@@ -0,0 +1,4 @@
+import { SimpleDatabase } from "./database";
+import { SimpleObject } from "./interfaces";
+
+export { SimpleDatabase, SimpleObject };

package/src/database/interfaces.ts

@@ -0,0 +1,6 @@
+/**
+ * SimpleObject is an interface for objects with an id property.
+ */
+export interface SimpleObject {
+	id: string;
+}

package/src/math/index.ts

@@ -1,4 +1,4 @@
-import { Vector3 } from "@minecraft/server";
+import { RGB, RGBA, Vector3 } from "@minecraft/server";
 
 /**
  * Converts an angle in degrees to radians.
@@ -18,7 +18,7 @@ export function toRadians(degrees: number): number {
  */
 export function calculateDistance(position1: Vector3, position2: Vector3): number {
 	return Math.sqrt(
-		Math.sqrt(Math.pow(position1.x - position2.x, 2) + Math.pow(position1.y - position2.y, 2)) + Math.pow(position1.z - position2.z, 2)
+		Math.pow(position1.x - position2.x, 2) + Math.pow(position1.y - position2.y, 2) + Math.pow(position1.z - position2.z, 2)
 	);
 }
 
@@ -39,7 +39,7 @@ export function toDegrees(radians: number): number {
  * @returns An object containing the red, green, blue, and alpha components as numbers between 0 and 1.
  * @throws Error if the hex string is invalid.
  */
-export function hexToRgba(hex: string): { red: number; green: number; blue: number; alpha: number } {
+export function hexToRgba(hex: string, stripAlpha: boolean = false): RGB | RGBA {
 	if (!/^#([a-fA-F0-9]{4}|[a-fA-F0-9]{8}|[a-fA-F0-9]{6}|[a-fA-F0-9]{3})$/.test(hex)) {
 		throw new Error("Invalid hex color");
 	}
@@ -57,6 +57,9 @@ export function hexToRgba(hex: string): { red: number; green: number; blue: numb
 	const blue = parseInt(normalized.substring(4, 6), 16) / 255;
 	const alpha = (normalized.length === 8 ? parseInt(normalized.substring(6, 8), 16) : 255) / 255;
 
+	if (stripAlpha) {
+		return { red, green, blue };
+	}
 	return { red, green, blue, alpha };
 }
 

package/src/minecraft/index.ts

@@ -1,5 +1,19 @@
-import { Player, Entity, Block, Vector3, world } from "@minecraft/server";
-import { calculateDistance, toUnsigned } from "../math";
+import {
+	Player,
+	Entity,
+	Block,
+	Vector3,
+	world,
+	StructureRotation,
+	Vector2,
+	BlockInventoryComponent,
+	BlockPermutation,
+	EntityEquippableComponent,
+	EntityInventoryComponent,
+	EquipmentSlot,
+	ItemStack,
+} from "@minecraft/server";
+import { calculateDistance, toRadians, toSigned, toUnsigned } from "../math";
 
 export function getBlocksInASphere(centerBlock: Block | Entity, radius: number, innerRadius?: number) {
 	if (centerBlock) {
@@ -37,7 +51,7 @@ export function displayActionbar(player: Player | undefined, ...message: any) {
 	let selector;
 	target = player && player.isValid ? player : world.getDimension("overworld");
 	selector = player ? `@s` : `@a`;
-	target.runCommand(`title @s actionbar ${JSON.stringify(text)}`);
+	target.runCommand(`title ${selector} actionbar ${JSON.stringify(text)}`);
 }
 
 /**
@@ -46,9 +60,11 @@ export function displayActionbar(player: Player | undefined, ...message: any) {
  * @param angle - The angle in degrees to be snapped.
  * @returns The snapped unsigned angle in degrees.
  */
-export function snapRotationToGrid(angle: number): number {
+export function snapYawToGrid(angle: number): number {
 	const gridSize = 90;
-	return Math.round(toUnsigned(angle) / gridSize) * gridSize;
+	// Round to nearest grid step, then normalize into [0, 360)
+	const snapped = Math.round(toUnsigned(angle) / gridSize) * gridSize;
+	return ((snapped % 360) + 360) % 360;
 }
 
 /**
@@ -57,6 +73,138 @@ export function snapRotationToGrid(angle: number): number {
  * @param v - The vector to be snapped.
  * @returns A new vector with each component rounded to the nearest integer.
  */
-export function snapLocationToGrid(v: Vector3): Vector3 {
-	return { x: Math.round(v.x), y: Math.floor(v.y), z: Math.round(v.z) };
+export function snapLocationToGrid(location: Vector3, yaw: Vector2, gridSize: number = 1): Vector3 {
+	const snappedYaw = snapYawToGrid(yaw.y);
+	const dx = Math.round(Math.sin(snappedYaw));
+	const dz = Math.round(Math.cos(snappedYaw));
+
+	return {
+		x: Math.floor(location.x / gridSize) * gridSize,
+		y: Math.floor(location.y / gridSize) * gridSize,
+		z: Math.floor(location.z / gridSize) * gridSize,
+	};
+}
+
+export function getStructureRotationEnum(angle: number, offset?: number): StructureRotation {
+	const diff = snapYawToGrid(toUnsigned(angle - (offset ?? 0)));
+	console.log(diff);
+
+	if (Math.abs(diff - 90) < Number.EPSILON) return StructureRotation.Rotate90;
+	if (Math.abs(diff - 180) < Number.EPSILON) return StructureRotation.Rotate180;
+	if (Math.abs(diff - 270) < Number.EPSILON) return StructureRotation.Rotate270;
+	return StructureRotation.None;
+}
+
+export function getRelativeMovementDirection(player: Player, round: boolean): Vector3 {
+	const playerYaw = toRadians(player.getRotation().y);
+	const { sin, cos } = { sin: Math.sin(playerYaw), cos: Math.cos(playerYaw) };
+
+	const playerMovement = player.inputInfo.getMovementVector();
+
+	const dx = -sin * playerMovement.y + cos * playerMovement.x;
+	const dz = cos * playerMovement.y + sin * playerMovement.x;
+
+	if (round) {
+		return { x: Math.round(dx), y: 0, z: Math.round(dz) };
+	}
+	return { x: dx, y: 0, z: dz };
+}
+
+export function restoreInventory(entity: Entity, id: string) {
+	const blockLocation = entity.dimension.getBlockFromRay(entity.location, { x: 0, y: -1, z: 0 })!.block.location;
+	blockLocation.y++;
+	const blockLocation2 = { ...blockLocation, y: blockLocation.y + 1 };
+
+	const savedStructure = world.structureManager.get(id);
+	if (savedStructure) world.structureManager.place(savedStructure, entity.dimension, blockLocation);
+	world.structureManager.delete(id);
+
+	const block = entity.dimension.getBlock(blockLocation)!;
+	const block2 = entity.dimension.getBlock(blockLocation2)!;
+
+	const equipment = entity.getComponent(EntityEquippableComponent.componentId) as EntityEquippableComponent;
+	const invComponent = entity.getComponent(EntityInventoryComponent.componentId) as EntityInventoryComponent;
+	const blockInventory = block.getComponent(BlockInventoryComponent.componentId) as BlockInventoryComponent;
+	const blockInventory2 = block2.getComponent(BlockInventoryComponent.componentId) as BlockInventoryComponent;
+
+	const slots = Object.values(EquipmentSlot);
+	slots.forEach((slot) => {
+		equipment.setEquipment(slot, blockInventory.container!.getItem(slots.indexOf(slot))!);
+	});
+
+	Array(41)
+		.fill(0)
+		.forEach((_, i) => {
+			if (i < invComponent.container!.size) {
+				if (i < 9) {
+					// First chest: starts filling from slot 5
+					blockInventory.container!.moveItem(i + 5, i, invComponent.container!);
+				} else {
+					// Second chest: adjusts index for 0-26 range starting from slot 0
+					blockInventory2.container!.moveItem(i - 9, i, invComponent.container!);
+				}
+			}
+		});
+
+	blockInventory.container!.clearAll();
+	blockInventory2.container!.clearAll();
+	block.setPermutation(BlockPermutation.resolve("minecraft:air"));
+	block2.setPermutation(BlockPermutation.resolve("minecraft:air"));
+}
+
+export function saveInventory(entity: Entity, id: string, clearAll: boolean = false): number {
+	const blockLocation = entity.dimension.getTopmostBlock(entity.location)!.location;
+	blockLocation.y++;
+	const blockLocation2 = { ...blockLocation, y: blockLocation.y + 1 };
+
+	const block = entity.dimension.getBlock(blockLocation)!;
+	const block2 = entity.dimension.getBlock(blockLocation2)!;
+
+	block.setPermutation(BlockPermutation.resolve("minecraft:chest"));
+	block2.setPermutation(BlockPermutation.resolve("minecraft:chest"));
+
+	const equipment = entity.getComponent(EntityEquippableComponent.componentId) as EntityEquippableComponent;
+	const invComponent = entity.getComponent(EntityInventoryComponent.componentId) as EntityInventoryComponent;
+	const blockInventory = block.getComponent(BlockInventoryComponent.componentId) as BlockInventoryComponent;
+	const blockInventory2 = block2.getComponent(BlockInventoryComponent.componentId) as BlockInventoryComponent;
+
+	const itemCount = invComponent.container!.size - invComponent.container!.emptySlotsCount;
+
+	Object.values(EquipmentSlot).forEach((slot) => {
+		if (clearAll) {
+			equipment.setEquipment(slot);
+		}
+		blockInventory.container!.addItem(equipment.getEquipment(slot) ?? new ItemStack("minecraft:air", 1));
+	});
+
+	if (clearAll) {
+	}
+
+	Array(41)
+		.fill(0)
+		.forEach((_, i) => {
+			if (i < invComponent.container!.size) {
+				if (i < 9) {
+					// First chest: starts filling from slot 5
+					invComponent.container!.moveItem(i, 5 + i, blockInventory.container!);
+				} else {
+					// Second chest: adjusts index for 0-26 range starting from slot 0
+					invComponent.container!.moveItem(i, i - 9, blockInventory2.container!);
+				}
+				if (clearAll) {
+					invComponent.container!.setItem(i);
+				}
+			}
+		});
+
+	world.structureManager.delete(id);
+	world.structureManager.createFromWorld(id, entity.dimension, blockLocation, blockLocation2);
+
+	blockInventory.container!.clearAll();
+	blockInventory2.container!.clearAll();
+
+	block.setPermutation(BlockPermutation.resolve("minecraft:air"));
+	block2.setPermutation(BlockPermutation.resolve("minecraft:air"));
+
+	return itemCount;
 }

package/src/player-event/index.ts

@@ -0,0 +1,184 @@
+import {
+	system,
+	world,
+	Player,
+	ButtonState,
+	EntityEquippableComponent,
+	EntityInventoryComponent,
+	EquipmentSlot,
+	InputButton,
+	ItemStack,
+} from "@minecraft/server";
+
+type EventCallback<T = CustomPlayer> = (player: T) => void;
+type PlayerEventType = CustomPlayerEvents | string;
+
+enum CustomPlayerEvents {
+	Tick = "tick",
+	JumpStart = "jumpStart",
+	JumpHold = "jumpHold",
+	JumpEnd = "jumpEnd",
+	SneakStart = "sneakStart",
+	SneakHold = "sneakHold",
+	SneakEnd = "sneakEnd",
+}
+
+class EventGroup<T = CustomPlayer> {
+	private callbacks = new Map<PlayerEventType, EventCallback<T>[]>();
+
+	constructor() {
+		// Initialize with core events
+		Object.values(CustomPlayerEvents).forEach((event) => {
+			this.callbacks.set(event, []);
+		});
+	}
+
+	private run(callbacks: EventCallback<T>[], player: T) {
+		for (const cb of callbacks) cb(player);
+	}
+
+	trigger(type: PlayerEventType, player: T) {
+		const callbacks = this.callbacks.get(type);
+		if (callbacks) {
+			this.run(callbacks, player);
+		}
+	}
+
+	on(type: PlayerEventType, callback: EventCallback<T>) {
+		if (!this.callbacks.has(type)) {
+			this.callbacks.set(type, []);
+		}
+		this.callbacks.get(type)!.push(callback);
+	}
+
+	// Simple way to remove listeners
+	off(type: PlayerEventType, callback: EventCallback<T>) {
+		const callbacks = this.callbacks.get(type);
+		if (callbacks) {
+			const index = callbacks.indexOf(callback);
+			if (index > -1) {
+				callbacks.splice(index, 1);
+			}
+		}
+	}
+}
+
+class CustomPlayer {
+	player: Player;
+	stateTick = 0;
+	JumpTick = 0;
+	SneakTick = 0;
+
+	constructor(player: Player) {
+		this.player = player;
+		this.reset();
+	}
+
+	get equippableComponent() {
+		return this.player.getComponent(EntityEquippableComponent.componentId) as EntityEquippableComponent;
+	}
+
+	get inventoryComponent() {
+		return this.player.getComponent(EntityInventoryComponent.componentId) as EntityInventoryComponent;
+	}
+
+	getEquippedItem(): ItemStack | undefined {
+		return this.equippableComponent.getEquipment(EquipmentSlot.Mainhand);
+	}
+
+	reset() {
+		this.stateTick = 0;
+		this.JumpTick = 0;
+		this.player.camera.clear();
+	}
+
+	tick() {
+		this.stateTick++;
+		
+		if (this.player.inputInfo.getButtonState(InputButton.Jump) === ButtonState.Pressed) {
+			this.JumpTick++;
+		} else if (this.JumpTick > 0) {
+			this.JumpTick = -1;
+		} else {
+			this.JumpTick = 0;
+		}
+
+		if (this.player.inputInfo.getButtonState(InputButton.Sneak) === ButtonState.Pressed) {
+			this.SneakTick++;
+		} else if (this.SneakTick > 0) {
+			this.SneakTick = -1;
+		} else {
+			this.SneakTick = 0;
+		}
+	}
+}
+
+class PlayerManager<T extends CustomPlayer = CustomPlayer> {
+	private players = new Map<string, T>();
+	private events = new Map<string, EventGroup<T>>();
+
+	protected constructor() {
+		world.afterEvents.playerSpawn.subscribe(({ player, initialSpawn }) => {
+			const id = player.id;
+			const existing = this.getPlayer(id);
+
+			if (initialSpawn || !existing) {
+				this.addPlayer(player);
+			} else {
+				existing.reset();
+			}
+		});
+
+		world.afterEvents.playerLeave.subscribe(({ playerId }) => {
+			this.removePlayer(playerId);
+		});
+
+		world.afterEvents.worldLoad.subscribe(() => {
+			world.getAllPlayers().forEach((player) => this.addPlayer(player));
+			system.runInterval(() => {
+				this.tick();
+			});
+		});
+	}
+
+	protected createPlayerManager(player: Player): T {
+		return new CustomPlayer(player) as T;
+	}
+
+	getPlayer(id: string) {
+		return this.players.get(id);
+	}
+
+	removePlayer(id: string) {
+		this.players.delete(id);
+	}
+
+	addPlayer(player: Player) {
+		if (this.players.has(player.id)) return;
+		this.players.set(player.id, this.createPlayerManager(player));
+	}
+
+	registerEvents(eventID: string) {
+		const eventGroup = new EventGroup<T>();
+		this.events.set(eventID, eventGroup);
+		return { event: eventGroup };
+	}
+
+	getEvents(eventID: string) {
+		return this.events.get(eventID);
+	}
+
+	tick() {
+		for (const manager of this.players.values()) {
+			const { player } = manager;
+			if (!player.isValid) continue;
+
+			manager.tick();
+			this.events.forEach((eventGroup) => {
+				eventGroup.trigger(CustomPlayerEvents.Tick, manager);
+			});
+		}
+	}
+}
+
+export { CustomPlayerEvents, CustomPlayer, PlayerManager };