Skip to content
Last Updated
Mar 28, 2025, 03:08

Client Module ​

npm versionDownloadsInstall sizenpmBuild Status

Minecraft socket pipeline utilities. Support Minecraft lan server discovery.

Usage ​

Ping Minecraft Server ​

Read sever info (server ip, port) and fetch its status (ping, server motd):

ts
import { queryStatus, Status, QueryOptions } from '@xmcl/client'
const serverInfo = {
    host: 'your host',
    port: 25565, // be default
};
const options: QueryOptions = {
    /**
     * see http://wiki.vg/Protocol_version_numbers
     */
    protocol: 203,
};
const rawStatusJson: Status = await fetchStatus(info, options);

Detect LAN Minecraft Server ​

You can detect if player share LAN server.

Or you can fake a LAN server.

ts
import { MinecraftLanDiscover, LanServerInfo } from '@xmcl/client'
const discover = new MinecraftLanDiscover();

await discover.bind(); // start to listen any lan server

discover.on('discover', ({ motd, port }: LanServerInfo) => {
    console.log(motd); // server motd
    console.log(port); // server port
})

const isReady = discover.isReady // a boolean represent whether the discover is ready to use

// you can also fake a lan server
discover.broadcast({
    motd: 'your motd',
    port: 2384 // fake port
});
// fake LAN server is useful when you want to implement the P2P connection between two players

dicover.destroy(); // stop listening

🧾 Classes ​

🤝 Interfaces ​

🏭 Functions ​

createChannel ​

ts
createChannel(): Channel

Create a channel with Handleshake, ServerQuery, ServerStatus, Ping, Pong packets are registered.

This is a lower level function for the case that you want to use channel directly

Return Type ​

  • Channel

Defined in: packages/client/status.ts:110

createClient ​

ts
createClient(protocol: number, timeout: number): { channel: any; protocol: any; query: any }

Create a query client for certain protocol and timeout setting.

Parameters ​

  • protocol: number The protocol number
  • timeout: number The timeout millisecond

Return Type ​

  • { channel: any; protocol: any; query: any }

Defined in: packages/client/status.ts:157

Field ​

ts
Field(type: Coder<T>): (target: any, key: string) => void

Annotate the field type in your packet. Assign a coder for serialization/deserialization. This will generate a list of FieldType in your class prototype.

Parameters ​

  • type: Coder<T> The coder to serialize/deserialize the field.

Return Type ​

  • (target: any, key: string) => void

Defined in: packages/client/packet.ts:37

getPacketRegistryEntry ​

ts
getPacketRegistryEntry(clazz: (args: any) => any): PacketRegistryEntry

Get a packet registry entry for a class

Parameters ​

  • clazz: (args: any) => any The class object

Return Type ​

  • PacketRegistryEntry

Defined in: packages/client/packet.ts:26

Packet ​

ts
Packet(side: Side, id: number, state: keyof States, name: string= ''): (constructor: (args: any[]) => any) => void

Decoarte for you packet class. This will generate a PacketRegistryEntry in your class prototype.

Parameters ​

  • side: Side The side of your packet
  • id: number The id of your packet
  • state: keyof States The state of you packet should be
  • name: string

Return Type ​

  • (constructor: (args: any[]) => any) => void

Defined in: packages/client/packet.ts:54

queryStatus ​

ts
queryStatus(server: { host: string; port?: number }, options: QueryOptions= {}): Promise<Status>

Query the server status in raw JSON format in one shot.

Parameters ​

  • server: { host: string; port?: number } The server information
  • options: QueryOptions The query options

Return Type ​

  • Promise<Status>

Defined in: packages/client/status.ts:126

🏷️ Variables ​

Bool const ​

ts
Bool: Coder<boolean> = ...

Defined in: packages/client/coders.ts:42

Byte const ​

ts
Byte: Coder<number> = ...

Defined in: packages/client/coders.ts:32

ByteArray const ​

ts
ByteArray: Coder<Int8Array> = ...

Defined in: packages/client/coders.ts:177

Double const ​

ts
Double: Coder<number> = ...

Defined in: packages/client/coders.ts:52

Float const ​

ts
Float: Coder<number> = ...

Defined in: packages/client/coders.ts:47

Int const ​

ts
Int: Coder<number> = ...

Defined in: packages/client/coders.ts:27

Json const ​

ts
Json: Coder<any> = ...

Defined in: packages/client/coders.ts:135

LAN_MULTICAST_ADDR const ​

ts
LAN_MULTICAST_ADDR: "224.0.2.60" = '224.0.2.60'

Defined in: packages/client/lan.ts:4

LAN_MULTICAST_ADDR_V6 const ​

ts
LAN_MULTICAST_ADDR_V6: "FF75:230::60" = 'FF75:230::60'

Defined in: packages/client/lan.ts:5

LAN_MULTICAST_PORT const ​

ts
LAN_MULTICAST_PORT: 4445 = 4445

Defined in: packages/client/lan.ts:6

Long const ​

ts
Long: Coder<bigint> = ...

Defined in: packages/client/coders.ts:112

PacketFieldsMetadata const ​

ts
PacketFieldsMetadata: typeof PacketFieldsMetadata = ...

Defined in: packages/client/packet.ts:20

PacketMetadata const ​

ts
PacketMetadata: typeof PacketMetadata = ...

Defined in: packages/client/packet.ts:19

Short const ​

ts
Short: Coder<number> = ...

Defined in: packages/client/coders.ts:102

Slot const ​

ts
Slot: Coder<SlotData> = ...

Defined in: packages/client/coders.ts:144

String const ​

ts
String: Coder<string> = ...

Defined in: packages/client/coders.ts:123

UByte const ​

ts
UByte: Coder<number> = ...

Defined in: packages/client/coders.ts:37

UShort const ​

ts
UShort: Coder<number> = ...

Defined in: packages/client/coders.ts:107

UUID const ​

ts
UUID: Coder<string> = ...

Defined in: packages/client/coders.ts:57

VarInt const ​

ts
VarInt: Coder<number> = ...

Defined in: packages/client/coders.ts:22

VarLong const ​

ts
VarLong: Coder<bigint> = ...

Defined in: packages/client/coders.ts:117

⏩ Type Aliases ​

FieldType ​

ts
FieldType: (type: Coder<T>) => (target: any, key: string) => void

Defined in: packages/client/packet.ts:16

PacketType ​

ts
PacketType: (side: Side, id: number, state: State) => (constructor: (args: any[]) => any) => void

Defined in: packages/client/packet.ts:17

Side ​

ts
Side: "server" | "client"

Defined in: packages/client/packet.ts:6

State ​

ts
State: keyof States

Defined in: packages/client/channel.ts:9