@minecraft/server-admin 1.0.0-beta.1.21.10-preview.23 → 1.0.0-beta.1.21.100-preview.20

package/README.md

@@ -1,6 +1,6 @@
 # `@minecraft/server-admin`
 
-Contains types related to administering a Bedrock Dedicated Server. These types allow for the configuration of variables and secrets in JSON files in the Bedrock Dedicated Server folder. These types cannot be used on Minecraft clients.
+Contains types related to administering a Bedrock Dedicated Server. These types allow for the configuration of variables and secrets in JSON files in the Bedrock Dedicated Server folder. These types cannot be used on Minecraft clients or within Minecraft Realms.
 
 ## **NOTE: This version of this module is still in pre-release.  It may change or it may be removed in future releases.**
 

package/index.d.ts

@@ -12,18 +12,89 @@
  * Contains types related to administering a Bedrock Dedicated
  * Server. These types allow for the configuration of variables
  * and secrets in JSON files in the Bedrock Dedicated Server
- * folder. These types cannot be used on Minecraft clients.
+ * folder. These types cannot be used on Minecraft clients or
+ * within Minecraft Realms.
  *
  * Manifest Details
  * ```json
  * {
  *   "module_name": "@minecraft/server-admin",
- *   "version": "1.0.0-beta.1.21.10-preview.23"
+ *   "version": "1.0.0-beta"
  * }
  * ```
  *
  */
 import * as minecraftcommon from '@minecraft/common';
