Skip to content

Commit 5ab6fa9

Browse files
aesthetic0001aesthetic0001
authored
update readme
1 parent b1f9692 commit 5ab6fa9

File tree

1 file changed

+7
-285
lines changed

1 file changed

+7
-285
lines changed

‎docs/README.md‎

Lines changed: 7 additions & 285 deletions
Original file line numberDiff line numberDiff line change
@@ -1,292 +1,14 @@
1-
# Mineflayer
2-
3-
[![NPM version](https://img.shields.io/npm/v/mineflayer.svg?color=success&label=npm%20package&logo=npm)](https://www.npmjs.com/package/mineflayer)
4-
[![Build Status](https://img.shields.io/github/actions/workflow/status/PrismarineJS/mineflayer/ci.yml.svg?label=CI&logo=github&logoColor=lightgrey)](https://github.com/PrismarineJS/mineflayer/actions?query=workflow%3A%22CI%22)
5-
[![Try it on gitpod](https://img.shields.io/static/v1.svg?label=try&message=on%20gitpod&color=brightgreen&logo=gitpod)](https://gitpod.io/#https://github.com/PrismarineJS/mineflayer)
6-
[![Open In Colab](https://img.shields.io/static/v1.svg?label=open&message=on%20colab&color=blue&logo=google-colab)](https://colab.research.google.com/github/PrismarineJS/mineflayer/blob/master/docs/mineflayer.ipynb)
7-
[![GitHub Sponsors](https://img.shields.io/github/sponsors/PrismarineJS)](https://github.com/sponsors/PrismarineJS)
8-
9-
[![Official Discord](https://img.shields.io/static/v1.svg?label=OFFICIAL&message=DISCORD&color=blue&logo=discord&style=for-the-badge)](https://discord.gg/GsEFRM8)
10-
11-
| <sub>EN</sub> [English](README.md) | <sub>RU</sub> [русский](ru/README_RU.md) | <sub>ES</sub> [Español](es/README_ES.md) | <sub>FR</sub> [Français](fr/README_FR.md) | <sub>TR</sub> [Türkçe](tr/README_TR.md) | <sub>ZH</sub> [中文](zh/README_ZH_CN.md) | <sub>BR</sub> [Português](br/README_BR.md) |
12-
|-------------------------|----------------------------|----------------------------|----------------------------|----------------------------|-------------------------|--------------------|
13-
14-
Create Minecraft bots with a powerful, stable, and high level JavaScript [API](api.md), also usable from Python.
15-
16-
First time using Node.js? You may want to start with the [tutorial](tutorial.md). Know Python? Checkout some [Python examples](https://github.com/PrismarineJS/mineflayer/tree/master/examples/python) and try out [Mineflayer on Google Colab](https://colab.research.google.com/github/PrismarineJS/mineflayer/blob/master/docs/mineflayer.ipynb).
17-
18-
## Features
19-
20-
* Supports Minecraft 1.8 to 1.21 (1.8, 1.9, 1.10, 1.11, 1.12, 1.13, 1.14, 1.15, 1.16, 1.17, 1.18, 1.19, 1.20, and 1.21)
21-
* Entity knowledge and tracking.
22-
* Block knowledge. You can query the world around you. Milliseconds to find any block.
23-
* Physics and movement - handle all bounding boxes
24-
* Attacking entities and using vehicles.
25-
* Inventory management.
26-
* Crafting, chests, dispensers, enchantment tables.
27-
* Digging and building.
28-
* Miscellaneous stuff such as knowing your health and whether it is raining.
29-
* Activating blocks and using items.
30-
* Chat.
31-
32-
### Roadmap
33-
34-
Checkout [this page](https://github.com/PrismarineJS/mineflayer/wiki/Big-Prismarine-projects) to see what our current projects are.
1+
# Mineflayer with Anticheat Compliance
352

363
## Installation
374

38-
First install Node.js >= 18 from [nodejs.org](https://nodejs.org/) then:
39-
40-
```bash
41-
npm install mineflayer
42-
```
43-
44-
To update mineflayer (or any Node.js) package and its dependencies, use
45-
```bash
46-
npm update
47-
```
48-
49-
## Documentation
50-
51-
| link | description |
52-
|---|---|
53-
|[tutorial](tutorial.md) | Begin with Node.js and mineflayer |
54-
| [FAQ.md](FAQ.md) | Got a question ? go there first |
55-
| **[api.md](api.md)** <br/>[unstable_api.md](unstable_api.md) | The full API reference |
56-
| [history.md](history.md) | The changelog for mineflayer |
57-
| [examples/](https://github.com/PrismarineJS/mineflayer/tree/master/examples) | Checkout all the mineflayer examples |
58-
59-
60-
## Contribute
61-
62-
Please read [CONTRIBUTING.md](CONTRIBUTING.md) and [prismarine-contribute](https://github.com/PrismarineJS/prismarine-contribute)
63-
64-
## Usage
65-
66-
**Videos**
67-
68-
A tutorial video explaining the basic set up process for a bot can be found [here.](https://www.youtube.com/watch?v=ltWosy4Z0Kw)
69-
70-
If you want to learn more, more video tutorials are [there,](https://www.youtube.com/playlist?list=PLh_alXmxHmzGy3FKbo95AkPp5D8849PEV) and the corresponding source codes for those bots is [there.](https://github.com/TheDudeFromCI/Mineflayer-Youtube-Tutorials)
71-
72-
[<img src="https://img.youtube.com/vi/ltWosy4Z0Kw/0.jpg" alt="tutorial 1" width="200">](https://www.youtube.com/watch?v=ltWosy4Z0Kw)
73-
[<img src="https://img.youtube.com/vi/UWGSf08wQSc/0.jpg" alt="tutorial 2" width="200">](https://www.youtube.com/watch?v=UWGSf08wQSc)
74-
[<img src="https://img.youtube.com/vi/ssWE0kXDGJE/0.jpg" alt="tutorial 3" width="200">](https://www.youtube.com/watch?v=ssWE0kXDGJE)
75-
[<img src="https://img.youtube.com/vi/walbRk20KYU/0.jpg" alt="tutorial 4" width="200">](https://www.youtube.com/watch?v=walbRk20KYU)
76-
77-
**Getting Started**
78-
79-
Without a version specified, the version of the server will be guessed automatically.
80-
Without auth specified, the mojang auth style will be guessed.
81-
82-
### Echo Example
83-
```js
84-
const mineflayer = require('mineflayer')
85-
86-
const bot = mineflayer.createBot({
87-
host: 'localhost', // minecraft server ip
88-
username: 'Bot', // username to join as if auth is `offline`, else a unique identifier for this account. Switch if you want to change accounts
89-
auth: 'microsoft' // for offline mode servers, you can set this to 'offline'
90-
// port: 25565, // set if you need a port that isn't 25565
91-
// version: false, // only set if you need a specific version or snapshot (ie: "1.8.9" or "1.16.5"), otherwise it's set automatically
92-
// password: '12345678' // set if you want to use password-based auth (may be unreliable). If specified, the `username` must be an email
93-
})
94-
95-
bot.on('chat', (username, message) => {
96-
if (username === bot.username) return
97-
bot.chat(message)
98-
})
99-
100-
// Log errors and kick reasons:
101-
bot.on('kicked', console.log)
102-
bot.on('error', console.log)
1035
```
104-
105-
If `auth` is set to `microsoft`, you will be prompted to login to microsoft.com with a code in your browser. After signing in on your browser,
106-
the bot will automatically obtain and cache authentication tokens (under your specified username) so you don't have to sign-in again.
107-
108-
To switch the account, update the supplied `username`. By default, cached tokens will be stored in your user's .minecraft folder, or if `profilesFolder` is specified, they'll instead be stored there.
109-
For more information on bot options see node-minecraft-protocol's [API doc](https://github.com/PrismarineJS/node-minecraft-protocol/blob/master/docs/API.md#mccreateclientoptions).
110-
111-
#### Connecting to a Realm
112-
113-
To join a Realm that your Minecraft account has been invited to, you can pass a `realms` object with a selector function like below.
114-
115-
```js
116-
const client = mineflayer.createBot({
117-
username: '[email protected]', // minecraft username
118-
realms: {
119-
// This function is called with an array of Realms the account can join. It should return the one it wants to join.
120-
pickRealm: (realms) => realms[0]
121-
},
122-
auth: 'microsoft'
123-
})
124-
```
125-
126-
### See what your bot is doing
127-
128-
Thanks to the [prismarine-viewer](https://github.com/PrismarineJS/prismarine-viewer) project, it's possible to display in a browser window what your bot is doing.
129-
Just run `npm install prismarine-viewer` and add this to your bot:
130-
```js
131-
const { mineflayer: mineflayerViewer } = require('prismarine-viewer')
132-
bot.once('spawn', () => {
133-
mineflayerViewer(bot, { port: 3007, firstPerson: true }) // port is the minecraft server port, if first person is false, you get a bird's-eye view
134-
})
6+
npm i github:binmasterdotpro/mineflayer#master
1357
```
136-
And you'll get a *live* view looking like this:
137-
138-
[<img src="https://prismarinejs.github.io/prismarine-viewer/test_1.16.1.png" alt="viewer" width="500">](https://prismarinejs.github.io/prismarine-viewer/)
139-
140-
#### More Examples
141-
142-
| example | description |
143-
|---|---|
144-
|[viewer](https://github.com/PrismarineJS/mineflayer/tree/master/examples/viewer) | Display your bot world view in the browser |
145-
|[pathfinder](https://github.com/PrismarineJS/mineflayer/tree/master/examples/pathfinder) | Make your bot go to any location automatically |
146-
|[chest](https://github.com/PrismarineJS/mineflayer/blob/master/examples/chest.js) | Use chests, furnaces, dispensers, enchantment tables |
147-
|[digger](https://github.com/PrismarineJS/mineflayer/blob/master/examples/digger.js) | Learn how to create a simple bot that is capable of digging blocks |
148-
|[discord](https://github.com/PrismarineJS/mineflayer/blob/master/examples/discord.js) | Connect a discord bot with a mineflayer bot |
149-
|[jumper](https://github.com/PrismarineJS/mineflayer/blob/master/examples/jumper.js) | Learn how to move, jump, ride vehicles, attack nearby entities |
150-
|[ansi](https://github.com/PrismarineJS/mineflayer/blob/master/examples/ansi.js) | Display your bot's chat with all of the chat colors shown in your terminal |
151-
|[guard](https://github.com/PrismarineJS/mineflayer/blob/master/examples/guard.js) | Make a bot guard a defined area from nearby mobs |
152-
|[multiple-from-file](https://github.com/PrismarineJS/mineflayer/blob/master/examples/multiple_from_file.js) | Add a text file with accounts and have them all login |
153-
154-
And many more in the [examples](https://github.com/PrismarineJS/mineflayer/tree/master/examples) folder.
1558

156-
### Modules
157-
158-
A lot of the active development is happening inside of small npm packages which are used by mineflayer.
159-
160-
#### The Node Way&trade;
161-
162-
> "When applications are done well, they are just the really application-specific, brackish residue that can't be so easily abstracted away. All the nice, reusable components sublimate away onto github and npm where everybody can collaborate to advance the commons." — substack from ["how I write modules"](https://gist.github.com/substack/5075355)
163-
164-
#### Modules
165-
166-
These are the main modules that make up mineflayer:
167-
168-
| module | description |
169-
|---|---|
170-
| [minecraft-protocol](https://github.com/PrismarineJS/node-minecraft-protocol) | Parse and serialize minecraft packets, plus authentication and encryption.
171-
| [minecraft-data](https://github.com/PrismarineJS/minecraft-data) | Language independent module providing minecraft data for minecraft clients, servers and libraries.
172-
| [prismarine-physics](https://github.com/PrismarineJS/prismarine-physics) | Provide the physics engine for minecraft entities
173-
| [prismarine-chunk](https://github.com/PrismarineJS/prismarine-chunk) | A class to hold chunk data for Minecraft
174-
| [node-vec3](https://github.com/PrismarineJS/node-vec3) | 3d vector math with robust unit tests
175-
| [prismarine-block](https://github.com/PrismarineJS/prismarine-block) | Represent a minecraft block with its associated data
176-
| [prismarine-chat](https://github.com/PrismarineJS/prismarine-chat) | A parser for a minecraft chat message (extracted from mineflayer)
177-
| [node-yggdrasil](https://github.com/PrismarineJS/node-yggdrasil) | Node.js library to interact with Mojang's authentication system, known as Yggdrasil
178-
| [prismarine-world](https://github.com/PrismarineJS/prismarine-world) | The core implementation of worlds for prismarine
179-
| [prismarine-windows](https://github.com/PrismarineJS/prismarine-windows) | Represent minecraft windows
180-
| [prismarine-item](https://github.com/PrismarineJS/prismarine-item) | Represent a minecraft item with its associated data
181-
| [prismarine-nbt](https://github.com/PrismarineJS/prismarine-nbt) | An NBT parser for node-minecraft-protocol
182-
| [prismarine-recipe](https://github.com/PrismarineJS/prismarine-recipe) | Represent minecraft recipes
183-
| [prismarine-biome](https://github.com/PrismarineJS/prismarine-biome) | Represent a minecraft biome with its associated data
184-
| [prismarine-entity](https://github.com/PrismarineJS/prismarine-entity) | Represent a minecraft entity
185-
186-
187-
### Debug
188-
189-
You can enable some protocol debugging output using `DEBUG` environment variable:
190-
191-
```bash
192-
DEBUG="minecraft-protocol" node [...]
193-
```
194-
195-
On windows :
196-
```
197-
set DEBUG=minecraft-protocol
198-
node your_script.js
199-
```
200-
201-
## Third Party Plugins
202-
203-
Mineflayer is pluggable; anyone can create a plugin that adds an even
204-
higher level API on top of Mineflayer.
205-
206-
The most updated and useful are :
207-
208-
* [minecraft-mcp-server](https://github.com/yuniko-software/minecraft-mcp-server) A MCP server for mineflayer, allowing using mineflayer from an LLM
209-
* [pathfinder](https://github.com/Karang/mineflayer-pathfinder) - advanced A* pathfinding with a lot of configurable features
210-
* [prismarine-viewer](https://github.com/PrismarineJS/prismarine-viewer) - simple web chunk viewer
211-
* [web-inventory](https://github.com/ImHarvol/mineflayer-web-inventory) - web based inventory viewer
212-
* [statemachine](https://github.com/PrismarineJS/mineflayer-statemachine) - A state machine API for more complex bot behaviors
213-
* [Armor Manager](https://github.com/G07cha/MineflayerArmorManager) - automatic armor management
214-
* [Dashboard](https://github.com/wvffle/mineflayer-dashboard) - Frontend dashboard for mineflayer bot
215-
* [PVP](https://github.com/PrismarineJS/mineflayer-pvp) - Easy API for basic PVP and PVE.
216-
* [Auto Eat](https://github.com/link-discord/mineflayer-auto-eat) - Automatic eating of food.
217-
* [Auto Crystal](https://github.com/link-discord/mineflayer-autocrystal) - Automatic placing & breaking of end crystals.
218-
* [Tool](https://github.com/TheDudeFromCI/mineflayer-tool) - A utility for automatic tool/weapon selection with a high level API.
219-
* [Hawkeye](https://github.com/sefirosweb/minecraftHawkEye) - A utility for using auto-aim with bows.
220-
* [GUI](https://github.com/firejoust/mineflayer-GUI) - Interact with nested GUI windows using async/await
221-
* [Projectile](https://github.com/firejoust/mineflayer-projectile) - Get the required launch angle for projectiles
222-
* [Movement](https://github.com/firejoust/mineflayer-movement) - Smooth and realistic player movement, best suited for PvP
223-
* [Collect Block](https://github.com/PrismarineJS/mineflayer-collectblock) - Quick and simple block collection API.
224-
225-
But also check out :
226-
227-
* [radar](https://github.com/andrewrk/mineflayer-radar/) - web based radar
228-
interface using canvas and socket.io. [YouTube Demo](https://www.youtube.com/watch?v=FjDmAfcVulQ)
229-
* [auto-auth](https://github.com/G07cha/MineflayerAutoAuth) - chat-based bot authentication
230-
* [Bloodhound](https://github.com/Nixes/mineflayer-bloodhound) - determine who and what is responsible for damage to another entity
231-
* [tps](https://github.com/SiebeDW/mineflayer-tps) - get the current tps (processed tps)
232-
* [panorama](https://github.com/IceTank/mineflayer-panorama) - take Panorama Images of your world
233-
* [player-death-event](https://github.com/tuanzisama/mineflayer-death-event) - emit player death event in Mineflayer.
234-
235-
## Projects Using Mineflayer
236-
237-
* [Voyager](https://github.com/MineDojo/Voyager) An Open-Ended Embodied Agent with Large Language Models
238-
* [mindcraft](https://github.com/kolbytn/mindcraft) Lib for using mineflayer with LLMs
239-
* [rom1504/rbot](https://github.com/rom1504/rbot)
240-
- [YouTube - building a spiral staircase](https://www.youtube.com/watch?v=UM1ZV5200S0)
241-
- [YouTube - replicating a building](https://www.youtube.com/watch?v=0cQxg9uDnzA)
242-
* [Darthfett/Helperbot](https://github.com/Darthfett/Helperbot)
243-
* [vogonistic/voxel](https://github.com/vogonistic/mineflayer-voxel) - visualize what
244-
the bot is up to using voxel.js
245-
* [JonnyD/Skynet](https://github.com/JonnyD/Skynet) - log player activity onto an online API
246-
* [MinecraftChat](https://github.com/rom1504/MinecraftChat) (last open source version, built by AlexKvazos) - Minecraft web based chat client
247-
* [Cheese Bot](https://github.com/Minecheesecraft/Cheese-Bot) - Plugin based bot with a clean GUI. Made with Node-Webkit.
248-
* [Chaoscraft](https://github.com/schematical/chaoscraft) - Minecraft bot using genetic algorithms, see [its youtube videos](https://www.youtube.com/playlist?list=PLLkpLgU9B5xJ7Qy4kOyBJl5J6zsDIMceH)
249-
* [hexatester/minetelegram](https://github.com/hexatester/minetelegram) - Minecraft - Telegram bridge, build on top of mineflayer & telegraf.
250-
* [PrismarineJS/mineflayer-builder](https://github.com/PrismarineJS/mineflayer-builder) - Prints minecraft schematics in survival, keeping orientation
251-
* [SilkePilon/OpenDeliveryBot](https://github.com/SilkePilon/OpenDeliveryBot) - Minecraft bot in python to deliver items from place to place.
252-
* [and hundreds more](https://github.com/PrismarineJS/mineflayer/network/dependents) - All the projects that github detected are using mineflayer
253-
254-
255-
## Testing
256-
257-
### Testing everything
258-
259-
Simply run:
260-
261-
```bash
262-
npm test
263-
```
264-
265-
### Testing specific version
266-
Run
267-
268-
```bash
269-
npm run mocha_test -- -g <version>
270-
```
271-
272-
where `<version>` is a minecraft version like `1.12`, `1.15.2`...
273-
274-
### Testing specific test
275-
Run
276-
277-
```bash
278-
npm run mocha_test -- -g <test_name>
279-
```
280-
281-
where `<test_name>` is a name of the test like `bed`, `useChests`, `rayTrace`...
282-
283-
### Example
284-
285-
```bash
286-
npm run mocha_test -- -g "1.18.1.*BlockFinder"
287-
```
288-
to run the block finder test for 1.18.1
289-
290-
## License
9+
## Features
29110

292-
[MIT](/LICENSE)
11+
* Everything from [mineflayer](https://github.com/PrismarineJS/mineflayer) (except version compatibility guarantee. this package has been mostly tested on 1.8.9 and 1.21.5 servers)
12+
* Fixes for 1.8.9 & 1.21.5 anticheat compliance, with a fork of node-minecraft-protocol to fix peculiarities in 1.21.5
13+
* Passes Grim's simulation checks (only tested on 1.8.9)
14+
* Works on Hypixel out of the box

0 commit comments

Comments
 (0)