# Transcript

<!-- Solo screen-recorded tutorial uploaded 22 Jan 2021, https://youtu.be/bjanNXXwQbo. Transcribed with ~/code/scripts/call (Gemini 3 Flash Preview), on 17 Oct 2026. Video-relative cumulative timestamps; automatically transcribed and not manually verified. Check exact technical snippets against historical source/tutorial code and the recording before publication. -->

**Anand**: [00:01] Let's talk about how we can connect to Minecraft using WebSockets. So it turns out that **Minecraft has an option to connect to a web server when we are in a game**, and specifically a WebSocket server. And the socket server can send and receive any commands.

**Anand**: [00:19] So, the way commands work in Minecraft is when you type slash, you can type in something like let's say `setblock`, which changes the block from one to the other. So I can say tilda one zero zero—so that's basically just one step away from me towards X—and I can set any type of block. So what we'll do is maybe create a grass block. That's just `grass`. And I can put in more information about that type of grass block, but for now, I'm just going to leave it blank and press enter. So what that's done is placed a block. Okay, I have no idea where it's placed it.

**Anand**: [01:09] Oh right, I gave the command wrong. What I should have done was said tilda zero because that means it's relative to me, whereas it's placing it at an absolute Y and Z of zero. So that, yes, placed a grass block right next to me.

**Anand**: [01:25] So this kind of command can be sent from a Minecraft WebSocket server—sorry, from a WebSocket server to Minecraft and vice versa. Let's talk about how we do this. **I'm going to use Node to run this**. So I've already installed Node.js, which you can get from nodejs.org and select any of the download options that are available here.

**Anand**: [01:54] Now, let's create an application that acts as a WebSocket server. **For this, we need a WebSocket module**. I'm going to use the library that comes with npm, the Node Package Manager, called `ws`. This seems to be a fairly popular WebSocket library. And the way it works is you can require `ws` and create a new WebSocket server with a bunch of parameters, and yeah, that's pretty much it really.

**Anand**: [02:27] So let's install it: `npm install ws`. And that will allow me to require the `ws` package. So we'll copy-paste this code: `const WebSocket = require('ws')`. I don't use semicolons so I'll just get rid of that. And then we'll create a new WebSocket server. The only real thing that it requires is what port we run it on. I'm going to run it on port 3000. No reason, it could be literally any port.

**Anand**: [02:59] And then after that, we have to start the server. Well, actually this would pretty much initiate the server. But we have to tell the server what to do when it gets a connection or when it gets a message and so on. So the way to do that is using the `connection` event. So **when it gets a connection from Minecraft, we can run a function that does whatever we want it to**. For now, I'm just going to `console.log("connected")`.

**Anand**: [03:34] So now with this code, when I run `node mineserver.js`, it's doing nothing, but presumably, the server has started. It'll be good to have a message that says "server started". So let's say `console.log("ready")`. And on Minecraft, what we should do is type `/connect localhost:3000`. That's basically giving ourselves instructions that what we need to do next is on Minecraft, type this as a command.

**Anand**: [04:10] Let's do that. We'll get back into the game and `/connect localhost:3000`. And you'll notice that it said "Connection established to server: ws://localhost:3000". And out here, it says "connected". So which means that **our WebSocket server is ready to send and receive messages**.

**Anand**: [04:30] Now, this, in case you get a message saying "cannot find module ws", that basically means you haven't typed `npm install ws`. That is what's needed to make the first line work. Now, if we want to disconnect, we can send `/connect off`. And that will turn off the message—oh yeah, the chat message says "Connection closed". Now we aren't printing anything on disconnect, so on Node there's just no extra message. But this connection has been disconnected. And we can demonstrate that by adding another connection. So if I reconnect, now it says "Connection established" and out here it says "connected" again.

**Anand**: [05:18] Let's see what we can do next. Supposing the player types a chat message. We want to listen to it. Now, **the WebSocket server can now send a subscribe message to Minecraft saying that it wants to listen to specific actions**. For example, we can subscribe to a message called `PlayerMessage`. And anytime the player sends a chat message, Minecraft will notify our WebSocket client.

