更新gradle相关

Author: Alumopper

docs/zh/quickstart/01project/01create-project.md

@@ -38,4 +38,85 @@ java -jar mcfpp.jar example.json
 
 ## 使用Gradle构建
 
-TODO
+基于Gradle的MCFPP项目拥有更多的功能支持。
+
+:::tip
+本例使用IntelliJ Idea，Gradle DSL使用Kotlin
+:::
+
+要使用Gradle构建MCFPP项目，首先需要创建一个空白的Java项目或Kotlin项目。MCFPP支持Java和Kotlin，但是由于本身由Kotlin编写，使用Kotlin可以获得更好的编写体验。
+
+![alt text](image.png)
+
+创建项目后，等待项目加载完成，打开`build.gradle.kts`。按照如下配置Gradle以添加MCFPP相关支持：
+
+```kt
+plugins {
+    // ...已有的代码
+    //添加MCFPP插件
+    id("mcfpp-gradle") version "1.0.2-SNAPSHOT"
+}
+
+repositories {
+    // ...已有的代码
+    // 添加MCFPP所需要的依赖库的仓库地址以及MCFPP所在库的地址
+    maven("https://nexus.mcfpp.top/repository/maven-public/")
+    maven("https://jitpack.io")
+    maven("https://maven.aliyun.com/nexus/content/groups/public/")
+    maven("https://libraries.minecraft.net")
+}
+
+group = "top.mcfpp"
+version = "1.0-SNAPSHOT"
+
+dependencies {
+    // ...已有的代码
+    // 添加MCFPP库。如果不使用MCFPP MNI可不添加本行
+    implementation("top.mcfpp:mcfpp:1.0.2-SNAPSHOT")
+}
+```
+
+随后，打开`settings.gradle.kts`，添加如下配置：
+
+```kt
+//添加插件需要的依赖库的地址，以及插件所在的库的地址
+pluginManagement {
+    repositories {
+        maven("https://nexus.mcfpp.top/repository/maven-public/")
+        maven("https://jitpack.io")
+        maven("https://maven.aliyun.com/nexus/content/groups/public/")
+        maven("https://libraries.minecraft.net")
+        gradlePluginPortal()
+    }
+}
+```
+
+然后，重新加载gradle项目，如果一切正常，你就成功地为Gradle添加了MCFPP支持。MCFPP默认会读取`src/main/mcfpp`中的mcfpp文件，所以你需要在对应的位置新建这个文件夹，在其中编写MCFPP。
+
+使用Gradle时候，你不需要编写项目配置相关的json文件。对应的，你可以在`build.gradle.kts`中对MCFPP项目进行配置。使用`mcfpp`方法块配置你的项目：
+
+```kt
+mcfpp {
+    version = "1.21.4"
+    description = "MCFPP Example Project"
+}
+```
+
+事实上此方法块修改的是`Project`类中的`config`字段。此字段是[`ProjectConfig`](https://github.com/MinecraftFunctionPlusPlus/MCFPP/blob/kotlin-latest/src/main/kotlin/top/mcfpp/ProjectConfig.kt)的实例，其管理了MCFPP项目的各项配置。
+
+|字段名|类型|默认值|描述|
+|-|-|-|-|
+|version|String|"1.21.8"|工程对应的mc版本。仅支持正式版本，不支持快照|
+|rootNamespace|String|"default"|工程的默认命名空间|
+|targetPath|java.nio.file.Path?|null|数据包输出的文件夹。若为空，在使用配置文件的时候为`$root/build/`，使用Gradle时为Gradle构建产出目录的`datapack`文件夹中（通常为`build/datapack`）|
+|commentLevel|top.mcfpp.command.CommandLevel|CommentLevel.DEBUG|注释输出等级|
+|root|java.nio.file.Path?|null|工程的根目录。若为空，则为配置json文件所在的目录，或Gradle项目的根目录|
+|name|String|"new_mcfpp_project"|工程的名字|
+|description|String|"A new datapack"|数据包的描述|
+|includes|ArrayList\<String>|ArrayList()|工程包含的所有引用|
+|jars|ArrayList\<String>|ArrayList()|所有Jar文件的路径|
+|sourcePath|java.nio.file.Path?|null|mcfpp源代码根目录。若为空，在使用配置文件的时候为`$root`，在使用Gradle时为`src/main/mcfpp`|
+|noDatapack|Boolean|false|不生成数据包|
+|copyImport|Boolean|true|生成数据包的时候复制导入的库|
+
+你可以在gradle任务的`build`分类下找到名为`mcfppCompile`的任务。

docs/zh/quickstart/01project/image.png

@@ -2,7 +2,7 @@
 lastUpdated: true
 ---
 
-# 顶层语句<Badge type="tip">未来特性</Badge>
+# 顶层语句
 
 在MCFPP中，允许在文件的开始直接编写语句而无需额外定义函数，即顶层语句。顶层语句处于一个隐式的函数中，这个函数每个文件有且只有一个，且不能被外部调用。它的返回值类型为`void`。
 
@@ -16,12 +16,20 @@ func main(){
 
 在编译后，会生成两个函数——分别对应main函数以及顶层语句对应的默认函数。
 
-顶层语句只能在文件的开始编写，即在函数定义或类定义之前。顶层语句可以调用文件中声明的其他函数和类
+顶层语句只能在文件的开始编写，即在函数定义或类定义之前。顶层语句可以调用文件中声明的其他函数和类，而顶层语句中声明的变量则可以被同文件的其他函数使用。
 
 ```mcfpp
+var qwq = "qwq";
+
 main();
 
 func main(){
-    print("Function");
+    print(qwq);
 }
 ```
+
+顶层语句永远都会拥有一个`minecraft:load`标签，即顶层语句永远都会在数据包被加载的时候执行一次。因此，顶层语句中非常适合进行一些初始化操作。
+
+:::tip
+顶层语句的函数为`命名空间:文件名__top__`，会在编译的时候加入对应命名空间中，因此理论上你可以使用调用函数的一般方式去调用它。但是我们一般不推荐这样做，因为调用一个*没有被明确声明的函数*会让代码显得很混乱，而且这并不是我们希望你使用顶层语句的方式。
+:::

docs/zh/quickstart/02base/04top-statements.md

@@ -4,6 +4,8 @@ lastUpdate: true
 
 # 命名空间
 
+## 定义
+
 MCFPP中的命名空间和MC中的命名空间是同一种东西。这也意味着，命名空间只能是小写字母、数字，点和下划线的组合。
 
 你可以在文件中声明一个命名空间，这样文件中的所有函数和变量都会被放置在这个命名空间中。例如：
@@ -19,3 +21,21 @@ func test {    # test:test函数
 一个文件中只能声明一次命名空间。
 
 若没有声明命名空间，文件的命名空间将会由文件路径相对于源代码路径的相对路径决定。例如，假设源代码目录为`src/main/mcfpp`，项目命名空间为`test`，那么文件`src/main/mcfpp/uwu/test.mcfpp`的命名空间将会是`test:uwu`。源代码路径通过工程配置文件中的`sourcePath`决定。
+
+## 编译时命令<Badge type="tip">技术性内容</Badge>
+
+在命名空间下声明一个没有名字的`mcfpp`文件，即`.mcfpp`文件，编译器将会把此文件判定为包含了编译时命令的文件。
+
+编译时命令将会在`INDEX_TYPE`编译阶段后，`stageProcessor[INDEX_TYPE]`处理器执行前执行。编译时命令定义为`#>`开头的一行行注释，其后的内容就是命令内容。目前支持的命令有：
+
+### `injectedBy <classPath>`
+
+向当前命名空间中注入一个MNI类定义的函数作为命名空间内的全局函数。
+
+* `classPath`一个MNI类的完全Java类限定名。
+
+例如
+
+```mcfpp
+#> injectedBy top.mcfpp.mni.minecraft.StdCommands
+```