JSPrismarine

API reference / @jsprismarine/client

@jsprismarine/client ​

Join the Discord Servernpm

Enumerations ​

LoginStage ​

Defined in: client/src/login/LoginSequence.ts:27

How far a login has got. Every step is driven by a packet, never by a timer.

Enumeration Members ​

AUTHENTICATING ​

AUTHENTICATING: 1

Defined in: client/src/login/LoginSequence.ts:29

AWAITING_SPAWN ​

AWAITING_SPAWN: 3

Defined in: client/src/login/LoginSequence.ts:31

FAILED ​

FAILED: 5

Defined in: client/src/login/LoginSequence.ts:33

NEGOTIATING_RESOURCE_PACKS ​

NEGOTIATING_RESOURCE_PACKS: 2

Defined in: client/src/login/LoginSequence.ts:30

REQUESTING_NETWORK_SETTINGS ​

REQUESTING_NETWORK_SETTINGS: 0

Defined in: client/src/login/LoginSequence.ts:28

SPAWNED ​

SPAWNED: 4

Defined in: client/src/login/LoginSequence.ts:32

SendPriority ​

Defined in: client/src/net/ITransport.ts:2

How urgently a payload should leave. Mirrors RakNet's own two levels.

Enumeration Members ​

IMMEDIATE ​

IMMEDIATE: 1

Defined in: client/src/net/ITransport.ts:4

NORMAL ​

NORMAL: 0

Defined in: client/src/net/ITransport.ts:3

Classes ​

Interfaces ​

Behavior ​

Defined in: client/src/bot/behavior/Behavior.ts:27

Something a bot does, once per tick.

Small and composable on purpose: a load test is a question, and the question is usually about one kind of traffic. "Two hundred clients walking" and "two hundred clients chatting" load a server very differently, and being able to ask them separately is worth more than a single realistic-looking simulation that mixes everything.

A behavior must never throw for a reason it could have checked - a bot that dies takes its connection out of the fleet and quietly changes what is being measured.

Properties ​

name ​

readonly name: string

Defined in: client/src/bot/behavior/Behavior.ts:28

Methods ​

tick() ​

tick(context): void | Promise<void>

Defined in: client/src/bot/behavior/Behavior.ts:31

Called on every tick of the bot that owns it.

Parameters ​
context ​

BehaviorContext

Returns ​

void | Promise<void>

BehaviorContext ​

Defined in: client/src/bot/behavior/Behavior.ts:5

Properties ​

bot ​

readonly bot: Bot

Defined in: client/src/bot/behavior/Behavior.ts:6

random ​

readonly random: Random

Defined in: client/src/bot/behavior/Behavior.ts:8

This bot's own generator, derived from the fleet seed and its index.

tick ​

readonly tick: number

Defined in: client/src/bot/behavior/Behavior.ts:10

How many times this bot has ticked since it spawned.

Methods ​

record() ​

record(action): void

Defined in: client/src/bot/behavior/Behavior.ts:13

Counted into the report, so a run can say what it actually did.

Parameters ​
action ​

string

Returns ​

void

send() ​

send(packet): Promise<void>

Defined in: client/src/bot/behavior/Behavior.ts:11

Parameters ​
packet ​

NetworkPacket<any>

Returns ​

Promise<void>

BotOptions ​

Defined in: client/src/bot/Bot.ts:14

Properties ​

behaviors ​

readonly behaviors: readonly Behavior[]

Defined in: client/src/bot/Bot.ts:20

displayName ​

readonly displayName: string

Defined in: client/src/bot/Bot.ts:19

host ​

readonly host: string

Defined in: client/src/bot/Bot.ts:15

logger ​

readonly logger: Logger

Defined in: client/src/bot/Bot.ts:22

loginTimeoutMs? ​

readonly optional loginTimeoutMs?: number

Defined in: client/src/bot/Bot.ts:24

network? ​

readonly optional network?: "raknet" | "nethernet"

Defined in: client/src/bot/Bot.ts:18

Which transport to dial; RakNet by default.

port ​

readonly port: number

Defined in: client/src/bot/Bot.ts:16

random ​

readonly random: Random

Defined in: client/src/bot/Bot.ts:21

viewDistance ​

readonly viewDistance: number