+import * as minecraftserver from '@minecraft/server';
+export class AdminBeforeEvents {
+    private constructor();
+    /**
+     * @remarks
+     * This event is fired before a player joins the world. Unlike
+     * other before events, this event is a before event that you
+     * can delay several ticks by not resolving the promise
+     * returned in the subscribe function. If the promise is
+     * rejected, the client is rejected.
+     *
+     */
+    readonly asyncPlayerJoin: AsyncPlayerJoinBeforeEventSignal;
+}
+
+/**
+ * The data available before a player joins the world.
+ */
+export class AsyncPlayerJoinBeforeEvent {
+    private constructor();
+    /**
+     * @remarks
+     * The player's name
+     *
+     */
+    readonly name: string;
+    /**
+     * @remarks
+     * An identifier that can be used to identify a player across
+     * sessions.
+     *
+     */
+    readonly persistentId: string;
+    /**
+     * @remarks
+     * Call this to disconnect a player. They will be allowed to
+     * try to join again.
+     *
+     * @throws This function can throw errors.
+     *
+     * {@link DisconnectedError}
+     */
+    disconnect(reason?: string): void;
+    /**
+     * @remarks
+     * Will return true if the player is still waiting to join the
+     * world. If they disconnect then it will return false.
+     *
+     */
+    isValid(): boolean;
+}
+
+export class AsyncPlayerJoinBeforeEventSignal {
+    private constructor();
+    /**
+     * @remarks
+     * Add a callback that's ran before a player joins the world.
+     * This callback returns a promise and the player won't join
+     * until that promise is resolved. If the promise is not
+     * resolved within a reasonable time, the player joining will
+     * be rejected. If the player joining leaves/disconnects, then
+     * the event data's isValid will return false.
+     *
+     */
+    subscribe(
+        callback: (arg0: AsyncPlayerJoinBeforeEvent) => Promise<void>,
+    ): (arg0: AsyncPlayerJoinBeforeEvent) => Promise<void>;
+    unsubscribe(callback: (arg0: AsyncPlayerJoinBeforeEvent) => Promise<void>): boolean;
+}
+
 /**
  * This represents a placeholder object that represents a
  * secret string. The contents of that string are not available
@@ -61,8 +132,6 @@ export class SecretString {
  *
  *     return http.request(req);
  * }
- *
- * getPlayerProfile('dark navi');
  * ```
  */
 export class ServerSecrets {
@@ -82,6 +151,8 @@ export class ServerSecrets {
      *
      * This function can't be called in read-only mode.
      *
+     * This function can be called in early-execution mode.
+     *
      */
     get(name: string): SecretString | undefined;
 }
@@ -114,8 +185,6 @@ export class ServerSecrets {
  *
  *     return http.request(req);
  * }
- *
- * getPlayerProfile('dark navi');
  * ```
  */
 export class ServerVariables {
@@ -133,10 +202,78 @@ export class ServerVariables {
      *
      * This function can't be called in read-only mode.
      *
+     * This function can be called in early-execution mode.
+     *
      */
-    get(name: string): any | undefined;
+    get(name: string): unknown | undefined;
 }
 
+/**
+ * Options when transferring a player to a server that supports
+ * direct host/port connections.
+ */
+export interface TransferPlayerIpPortOptions {
+    /**
+     * @remarks
+     * Hostname of the destination server.
+     *
+     */
+    hostname: string;
+    /**
+     * @remarks
+     * Port of the destination server.
+     *
+     */
+    port: number;
+}
+
+/**
+ * Options when transferring a player to a server that supports
+ * NetherNet connections.
+ */
+export interface TransferPlayerNetherNetOptions {
+    /**
+     * @remarks
+     * NetherNet ID of the destination server.
+     *
+     */
+    netherNetId: string;
+}
+
+/**
+ * An error that is thrown when trying to interact with a join
+ * event and the player is disconnected.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class DisconnectedError extends Error {
+    private constructor();
+    /**
+     * @remarks
+     * The id of the player that was disconnected.
+     *
+     * This property can be read in early-execution mode.
+     *
+     */
+    id: string;
+}
+
+/**
+ * @remarks
+ * Transfer player to another server.
+ *
+ * This function can't be called in read-only mode.
+ *
+ * @param player
+ * Player to transfer.
+ * @param options
+ * Options for where to send the player.
+ * @throws This function can throw errors.
+ */
+export function transferPlayer(
+    player: minecraftserver.Player,
+    options: TransferPlayerIpPortOptions | TransferPlayerNetherNetOptions,
+): void;
+export const beforeEvents: AdminBeforeEvents;
 /**
  * @remarks
  * A globally available object that returns a list of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minecraft/server-admin",
-  "version": "1.0.0-beta.1.21.10-preview.23",
+  "version": "1.0.0-beta.1.21.100-preview.20",
   "description": "",
   "contributors": [
     {
@@ -13,7 +13,8 @@
     }
   ],
   "dependencies": {
-    "@minecraft/common": "^1.0.0"
+    "@minecraft/common": "^1.0.0",
+    "@minecraft/server": "^1.17.0 || ^2.0.0-rc.1.21.100-preview.20"
   },
   "license": "MIT"
 }

package/.eslintrc.json

@@ -1,23 +0,0 @@
-{
-    "env": {
-        "browser": true,
-        "es2021": true
-    },
-    "extends": [
-        "eslint:recommended",
-        "plugin:@typescript-eslint/recommended"
-    ],
-    "overrides": [
-    ],
-    "parser": "@typescript-eslint/parser",
-    "parserOptions": {
-        "ecmaVersion": "latest",
-        "sourceType": "module"
-    },
-    "plugins": [
-        "@typescript-eslint"
-    ],
-    "rules": {
-        "@typescript-eslint/no-explicit-any": "off"
-    }
-}

package/tests.ts

@@ -1,142 +0,0 @@
-/* eslint-disable  @typescript-eslint/no-unused-vars */
-import * as mc from '@minecraft/server';
-
-export async function getPlayerProfile(log: (message: string, status?: number) => void, targetLocation: mc.Vector3) {
-    const serverUrl = mcsa.variables.get('serverEndpoint');
-
-    const req = new mcnet.HttpRequest(serverUrl + 'getPlayerProfile');
-
-    req.body = JSON.stringify({
-        playerId: 'johndoe',
-    });
-
-    req.method = mcnet.HttpRequestMethod.POST;
-    req.headers = [
-        new mcnet.HttpHeader('Content-Type', 'application/json'),
-        new mcnet.HttpHeader('auth', mcsa.secrets.get('authtoken')),
-    ];
-
-    await mcnet.http.request(req);
-}
-
-export default class SampleManager {
-    tickCount = 0;
-
-    _availableFuncs: {
-        [name: string]: Array<(log: (message: string, status?: number) => void, location: mc.Vector3) => void>;
-    };
-
-    pendingFuncs: Array<{
-        name: string;
-        func: (log: (message: string, status?: number) => void, location: mc.Vector3) => void;
-        location: mc.Vector3;
-    }> = [];
-
-    gameplayLogger(message: string, status?: number) {
-        if (status !== undefined && status > 0) {
-            message = 'SUCCESS: ' + message;
-        } else if (status !== undefined && status < 0) {
-            message = 'FAIL: ' + message;
-        }
-
-        this.say(message);
-    }
-    say(message: string) {
-        mc.world.getDimension('overworld').runCommand('say ' + message);
-    }
-
-    newChatMessage(chatEvent: mc.ChatEvent) {
-        const message = chatEvent.message.toLowerCase();
-
-        if (message.startsWith('howto') && chatEvent.sender) {
-            const nearbyBlock = chatEvent.sender.getBlockFromViewVector();
-            if (!nearbyBlock) {
-                this.gameplayLogger('Please look at the block where you want me to run this.');
-                return;
-            }
-
-            const nearbyBlockLoc = nearbyBlock.location;
-            const nearbyLoc: mc.Vector3 = { x: nearbyBlockLoc.x, y: nearbyBlockLoc.y + 1, z: nearbyBlockLoc.z };
-
-            const sampleId = message.substring(5).trim();
-
-            if (sampleId.length < 2) {
-                let availableFuncStr = 'Here is my list of available samples:';
-
-                for (const sampleFuncKey in this._availableFuncs) {
-                    availableFuncStr += ' ' + sampleFuncKey;
-                }
-
-                this.say(availableFuncStr);
-            } else {
-                for (const sampleFuncKey in this._availableFuncs) {
-                    if (sampleFuncKey.toLowerCase() === sampleId) {
-                        const sampleFunc = this._availableFuncs[sampleFuncKey];
-
-                        this.runSample(sampleFuncKey + this.tickCount, sampleFunc, nearbyLoc);
-
-                        return;
-                    }
-                }
-
-                this.say(`I couldn't find the sample '${sampleId}"'`);
-            }
-        }
-    }
-
-    runSample(
-        sampleId: string,
-        snippetFunctions: Array<(log: (message: string, status?: number) => void, location: mc.Vector3) => void>,
-        targetLocation: mc.Vector3,
-    ) {
-        for (let i = snippetFunctions.length - 1; i >= 0; i--) {
-            this.pendingFuncs.push({ name: sampleId, func: snippetFunctions[i], location: targetLocation });
-        }
-    }
-
-    worldTick() {
-        if (this.tickCount % 10 === 0) {
-            if (this.pendingFuncs.length > 0) {
-                const funcSet = this.pendingFuncs.pop();
-
-                if (funcSet) {
-                    funcSet.func(this.gameplayLogger, funcSet.location);
-                }
-            }
-        }
-
-        this.tickCount++;
-    }
-
-    constructor() {
-        this._availableFuncs = {};
-
-        this.gameplayLogger = this.gameplayLogger.bind(this);
-
-        mc.world.events.tick.subscribe(this.worldTick.bind(this));
-        mc.world.events.chat.subscribe(this.newChatMessage.bind(this));
-    }
-
-    registerSamples(sampleSet: {
-        [name: string]: Array<(log: (message: string, status?: number) => void, location: mc.Vector3) => void>;
-    }) {
-        for (const sampleKey in sampleSet) {
-            if (sampleKey.length > 1 && sampleSet[sampleKey]) {
-                this._availableFuncs[sampleKey] = sampleSet[sampleKey];
-            }
-        }
-    }
-}
-
-import * as mcsa from '@minecraft/server-admin';
-import * as mcnet from '@minecraft/server-net'; // keep in for net samples
-
-const mojangServerAdminTestFuncs: {
-    [name: string]: Array<(log: (message: string, status?: number) => void, location: mc.Vector3) => void>;
-} = {
-    getPlayerProfile: [getPlayerProfile],
-};
-
-export function register(sampleManager: SampleManager) {
-    sampleManager.registerSamples(mojangServerAdminTestFuncs);
-}

package/tsconfig.json

@@ -1,20 +0,0 @@
-{
-  "compilerOptions": {
-      "module": "commonjs",
-      "lib": ["es6"],
-      "target": "es6",
-      "forceConsistentCasingInFileNames": true,
-      "noEmit": true,
-      "noImplicitAny": true,
-      "noImplicitThis": true,
-      "strictFunctionTypes": true,
-      "strictNullChecks": true,
-      "baseUrl": "../",
-      "typeRoots": ["../"],
-      "types": []
-  },
-  "files": [
-      "index.d.ts",
-      "tests.ts"
-  ]
-}