Minestom/.github/README.md

98 lines
5.3 KiB
Markdown
Raw Normal View History

2020-05-03 14:19:06 +02:00
# Minestom
![banner](banner.png)
2019-08-10 05:00:00 +02:00
2020-05-03 14:19:06 +02:00
[![license](https://img.shields.io/github/license/Minestom/Minestom.svg)](../LICENSE)
[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
[![discord-banner](https://discordapp.com/api/guilds/706185253441634317/widget.png?style=banner2)](https://discord.gg/pkFRvqB)
2019-09-07 16:40:56 +02:00
2020-05-03 14:19:06 +02:00
Minestom is an alternative to the popular Minecraft server API called Bukkit.
The main difference is that our implementation of the Notchian server does not contain any features by default!
However, we have a complete API which allows you to make anything possible with current spigot plugins.
This is a developer API not meant to be used by the end-users. Replacing Spigot/Paper with this will **not** work since we do not implement the Bukkit API
2020-05-03 14:19:06 +02:00
# Table of contents
- [Install](#install)
- [Usage](#usage)
- [Why Minestom?](#why-minestom)
- [Advantages & Disadvantages](#advantages-and-disadvantages)
- [API](#api)
2020-08-17 17:28:27 +02:00
- [Credits](#credits)
2020-05-03 14:19:06 +02:00
- [Contributing](#contributing)
- [License](#license)
# Install
Minestom is similar to Bukkit in the fact that it is not a standlone program, it must be expanded upon.
It is the base for interfacing between the server and client.
Our own expanded version for Vanilla can be found [here](https://github.com/Minestom/VanillaReimplementation).
# Usage
2020-05-03 19:25:22 +02:00
An example of how to use the Minestom library is available [here](https://github.com/Minestom/Minestom/tree/master/src/main/java/fr/themode/demo).
Alternatively you can check the official wiki [here](https://github.com/Minestom/Minestom/wiki).
2020-04-08 13:15:48 +02:00
2019-08-10 05:09:05 +02:00
# Why Minestom?
Minecraft evolved a lot since its release, most of the servers today do not take advantage of vanilla features and even have to struggle because of them. Our target audience is those who want to make a completely different server compared to default Minecraft gamemode such as survival or creative building.
The goal is to offer more performance for those who need it, Minecraft being single-threaded is the most important problem for them.
2019-08-10 05:00:00 +02:00
2020-04-15 13:20:28 +02:00
In other words, it makes sense to use Minestom when it takes less time to implement everything you want than removing everything you don't need.
2020-05-03 14:19:06 +02:00
# Advantages and Disadvantages
Minestom isn't perfect, our choices make it much better for some cases, worse for some others.
## Advantages
* Remove the overhead of vanilla features
2020-09-24 05:52:20 +02:00
* Multi-threaded
2020-05-03 14:19:06 +02:00
* Instance system which is much more scalable than worlds
* Open-source
* Modern API
* No more disgusting NMS
## Disadvantages
* Does not work with Bukkit/Spigot plugins
* Does not work with older clients
* Bad for those who want a vanilla experience
* Longer to develop something playable
* Multi-threaded environments are prone to complications
# API
2019-08-10 11:43:21 +02:00
Even if we do not include anything by default in the game, we simplify the way you add them, here is a preview.
## Instances
2019-08-10 11:51:26 +02:00
It is our major concept, worlds are great for survival with friends, but when it scales up it can become unmanageable. The best examples can be found in Skyblock or minigames, not being able to separate each part properly and being forced to save everything in files, not to say the overhead caused by unnecessary data contained in them. Instances are a lightweight solution to it, being able to have every chunk in memory only, copying and sending it to another player in no time, making your serializer and much more...
2019-08-10 11:43:21 +02:00
2019-08-10 11:47:31 +02:00
Being able to create instances directly on the go is a must-have, according to us it can push many more projects forward.
2019-08-10 11:43:21 +02:00
2020-06-22 00:42:37 +02:00
Instances also come with performance benefits, unlike some others which will be fully single-threaded or maybe using one thread per world we are using a set number of threads (pool) to manage all chunks independently from instances, meaning using more CPU power.
2019-08-10 11:43:21 +02:00
## Blocks
2020-04-08 10:10:05 +02:00
Minestom by default does not know what is a chest, you will have to tell him that it opens an inventory.
Every "special blocks" (which aren't only visual) have to be registered, then they can be placed anywhere simply.
However, all blocks are visually there, they just won't have interaction by default.
2019-08-10 11:43:21 +02:00
## Entities
2019-08-10 11:48:01 +02:00
The terms "passive" or "aggressive" monsters do not exist, nobody forbid you from making a flying chicken rushing into any players coming too close, doing so with NMS is a real mess because of obfuscation and the large inheritance.
2019-08-10 11:43:21 +02:00
## Inventories
2019-08-10 11:47:31 +02:00
It is a field where Minecraft evolved a lot, inventories are now used a lot as client<->server interface with clickable items and callback, we support it natively without the need of programming your solution.
2019-08-10 11:43:21 +02:00
## Commands
2019-08-10 11:47:31 +02:00
Commands are the simplest way of communication between clients and server. Since 1.13 Minecraft has incorporated a new library denominated "Brigadier", we then integrated an API meant to use the full potential of args types.
2019-08-10 11:43:21 +02:00
2020-08-17 17:28:27 +02:00
# Credits
* [The Minecraft Coalition](https://wiki.vg/) and [`#mcdevs`](https://github.com/mcdevs) -
protocol and file formats research.
* [The Minecraft Wiki](https://minecraft.gamepedia.com/Minecraft_Wiki) for all their useful info
* [JProfiler](https://www.ej-technologies.com/products/jprofiler/overview.html) for their amazing Java profiler
2020-05-03 14:19:06 +02:00
# Contributing
See [the contributing file](CONTRIBUTING.md)!
All planned features are listed on [Trello](https://trello.com/b/4ysvj5hT/minestom)
# License
This project is licensed under the [Apache License Version 2.0](../LICENSE).
2019-08-10 05:00:00 +02:00