**Anand**: [05:43] So here's how we'll do that. What we'll do is in this [connection listener], add a request saying `socket.send`. We want to send a message. Now, messages are sent as JSON strings. So we'll take a JSON object and stringify it. The object should have following information: it should have a `header`—and that's a dictionary—and it should have a `body`. That's also an object.

**Anand**: [06:26] This header should contain the following information: it should contain a `version`, which must always be 1 because we're using version 1 of the messaging protocol. And the `requestId` should be some unique ID. It could be any unique ID. I'm just going to put in 000. But actually, **a good practice would be to automatically generate unique IDs**. A good way of doing that would be using a package called `uuid` which generates unique IDs. And this allows us to use, let's say, `uuid.v4()` as a function that generates unique random IDs like this.

**Anand**: [07:13] In fact, why don't we just go ahead and do that: `npm install uuid`. And with that, I can `const uuid = require('uuid')`. And then we can have this `requestId` to simply be `uuid.v4()`. The third thing that we have to send as part of the header is the `messageType`, which must be "commandRequest" because we are sending a command request. And the fourth thing is `messagePurpose`. Here we say we want to "subscribe" to a message.

**Anand**: [07:53] So what we've told Minecraft is that we're sending a new request in version 1 protocol, which is a command request saying "I want to subscribe to something." What exactly do we want to subscribe to comes in here as `eventName`, which becomes `PlayerMessage`. So we want to subscribe to all player messages. Now, every time the player types something in the chat window, our socket will receive it.

**Anand**: [08:21] Now, how exactly do we receive it? We would say `socket.on` whenever we get any message. We'll call a function and we'll get this as a packet, so let's say some packet, which is really just a string, which we'll process. And let's say `JSON.parse(packet)` that will convert the string back into an object. We'll store it as the message. And for now, let's just print the message: `console.log(message)`.

**Anand**: [08:57] So what this does is it parses all the messages it receives and just prints it. This says whenever the player sends a message, send it to me. Let's run this. We'll run `node mineserver.js`. It says connect to this WebSocket, so we'll connect to the WebSocket in Minecraft: `/connect localhost:3000`. And it's established the connection. And our web server also says "connected", so we're good.

**Anand**: [09:28] Now let's send a message. We'll say "hello". Now we get a huge message printed here. That says the—well let's start with the header. The `messagePurpose` is an "event" which has a `requestId` of zero and `version` 1. And this has the message "hello" which came in as a chat message and a bunch of other things. It says, for example, I'm in biome type 1, which is a plains biome. I am on build 1.16.201 on platforms [inaudible]... which I presume is Bedrock, which is what I'm on. This is my client ID and a whole bunch of things and that I'm on Windows 10.

**Anand**: [10:11] So this allows us now to listen to all of these messages. Now, these messages are in the Minecraft WebSocket protocol, which is actually undocumented. But it turns out that there are a few places on the internet where you can search for this and get some information. So **this is largely about trial and error**.

**Anand**: [10:33] Let's go a step further and we'll start actually adding blocks. What we'll do is when the player sends a message saying, let's say "pyramid". So when we get a packet where the player types a message, say "pyramid 3" or "pyramid 5", we'll draw a pyramid. So how do we do that? Well, we know that the message body will contain a `message` property, which is the text that we typed.

**Anand**: [11:07] So let's do this. Well, and of course we have to make sure that it's a `PlayerMessage` that we actually got. So let's make sure that the event name is `PlayerMessage`. So if `message.body.eventName === 'PlayerMessage'`, then what we can do is create a match to see if we actually got a message that begins with "pyramid". So this will be, let's say, `message.body.properties`. And under these properties, we have a `message`. And let's see if this matches a regular expression that begins with "pyramid". And we can make it case-insensitive.

**Anand**: [12:09] Yeah, let's also say it's "pyramid" followed by a space to create a pyramid of size 2 or "pyramid 5" to create a size of pyramid—create a pyramid of size 5. So we'll put in any number of numbers after that. Now, if we get a match, so that's `if (match)`, what we do is, you know, for now `console.log` "drawing pyramid of size" and this will be `match[1]`.

**Anand**: [12:45] Now let's see if this works. And let's restart the application. We'll connect to Minecraft again and we'll say "pyramid 23". So that says "drawing a pyramid of size 23". Now let's actually draw the pyramid here. So what we'll do instead of `console.log`, we'll create a function `drawPyramid`. And we will send this. Well, since it's a number, we might as well just convert it to a number. And now what the pyramid function should do is actually draw the pyramid. Let's do that.

