@vaitosoi/minejs 0.2.1 → 0.3.1

package/src/version/registry.ts

@@ -0,0 +1,333 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { RegistryItemNotFound, UnexpectedValue, VersionNotSupport } from "../base/error";
+import { Block, BlockState } from "../world/block";
+import z from "zod";
+
+export const BASE_REGISTRY_PATH = join(__dirname, "..", "..", "assets", "minecraft");
+export const SupportVersions = [
+    "26.2"
+];
+
+export const ProtocolVersionMapping: Record<string, number> = {
+    "26.2": 776
+};
+
+export class EntityRegistry {
+    private static loaded: boolean = false;
+    public static readonly data: Record<string, { height: number, width: number, type: number }> = {};
+    public static readonly mapTypeToData: Record<number, string> = {};
+
+    /**
+     * Load entity registry from JSON file.
+     * 
+     * Should be called once time
+     */
+    public static async load(version: string) {
+        if (!SupportVersions.includes(version))
+            throw new VersionNotSupport(version);
+        if (this.loaded) return;
+        this.loaded = true;
+
+        const file = await readFile(join(BASE_REGISTRY_PATH, version, "entities.json"), { encoding: "utf8" });
+        const json = JSON.parse(file);
+        for (const entity in json) {
+            this.data[entity] = json[entity];
+            this.mapTypeToData[json[entity]["id"]] = entity;
+        }
+    }
+
+    /**
+     * Get an entity registy item
+     */
+    public static get(entity: string | number) {
+        if (typeof entity === "string") {
+            return this.data[entity];
+        } else {
+            const key = this.mapTypeToData[entity];
+            return this.data[key!];
+        }
+    }
+};
+
+export class BlockRegistry {
+    private static loaded: boolean = false;
+    /**
+     * block id to block
+     */
+    public static readonly blocks: Record<string, Block> = {};
+    /**
+     * state id to block state
+     */
+    public static readonly states: Record<string, BlockState> = {};
+
+    /**
+     * Load block registry from JSON file.
+     * 
+     * Should be called once time
+     */
+    public static async load(version: string) {
+        if (!SupportVersions.includes(version))
+            throw new VersionNotSupport(version);
+        if (this.loaded) return;
+        this.loaded = true;
+
+        const file = await readFile(join(BASE_REGISTRY_PATH, version, "blocks.json"), { encoding: "utf8" });
+        const json = JSON.parse(file) as Record<string, any>;
+        for (const [type, blockRaw] of Object.entries(json)) {
+            const block = new Block(type, blockRaw['definition'], blockRaw['properties'], blockRaw['states']);
+            this.blocks[type] = block;
+            for (const state of block.states)
+                this.states[state.id] = state;
+        }
+    }
+
+    /**
+     * Get a block registy item
+     */
+    public static getBlock(type: string) {
+        if (!(type in this.blocks))
+            throw new RegistryItemNotFound(`block ${type}`);
+        return this.blocks[type]!;
+    }
+
+    /**
+     * Get a block state registy item
+     */
+    public static getState(id: string) {
+        if (!(id in this.states))
+            throw new RegistryItemNotFound(`block state ${id}`);
+        return this.states[id]!;
+    }
+};
+
+export const SupportTypes = z.enum([
+    "byte",
+    "unsigned_byte",
+    "short",
+    "unsigned_short",
+    "int",
+    "long",
+    "float",
+    "double",
+    "boolean",
+    "var_int",
+    "var_long",
+    "string",
+    "uuid",
+    "position",
+    "array",
+    "prefixed_array",
+    "teleport_flag",
+    "prefixed_optional",
+    "nbt",
+    "lpvec3",
+    "fixed_point",
+    "angle",
+    "id_or_x",
+    "chat_type_decoration",
+    "chat_type",
+    "chunk_data",
+    "enum",
+    "json_text",
+    "not_implemented",
+    "varies",
+    "object",
+    "game_profile",
+    "heightmap",
+    "teleport_flags",
+    "bitset",
+    "null", // a constant
+
+    /**
+     * This is used for handle field that its type depends on previous field type, or value
+     */
+    "switch"
+]);
+export type FieldNode = {
+    type: Exclude<z.infer<typeof SupportTypes>, "prefixed_array" | "prefixed_optional" | "string" | "id_or_x" | "array" | "switch" | "fixed_point" | "enum" | "object" | "not_implemented">,
+} | {
+    type: "not_implemented",
+    comment?: string | undefined
+} | {
+    type: "object",
+    fields: Record<string, FieldNode>
+} | {
+    type: "prefixed_array",
+    subType: FieldNode,
+    length?: number | undefined,
+} | {
+    type: "id_or_x" | "enum" | "prefixed_optional",
+    subType: FieldNode
+} | {
+    type: "string",
+    length?: number | undefined
+} | {
+    type: "array",
+    subType: FieldNode,
+    length: string | number,
+} | {
+    type: "switch",
+    dependsOn: string,
+    cases: [string, FieldNode][],
+    default?: FieldNode | undefined
+} | {
+    type: "fixed_point",
+    subType: FieldNode,
+    fractionBits: number
+}
+export const Field: z.ZodType<FieldNode> = z.union([
+    z.object({
+        type: SupportTypes.exclude(["prefixed_array", "prefixed_optional", "string", "id_or_x", "array", "switch", "fixed_point", "enum", "not_implemented", "object"]),
+    }),
+    z.object({
+        type: z.literal(["not_implemented"]),
+        comment: z.string().optional()
+    }),
+    z.object({
+        type: z.literal(["object"]),
+        fields: z.record(z.string(), z.lazy(() => Field))
+    }),
+    z.object({
+        type: z.literal(["prefixed_array"]),
+        /**
+         * For case like `Array<subType>` or `PrefixedOptional<subType>`
+         */
+        subType: z.lazy(() => Field),
+        /**
+         * The length of the array type, not used.
+         */
+        length: z.number().optional()
+    }),
+    z.object({
+        type: z.literal(["id_or_x", "enum", "prefixed_optional"]),
+        /**
+         * For case like `Array<subType>` or `PrefixedOptional<subType>`
+         */
+        subType: z.lazy(() => Field),
+    }),
+    z.object({
+        type: z.literal("string"),
+        /**
+         * The length of the string, not used.
+         */
+        length: z.number().optional(),
+    }),
+    z.object({
+        type: z.literal("array"),
+        /**
+         * For case like `Array<subType>` or `PrefixedOptional<subType>`
+         */
+        subType: z.lazy(() => Field),
+        /**
+         * Specially for `array` type, which is not prefixed with length.
+         * 
+         * Point to another field, should be numberic field
+         */
+        length: z.string().or(z.number()),
+    }),
+    z.object({
+        type: z.literal("switch"),
+        /**
+         * Specially for case that this field type depends on other field value.
+         * 
+         * Point to the field that this field is depended on.
+         */
+        dependsOn: z.string(),
+        /**
+         * Mapping depend value to type
+         */
+        cases: z.array(z.tuple([z.any(), z.lazy(() => Field)])),
+        default: z.lazy(() => Field).optional(),
+    }),
+    z.object({
+        type: z.literal(["fixed_point"]),
+        /**
+         * For case like `Array<subType>` or `PrefixedOptional<subType>`
+         */
+        subType: z.lazy(() => Field),
+        fractionBits: z.number()
+    }),
+
+]);
+export const PacketObject = z.object({
+    name: z.string(),
+    id: z.number(),
+    structure: z.record(z.string(), Field),
+    skipForNow: z.boolean().default(false)
+});
+export const PacketsDefinition = z.record(z.string().or(z.number()), PacketObject);
+export const StatesDefinition = z.object({
+    clientbound: PacketsDefinition,
+    serverbound: PacketsDefinition,
+});
+export const VersionDefinitions = z.object({
+    handshaking: StatesDefinition,
+    status: StatesDefinition,
+    login: StatesDefinition,
+    configuration: StatesDefinition,
+    play: StatesDefinition,
+});
+
+export class PacketRegistry {
+    private static loaded: boolean = false;
+    private static definition: z.infer<typeof VersionDefinitions>;
+    private static nameToId: Record<
+        string, // State
+        Record<
+            string, // Type
+            Record<string, number> // Packet
+        >
+    > = {};
+
+    /**
+     * Load block registry from JSON file.
+     * 
+     * Should be called once time
+     */
+    public static async load(version: string) {
+        if (!SupportVersions.includes(version))
+            throw new VersionNotSupport(version);
+        if (this.loaded) return;
+        this.loaded = true;
+
+        const file = await readFile(join(BASE_REGISTRY_PATH, version, "packets.json"), { encoding: "utf8" });
+        const json = JSON.parse(file) as Record<string, any>;
+
+        const definition = VersionDefinitions.parse(json);
+        for (const [stateKey, state] of Object.entries(definition)) {
+            this.nameToId[stateKey] = {};
+            for (const [typeKey, type] of Object.entries(state)) {
+                this.nameToId[stateKey]![typeKey] = {};
+                // eslint-disable-next-line prefer-const
+                for (let [key, value] of Object.entries(type) as [string | number, any]) {
+                    if (typeof key === "string" && !isNaN(parseInt(key))) {
+                        type[parseInt(key)] = value;
+                        delete type[key];
+                        key = parseInt(key);
+                    } // transform all string key into numberic key
+                    this.nameToId[stateKey]![typeKey]![value.name] = key;
+                }
+            }
+        }
+        this.definition = definition;
+    }
+
+    public static getPacket(
+        state: keyof z.infer<typeof VersionDefinitions>,
+        type: keyof z.infer<typeof StatesDefinition>,
+        id: string | number
+    ): z.infer<typeof PacketObject> | undefined {
+        const nameToId = this.nameToId[state]?.[type]?.[id]?.toString();
+        if (nameToId)
+            return this.definition[state][type][nameToId]!;
+        let numbericId;
+        if (typeof id === "string")
+            numbericId = parseInt(id, 16);
+        else numbericId = id;
+        if (isNaN(numbericId))
+            throw new UnexpectedValue("valid packet id", id.toString(), "name or number or hex");
+        else
+            return this.definition[state][type][numbericId.toString()];
+    }
+}

