Merge remote-tracking branch 'origin/master'

README.md

@@ -17,7 +17,7 @@ The next-generation Minecraft: Bedrock Edition server software
 <a href="https://feedback.minecraft.net/hc/en-us/sections/360001186971-Release-Changelogs"><img src="https://img.shields.io/badge/minecraft-v1.20.81%20(Bedrock)-green" /></a>
 <img src="https://img.shields.io/badge/protocol-662-blue">
 
-English | [简体中文](README.zh.md)
+English | [简体中文](README.zh.md) | [Русский](README.ru.md)
 </div>
 
 ## Introduction

README.ru.md

@@ -0,0 +1,134 @@
+<!-- PROJECT LOGO -->
+<br/>
+<div align="center">
+
+<a href="https://github.com/AllayMC/Allay">
+    <img src="docs/assets/logo/allay-chan-640x.png" alt="Logo" width="200" height="200">
+</a>
+<h3 align="center">Allay</h3>
+
+Серверное программное обеспечение для Minecraft: Bedrock Edition нового поколения
+
+<a href="https://github.com/AllayMC/Allay/actions"><img src="https://github.com/AllayMC/Allay/actions/workflows/gradle.yml/badge.svg" alt="Build"/></a>
+<a href="https://docs.allaymc.org/zh"><img src="https://readthedocs.org/projects/allaymc/badge/?version=latest" alt="Documentation Status"></a>
+[![codecov](https://codecov.io/gh/AllayMC/Allay/graph/badge.svg?token=EI8EDEKI51)](https://codecov.io/gh/AllayMC/Allay)
+<a href="https://app.codacy.com/gh/AllayMC/Allay/dashboard"><img src="https://app.codacy.com/project/badge/Grade/30e264923da2425a8b777a84b4028334"></a>
+<a href="https://discord.gg/ngkkE4hPTU"><img src="https://img.shields.io/discord/1147136608290750526?label=discord&color=7289DA&logo=discord" alt="Discord" /></a>
+<a href="https://feedback.minecraft.net/hc/en-us/sections/360001186971-Release-Changelogs"><img src="https://img.shields.io/badge/minecraft-v1.20.81%20(Bedrock)-green" /></a>
+<img src="https://img.shields.io/badge/protocol-662-blue">
+
+[English](README.md) | [简体中文](README.zh.md) | Русский
+</div>
+
+## Введение
+
+[//]: # (Allay - самое миленькое программное обеспечение в мире!)
+
+Allay - это серверное программное обеспечение сторонних разработчиков для Minecraft: Bedrock Edition, написанное на
+Java, с целью обеспечения высокой производительности при сохранении высокой расширяемости благодаря тщательно
+разработанной архитектуре. Для получения дополнительной информации ознакомьтесь с нашей [Q&A](docs/Q&A.zh.md)
+
+> [!IMPORTANT]
+> Обратите внимание, что этот проект находится на очень ранней стадии и еще не выпущен в стабильной версии. Многие
+> интерфейсы могут быть добавлены или удалены без предварительного уведомления. Пожалуйста, не используйте Allay в
+> производственной среде.
+>
+> Вы можете просмотреть наш RoadMap, чтобы узнать о ходе разработки.
+
+## Название
+
+Как вы могли заметить, наш проект называется Allay, что является именем одного из существ в Minecraft.
+
+Мы надеемся, что этот проект будет таким же простым, надежным и эффективным, как и Allay.
+
+## Особенности
+
+- **Кроссплатформенность:** Allay работает на JVM, поэтому может запускаться на большинстве платформ, поддерживающих
+  JVM.
+- **Высокая производительность:**
+    - Мы полностью понимаем проблемы серверов на базе Nukkit в условиях высокой нагрузки. Allay показывает почти
+      стократное улучшение производительности в определенных аспектах (например, физика entity) при такой же нагрузке.
+    - Кроме того, благодаря переработанной модели потоков, Allay может эффективно использовать многоядерные процессоры.
+      Это означает, что вам не нужно специально использовать процессоры с высокой тактовой частотой.
+    - Allay использует Java 21, что теоретически обеспечивает лучшую производительность.
+- **Простота использования:**
+    - Вы можете писать плагины для Allay на языках Java/JVM.
+    - Мы добавили поддержку GraalVM и JavaScript, что позволяет писать плагины на JavaScript/TypeScript с той же
+      производительностью и бесшовной интероперабельностью, как и на Java.
+- **Высокая настраиваемость:** Allay предоставляет множество интерфейсов, которых нет в BDS. Кроме того, вы даже можете
+  контролировать отправку пакетов для максимальной настраиваемости.
+- **Безопасность:**
+    - В сравнении с BDS, Allay проводит больше проверок пакетов от клиента, что теоретически устраняет многие
+      уязвимости, присущие BDS.
+    - Allay по умолчанию включает шифрование сети. Кроме того, в Allay встроена функция шифрования ресурсных пакетов,
+      которая автоматически шифрует ресурсные пакеты, отправляемые клиенту, что в определенной степени защищает ваши
+      данные от утечек.
+- **Множество новых функций:** В отличие от серверов на базе Nukkit, Allay использует множество новых функций протокола,
+  уже введенных в BDS, включая серверную авторизацию инвентаря, отправку подблоков и многое другое.
+- **Качество кода:** Мы уделяем большое внимание качеству кода и поддерживаем стабильность проекта с помощью множества
+  юнит-тестов и рефакторинга.
+
+## Начало работы
+
+Allay основан на Java 21, поэтому перед запуском и сборкой Allay вам нужно установить Java 21.
+Если у вас есть потребность в разработке скриптов для плагинов, мы рекомендуем использовать GraalVM для достижения
+наилучшей производительности.
+
+**Прямой запуск:**
+
+```shell
+gradlew Allay-Server:runShadow
+```
+
+**Сборка:**
+
+```shell
+gradlew Allay-Server:build
+```
+
+## Плагины
+
+Allay поддерживает плагины, написанные на языках Java/JVM или JavaScript. Вы можете ознакомиться с примерами плагинов,
+чтобы понять, как начать:
+
+**Пример на Java**: [Allay-ExamplePlugin](Allay-ExamplePlugin)
+
+**Пример на JavaScript**: [@Allay-ExamplePlugin-JS](@Allay-ExamplePlugin-JS)
+
+Для получения дополнительной информации посетите нашу [документацию](https://docs.allaymc.org/zh/).
+
+## Участие в проекте
+
+Прежде чем отправить PR, пожалуйста, прочтите [CONTRIBUTING.md](CONTRIBUTING.md)
+
+Этот проект существует благодаря участию следующих разработчиков:
+
+![contributors](https://contrib.rocks/image?repo=AllayMC/Allay)
+
+## Покрытие кода
+
+Помогите нам улучшить юнит-тесты! Юнит-тестирование способствует развитию этого проекта.
+
+![Codecov Graph](https://codecov.io/gh/AllayMC/Allay/graphs/sunburst.svg?token=EI8EDEKI51)
+
+## Обратная связь
+
+Ваши отзывы помогут сделать этот проект лучше. Если вы обнаружили проблему или у вас есть новая идея, пожалуйста,
+сообщите об этом на странице [issues](https://github.com/AllayMC/Allay/issues).
+
+Для обсуждения других вопросов присоединяйтесь к нашему Discord-сообществу.
+
+## Звезды!
+
+[![Stargazers over time](https://starchart.cc/AllayMC/Allay.svg)](https://starchart.cc/AllayMC/Allay)
+
+## Лицензия
+
+Все права защищены **© 2023-2024 AllayMC**.
+
+Если не указано иное, содержимое проекта лицензировано по LGPL-3.0.
+
+Содержимое следующих папок лицензировано по MIT:
+
+- Allay-Data
+- Allay-CodeGen

README.zh.md

@@ -17,7 +17,7 @@
 <a href="https://feedback.minecraft.net/hc/en-us/sections/360001186971-Release-Changelogs"><img src="https://img.shields.io/badge/minecraft-v1.20.81%20(Bedrock)-green" /></a>
 <img src="https://img.shields.io/badge/protocol-662-blue">
 
-[English](README.md) | 简体中文
+[English](README.md) | 简体中文 | [Русский](README.ru.md)
 </div>
 
 ## 介绍

docs/core_and_architecture/about_the_chunk_lagging_issue.md

@@ -2,8 +2,6 @@
 comments: true
 ---
 
-**This article need to be updated**
-
 Block freezing has been an issue for a long time, and we have been looking for the root cause and solutions. Below is a
 summary of the current progress.
 
@@ -78,3 +76,12 @@ Both incorrect chunk packets and excessively high chunk packet sending rates can
 above understanding, limiting the sending rate of chunk packets is an effective method, provided that the chunk packet
 encoding is correct. By lowering the value of `world-settings.chunk-try-send-count-per-tick`, we found that the block
 freezing issue almost disappeared.
+
+## 2024/5/31 Supplement
+
+It seems that the incorrect order of chunk sending can also cause block freezing. Chunks close to the player **must** be
+sent first. If a distant chunk is sent while skipping an unsent closer chunk, the skipped chunk is very likely to
+freeze.
+
+This indicates that asynchronous chunk sending cannot simply be made asynchronous. The best approach is to create a
+separate chunk sending thread to ensure the correct order of chunk sending.

docs/core_and_architecture/coding_specifications.md

@@ -0,0 +1,147 @@
+---
+comments: true
+---
+
+[//]: # (PS: Further discussion needed)
+
+[//]: # (The project coding standard is generally based on [Google's Java coding standard](https://google.github.io/styleguide/javaguide.html), but there may be differences in some aspects)
+
+## Prohibition of using @NotNull and @Nullable annotations
+
+Previously, our project used a large number of such annotations, but later we noticed that the benefits of these
+annotations were very limited, while the disadvantages were very obvious.
+
+Specifically, these annotations can only serve as identifiers and cannot provide any compile-time checks.
+
+In addition, we noticed that the false positive rate of IntelliJ IDEA is very high: the editor cannot perform advanced
+semantic analysis, resulting in yellow warnings in some points where problems are impossible, causing great confusion.
+
+Therefore, we stipulate that the use of @NotNull and @Nullable annotations is prohibited under any circumstances.
+
+## Use of @Range
+
+@Range is also a purely identifying annotation, which can provide range checks for numerical parameters in the IDE.
+However, please note that @Range itself does not provide any real checks, and you still need to add checking code.
+
+```java
+public void setBlockInChunk(@Range(min = 0, max = 15) int x, @Range(min = 0, max = 15) int y, int z, BlockState block) {
+    // Assuming that the values of x and z here should be in the range [0, 15]
+    if (x < 0 || x > 15) error();
+    if (z < 0 || z > 15) error();
+    // ...
+}
+```
+
+We stipulate:
+
+- @Range annotation must be used together with explicit code checking, that is, @Range must not be used alone (to avoid
+  giving callers the misconception that "the @Range annotation ensures everything").
+- For methods with parameter ranges or other restrictions, explicit checks must be performed inside the method body. For
+  numerical parameters, it is recommended to use @Range annotation together.
+
+## Class comments
+
+Allay requires certain information to be marked on each class file in a certain format, here is an example:
+
+```java
+/**
+ * Allay Project 2024/6/1
+ *
+ * @author daoge_cmd
+ */
+class XXX {
+
+}
+```
+
+## Reduce nesting levels
+
+This is an age-old problem. Excessive nesting in code greatly reduces readability, while reducing nesting levels can
+bring great benefits.
+Here are some commonly used methods to reduce nesting levels:
+
+### Guard Clauses
+
+Guard clauses are a programming technique that splits complex conditional expressions into multiple simpler ones,
+reducing nesting.
+If a conditional statement is extremely complex, it should be broken down into individual checks, and the function
+should immediately return from the function when the condition is true. Such individual checks are often called "guard
+clauses".
+The effect of guard clauses is to organize the original code that requires careful reading and careful logic arrangement
+into logical relationships that can be seen through at a glance.
+
+For example:
+
+Original code:
+
+```java
+public static void main(String[] args) {
+    for (int i = 1; i <= 100; i++) {
+        if (i % 3 == 0) {
+            if (i % 4 == 0) {
+                if (i % 5 == 0) {
+                    System.out.println(i);
+                }
+            }
+        }
+    }
+}
+```
+
+Refactored code:
+
+```java
+public static void main(String[] args) {
+    for (int i = 1; i <= 100; i++) {
+        if (i % 3 != 0) {
+            continue;
+        }
+        // or
+        if (i % 4 != 0) continue;
+        if (i % 5 != 0) continue;
+        System.out.println(i);
+    }
+}
+```
+
+The statement for output will only be executed if none of the above three conditions are met. That is, excluding cases
+that do not meet
+
+Only when all three conditions above are not met will the final output statement be executed. In other words, it
+excludes cases that do not meet the conditions, leaving only those that naturally do.
+
+## Method Extraction
+
+Some methods bear heavy functionality and have complex logic, often resulting in severe code nesting. In such cases, we
+can consider extracting methods, splitting one method into a combination of multiple method calls.
+
+## Efficient Use of return Statements (Similar to Guard Clauses)
+
+In the era of C programming, the single exit principle was widely accepted, meaning "a method should only have one
+return statement". We believe this requirement is overly strict. At least in some cases, using return early can reduce
+nesting levels:
+
+Original Code:
+
+```java
+public static void main(String[] args) {
+    if (args.length == 0) {
+        return;
+    } else {
+        // Do something else
+    }
+}
+```
+
+Refactored Code:
+
+```java
+public static void main(String[] args) {
+    if (args.length == 0) {
+        return;
+    }
+    // Do something else
+}
+```
+
+This is a very simple yet effective technique.

docs/core_and_architecture/coding_specifications.zh.md

@@ -44,7 +44,7 @@ Allay要求在每个类文件上按照一定格式标明信息，这是一个例
  *
  * @author daoge_cmd
  */
-class XXX{
+class XXX {
 
 }
 ```
@@ -81,15 +81,12 @@ public static void main(String[] args) {
 ```java
 public static void main(String[] args) {
     for (int i = 1; i <= 100; i++) {
-        if (i%3 != 0){
-            continue;
-        }
-        if (i%4 != 0){
-            continue;
-        }
-        if (i%5 != 0){
+        if (i % 3 != 0) {
             continue;
         }
+        // or
+        if (i % 4 != 0) continue;
+        if (i % 5 != 0) continue;
         System.out.println(i);
     }
 }

docs/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "allay-docs",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "cd ../;mkdocs serve",
+    "build": "cd ../;mkdocs build -d public"
+  }
+}