**Anand**: [13:23] We'll create that function just maybe below here. `function drawPyramid(size)`. This should, let's see. What we'll do is loop through. So if it's size, then let's start from bottom to top. **We'll build the pyramid from the bottom**. So let's say the Y coordinate starts at 0 and goes up to size and keeps on incrementing. So that will be the Y coordinate.

**Anand**: [14:10] Now at Y equals 0, we want to draw a rectangle whose side is well, the full size. At Y equals 1, we want it to be size minus 1. Y equals 2 it'll be size minus 2, and so on. So the `side` is basically the `size` overall of the pyramid minus Y where we are. Now let's actually draw the rectangle. For let's say X we start with minus side and X less than or equal to side, keep incrementing X. And we'll place four blocks: left, right, front, and back.

**Anand**: [14:52] Now for this, what we'll need to do is actually send a set of commands. **How does one go about sending commands to Minecraft? Well, it's actually using a JSON protocol again**. So what we'll do is first create a function called `send` which takes a command. And we'll want to send commands like `setblock`. We'll have to figure out the number. It'll be let's say X. We'll convert this to a template literal. Dollar Y, something like that. And then maybe we'll place a `glowstone` block. We'll also need a dollar Z.

**Anand**: [15:49] So once we create a command like this and we want to send it, the way the command should be sent is we'll create a message first, which is an object, and we'll finally send it as a JSON stringified message. This also requires a header and a body. And the header should contain a `version` which is 1, a `requestId` which should be `uuid.v4()`, some unique uuid, a `messagePurpose` which in our case is going to be again "commandRequest", and it should contain a `messageType` which again is a "commandRequest".

**Anand**: [16:37] The body should contain a `commandLine` which says that this is the command that we want to send. And we can put in an additional information saying where this command comes from is `origin`, specifically a `type` "player". I'm not really sure if this is required; I just am using this from one of the sources that I found on the internet.

**Anand**: [17:08] Once we have this object, this message, we can do a `socket.send`—`socket` is still defined, we're still in the same inner function—so `socket.send(JSON.stringify(message))`. And that should be able to send any command that we want. Now, let's actually send the block positions. What we want is to send something just in front around us with a distance of X and a distance of Y, which is the height. And the Z in this case, let's say minus side, that should cover one part of the rectangle. Then let's put in plus side, that should cover the other half of the rectangle.

**Anand**: [17:58] So that's basically saying where keeping X constant as the side. Then let's send one where we keep X constant as the side at minus side and put it at X and plus side and put it again at X. So that should set four glowstone blocks and sort of build a rectangle around the constant Y. And as the Y keeps increasing, it'll keep building one on top of the other.

**Anand**: [18:29] So let's try our luck. We'll stop this server. We'll run [mineserver] again, connect to it. That's connected. And we'll say "pyramid 3". "pyramid 3". And that closed the connection because `drawPyraid` is not defined. Well, obviously I should make sure that I have an 'n' here. Let's try this again. We'll connect to localhost and that's connected. Let's try saying "pyramid 3" and it didn't do a single thing. We should have been surrounded by a glowstone pyramid. Let's explore what happened.

**Anand**: [19:13] Let's look at what commands we are running. Let's do a `console.log` to see what commands we're actually sending and see if we made a mistake there. Resume the game. Connect again to the localhost and send "pyramid 3". So we're sending okay, a bunch of `setblock`s, so we are sending—okay, so we're sending the X and the Y relative to us, but we forgot to send the Z relative to us. That's a typo. Let's fix that with a tilda here as well and here. So with that, the commands that we send should be better. Let's reconnect and let's...



**Anand**: [19:59] And let’s create a pyramid of size 3. And wow, okay, that has created a glowstone pyramid around us of size 3. Let’s get stuck in it. Let’s break out of it and explore what it looks like.

**Anand**: [20:16] So, as you can see, it started with Y is equal to 0, then 1, then 2, and then went on right to the top, which is the glowstone we broke, and then created the rectangles around it. So, which is cool. What’s also cool is that I get to break this glowstone pyramid, which is a lot of fun. I’m going to break some grass at the bottom, but nonetheless, it’s fun. So, let’s fill the grass.

