-green){kind=icon}
-English | [简体中文](README.zh.md)
+English | [简体中文](README.zh.md) | [Русский](README.ru.md)
## Introduction
diff --git a/README.ru.md b/README.ru.md
new file mode 100644
index 000000000..2e7657d0b
--- /dev/null
+++ b/README.ru.md
@@ -0,0 +1,134 @@
+
+
+
+
+
+
+
+
+[English](README.md) | [简体中文](README.zh.md) | Русский
+
-[English](README.md) | 简体中文
+[English](README.md) | 简体中文 | [Русский](README.ru.md)
## 介绍
diff --git a/docs/core_and_architecture/about_the_chunk_lagging_issue.md b/docs/core_and_architecture/about_the_chunk_lagging_issue.md
index e8341706b..640c82154 100644
--- a/docs/core_and_architecture/about_the_chunk_lagging_issue.md
+++ b/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.
diff --git a/docs/core_and_architecture/coding_specifications.md b/docs/core_and_architecture/coding_specifications.md
new file mode 100644
index 000000000..4bfcb3b5c
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/core_and_architecture/coding_specifications.zh.md b/docs/core_and_architecture/coding_specifications.zh.md
index 664c79c33..2c3326566 100644
--- a/docs/core_and_architecture/coding_specifications.zh.md
+++ b/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);
}
}
diff --git a/docs/package.json b/docs/package.json
new file mode 100644
index 000000000..fb9e75ead
--- /dev/null
+++ b/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"
+ }
+}
\ No newline at end of file
diff --git a/docs/plugin_development/about_plugin_reloading.md b/docs/plugin_development/about_plugin_reloading.md
new file mode 100644
index 000000000..ec1c8c57c
--- /dev/null
+++ b/docs/plugin_development/about_plugin_reloading.md
@@ -0,0 +1,62 @@
+---
+comments: true
+---
+
+## About Plugin Hot Reload
+
+Plugin hot reload has been proven to be unreliable and unstable in the Nukkit community. Theoretically, a well-written
+plugin should support hot reload, but in reality, the skill levels of community users vary greatly. We have seen too
+many poorly written plugins, whose behaviors include but are not limited to:
+
+- Completing all necessary tasks for plugin startup in the `onLoad()` method, such as registering listeners, commands,
+ etc.
+- Not writing plugin unload logic, resulting in listeners, commands, and scheduled tasks registered by this plugin still
+ being available after the plugin is unloaded.
+- ...
+
+Considering the above reasons, for a Jar plugin, we default that it cannot be hot reloaded. However, we still allow
+users to mark their plugins as "reloadable", which is achieved by overriding the `Plugin.isReloadable()` method and
+returning `true`.
+
+Please note that overriding the `Plugin.isReloadable()` method and returning `true` does not mean your plugin supports
+hot reload. You still need to ensure that your code supports hot reload. Before introducing how to make your plugin
+support hot reload, let's first see what the `Plugin.reload()` method does:
+
+```java
+public final void reload() {
+ if (!isReloadable()) throw new UnsupportedOperationException("This plugin is not a reloadable plugin!");
+ onDisable();
+ onUnload();
+ onLoad();
+ onEnable();
+}
+```
+
+The `Plugin.reload()` method simulates the complete process of uninstalling and reloading the plugin. There used to be a
+wonderful operation in the Nukkit community years ago. Since Nukkit does not lock plugin files for writing, users modify
+the code, recompile it, replace the original jar file with the new one, and call the plugin's `reload()` method. The new
+code miraculously takes effect. I admit that this is indeed very convenient (in fact, I have done it myself), but in
+Allay, Jar plugins are not allowed to do so.
+
+Remember, for Jar plugins, calling the `reload()` method **does not mean it is actually reloaded from the file**.
+
+## Making Your Plugin Support Hot Reload
+
+**Ensure that operations related to plugin functionality are in the `onEnable()` method**, such as:
+
+- Registering listeners
+- Registering scheduled tasks
+- Registering commands
+- ...
+
+**Ensure that all content registered by the plugin is unregistered in the `onDisable()` method**.
+
+Even if the above is followed, we still cannot guarantee that your plugin can be hot reloaded correctly. **For Jar
+plugins, the best way is not to support hot reload**, as restarting the server does not take much time.
+
+## Hot Reload for JavaScript Plugins
+
+Unlike Jar plugins, JS plugins support hot reload by default. When calling the `reload()` method of a JS plugin, the
+current JS context is completely destroyed and recreated. We do not lock the files for JS plugins, which means you can
+modify the code while the plugin is running and reload it to make the changes take effect, which is particularly
+convenient.
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 0fff58362..6aad59fef 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,4 @@
+mkdocs
black
mkdocs-material
mkdocs-git-committers-plugin-2