Defined in: client/src/bot/Bot.ts:23

ClientOptions ​

Defined in: client/src/Client.ts:60

Properties ​

auth? ​

readonly optional auth?: IAuthProvider

Defined in: client/src/Client.ts:65

displayName? ​

readonly optional displayName?: string

Defined in: client/src/Client.ts:64

Defaults to an offline identity under this name.

host ​

readonly host: string

Defined in: client/src/Client.ts:61

logger? ​

readonly optional logger?: Logger

Defined in: client/src/Client.ts:66

loginTimeoutMs? ​

readonly optional loginTimeoutMs?: number

Defined in: client/src/Client.ts:74

network? ​

readonly optional network?: "raknet" | "nethernet"

Defined in: client/src/Client.ts:73

Which transport to dial when no ClientOptions.transport is given: RakNet over UDP, the default, or NetherNet, signaled over HTTP on the TCP side of the port.

port? ​

readonly optional port?: number

Defined in: client/src/Client.ts:62

protocolVersion? ​

readonly optional protocolVersion?: number

Defined in: client/src/Client.ts:84

Which protocol to speak. Defaults to PROTOCOL_VERSION.

A server admits one version and refuses every other, so this is only worth setting to reach a server of a version this client does not default to - which is what the Bedrock capture tool does when it records a newer server's data.

Throws ​

Error from the constructor when the version has no layout here.

transport? ​

readonly optional transport?: ITransport

Defined in: client/src/Client.ts:68

Supply one for single player; omit it and the client dials over ClientOptions.network.

DecodedPacket ​

Defined in: client/src/net/ClientPacketRegistry.ts:25

Properties ​

data ​

readonly data: unknown

Defined in: client/src/net/ClientPacketRegistry.ts:28

id ​

readonly id: number

Defined in: client/src/net/ClientPacketRegistry.ts:26

name ​

readonly name: string

Defined in: client/src/net/ClientPacketRegistry.ts:27

FleetOptions ​

Defined in: client/src/bot/Fleet.ts:8

Properties ​

behaviors? ​

readonly optional behaviors?: readonly string[]

Defined in: client/src/bot/Fleet.ts:15

Behavior names, e.g. ['walk', 'chat'].

count ​

readonly count: number

Defined in: client/src/bot/Fleet.ts:13

host ​

readonly host: string

Defined in: client/src/bot/Fleet.ts:9

logger? ​

readonly optional logger?: Logger

Defined in: client/src/bot/Fleet.ts:28

loginTimeoutMs? ​

readonly optional loginTimeoutMs?: number

Defined in: client/src/bot/Fleet.ts:29

namePrefix? ​

readonly optional namePrefix?: string

Defined in: client/src/bot/Fleet.ts:27

Base name; each bot gets its index appended.

network? ​

readonly optional network?: "raknet" | "nethernet"

Defined in: client/src/bot/Fleet.ts:12

Which transport every bot dials; RakNet by default.

port? ​

readonly optional port?: number

Defined in: client/src/bot/Fleet.ts:10

ramp? ​

readonly optional ramp?: number

Defined in: client/src/bot/Fleet.ts:23

How many bots to connect per second.

Not a politeness setting: connecting hundreds at once measures how a server copes with a thundering herd, which is a different question from how it copes with hundreds of players. Ramping lets you ask the second one.

seed? ​

readonly optional seed?: number

Defined in: client/src/bot/Fleet.ts:24

viewDistance? ​

readonly optional viewDistance?: number

Defined in: client/src/bot/Fleet.ts:25

FleetReport ​

Defined in: client/src/bot/Metrics.ts:70

Properties ​

actions ​

actions: Record<string, number>

Defined in: client/src/bot/Metrics.ts:89

connected ​

connected: number

Defined in: client/src/bot/Metrics.ts:75

durationMs ​

durationMs: number

Defined in: client/src/bot/Metrics.ts:72

Wall clock the run covered, in milliseconds.

failed ​

failed: number

Defined in: client/src/bot/Metrics.ts:76

failures ​

failures: object[]

Defined in: client/src/bot/Metrics.ts:78

One entry per distinct failure, with how many bots hit it.

count ​

count: number

reason ​

reason: string

loginLatencyMs ​

