mni新内容

Author: Alumopper

docs/.vitepress/config.mts

@@ -9,7 +9,7 @@ export default defineConfig({
     // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: 'Home', link: '/' },
-      { text: 'Examples', link: '/markdown-examples' }
+      { text: 'QuickStart', link: '/quick-start' }
     ],
 
     search: {
@@ -25,16 +25,41 @@ export default defineConfig({
     ]
   },
 
+  vite: {
+    build: {
+      rollupOptions: {
+        input: {
+          main: 'index.html',
+          dokka: '/mcfppdocs/index.html'
+        }
+      }
+    }
+  },
+
   locales: {
     root: {
       label: '简体中文',
       lang: 'zh',
-      link: '/zh/'
+      link: '/zh/',
+      themeConfig: {
+        nav: [
+          { text: '主页', link: '/zh/' },
+          { text: '快速开始', link: '/zh/quickstart/index' },
+          { text: '文档', link: '/mcfppdocs/index.html' }
+        ]
+      }
     },
     en : {
       label: 'English',
       lang: 'en',
-      link: '/en/'
+      link: '/en/',
+      themeConfig: {
+        nav: [
+          { text: 'Home', link: '/en/' },
+          { text: 'QuickStart', link: '/en/quickstart/index' },
+          { text: 'Docs', link: '/mcfppdocs/index.html' }
+        ]
+      }
     }
   }
 })

docs/.vitepress/sidebar.ts

@@ -182,6 +182,10 @@ export const sidebar: DefaultTheme.Sidebar = {
                 {
                     text: "注解",
                     link: "/zh/quickstart/11mni/04annotation",
+                },
+                {
+                    text: "JVM访问符",
+                    link: "/zh/quickstart/11mni/05access",
                 }
             ],
         },

docs/zh/api/annotation/insertcommand.md

@@ -0,0 +1,21 @@
+# public @interface InsertCommand<Badge type="tip">已废弃</Badge>
+
+```java
+package top.mcfpp.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface InsertCommand {
+}
+```
+
+InsertCommand类用来标记一个JVM方法是否调用了`Function.addCommand`方法，也就是是否往一个函数里面添加了命令。由于Java和Kotlin之间的注解并不互通，因此此注解实际已经废弃。
+
+## 函数格式
+
+这个注解对函数格式没有要求。

docs/zh/api/annotation/mniaccessor.md

@@ -0,0 +1,61 @@
+# public @interface MNIAccessor
+
+```java
+package top.mcfpp.annotations;
+
+public @interface MNIAccessor {
+    
+    /**
+     * 访问器的名称
+     */
+    String name();
+}
+```
+
+这个方法用于标记一个Java方法是否是一个Native访问器。
+
+::: info
+
+在mcfpp中定义Native访问器：
+
+```mcfpp
+data BossBar{
+    #...
+
+    int max { get = top.mcfpp.mni.minecraft.BossBarData; };
+    
+    #...
+}
+```
+
+在Java中实现Native访问器：
+
+```java
+package top.mcfpp.mni.minecraft;
+
+//import ...
+
+public class BossBarData {
+    @MNIAccessor(name = "max")
+    public static void getMax(DataTemplateObject bossbar, ValueWrapper<MCInt> returnValue){
+        //具体的实现
+    }
+}
+```
+
+:::
+
+## 函数格式
+
+### 定义要求
+
+|静态|需要为静态|
+|返回值|无要求|
+|标识符|无要求，但是建议为`getXXX`的形式|
+
+### 参数要求
+
+|参数类型|描述|
+|-|-|
+|`DataTemplateObject`|这个访问器所在的数据模板对象|
+|`ValueWrapper<T extends Var<?>>`|访问器获取到的变量，类型为T|

docs/zh/api/annotation/mnifunction.md

