mcproxy [WIP]

a minecraft proxy library powered by mineflayer that replicates data as well as possible from available information of mineflayer

Contribution

This project was inspired by 2bored2wait and now serves as a dependency of it. This project relies heavily on the great work that the awesome people of the PrismarineJS project have done.

Installation

To add this to your project, just install it with your favourite package manager.

npm install @rob9315/mcproxy
# or
yarn add @rob9315/mcproxy
# or
pnpm add @rob9315/mcproxy

API

This project provides the Conn class, which enables you to create a connection to a server and connect clients to the Conn instance. The connection will stay after you disconnect from the Conn instance.

// How to instanciate Conn:
import { Conn } from '@rob9315/mcproxy';
const conn = new Conn(botOptions: mineflayer.BotOptions, options: ConnOptions);

Types and Classes

`BotOptions`

The botOptions which are needed in the constructor of Conn, are the same as the ones from mineflayer itself.

`ConnOptions`

ConnOptions regulate Conn-specific settings.

ConnOptions.events: extra events you can specify that will listen on every pclient that is attached. You can also specify methods in the array that return an event. They can take the Conn and specific pclient as options. The type definition of events looks as such:
```
type ClientEventTuple = [event: string, listener: (...args: any) => void];
type ClientEvents = (ClientEventTuple | ((conn: Conn, pclient: Client) => ClientEventTuple))[];
```
ConnOptions.internalWhitelist: a packet name whitelist for the internal bot. Whitelisted packets are still sent even if a proxyClient is currently linked.
ConnOptions.toServerBlackList: a packet name blacklist for all proxyClients. Blacklisted packets will not be transmitted from the proxyClient to the server.
ConnOptions.toServerBlackList: a packet name blacklist for all proxyClients. Blacklisted packets will not be transmitted from the server to the proxyClient.

`Client` | `pclient`

The Client class is the same as the minecraft-protocol client class with the one exception that it can also contain the following settings used in the Conn class to cause different behaviors.

pclient.toServerWhiteList: a packet name whitelist for the client. Whitelisted packets will still be sent to the server even if the client isn't linked.
pclient.toServerBlackList: a packet name blacklist for the client. Blacklisted packets will not be sent to the server even if the client is linked.
pclient.toClientBlackList: a packet name blacklist for the client. Blacklisted packets will not be sent to the client it it is attached.

`Packet`

A tuple consisting of the name and data of the packet. Reason for this is to be easily used with the .write function of any client.

import type { Packet } from '@rob9315/mcproxy';
const packet: Packet = ['chat', { message: 'Welcome to mcproxy!', position: 0 }];
pclient.write(...packet);

`PacketMeta`

The packet meta. Name is the packet name. State can be play or login (?).

name: string
state: States

`Middleware`

A function to interact with send packets between a connected client and the server.

Arguments:

info - Object that contains meta info about the packet.
- bound - String. Either 'client' or 'server'. Will always be the same depending on If the middleware was attached as a to Client or to Server middleware.
- meta - The PacketMeta off the send packet.
- writeType - Only 'packet' at the moment
pclient - Client. The client this packet belongs to or is destined to.
data - The parsed packet data. See the prismarine data for protocol specific packet data.
cancel - The packet canceler function. If you want cancel a packet you call this function. Also has a isCanceled attribute to check if a packet is already canceled or not. Can be called with the first argument as false to revers an already set canceled attribute to un cancel a packet.
update - The packet updater. If a packet has been changed this function should be called. This can be used to speed up middleware performance by only serializing packets that have been changed. Has an attribute isUpdated to check if the current packet will be treated as updated or not. Can be called with the first argument as false to revers an already set update attribute to un update a packet.

const middlewareFunction: PacketMiddleware = (info, pclient, data: any, cancel) => {
  if (cancel.isCanceled) return // Not necessary but may improve performance when using multiple middleware's after each other
  if (info.meta.name !== 'chat') return
  if (JSON.stringify(data.message).includes('censor')) return cancel() // Cancel all packets that have the word censor in the chat message string
}

`generatePackets()`

import { generatePackets } from '@rob9315/mcproxy';
let packets: Packet[] = generatePackets(bot, pclient?: Client);
packets.forEach((packet)=>pclient.write(...packet));

the internal method used to generate packets from a bot and an optional pclient. If a pclient is provided some aspects of the packets are changed such as the uuid and some version specific changes might be done for compatibility (though not all versions are supported [yet])

`Conn.bot`

the mineflayer Bot integrated into the library, You cannot write with the bot's bot._client.write() method, instead use the Conn.write() method if you need to manually send packets.

`Conn.pclient`

The proxyClient which is able to send packets to the server. Also receives them as a part of the Conn.pclients array. Do not write to this manually

`Conn.pclients`

An array of all proxyClients which are attached to the Connection. Use Conn.attach() to add a client to the array and Conn.detach(), they handle some more things which you'll probably want as well.

`Conn.generatePackets()`

Conn.generatePackets(pclient?: Client): Packet[]

returns the generated packets for the current gamestate

`Conn.sendPackets()`

Conn.sendPackets(pclient: Client);

calls Conn.generatePackets() and sends the result to the proxyClient specified

`Conn.attach()`

Conn.attach(pclient: Client, options?: { toClientMiddleware?: PacketMiddleware[], toServerMiddleware?: PacketMiddleware[] })

pclient - The client to be attached
options - Optional
- toClientMiddleware - Optional. A middleware function array to be used as this clients middle ware to the client. See middleware for a function definition.
- toServerMiddleware - Optional. A middleware function array to be used as this clients middle ware to the server

the pclient specified will be added to the Conn.pclients array and the Conn.receivingPclients, which means that it will receive all packets from the server. If you want the client to be able to send packets to the server as well, don't forget to call Conn.link()

`Conn.detach()`

Conn.detach(pclient: Client)

the pclient specified will be removed from the Conn.pclients array, meaning that it will no longer receive packets from the server. If the client was linked before, Conn.unlink() will also be called.

`Conn.link()`

Conn.link(pclient: Client)

stops the internal bot from sending any packets to the server and starts relaying all packets from the proxyClient to the server.

`Conn.unlink()`

Conn.unlink();

reverses the link method. The bot becomes the one to send packets to the server again. If the proxyClient should be detached as well

`Conn.writeIf()`

Conn.writeIf(name, data);

an internal method for filtering the bots Packets, can be used outside but as an API method basically useless.

`Conn.disconnect()`

disconnects from the server and detaches all pclients

Febzey/mcproxy

mcproxy [WIP]

Contribution

Installation

API

Types and Classes

BotOptions

ConnOptions

Client | pclient

Packet

PacketMeta

Middleware

Arguments:

generatePackets()

Conn.bot

Conn.pclient

Conn.pclients

Conn.generatePackets()

Conn.sendPackets()

Conn.attach()

Conn.detach()

Conn.link()

Conn.unlink()

Conn.writeIf()

Conn.disconnect()