loginLatencyMs: LatencySummary

Defined in: client/src/bot/Metrics.ts:80

From the first packet sent to standing in the world.

requested ​

requested: number

Defined in: client/src/bot/Metrics.ts:74

rssBytes ​

rssBytes: number

Defined in: client/src/bot/Metrics.ts:91

Resident set size of this process, which is the harness and not the server.

rttMs ​

rttMs: LatencySummary

Defined in: client/src/bot/Metrics.ts:82

RakNet's smoothed estimate, sampled at the end of the run.

seed ​

seed: number

Defined in: client/src/bot/Metrics.ts:73

traffic ​

traffic: object

Defined in: client/src/bot/Metrics.ts:83

bytesReceived ​

bytesReceived: number

bytesSent ​

bytesSent: number

packetsReceived ​

packetsReceived: number

packetsSent ​

packetsSent: number

ITransport ​

Defined in: client/src/net/ITransport.ts:31

What the client needs from whatever carries its bytes.

The seam that lets single player be the same client as multiplayer: over a network this is RakNet over UDP, and in the same process it is a loopback pair, and nothing above here can tell which. It deliberately sits below batching - a transport moves opaque payloads and knows nothing about compression, encryption or packet ids, all of which belong to the session on top of it.

Properties ​

encrypted? ​

readonly optional encrypted?: boolean

Defined in: client/src/net/ITransport.ts:37

Whether the transport encrypts the wire itself, as NetherNet's DTLS does. A server on such a transport still sends ServerToClientHandshake, as Bedrock Dedicated Server does over NetherNet, but both ends leave batches in the clear. Absent means it does not.

Methods ​

close() ​

close(reason?): void

Defined in: client/src/net/ITransport.ts:47

Parameters ​
reason? ​

string

Returns ​

void

connect() ​

connect(): Promise<void>

Defined in: client/src/net/ITransport.ts:39

Returns ​

Promise<void>

getStats() ​

getStats(): TransportStats

Defined in: client/src/net/ITransport.ts:50

Counters the bot harness reports on; cheap enough to read every tick.

Returns ​

TransportStats

off() ​

off<E>(event, listener): void

Defined in: client/src/net/ITransport.ts:45

Type Parameters ​
E ​

E extends keyof TransportEvents

Parameters ​
event ​

E

listener ​

TransportEvents[E]

Returns ​

void

on() ​

on<E>(event, listener): void

Defined in: client/src/net/ITransport.ts:44

Type Parameters ​
E ​

E extends keyof TransportEvents

Parameters ​
event ​

E

listener ​

TransportEvents[E]

Returns ​

void

send() ​

send(payload, priority?): void

Defined in: client/src/net/ITransport.ts:42

Sends one framed batch.

Parameters ​
payload ​

Buffer

priority? ​

SendPriority

Returns ​

void

LatencySummary ​

Defined in: client/src/bot/Metrics.ts:60

Properties ​

count ​

count: number

Defined in: client/src/bot/Metrics.ts:61

max ​

max: number | null

Defined in: client/src/bot/Metrics.ts:67

mean ​

mean: number | null

Defined in: client/src/bot/Metrics.ts:63

min ​

min: number | null

Defined in: client/src/bot/Metrics.ts:62

p50 ​

p50: number | null

Defined in: client/src/bot/Metrics.ts:64

p95 ​

p95: number | null

Defined in: client/src/bot/Metrics.ts:65

p99 ​

p99: number | null

Defined in: client/src/bot/Metrics.ts:66

LoginResult ​

Defined in: client/src/login/LoginSequence.ts:36

Properties ​

startGame ​

readonly startGame: StartGame

Defined in: client/src/login/LoginSequence.ts:37

LoginSequenceOptions ​

Defined in: client/src/login/LoginSequence.ts:40

Properties ​

protocolVersion ​

readonly protocolVersion: number

Defined in: client/src/login/LoginSequence.ts:41

serverAddress ​

readonly serverAddress: string

Defined in: client/src/login/LoginSequence.ts:43

host:port, as the client reports having dialled it.

timeoutMs? ​

readonly optional timeoutMs?: number

Defined in: client/src/login/LoginSequence.ts:44

PendingDimensionChange ​