@@ -0,0 +1,92 @@
+# public @interface MNIFunction
+
+```java
+package top.mcfpp.annotations;
+
+//import ...
+
+@Target({ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface MNIFunction {
+
+    /**
+     * 只读参数。格式是类型+空格+参数名
+     */
+    String[] readOnlyParams() default {};
+
+    /**
+     * 普通参数。格式是类型+空格+参数名
+     */
+    String[] normalParams() default {};
+
+    /**
+     * 调用者类型。默认为void
+     */
+    String caller() default "void";
+
+    /**
+     * 函数的返回类型。默认为void
+     */
+    String returnType() default "void";
+
+    /**
+     * 是否重写了父类中的函数。默认为false
+     */
+    boolean override() default false;
+
+    /**
+     * 是否是单例对象
+     */
+    boolean isObject() default false;
+
+}
+```
+
+这个方法用于标记一个Java方法是否是一个MNINative函数。
+
+::: info
+在mcfpp中定义MNINative函数：
+
+```mcfpp
+func print(text t) = top.mcfpp.mni.System.print;
+```
+
+在java中实现MNINative函数：
+
+```java
+package top.mcfpp.mni;
+
+//import ...
+
+public class System {
+
+    @InsertCommand
+    @MNIFunction(normalParams = {"text t"})
+    public static void print(@NotNull JsonText text){
+        if(text instanceof JsonTextConcrete textC){
+            Function.Companion.addCommand(new Command("tellraw @a").build(textC.getValue().toCommandPart(), true));
+        }else {
+            Function.Companion.addCommand(new Command("tellraw @a").build(text.toCommandPart(), true));
+        }
+    }
+    
+}
+```
+:::
+
+## 函数格式
+
+### 定义要求
+
+|静态|需要为静态|
+|返回值|无要求|
+|标识符|无要求。使用`getNativeFromClass`方法获取函数时，mcfpp函数的标识符和java标识符相对一致。|
+
+### 参数要求
+
+|参数类型|描述|、
+|-|-|
+|（可选）`T extends Var<?>...`|这个函数的只读参数列表。需要按照定义顺序。|
+|（可选）`T extends Var<?>...`|这个函数的普通参数列表。需要按照定义顺序。|
+|（可选）`T extends Var<?>`|这个函数的调用者。|
+|（可选）`ValueWrapper<T>`|这个函数的返回值。|

docs/zh/api/annotation/mnimember.md

@@ -0,0 +1,40 @@
+# public @interface MNIMember
+
+```java
+package top.mcfpp.annotations;
+
+public @interface MNIMember {}
+```
+
+此方法用于在调用`getNativeFromClass`方法的过程中，标记一个Java方法能够用于向当前的复合数据类型变量中添加成员（变量、函数等。）
+
+::: info
+
+在java中使用：
+
+```java
+
+    @MNIMember
+    public static ArrayList<Var<?>> getMembers() {
+        NormalCompoundDataObject attributes = new NormalCompoundDataObject("attributes", Map.of());
+        CompoundData attributeData = new CompoundData("attribute", "mcfpp.hidden");
+        attributeData.getNativeFromClass(AttributeData.class);
+        attributes.getData().addMember(new NormalCompoundDataObject(attributeData, "armor", Map.of()));
+        return new ArrayList<>(List.of(attributes));
+    }
+
+```
+
+:::
+
+## 函数格式
+
+### 定义要求
+
+|静态|需要为静态|
+|返回值|`ArrayList<Var<?>>`|
+|标识符|`getMembers()`|
+
+### 参数要求
+
+参数列表为空。

docs/zh/api/annotation/mnimutator.md