**Anand**: [20:51] Of course, I could use a command to do this, but personally, I find it satisfying to do this manually. Right.

**Anand**: [21:00] So now we’ve created a pyramid, and that basically means we can well, do anything. Let’s create a bigger pyramid. Let’s create pyramid 5 and see what that does. Wow, we have a pyramid of size 5. Let’s break out of this and go somewhere else and build an even larger pyramid. Well, let’s build a pyramid in mid-air. So, pyramid 10—not quite—pyramid 10. And that—let’s see the whole pyramid now.

**Anand**: [21:42] So, you can see that it’s actually created a huge, massive pyramid out here. Well, that was a very quick introduction into how you can use Minecraft to send messages. Let me do one thing: I’m going to remove this `console.log`, restart the server, and see if I can show you one other thing.

**Anand**: [22:08] Let’s reconnect to the server and now we’re again going to build a pyramid of size 10. Now you’ll notice something. When I removed the `console.log`, it didn’t really print the—it didn’t put the whole pyramid out here. The reason is that **Minecraft isn't as fast as Node, and it only accepts a hundred messages at a time.**

**Anand**: [22:36] When we were doing the `console.log`, the WebSocket server slowed down a bit and printed each command and gave Minecraft enough breathing space to actually process the commands. But what happened now is that once it sent a hundred of these, it got overloaded and choked, and Minecraft was actually sending back responses saying "I can’t execute this command, I can’t execute this command," and so on.

**Anand**: [22:54] Now, we need to handle that. So, **why don't we now listen to more of Minecraft's responses and see what they have to say?** What we’ll do is every time Minecraft sends a message, we’ll log it—specifically, we’ll log it if it sends something called a `commandResponse`. See, we are already listening to the messages and we’re saying if it's a `PlayerMessage`, then do this stuff. But what we’ll do is if the `message.header.messagePurpose` is a "commandResponse" in response to a command request, then let's do a `console.log` of that message.

**Anand**: [23:39] Now, with this, let’s restart and reconnect and create this pyramid again. Now—that didn’t send anything. Maybe because—it did draw this stuff, but it should have sent a set of messages. Let’s look at our text again if the `messagePurpose` is "command"—oh, I got a typo here, it’s "commandResponse". Now this should work. Let’s restart our server and connect to it again and draw a pyramid of size 10.

**Anand**: [24:23] Now, yes. That put in a bunch of messages. Some of those say "This block couldn't be placed." And let's see if there’s any other type of message. "commandResponse" is "block couldn't be placed." Let’s go all the way up. Okay, here we got "Block placed," "Block placed," "Block placed." So it managed to place a bunch of blocks. And then after a point, the block couldn't be placed.

**Anand**: [24:50] Now, the reason this happens is well, because it got overloaded. And you can also get a different kind of a message that says **"Too many commands have been requested and wait for one to be done."**

**Anand**: [25:03] So, here's what we are going to do. **If there are more than a hundred messages, we are going to put it into a queue and just send at most a hundred at a time.** So, how exactly are we going to do that? Well, let’s get rid of this `commandResponse`. We’ll create a couple of constants. Let’s say one is a `sendQueue`, which is an empty list—this is what we’re going to send commands into—and an `awaitedQueue`, which is where we’ll be putting in the responses—meaning, anything that we are going to send we put into `sendQueue`. Anything we've sent but are awaiting a response, we'll put into the `awaitedQueue`.

**Anand**: [25:53] Now, out here well, let’s check what messages we get. If the `message.header.messagePurpose` is the same, "commandResponse". Now notice that we get a `commandResponse` that says "For this particular request ID, I'm sending you a command response and I either couldn't place it—in which case the status code is negative—or I actually could place it, in which case the status code is zero." So we can use that to figure out if it actually managed to place the block or not. And we just wait until some of the blocks have been placed.

**Anand**: [26:27] So, what we’ll do is check if `message.header.requestId`—that’s something that's already in our `awaitedQueue`. If it is, then if the `message.body.statusCode` is less than zero, which basically means if it's an error, then we’ll print the error message: `console.log`. Now what does the error message look like? `commandResponse`—all these are "Block placed". Yeah, so `body.statusMessage`.