Defined in: client/src/DimensionChange.ts:17

A dimension change the server started and this client has not yet closed the screen for.

Properties ​

dimension ​

readonly dimension: number

Defined in: client/src/DimensionChange.ts:19

The Dimension ID the server is moving us to.

loadingScreenId ​

readonly loadingScreenId: number | null

Defined in: client/src/DimensionChange.ts:21

The Loading Screen Id the server expects back, or null when it sent none.

position ​

readonly position: Vector3

Defined in: client/src/DimensionChange.ts:23

Where ChangeDimension said we arrive.

RakNetTransportOptions ​

Defined in: client/src/net/RakNetTransport.ts:9

Properties ​

host ​

readonly host: string

Defined in: client/src/net/RakNetTransport.ts:10

port ​

readonly port: number

Defined in: client/src/net/RakNetTransport.ts:11

timeoutMs? ​

readonly optional timeoutMs?: number

Defined in: client/src/net/RakNetTransport.ts:13

Overall budget for the connection attempt.

TransportEvents ​

Defined in: client/src/net/ITransport.ts:16

Properties ​

batch ​

batch: (payload) => void

Defined in: client/src/net/ITransport.ts:18

One complete Minecraft batch, still framed - id, prefix and all.

Parameters ​
payload ​

Buffer

Returns ​

void

close ​

close: (reason) => void

Defined in: client/src/net/ITransport.ts:19

Parameters ​
reason ​

string

Returns ​

void

TransportStats ​

Defined in: client/src/net/ITransport.ts:7

Properties ​

bytesReceived ​

readonly bytesReceived: number

Defined in: client/src/net/ITransport.ts:11

bytesSent ​

readonly bytesSent: number

Defined in: client/src/net/ITransport.ts:10

packetsReceived ​

readonly packetsReceived: number

Defined in: client/src/net/ITransport.ts:13

packetsSent ​

readonly packetsSent: number

Defined in: client/src/net/ITransport.ts:12

rtt ​

readonly rtt: number | null

Defined in: client/src/net/ITransport.ts:9

Smoothed round trip in milliseconds, or null before the first measurement.

Type Aliases ​

PacketConstructor ​

PacketConstructor = new () => NetworkPacket<any>

Defined in: client/src/net/ClientPacketRegistry.ts:20

A packet class that can be built with no arguments, i.e. for decoding into.

Returns ​

NetworkPacket<any>

Variables ​

BEHAVIORS ​

const BEHAVIORS: Record<string, () => Behavior>

Defined in: client/src/bot/behavior/Behaviors.ts:9

Behaviors by the name the command line uses.

BEHAVIOR_NAMES ​

const BEHAVIOR_NAMES: string[]

Defined in: client/src/bot/behavior/Behaviors.ts:16

MINECRAFT_VERSION ​

const MINECRAFT_VERSION: "1.26.51" = '1.26.51'

Defined in: client/src/Client.ts:45

PROTOCOL_VERSION ​

const PROTOCOL_VERSION: 2193 = v2193.protocolVersion

Defined in: client/src/Client.ts:44

The protocol version this client speaks unless it is told otherwise.

One default, exactly as the server has one. A mismatch is refused by both ends with a message that says which side is behind, which is the least a client owes somebody who cannot connect.

TICK_INTERVAL_MS ​

const TICK_INTERVAL_MS: 50 = 50

Defined in: client/src/bot/Bot.ts:12

The server's own rate, and therefore the rate a client's input is meaningful at.

Functions ​

createBehaviors() ​

createBehaviors(names): Behavior[]

Defined in: client/src/bot/behavior/Behaviors.ts:25

Builds behaviors from a list of names.

Parameters ​

names ​

readonly string[]

as given on the command line, e.g. ['walk', 'chat'].

Returns ​

Behavior[]

Throws ​

when a name is not one of BEHAVIOR_NAMES, rather than silently running a fleet that does less than was asked for - a load test quietly missing half its traffic is worse than one that refuses to start.

formatReport() ​

formatReport(report): string

Defined in: client/src/bot/Metrics.ts:95

Renders a report as a block of aligned text, for a terminal rather than a file.

Parameters ​

report ​

FleetReport

Returns ​

string

References ​

default ​

Renames and re-exports Client