Add Gameplay-Utilities library with EventThenable (#97)

* Event promise and thenable added to new gameplay utility library

Some changes to the readme, advances to the tests

Tests and linting done

Change files

Removing change log files, not sure if correct or not

Removed last references to math

* PR Requests, removing thenable, event promise becomes private, next event only allows minecraft signals

* Working promise

* Not sure what is wrong

* Something works

* Tests passing

* Fix build

* PR requests

Author: optic5471ms

change/@minecraft-gameplay-utilities-8aec48fc-0353-4ce9-81d8-835ede162757.json

@@ -0,0 +1,7 @@
+{
+  "type": "major",
+  "comment": "EventPromise and nextEvent() added to gameplay-utilities",
+  "packageName": "@minecraft/gameplay-utilities",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

libraries/gameplay-utilities/README.md

@@ -0,0 +1,36 @@
+# Minecraft Gameplay Utilities
+
+A set of utilities and functions for common gameplay operations. Major pieces are covered below.
+
+## nextEvent() and EventPromise
+
+`nextEvent()` is a function which takes a Minecraft event signal and wraps a promise around the next event being raised. The function returns an `EventPromise` object which is a promise type. When the event is raised, the promise will resolve with the event data, and unsubscribe from the event's signal. The `EventPromise` type also adds a `cancel()` function which will unsubscribe from the event's signal, and fulfill the promise with `undefined`.
+
+### Can be awaited to receive the event
+
+```ts
+const event = await nextEvent(world.afterEvents.buttonPush);
+```
+
+### Can be used like a promise
+
+```ts
+await nextEvent(world.afterEvents.leverAction).then(
+    (event) => {
+        // do something with the event
+    }).finally(() => {
+        // something else to do
+    });
+```
+
+### Optionally provide filters for the signal and use helper function
+
+```ts
+const creeperDeathEvent = await nextEvent(world.afterEvents.entityDie, { entityTypes: ['minecraft:creeper'] });
+```
+
+## How to use @minecraft/gameplay-utilities in your project
+
+@minecraft/gameplay-utilities is published to NPM and follows standard semver semantics. To use it in your project,
+
+- Download `@minecraft/gameplay-utilities` from NPM by doing `npm install @minecraft/gameplay-utilities` within your scripts pack. By using `@minecraft/gameplay-utilities`, you will need to do some sort of bundling to merge the library into your packs code. We recommend using [esbuild](https://esbuild.github.io/getting-started/#your-first-bundle) for simplicity.

libraries/gameplay-utilities/__mocks__/minecraft-server.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import type { EntityEventOptions, WeatherChangeAfterEvent, EntityRemoveAfterEvent } from '@minecraft/server';
+
+export enum WeatherType {
+    Clear = 'Clear',
+    Rain = 'Rain',
+    Thunder = 'Thunder',
+}
+export function createWeatherEvent(dim: string): WeatherChangeAfterEvent {
+    return { dimension: dim, newWeather: WeatherType.Clear, previousWeather: WeatherType.Rain };
+}
+export type WeatherChangeAfterEventCallback = (event: WeatherChangeAfterEvent) => void;
+export const MockWeatherChangeEventHandlers: WeatherChangeAfterEventCallback[] = [];
+
+export type EntityRemoveAfterEventCallback = (event: EntityRemoveAfterEvent) => void;
+export type MockEntityRemoveAfterEventCallbackData = {
+    callback: EntityRemoveAfterEventCallback;
+    options?: EntityEventOptions;
+};
+export const MockEntityRemoveEventHandlers: MockEntityRemoveAfterEventCallbackData[] = [];
+
+export function clearMockState() {
+    MockWeatherChangeEventHandlers.length = 0;
+    MockEntityRemoveEventHandlers.length = 0;
+}
+
+export const createMockServerBindings = () => {
+    return {
+        world: {
+            afterEvents: {
+                weatherChange: {
+                    subscribe: (callback: WeatherChangeAfterEventCallback) => {
+                        MockWeatherChangeEventHandlers.push(callback);
+                        return callback;
+                    },
+                    unsubscribe: (callback: WeatherChangeAfterEventCallback) => {
+                        const index = MockWeatherChangeEventHandlers.indexOf(callback);
+                        if (index !== -1) {
+                            MockWeatherChangeEventHandlers.splice(index, 1);
+                        }
+                    },
+                },
+                entityRemove: {
+                    subscribe: (callback: EntityRemoveAfterEventCallback, options?: EntityEventOptions) => {
+                        MockEntityRemoveEventHandlers.push({ callback, options });
+                        return callback;
+                    },
+                    unsubscribe: (callback: EntityRemoveAfterEventCallback) => {
+                        const index = MockEntityRemoveEventHandlers.findIndex(value => value.callback === callback);
+                        if (index !== -1) {
+                            MockEntityRemoveEventHandlers.splice(index, 1);
+                        }
+                    },
+                },
+            },
+        },
+    };
+};

libraries/gameplay-utilities/api-extractor.json

@@ -0,0 +1,8 @@
+/**
+ * Config file for API Extractor.  For more info, please visit: https://api-extractor.com
+ */
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+    "extends": "@minecraft/api-extractor-base/api-extractor-base.json",
+    "mainEntryPointFilePath": "<projectFolder>/temp/types/src/index.d.ts"
+}

libraries/gameplay-utilities/api-report/gameplay-utilities.api.md

@@ -0,0 +1,29 @@
+## API Report File for "@minecraft/gameplay-utilities"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { system } from '@minecraft/server';
+import { world } from '@minecraft/server';
+
+// @public
+export interface EventPromise<T> extends Promise<T | undefined> {
+    cancel(): void;
+    catch<TReject = never>(onrejected?: ((reason: unknown) => TReject | PromiseLike<TReject>) | null): Promise<T | undefined | TReject>;
+    finally(onfinally?: (() => void) | null): Promise<T | undefined>;
+    then<TFulfill = T | undefined, TReject = never>(onfulfilled?: ((value: T | undefined) => TFulfill | PromiseLike<TFulfill>) | null, onrejected?: ((reason: unknown) => TReject | PromiseLike<TReject>) | null): Promise<TFulfill | TReject>;
+}
+
+// @public
+export type FirstArg<T> = T extends (arg: infer U) => void ? U : never;
+
+// @public
+export type MinecraftAfterEventSignals = (typeof world.afterEvents)[keyof typeof world.afterEvents] | (typeof system.afterEvents)[keyof typeof system.afterEvents];
+
+// @public
+export function nextEvent<U>(signal: MinecraftAfterEventSignals, filter?: U): EventPromise<FirstArg<FirstArg<typeof signal.subscribe>>>;
+
+// (No @packageDocumentation comment for this package)
+
+```

libraries/gameplay-utilities/eslint.config.mjs

@@ -0,0 +1,6 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import configMinecraftScripting from 'eslint-config-minecraft-scripting';
+
+export default [...configMinecraftScripting];

libraries/gameplay-utilities/just.config.cts

@@ -0,0 +1,55 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { execSync } from 'child_process';
+import { argv, series, task, tscTask } from 'just-scripts';
+import {
+    DEFAULT_CLEAN_DIRECTORIES,
+    apiExtractorTask,
+    cleanTask,
+    coreLint,
+    publishReleaseTask,
+    vitestTask,
+} from '@minecraft/core-build-tasks';
+import { copyFileSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const isOnlyBuild = argv()._.findIndex(arg => arg === 'test') === -1;
+
+// Lint
+task('lint', coreLint(['src/**/*.ts'], argv().fix));
+
+// Build
+task('typescript', tscTask());
+task('api-extractor-local', apiExtractorTask('./api-extractor.json', isOnlyBuild /* localBuild */));
+task('bundle', () => {
+    execSync(
+        'npx esbuild ./lib/src/index.js --bundle --outfile=dist/minecraft-gameplay-utilities.js --format=esm --sourcemap --external:@minecraft/server'
+    );
+    // Copy over type definitions and rename
+    const officialTypes = JSON.parse(readFileSync('./package.json', 'utf-8'))['types'];
+    if (!officialTypes) {
+        // Has the package.json been restructured?
+        throw new Error('The package.json file does not contain a "types" field. Unable to copy types to bundle.');
+    }
+    const officialTypesPath = resolve(officialTypes);
+    copyFileSync(officialTypesPath, './dist/minecraft-gameplay-utilities.d.ts');
+});
+task('build', series('typescript', 'api-extractor-local', 'bundle'));
+
+// Test
+task('api-extractor-validate', apiExtractorTask('./api-extractor.json', isOnlyBuild /* localBuild */));
+task('vitest', vitestTask({ test: argv().test, update: argv().update }));
+task('test', series('api-extractor-validate', 'vitest'));
+
+// Clean
+task('clean', cleanTask(DEFAULT_CLEAN_DIRECTORIES));
+
+// Post-publish
+task('postpublish', () => {
+    return publishReleaseTask({
+        repoOwner: 'Mojang',
+        repoName: 'minecraft-scripting-libraries',
+        message: 'See attached zip for pre-built minecraft-gameplay-utilities bundle with type declarations.',
+    });
+});

libraries/gameplay-utilities/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@minecraft/gameplay-utilities",
+  "version": "0.1.0",
+  "author": "Andrew Griffin ([email protected])",
+  "contributors": [
+    {
+      "name": "Jake Shirley",
+      "email": "[email protected]"
+    }
+  ],
+  "description": "Gameplay utilities for use with minecraft scripting modules",
+  "exports": {
+    "import": "./lib/src/index.js",
+    "types": "./lib/types/gameplay-utilities-public.d.ts"
+  },
+  "type": "module",
+  "types": "./lib/types/gameplay-utilities-public.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Mojang/minecraft-scripting-libraries.git",
+    "directory": "libraries/gameplay-utilities"
+  },
+  "scripts": {
+    "build": "just build",
+    "lint": "just lint",
+    "test": "just test",
+    "clean": "just clean",
+    "postpublish": "just postpublish"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "lib",
+    "api-report"
+  ],
+  "peerDependencies": {
+    "@minecraft/server": "^1.15.0 || ^2.0.0"
+  },
+  "devDependencies": {
+    "@minecraft/core-build-tasks": "*",
+    "@minecraft/server": "^2.0.0",
+    "@minecraft/tsconfig": "*",
+    "just-scripts": "^2.4.1",
+    "prettier": "^3.5.3",
+    "vitest": "^3.0.8"
+  }
+}

libraries/gameplay-utilities/src/events/eventPromise.test.ts

@@ -0,0 +1,65 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { afterEach, describe, it, vi, expect } from 'vitest';
+
+import {
+    clearMockState,
+    createMockServerBindings,
+    MockWeatherChangeEventHandlers,
+    createWeatherEvent,
+    MockEntityRemoveEventHandlers,
+} from '../../__mocks__/minecraft-server.js';
+
+vi.mock('@minecraft/server', () => createMockServerBindings());
+
+import { nextEvent } from './eventPromise.js';
+
+describe('EventPromise', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+        clearMockState();
+    });
+
+    it('Event is subscribed', () => {
+        const server = createMockServerBindings();
+        void nextEvent(server.world.afterEvents.weatherChange);
+        expect(MockWeatherChangeEventHandlers.length).toBe(1);
+    });
+
+    // specifically this test differs from above because this signal supports filters
+    it('Event is subscribed without filter', () => {
+        const server = createMockServerBindings();
+        void nextEvent(server.world.afterEvents.entityRemove);
+        expect(MockEntityRemoveEventHandlers.length).toBe(1);
+    });
+
+    it('Event is subscribed with filter', () => {
+        const server = createMockServerBindings();
+        void nextEvent(server.world.afterEvents.entityRemove, { entityTypes: ['foobar'] });
+        expect(MockEntityRemoveEventHandlers.length).toBe(1);
+    });
+
+    it('Event is unsubscribed when called', async () => {
+        const server = createMockServerBindings();
+        const prom = nextEvent(server.world.afterEvents.weatherChange);
+        const event = createWeatherEvent('foo');
+        MockWeatherChangeEventHandlers.forEach(handler => {
+            handler(event);
+        });
+        await prom;
+        expect(MockWeatherChangeEventHandlers.length).toBe(0);
+    });
+
+    it('Event is gathered from await promise', async () => {
+        const server = createMockServerBindings();
+        const eventExpected = createWeatherEvent('foobar');
+        setTimeout(() => {
+            MockWeatherChangeEventHandlers.forEach(handler => {
+                handler(eventExpected);
+            });
+        }, 100);
+        const eventActual = await nextEvent(server.world.afterEvents.weatherChange);
+        expect(eventActual).toBe(eventExpected);
+    });
+});