**Anand**: [27:04] So we’ll do a—well, let’s also print the command that should have been sent. We’ll get that from the `awaitedQueue`. The `awaitedQueue` will have—based on the request ID, so `message.header.requestId`—that’s where we’ll put it. And then from there, we’ll take its `body.commandLine`. Basically, **all of the messages have a body commandLine which has the actual command.** So we’ll know that this particular command has not been executed, and we’ll also print the exact error that we get: `message.body.statusMessage`. [Anand corrects self] No, not quite. `message.body.statusCode`.

**Anand**: [27:57] So that will print the error message. But in any case, now that we've got a response, either it was successful or not, we can delete from the `awaitedQueue` this particular `message.header.requestId`. Minecraft has said that this request ID has been processed, either unsuccessfully in which case we’ll print it, or successfully in which case we won’t do anything.

**Anand**: [28:22] Now, when we send it as we send commands, let’s not actually directly send them. We’ll put them instead into the `sendQueue`. How exactly do we do that? What we’ll do is modify our function where we’re sending it. Yeah, in `send`, we don't want to actually send it; we’ll just append it to the queue. That we can do by saying `sendQueue.push` and just push the `message` instead of the JSON stringified one.

**Anand**: [29:06] Now, once we’ve processed the command responses, what we’ll do is send whatever pending commands. So let’s say we first figure out how many commands we can send. **The count of commands we can send can be 100 minus the size of the awaitedQueue**, which is basically `Object.keys(awaitedQueue).length`.

**Anand**: [29:32] And of course, this—what if the `awaitedQueue` has—no, actually, yeah, this is the number of commands we can send. But let’s also look at the number of commands we need to send. That’s the `sendQueue` size. So take the minimum of those: `Math.min(sendQueue.length)`. So this is how many we want to send, and this is how many we can send; the minimum of the two is the count.

**Anand**: [29:58] What we’ll do then is for `counter = 0` go until the `count` and send that many commands. The command is basically `sendQueue`'s first item—let's get that using `shift()`, so that’s removed it from `sendQueue`. We’ll send into the `socket` the stringified version of the command. But technically this is a message, so we'll use `message`. Are we using—oh, we’re also already using a constant called `message`. Let’s say command, it’s fine. We’ll go with `command`.

**Anand**: [30:38] And then, we’ll also say that now that we've sent it, the `awaitedQueue` should await this response. `awaitedQueue[command.header.requestId] = command`. So we index it based on the request ID so that when we have received the response, we can clear it from there. And that’s about it. So once we’ve sent all the commands that we can, we wait for the next message and clear it.

**Anand**: [31:06] Let’s run this now. And let’s move up a bit and create a new—escape the pyramid. Let’s go higher up and somewhere else. Now, let’s create a pyramid here. We’ll connect to our WebSocket and we’ll create a pyramid of size 10. And that is creating a larger pyramid even though we—oh, okay, we still are doing `console.log`. That’s odd. Why is it—oh, oh, okay, it’s printing the status code message. Let’s print the message and see what this printed.

**Anand**: [32:02] And just for validation, let me move to a different spot and create the pyramid here. So we’ll restart the server, reconnect, and `pyramid 10`. Okay, that’s created the pyramid and it’s printed a few statements saying "The block couldn’t be placed." Now the reason is my rectangle algorithm wasn’t perfect. What I’m doing is—supposing I want to place X, X, X, X and then an X, X, X, X and so on—I’m not actually—what I’m doing is saying "Place the top row first and the bottom row first, and then I’m also saying place this left row and place this right row."

**Anand**: [32:55] Of course, I’m not saying place anything in the center, so that part vanishes. But **because I'm saying "place this" twice, both as part of the row as well as part of the column, Minecraft's saying "I can't place that glowstone because it's already there."** So that's what's leading to these messages, and it'll be literally one for each corner. So there should be roughly 40, or well, close to 40. For the top, there may be a bit more or less. How many messages do we have? Yeah, we have around 40-odd messages.

**Anand**: [33:24] So this is simply because of the way I’ve structured the pyramid algorithm. But what this means is that **now we can pretty much get Minecraft to take any request from a player, do anything on the player's behalf, and create more interesting worlds.**
