documentation and env enforcement

Author: OutdatedVersion

.env.example

@@ -0,0 +1,6 @@
+MINECRAFT_HOST=127.0.0.1
+MINECRAFT_PORT=25565
+MINECRAFT_USERNAME=idk
+MINECRAFT_CHEST_X=-382
+MINECRAFT_CHEST_Y=68
+MINECRAFT_CHEST_Z=-77

README.md

@@ -0,0 +1,71 @@
+# Minecraft Node.js package loader
+
+Load JavaScript packages from books in chests on a Minecraft server.
+
+This will create a headless Minecraft client, join the configured server, and open
+a chest to look for signed books.
+
+Huge shoutout to the authors of `minecraft-protocol` and Prismarine. Their work
+lets this simply stitch together some packages and patch a resolution quirk. 💙
+
+## Usage
+
+1.  **in-game:** Login to an offline mode Minecraft server (any version supported by [`minecraft-data`](https://npmjs.com/package/minecraft-data))
+
+2.  **in-game:** Write your code in a book and quill
+
+    > **Note**
+    > The first line of the first page should be a semver string
+
+    > **Note** > `import`ed packages will be loaded relative to the last on-disk module
+    >
+    > e.g. if `example.mjs` imports `minecraft:helloer`, any `import` in `helloer` will be
+    > loaded as if you were in `example.mjs`.
+
+    This could look something like:
+
+    ![Book page 1](./docs/assets/book-page-1.jpg)
+
+    ![Book page 2](./docs/assets/book-page-2.jpg)
+
+3.  **in-game:** Sign your book and quill with the package name as the title
+
+    ![Book title](./docs/assets/book-title.jpg)
+
+4.  **in-game:** Place your book, with any others, in a chest
+
+    - This chest must be close enough to the configured player that it can open the chest
+      without moving. This is 5 blocks away on an unmodified server. Keep in mind spawn
+      protection prevents non OP-ed players from opening a chest (I forgot this and spent hours trying
+      to fix the code 😅).
+
+    ![Chest](./docs/assets/chest.jpg)
+
+5.  Configure your shell's environment with the correct variables following [`.env.example`](./.env.example).
+
+6.  Put together a consuming script locally (see `example.mjs`)
+
+    ```js
+    // example.mjs
+    import * as helloer from 'minecraft:helloer';
+    console.log(helloer);
+    console.log(helloer.getWelcome('Cooper'));
+    console.log(helloer.getDatedWelcome('Cooper'));
+    ```
+
+7.  Run script with the `--loader` flag
+
+    ```console
+    $ node --loader ./dist/loader.mjs example.mjs
+    [Module: null prototype] {
+    getDatedWelcome: [Function: getDatedWelcome],
+    getWelcome: [Function: getWelcome]
+    }
+    Hi, Cooper
+    Welcome to 2023, Cooper!
+    ```
+
+## Wishlist
+
+- npm compatible registry so the consumer doesn't need any non-standard dependencies
+- Support teleporting the player (issue server command) so spawn location isn't a big deal

docs/assets/book-page-1.jpg

@@ -1,16 +1,28 @@
 import mineflayer from 'mineflayer';
 import { TagType, type List } from 'prismarine-nbt';
+// @ts-expect-error
 import vec3 from 'vec3';
 import { setTimeout } from 'timers/promises';
 import { Tags } from 'prismarine-nbt';
 import debug from 'debug';
+import { z } from 'zod';
+
+const envSchema = z.object({
+  MINECRAFT_HOST: z.string(),
+  MINECRAFT_PORT: z.string().transform((x) => parseInt(x, 10)),
+  MINECRAFT_USERNAME: z.string(),
+  MINECRAFT_CHEST_X: z.string().transform((x) => parseInt(x, 10)),
+  MINECRAFT_CHEST_Y: z.string().transform((x) => parseInt(x, 10)),
+  MINECRAFT_CHEST_Z: z.string().transform((x) => parseInt(x, 10)),
+});
+const env = envSchema.parse(process.env);
 
 const log = debug('loader:minecraft');
 
 const bot = mineflayer.createBot({
-  host: '127.0.0.1',
-  port: 25565,
-  username: 'idk',
+  host: env.MINECRAFT_HOST,
+  port: env.MINECRAFT_PORT,
+  username: env.MINECRAFT_USERNAME,
   auth: 'offline',
 });
 
@@ -44,13 +56,18 @@ export const getPackage = async (name: string) => {
 };
 
 bot.on('spawn', async () => {
-  let block = bot.blockAt(vec3(-382, 68, -77));
+  const loc = vec3(
+    env.MINECRAFT_CHEST_X,
+    env.MINECRAFT_CHEST_Y,
+    env.MINECRAFT_CHEST_Z
+  );
+  let block = bot.blockAt(loc);
   while (!block) {
-    log('Block state not yet available. Trying again soon..');
+    log('Block state not yet available. Trying again soon..', loc);
     await setTimeout(10);
-    block = bot.blockAt(vec3(-382, 68, -77));
+    block = bot.blockAt(loc);
   }
-  log('Block state available');
+  log('Block state available', loc);
 
   const chest = await bot.openContainer(block);