package/src/{base → world}/block.ts

@@ -1,8 +1,9 @@
 import { TCPClient } from "../client/tcp";
-import { AABB, BaseAABB, VoxelShape } from "./aabb";
-import { Epsilon, getFrac, getSign, lerp } from "./math";
-import { BlockRegistry } from "./registry";
-import { BaseVec3, Direction, Vec3 } from "./direction";
+import { AABB, BaseAABB, VoxelShape } from "../physics/aabb";
+import { Epsilon, getFrac, getSign, lerp } from "../base/math";
+import { BlockRegistry } from "../version/registry";
+import { BaseVec3, Direction, Vec3 } from "../physics/direction";
+import { SharedState } from "./state";
 
 /**
  * Represent a state of a block
@@ -76,7 +77,7 @@ export class Block {
  * Somehow, this is an equivalent implementation of Minecraft `Level`
  */
 export class BlockManager {
-    constructor(private tcp: TCPClient) { }
+    constructor(private state: SharedState) { }
 
     /**
      * Check if the chunk section is loaded
@@ -84,14 +85,14 @@ export class BlockManager {
     public hasChunkAt(x: number, y: number, z: number): boolean;
     public hasChunkAt(position: BaseVec3): boolean;
     public hasChunkAt(a: BaseVec3 | number, b?: number, c?: number): boolean {
-        this.tcp.checkReady();
+        this.state.checkReady();
         const { x, y, z } = Vec3.loadArgs(a, b, c);
         const sx = Math.floor(x / 16), sy = Math.floor((y + 64) / 16), sz = Math.floor(z / 16);
-        // // console.log({
+        // console.log({
         //     key: `${this.tcp.player!.dimension}:${sx}:${sz}`,
         //     hasKey: `${this.tcp.player!.dimension}:${sx}:${sz}` in this.tcp.world!.chunks
         // });
-        const section = this.tcp.world!.chunks[`${this.tcp.player!.dimension}:${sx}:${sz}`]?.sections[sy];
+        const section = this.state.world!.chunks[`${this.state.player!.dimension}:${sx}:${sz}`]?.sections[sy];
         if (!section) return false;
         return true;
     }
@@ -102,12 +103,12 @@ export class BlockManager {
     public at(x: number, y: number, z: number): BlockState | null;
     public at(position: BaseVec3): BlockState | null;
     public at(a: BaseVec3 | number, b?: number, c?: number): BlockState | null {
-        this.tcp.checkReady();
+        this.state.checkReady();
         let { x, y, z } = Vec3.loadArgs(a, b, c);
         x = Math.floor(x); y = Math.floor(y); z = Math.floor(z);
         const sx = Math.floor(x / 16), sy = Math.floor((y + 64) / 16), sz = Math.floor(z / 16);
         const px = ((x % 16) + 16) % 16, py = ((y % 16) + 16) % 16, pz = ((z % 16) + 16) % 16;
-        const section = this.tcp.world!.chunks[`${this.tcp.player!.dimension}:${sx}:${sz}`]?.sections[sy]?.block;
+        const section = this.state.world!.chunks[`${this.state.player!.dimension}:${sx}:${sz}`]?.sections[sy]?.block;
         if (!section) return null;
         if (section.data === null) return BlockRegistry.getState(section.palette[0]!.toString())!;
         const dataArray = section.data!;
@@ -128,7 +129,7 @@ export class BlockManager {
      * @returns 
      */
     public queryAABB(queryBB: AABB) {
-        this.tcp.checkReady();
+        this.state.checkReady();
 
         const { minX, minY, minZ, maxX, maxY, maxZ } = queryBB;
         const sx0 = Math.floor(minX), sx1 = Math.floor(maxX);

package/src/{base → world}/entity.ts

@@ -1,5 +1,5 @@
-import { TCPClient } from "../client/tcp";
-import { AABB } from "./aabb";
+import { AABB } from "../physics/aabb";
+import { SharedState } from "./state";
 
 export class EntitiesManager {
     /**
@@ -13,7 +13,7 @@ export class EntitiesManager {
      */
     public entityToSection: Map<number, string> = new Map();
 
-    constructor(private tcp: TCPClient) { }
+    constructor(private state: SharedState) { }
 
     /**
      * Clear data
@@ -70,7 +70,7 @@ export class EntitiesManager {
      * @returns
      */
     public queryAABB(queryBB: AABB, exclude: number[] = []) {
-        this.tcp.checkReady();
+        this.state.checkReady();
 
         const { minX, minY, minZ, maxX, maxY, maxZ } = queryBB;
         const results: AABB[] = [];
@@ -84,7 +84,7 @@ export class EntitiesManager {
                     const bucket = this.sections.get(`${sx},${sy},${sz}`);
                     if (bucket) for (const id of bucket) {
                         if (exclude.includes(id)) continue;
-                        const entity = this.tcp.world!.entities[id];
+                        const entity = this.state.world!.entities[id];
                         const entityBB = AABB.fromEntityType(entity!.type);
                         if (queryBB.isIntersect(entityBB))
                             results.push(entityBB);

package/src/world/state.ts

@@ -0,0 +1,232 @@
+import { Cipheriv, Decipheriv } from "node:crypto";
+import { If } from "../base/typing";
+import { Angle, BaseVec3 } from "../physics/direction";
+import { ClientNotReady } from "../base/error";
+import { ClientEvents, ClientOption } from "../client/client";
+import { TypedEmmiter } from "../base/event";
+import { TCPClient } from "../client/tcp";
+
+export interface Server {
+    knownPacks?: ServerKnownPack
+}
+
+export interface ServerKnownPack {
+    namespace: string,
+    id: string,
+    version: string
+}
+
+/**
+ * Represent world information
+ */
+export interface ServerWorld {
+    /** Is hardcore enabled */
+    hardcore: boolean,
+    /** All dimensions */
+    dimensions: string[],
+    /** Max players allowed */
+    maxPlayers: number,
+    /** View distances */
+    viewDistance: number,
+    /** Simulation distance */
+    simulationDistance: number,
+
+    /**
+     * The record key is a chunk section position packed as `Player Dimension:Chunk X:Chunk Z[Section Y]`
+     * 
+     * For `Section Y`, a chunk is splitted into several cubic 16x16x16 sections, or in other word, a chunk is a bund of 16x16x16 sections stacked on each other.
+     */
+    chunks: Record<string, ChunkColumn>,
+    /**
+     * The record key is entity ID
+     */
+    entities: Record<number, Entity>,
+}
+
+/** 
+ * Represent a chunk collumns, which may contains multiple chunks sections 
+ */
+export interface ChunkColumn {
+    sections: Record<number, ChunkSection>,
+    blockEntities: Record<number, BlockEntity>
+}
+
+export interface ChunkSection {
+    block: PaletteContainer,
+    biome: PaletteContainer,
+}
+
+/**
+ * Used for indirect mapping
+ * 
+ * @see https://minecraft.wiki/w/Java_Edition_protocol/Chunk_format#Paletted_Container_structure
+ */
+export interface PaletteContainer {
+    bpe: number, // Bit per entry
+    palette: number[],
+    data: BigInt64Array | null, // null if the whole section contains one 1 type of block
+}
+
+/** Represent a block entity */
+export interface BlockEntity {
+    type: number,
+    data: Record<string, any>
+}
+
+/** Represent an entity */
+export interface Entity {
+    id: number,
+    type: number,
+    position: BaseVec3,
+    velocity: BaseVec3,
+    angle: Angle,
+    data: number
+}
+
+export enum GameMode {
+    Survival = 0,
+    Creative = 1,
+    Adventure = 2,
+    Spectator = 3
+}
+
+export interface ClientPlayer {
+    /** Player UUID */
+    uuid: string,
+    /** Player username */
+    username: string,
+    /** Player entity ID */
+    entityId: number,
+    /** Current game mode */
+    gameMode: GameMode,
+
+    position: BaseVec3,
+    velocity: BaseVec3,
+    angle: Angle,
+
+    /** Current dimension */
+    dimension: string
+}
+
+export enum ClientStatus {
+    Disconnected,
+    Connecting,
+    Logining,
+    Ready,
+}
+
+export enum ConnectionState {
+    Disconnected,
+    Handshake,
+    Login,
+    Configure,
+    Play
+}
+
+export interface ServerRegistryEntry {
+    id: string,
+    data: object
+}
+
+export type MutateState = (state: SharedState) => void;
+export type EmittedEvent = {
+    [K in keyof ClientEvents]: { event: K, args: ClientEvents[K] }
+}[keyof ClientEvents]
+export type SendingPacket = {
+    id: string | number,
+    data: Record<string, any>
+}
+
+export class SharedState<IsReady extends boolean = boolean> {
+    private mutationQueue: MutateState[] = [];
+    private eventQueue: EmittedEvent[] = [];
+    private sendQueue: SendingPacket[] = [];
+
+    public state: ConnectionState = ConnectionState.Disconnected;
+    public status: ClientStatus = ClientStatus.Disconnected;
+    public compressionThreshold: number = 0;
+
+    public sharedSecret: Buffer | undefined = undefined;
+    public cipher: Cipheriv | undefined = undefined;
+    public decipher: Decipheriv | undefined = undefined;
+
+    public server: Server | undefined = undefined;
+    public registry: Record<string, ServerRegistryEntry[]> | undefined = undefined;
+    public world: If<IsReady, ServerWorld> = null as any;
+    public player: If<IsReady, ClientPlayer> = null as any;
+
+    constructor(
+        public clientOptions: ClientOption,
+        public getUuid: () => Buffer,
+    ) { }
+
+    public isReady(): this is SharedState<true> {
+        return this.status === ClientStatus.Ready;
+    }
+
+    public checkReady() {
+        if (!this.isReady())
+            throw new ClientNotReady();
+    }
+
+    public pruneStates() {
+        this.mutationQueue = [];
+        this.eventQueue = [];
+        this.sendQueue = [];
+        this.state = ConnectionState.Disconnected;
+        this.compressionThreshold = 0;
+        this.sharedSecret = undefined;
+        this.cipher = undefined;
+        this.decipher = undefined;
+        this.server = undefined;
+        this.registry = undefined;
+        this.world = undefined as any;
+        this.player = undefined as any;
+    }
+
+    public enqueueMutation(mutation: MutateState) { this.mutationQueue.push(mutation); }
+
+    public enqueuePacket(packet: string, data: object): void
+    public enqueuePacket(packet: SendingPacket): void
+    public enqueuePacket(packet: SendingPacket | string, data?: object) {
+        if (typeof packet === "string")
+            this.sendQueue.push({
+                id: packet,
+                data: data!
+            });
+        else
+            this.sendQueue.push(packet);
+    }
+
+    public enqueueEvent<K extends keyof ClientEvents>(event: K, ...args: ClientEvents[K]): void
+    public enqueueEvent(event: EmittedEvent): void
+    public enqueueEvent(event: EmittedEvent, ...args: any[]) {
+        if (typeof event === "string")
+            this.eventQueue.push({
+                event,
+                args: args as any
+            });
+        else
+            this.eventQueue.push(event);
+    }
+
+    public drainMutation() {
+        while (true) {
+            const mutation = this.mutationQueue.shift();
+            if (mutation)
+                mutation(this);
+            else
+                break;
+        }
+    }
+    public drainEvent() {
+        const events = structuredClone(this.eventQueue);
+        this.eventQueue = [];
+        return events;
+    }
+    public drainPacket() {
+        const packets = structuredClone(this.sendQueue);
+        this.sendQueue = [];
+        return packets;
+    }
+}

package/test/adapter/index.ts

@@ -0,0 +1,14 @@
+import { ZodError } from "zod";
+import { VersionDefinitions } from "../../src/version/adapter";
+import { readFileSync } from "node:fs";
+
+const raw = readFileSync("assets/minecraft/26.2/packets.json", { encoding: "utf8" });
+const obj = JSON.parse(raw);
+try {
+    VersionDefinitions.parse(obj);
+} catch (err) {
+    if (err instanceof ZodError) {
+        console.dir(err.issues[0], { depth: null });
+    } else
+        throw err;
+}

package/test/client/index.ts

@@ -4,7 +4,7 @@ const client = new Client({
     playerName: "bot",
     host: "localhost",
     port: 25565,
-    protocolVersion: 776,
+    version: "26.2",
     // debug: {
     //     packetLogger: true
     // },

package/test/json/index.ts

@@ -0,0 +1,3 @@
+import { PacketDefinitions } from "../../src/version/adapter";
+
+console.dir(PacketDefinitions.toJSONSchema({ reused: "ref", target: "openapi-3.0" }), { depth: null });