The Shell Shockers game websockets use packet-based communication, which means that data is sent in packets that are structured in a specific way. The yolkbot/comm package provides some utilities to help you work with these packets.

There are 2 ways to communicate, CommIn and CommOut. The CommIn class is used to parse packets the server sends, and the CommOut class is used to create packets to send to the server.

General Information

The communication system goes 2 ways. Theoretically, if you create a server, CommIn and CommOut would be reversed but obviously work on the server with the same general idea. However, the server -> client communication has one big change: it can stack packets.

Packets are stacked when the server has a lot of stuff to relay to the client. This means that instead of sending one packet at a time, it can send multiple packets in one go.

Stacked packets have no clear separator, which requires you to properly read all data on one packet in order to properly read the next packet.

For example, a stacked packet might look like this:

1 49 10 30 29 59 12 48 34 39

This is obviously a small packet, but there's no clear way to tell where one packet ends and the next begins. You have to read the data in order, and know how many bytes each packet is supposed to be.

The CommIn section will better explain how to read this, and the CommOut section will explain how the server creates these packets.

Packets are chiefly separated by CommCodes, which is a numeric code for each event. There are over 50 codes with 12 (at last count) being fully unused. These codes identify the type of packet and allow us to parse the data correctly.

CommIn

The CommIn class is used to parse incoming packets from the Shell Shockers game server. It takes a raw packet as input and parses it into a structured object that you can work with.

import CommIn from 'yolkbot/comm/CommIn';

websocket.onmessage = (event) => {
    const packet = event.data;
    CommIn.init(packet);
};

Once you've init a packet, CommIn can then be used to access the data in the packet. For each packet, the first argument is a CommCode. When packets are stacked, you have to read the data in order, and know how many bytes each packet is supposed to be.

There's no clear way to know how many bytes a packet should be, so we are forced to read the game code to figure this out. For example, to parse a hitMe packet, you would do the following:

import CommIn from 'yolkbot/comm/CommIn';

CommIn.init(packet);

// ...

CommIn.unPackInt8U(); // this would return a CommCode that is hitMe, it doesn't matter atm so we just ignore

const botNewHealth = CommIn.unPackInt8U(); // this would return the new health of the bot
const damageDx = CommIn.unPackFloat(); // for hit indicators
const damageDz = CommIn.unPackFloat();

// then, there might be another packet, so we can read the next CommCode

CommIn.unPackInt8U(); // this would return the next CommCode, which we can then use to parse the next packet
// if we assume this was a spawnItem packet, it'd be read differently

const itemId = CommIn.unPackInt8U(); // the item ID
const itemType = CommIn.unPackInt8U(); // the item type
const itemX = CommIn.unPackFloat(); // the X position of the item
const itemY = CommIn.unPackFloat(); // the Y position of the item
const itemZ = CommIn.unPackFloat(); // the Z position of the item

CommOut

The CommOut class is used to create packets to send to the Shell Shockers game server. It allows you to create structured packets that can be sent over the WebSocket connection.

CommOut is actually a wrapper of the OutBuffer (for some reason, this is how Shell does it). So, the first thing you need to do is get the buffer from CommOut:

import CommOut from 'yolkbot/comm/CommOut';

const out = CommOut.getBuffer();

Once you have the buffer, you can use the various methods to add data to the packet. For example, to create a packet that sends a hitMe event, you would do the following:

import CommCode from 'yolkbot/constants/CommCode';

out.packInt8(CommCode.reload);

If the packet is something like syncMe, where there are arguments, you'd pack those at this point as well:

out.packInt8(CommCode.syncMe);
out.packInt8(1); // you can pack an int8, int16, float, etc. depending on the data type you need
out.packInt16(100);
out.packFloat(200.0);

And then you would send it on the WebSocket connection:

out.send(websocket);

If you are writing a server and are sending data to the client, you would simply pack things "one after another" and then send the buffer. The client will then read the data.

import CommOut from 'yolkbot/comm/CommOut';

const out = CommOut.getBuffer();
out.packInt8(CommCode.hitMe);
out.packInt8(100); // new health
out.packFloat(0.5); // damageDx
out.packFloat(0.5); // damageDz
out.packInt8(CommCode.spawnItem);
out.packInt8(1); // itemId
out.packInt8(2); // itemType
out.packFloat(10.0); // itemX
out.packFloat(20.0); // itemY
out.packFloat(30.0); // itemZ
out.send(websocket);

Note that even one data mistake or typo could cause the entire client to crash and be unable to properly parse packets. Make sure to send packet stuff CAREFULLY.

CommCodes

The CommCode class is a collection of constants that represent the different types of packets that can be sent or received. Each constant corresponds to a specific packet type, and you can use these constants when creating or parsing packets.

import CommCode from 'yolkbot/constants/CommCode';
console.log(CommCode.syncMe);
console.log(CommCode.spawnItem);

CloseCodes

The CloseCode class is a collection of constants that represent the different close codes that can be sent when closing the WebSocket connection. These codes indicate the reason for the closure and can be used to handle different scenarios when the connection is closed.

import CloseCode from 'yolkbot/constants/CloseCode';
console.log(CloseCode.booted);
console.log(CloseCode.locked);

You will also sometimes get the code 1005, which means it closed without a reason. This also happens to be the code when the bot gets its account banned.