@@ -0,0 +1,61 @@
+# public @interface MNIMutator
+
+```java
+package top.mcfpp.annotations;
+
+public @interface MNIMutator {
+
+    /**
+     * 操作器的名称
+     */
+    String name();
+}
+```
+
+这个方法用于标记一个Java方法是否是一个Native操作器。
+
+::: info
+
+在mcfpp中定义Native操作器：
+
+```mcfpp
+data BossBar{
+    #...
+
+    int max { set = top.mcfpp.mni.minecraft.BossBarData; };
+    
+    #...
+}
+```
+
+在Java中实现Native操作器：
+
+```java
+package top.mcfpp.mni.minecraft;
+
+//import ...
+
+public class BossBarData {
+    @MNIMutator(name = "max")
+    public static void setMax(DataTemplateObject bossbar, MCInt value){
+        //具体的实现
+    }
+}
+```
+
+:::
+
+## 函数格式
+
+### 定义要求
+
+|静态|需要为静态|
+|返回值|无要求|
+|标识符|无要求，但是建议为`setXXX`的形式|
+
+### 参数要求
+
+|参数类型|描述|
+|-|-|
+|`DataTemplateObject`|这个操作器所在的数据模板对象|
+|`T extends Var<?>`|传入操作器的变量|

docs/zh/api/class/command.md

@@ -0,0 +1,50 @@
+# class Command
+
+top.mcfpp.command
+
+## 概述
+
+一条命令。在MCFPP编译过程中，一条命令可能会被分为多个命令片段，由接口`ICommandPart`实现。一个`Command`对象可以包含多个`CommandPart`对象。命令中的片段可以被字符串标签标记，从而能够对命令的某些片段进行替换操作。
+
+要开始构建一个命令，可以使用`Command`的伴随对象中的`Command.build`方法，或者使用`Command(String)`构造函数。此后，可以继续通过链式调用成员方法`build(String)`或者`build(Command)`来添加命令片段，或者使用`build(command:String, pointID: String)`来在添加命令片段的同时，标记该片段的替换标签为`pointID`。
+
+对于宏命令而言，可以使用成员方法`buildMacro(id: Var<*>)`来构建一个宏命令，其中`id`代表的变量就是要传递给宏的变量。随后，构建出的宏命令需要再使用`buildMacroFunction`方法将宏命令转换为宏函数来调用，从而提高宏命令的效率。此方法将会返回一个新的`Command`对象，即调用此宏函数的命令。
+
+要替换命令中的一些片段，可以使用成员方法`replace(pointID: String, target: String)`或者`replace(pointID: String, target: Command)`。它将会把标记为`pointID`的片段替换为`target`。
+
+## 例子
+
+```kotlin
+fun sbPlayerOperation(a: MCInt, operation: String, b: MCInt): Command {
+        return Command.build("scoreboard players operation")
+            .build(a.name,a.name)
+            .build(a.sbObject.toString(),a.sbObject.toString())
+            .build(operation,"operation")
+            .build(b.name,b.name)
+            .build(b.sbObject.toString(),b.sbObject.toString())
+}
+```
+
+```kotlin
+class XPredicate(val x: MCInt): EntitySelectorPredicate {
+    override fun toCommandPart(): Command {
+        return if(x is MCIntConcrete){
+            Command.build("x=${x.value}")
+        }else{
+            Command.build("x=").buildMacro(x, false)
+        }
+    }
+
+    override fun isConcrete(): Boolean = x is MCIntConcrete
+}
+```
+
+```java
+public static void print(@NotNull JsonText text){
+    if(text instanceof JsonTextConcrete textC){
+        Function.Companion.addCommand(new Command("tellraw @a").build(textC.getValue().toCommandPart(), true));
+    }else {
+        Function.Companion.addCommand(new Command("tellraw @a").build(text.toCommandPart(), true));
+    }
+}
+```

docs/zh/api/index.md

@@ -0,0 +1,4 @@
+# API 文档
+
+本文档提供了MCFPP编译器开发的基本信息。如果你需要进行MNI框架开发或者对编译器进行拓展开发，你可以参考MCFPP的Kotlin文档或者此文档。注意，此文档并非教程，可能包含大量技术性内容。如果你想要了解MNI框架，请参阅快速开始中的MNI章节。
+