feat:上传mcguide-开发指南部份

mcguide/20-玩法开发/14-预设玩法编程/9-第一个预设Mod/0-创建新版作品.md

@@ -0,0 +1,37 @@
+# 创建新版作品
+
+我们建议您跟随这个文档一步步的创建出第一个预设Mod。你可以在这里下载到已经制作完成的<a href="https://g79.gdl.netease.com/FirstPresetDemo.zip" target="_blank" rel="noopener noreferrer">第一个预设Mod</a>用于参考。
+
+新版编辑器提供了预设架构等一系列对于玩法开发威力强大的工具。想要使用这些工具，我们需要先创建一个使用新版编辑器的作品。
+## 新建新版作品
+
+我们在启动器的`创作`分页下点击`新建基岩版组件`按钮，在新建弹窗中选择`推荐`分页下的空白地图并点击，创建一个新的地图玩法组件。
+
+![new001](./images/new001.png)
+
+> `推荐`分页下创建的作品会使用全新预设架构的编辑器，功能强大，且未来会得到持续的功能更新和问题修复，推荐开发者优先选择使用。
+
+在弹出的新建作品的界面，设置好作品名称、世界类型等参数，点击`启动编辑`，即可创建和编辑一个新版作品了。
+
+![new001](./images/new001-2.png)
+
+## 将旧版作品升级为新版
+
+在当鼠标悬浮在作品卡片上时，旧版作品的左上角会有标签提示，如下图所示
+
+![new001](./images/new002-1.png)
+
+点击编辑按钮，在弹出的编辑作品面板中，开发者可以选择将旧版作品升级为新版作品，如下图所示。
+
+![new002](./images/new002.png)
+
+> **注意**：
+> 1.当前作品是使用旧版编辑器进行编辑的，一旦升级到新版编辑作品后，将无法使用旧版编辑器打开。
+> 2.新版编辑器不再支持编辑和新建旧版组件（已有组件的逻辑仍然生效），为了保护您的作品数据，我们将为您创建一个当前作品的副本，并使用新版编辑器打开这个副本。
+> 3.新版编辑器采用功能更强大的预设架构，未来将得到持续的功能更新和问题修复，强烈推荐使用。
+
+
+只有旧版作品可以被升级为新版，新版作品在编辑时，直接点击启动编辑即可用新版编辑器打开。
+
+![new003](./images/new003.png)
+

mcguide/20-玩法开发/14-预设玩法编程/9-第一个预设Mod/1-新建预设并添加素材.md

@@ -0,0 +1,57 @@
+# 新建预设并添加素材
+
+## 什么是预设？
+
+预设（Preset）就是预先设定的意思。即开发者们可以将方块、素材、实体、特效以及玩法逻辑拼装成一个预设。
+
+预设作为文件被保存在行为包的Preset目录中，如下图，在资源管理器的常用目录中，可以找到Preset文件夹。
+
+![new004](./images/new004.png)
+
+在使用时，一个预设作为一个整体被放置在游戏中，被放置到游戏中的预设被称为实例。
+
+预设的后缀是.preset，如果你对预设到底是什么感兴趣，可以使用文本编辑器打开预设文件，查看它的结构。
+
+
+
+## 创建第一个预设
+
+我们使用资源管理器的新建功能。
+
+![new005](./images/new005.png)
+
+这将打开新建文件向导界面，在这个界面中，选择空预设，并点击下一步。
+
+![new006](./images/new006.png)
+
+在下一步中，将文件命名为Cabinet，然后点击创建，就创建了一个名称是Cabinet的空预设。你现在可以在前述的Preset文件夹中发现这个预设。
+
+> 由于预设文件的路径是固定的，所以通常在一个作品中不能存在两个同名的预设。
+>
+> 预设文件的名称中不能出现中文字符。
+
+![new007](./images/new007.png)
+
+
+
+## 为预设添加素材
+
+首先，使用地图编辑器创建一个如下图的方块建筑，并将其保存为素材（或者点击<a href="https://g79.gdl.netease.com/cabinet.mdl" target="_blank" rel="noopener noreferrer">这里</a>下载）。
+
+![new008](./images/new008.png)
+
+在资源管理器中双击之前创建的Cabinet.preset（展览台预设），打开预设编辑器。
+
+下面我们为这个预设添加刚才制作的素材。点击预设编辑器的添加素材按钮，打开选择素材的文件夹，选择刚才制作或下载的素材，点击打开。
+
+![new010](./images/new010.png)
+
+素材会被导入作品的BoxData目录（见下图的目录），并且被添加到预设中。
+
+![new011](./images/new011.png)
+
+现在，你已完成了一个包含素材的展览台预设，你可以在层级面板中点击节点，并在属性面板中对其名称进行修改。
+
+下面这张图就是展览台预设当前的样子。
+
+![new012](./images/new012.png)

mcguide/20-玩法开发/14-预设玩法编程/9-第一个预设Mod/2-在场景中实例化.md

@@ -0,0 +1,51 @@
+# 在场景中实例化
+
+## 将预设放入场景
+
+打开关卡编辑器，并且在资源管理器中打开我们的预设（Preset）文件夹。
+
+在这里找到我们刚刚创建好的Cabinet预设，并将其拖拽到场景中，调整好位置后松开鼠标，这样你就成功的在场景中创建了一个Cabinet预设的实例，并且在关卡编辑器的舞台中，你可以看到这个实例的结构。
+
+在舞台上选中展览台节点，然后可以在预览窗中通过坐标系拖柄对其的位置进行实时更改。
+
+![instance001](./images/instance001.png)
+
+
+
+## 修改预设
+
+现在我们重新在资源管理器中双击Cabinet预设，在预设编辑器中打开它。
+
+然后选中展览台素材，使用Ctrl+D快捷键，或者右键菜单的创建副本功能，创建一个展览台素材的副本，并且调整其的位置如下。
+
+![instance002](./images/instance002.png)
+
+然后保存，返回关卡编辑器。
+
+你可以看到之前放置在场景中的展览台预设也跟着更新了。
+
+在编辑器中，实例与预设是引用关系。场景中所有的实例，都是引用的某个预设的数据，所以，当预设发生改动时，实例也会跟着改动。
+
+一个预设可以在场景中生成任意数量的实例，当你修改预设时，场景中的所有实例都会跟着改变。
+
+![instance003](./images/instance003.png)
+
+
+
+## 修改实例
+
+下面，我们在舞台中创建一个展览台实例的副本，将其拖拽到一边，并按照如下方式对这两个实例进行重命名。
+
+然后，我们将展览台（右）实例的其中一个展览台素材抬高一点，最终得到下图的样子。
+
+可以看到，我们可以单独对某个实例进行修改，对实例的修改不会影响到其他实例，并且也不会影响到预设，你的预设依旧是左边这个实例的样子。
+
+![instance004](./images/instance004.png)
+
+此时，如果我们修改预设，比如说将展览台预设上面的素材摆到下面的展览台素材的左侧与他平齐。
+
+然后返回关卡编辑器，你会发现，只有未经改动的实例发生了变化。
+
+即如果实例的某一个节点发生了修改，实例会记录这种修改，并忽略他引用的预设的这个值。
+
+![instance005](./images/instance005.png)

mcguide/20-玩法开发/14-预设玩法编程/9-第一个预设Mod/4-创建和挂接零件.md

@@ -0,0 +1,20 @@
+# 创建零件
+
+零件是预设架构下，一种可以挂接到预设下的玩法逻辑对象。
+
+我们首先通过新建文件向导创建一个零件。通过资源管理器左侧的“新建”按钮打开新建文件向导，然后在常用页签里选择空零件，点击下一步。
+
+![part001](./images/part001.png)
+
+我们将零件命名为Chat，在这里你会发现，我们在创建零件的时候，同时创建了4个文件。
+
+- Chat.part：零件的本体文件，与.preset的预设类似
+- ChatPart.py：这个是零件绑定的python脚本文件，我们后续的逻辑需要写在这个文件里。
+- ChatPartMeta.py：这个是ChatPart.py的Meta文件，主要用于将ChatPart.py的属性暴露至属性面板中。
+- \_init\_.py：固定的文件结构
+
+![part002](./images/part002.png)
+
+点击创建，完成Chat零件的创建，资源管理器自动跳转到刚创建的零件的文件夹。
+
+![part003](./images/part003.png)

mcguide/20-玩法开发/14-预设玩法编程/9-第一个预设Mod/5-拼装预设和零件.md

@@ -0,0 +1,35 @@
+# 拼装预设和零件
+
+## 零件挂接
+
+我们先不急于对零件的ChatPart.py进行修改，先双击打开Cabinet.preset，并且在预设编辑器中，将Chat零件拖拽至展览台预设的层次面板中，如下图所示。
+
+由于我们希望实现的零件逻辑与位置无关，所以无需调节零件的位置。
+
+![part004](./images/part004.png)
+
+
+
+## 挂接子预设
+
+除了零件之外，我们再通过预设编辑器的添加一个子预设。在预设编辑器中点击添加预设，在弹出的菜单中选择特效预设。
+
+![instance006](./images/instance006.png)
+
+然后在资源管理器的常用目录中，找到effects，点击“+”，创建一个粒子特效。
+
+![instance007](./images/instance007.png)
+
+在层级面板中选中特效预设，并在他的属性面板中，将特效文件修改为我们刚创建好的新特效，现在特效就开始播放了。
+
+你可以在预览窗中，为你的粒子调整到一个合适的位置。
+
+![image-20210708224440026](./images/image-20210708224440026.png)
+
+然后，返回关卡编辑器，我们可以看到展览台预设的实例均已得到更新。
+
+![part005](./images/part005.png)
+
+需要注意的是，预设架构下，所有的预设/零件，只有以实例的方式出现在场景（舞台）上，才可以生效。
+
+如果你创建了一个预设，或者一个实例，但是没有把它放置在场景中，或者通过其他方式在场景中生成实例，那么他永远不会生效。

mcguide/20-玩法开发/14-预设玩法编程/9-第一个预设Mod/6-使用零件编程.md

@@ -0,0 +1,232 @@
+# 使用零件编程
+
+## 内置函数
+
+现在我们已经把零件通过挂接到预设的方式，在场景中实例化了，下面我们可以进行零件的编程了。
+
+当然，你也可以先进行零件的编程，再进行他的挂接和实例化。
+
+我们找到上一步创建的零件的文件夹，然后双击打开ChatPart.py，这里把他的代码粘贴在下方。
+
+你可以发现，在零件的代码中，我们已经为你生成了总计6个内置函数，这些函数就是零件代码的逻辑入口。
+
+```python
+# -*- coding: utf-8 -*-
+from Preset.Model.PartBase import PartBase
+from Preset.Model.GameObject import registerGenericClass
+
+
+@registerGenericClass("ChatPart")
+class ChatPart(PartBase):
+	def __init__(self):
+		super(ChatPart, self).__init__()
+		self.name = "Chat"
+
+	def InitClient(self):
+		pass
+
+	def InitServer(self):
+		pass
+
+	def TickClient(self):
+		pass
+
+	def TickServer(self):
+		pass
+
+	def DestroyClient(self):
+		pass
+
+	def DestroyServer(self):
+		pass
+```
+
+他们分别是这些逻辑的入口：
+
+- \_init\_：零件初始化时，一般仅在此声明变量
+- InitClient：零件实例的客户端初始化时
+- InitServer：零件实例的服务端初始化时
+- TickClient：零件实例的客户端每帧调用
+- TickServer：零件实例的服务端每帧调用
+- DestroyClient：零件实例的客户端销毁时
+- DestroyServer：零件实例的服务端销毁时
+
+直接在脚本里重写这些函数就可以在这些时机执行对应的逻辑。
+
+
+
+## 零件python编程
+
+接下来，我们使用零件来实现一个简单的逻辑，我们在聊天栏输入“摧毁”时，摧毁这个零件的父预设实例。
+
+当一个实例被摧毁时，挂接在他下面的所有实例也会跟着摧毁，所以，在这种情况下展览台预设下的。
+
+代码如下，由于我们只用到服务端的初始化和销毁时，所以我们可以把其他的内置函数删除。
+
+可以看到，我们在InitServer里监听了ServerChatEvent事件，当系统（我的世界）里发生玩家的聊天框输入时，会调用零件的OnServerChat函数。
+
+然后我们在OnServerChat函数中判断，如果玩家输入的是摧毁，就摧毁父预设。
+
+```python
+	def InitServer(self):
+		import mod.server.extraServerApi as serverApi
+		self.ListenForEvent(serverApi.GetEngineNamespace(), serverApi.GetEngineSystemName(), "ServerChatEvent", self, self.OnServerChat)
+
+	def DestroyServer(self):
+		import mod.server.extraServerApi as serverApi
+		self.UnListenForEvent(serverApi.GetEngineNamespace(), serverApi.GetEngineSystemName(), "ServerChatEvent", self, self.OnServerChat)
+
+	def OnServerChat(self, args):
+		# 生成掉落物品
+		# 当我们输入的信息等于摧毁时，摧毁父节点
+		if args["message"] == "摧毁":
+			self.GetParent().Destroy()
+```
+
+> 当前我们已经支持在文件头 import 大部分库/文件。
+>
+> 如果产生了报错，可以在使用时 import。
+
+
+
+## 使用Mod开发包测试结果
+
+点击编辑器右上角的运行，进行本作品的开发测试。
+
+![instance008](./images/instance008.png)
+
+> 使用0.16.12（7月15日更新），或者更高版本的MC Studio新建的作品，只能使用1.23或更高版本的开发包进行开发测试
+
+在运行的开发包中可以看到场景中的2个实例。
+
+![coding007](./images/coding007.png)
+
+按回车调出指令窗，输入：摧毁，此时只有一个展览台实例被摧毁了，但两个展览台是都应该被摧毁的。
+
+MC的事件机制是当一个事件的函数执行完毕时，才会发送下一个事件，而我们在执行的过程中进行了事件的反监听，导致了这一问题。
+
+所以我们修改一下代码，让删除父节点的行为在事件触发的下一帧执行。
+
+在资源管理器里找到Chat零件的文件夹，然后右键空白处，选择打开当前文件夹，我们在Windows的资源管理器内创建一个新的python文件，命名为coroutineMgrGas.py，然后将如下代码复制进去（此部分代码涉及的知识点较深，可以先按步骤操作）：
+
+```python
+# -*- coding: utf-8 -*-
+import time
+
+# 这个类的作用是延迟执行给定的函数
+# 使用参考每个具体使用的地方，yield 正数为时间，负数为帧数
+class CoroutineMgr(object):
+    coroutines = {}
+    globalEnd = []
+    addCoroutines = {}
+
+    @classmethod
+    def StartCoroutine(cls, iter):
+        cls.addCoroutines[iter] = 0
+        return iter
+
+    @classmethod
+    def StopCoroutine(cls, iter):
+        cls.globalEnd.append(iter)
+
+    @classmethod
+    def Tick(cls):
+        if cls.addCoroutines:
+            for c,v in cls.addCoroutines.iteritems():
+                cls.coroutines[c] = v
+        cls.addCoroutines = {}
+        if cls.globalEnd:
+            for c in cls.globalEnd:
+                if cls.coroutines.get(c):
+                    del cls.coroutines[c]
+            cls.globalEnd = []
+        ended = []
+        for c, v in cls.coroutines.iteritems():
+            try:
+                if v < 0:
+                    v += 1
+                    cls.coroutines[c] = v
+                if v == 0 or (v > 0 and time.time() >= v):
+                    newv = c.next()
+                    if newv > 0:
+                        newv = newv + time.time()
+                    cls.coroutines[c] = newv
+            except StopIteration:
+                ended.append(c)
+        for c in ended:
+            del cls.coroutines[c]
+
+```
+
+然后修改ChatPart.py的代码如下：
+
+```python
+from coroutineMgrGas import CoroutineMgr	
+    
+    ……
+    
+    def TickServer(self):
+		CoroutineMgr.Tick()
+
+    def OnServerChat(self, args):
+		# 生成掉落物品
+		# 当我们输入的信息等于摧毁时，摧毁父节点
+		if args["message"] == "摧毁":
+			CoroutineMgr.StartCoroutine(self.DelayDestroy())
+
+	def DelayDestroy(self):
+		yield -1
+		self.GetParent().Destroy()
+```
+
+现在我们再进行开发测试，可以看到现象正常了！
+
+![coding008](./images/coding008.png)
+
+
+
+## 使用属性面板修改零件
+
+我们在资源管理器中点击Chat.part，可以在他的属性面板中发现它的两个配套文件。除了在ChatPart.py里编程之外，我们还可以利用ChatPartMeta.py将ChatPart.py中的变量暴露到编辑器的属性面板中。
+
+点击配套文件右侧的小图标可以直接打开它。
+
+![coding003](./images/coding003.png)
+
+首先，我们先改造一下ChatPart.py，将“摧毁”作为一个变量使用。
+
+```python
+	def __init__(self):
+		super(ChatPart, self).__init__()
+		self.name = "Chat"
+		self.message = "摧毁"
+        
+	def OnServerChat(self, args):
+		if args["message"] == self.message:
+			......
+```
+
+改造后的零件在使用上与之前没有什么区别，接下来，我们打开ChatPartMeta.py，这里面已经自动帮我们写好了一些必要的代码，我们在这个文件中键入1行代码，整体效果如下：
+
+```python
+@sunshine_class_meta
+class ChatPartMeta(PartBaseMeta):
+	CLASS_NAME = "ChatPart"
+	PROPERTIES = {
+		"message": PStr(group="默认", text="信息"),
+	}
+```
+
+然后返回编辑器，我们可以发现，Chat.part的属性面板中增加了我们自己定义的“信息”变量。
+
+![coding004](./images/coding004.png)
+
+接下来，我们在舞台上找到Chat零件，分别把两个展览台预设的Chat零件的信息更改为“左”和“右”，然后保存并重新点击运行进行开发测试。
+
+![image-20210710145051437](./images/coding005.png)
+
+我们打开聊天窗口，输入：右。
+
+这次，只有右边的展览台实例被删除了！
+
+![coding006](./images/coding006.png)

mcguide/20-玩法开发/14-预设玩法编程/9-第一个预设Mod/7-使用预设制作AddOn.md

@@ -0,0 +1,34 @@
+# 使用预设制作AddOn
+
+## 让预设预加载
+
+我们说，无论预设还是零件，只有在场景中实例化才会生效。
+
+对于地图来说，我们只需要把预设从资源管理器拖拽至场景即可。但是对于AddOn（附加包）来说，由于AddOn是不包含地图的，所以无法通过这种方式来使预设和零件的逻辑生效。
+
+对于空预设来说，我们提供了一个叫做预加载的功能。
+
+在资源管理器中选中你的空预设，你可以在它的属性面板中启用这个功能。
+
+启用预加载后，预设会有如下特性：
+
+1. 预设会在区块加载前，在(0,100,0)位置进行加载
+2. 不能在这个预设下挂接依赖区块的子节点，如素材，特效预设，EntityBasePart等
+3. 预加载的预设会自动出现在舞台中，无需手动放置
+4. 修改舞台中后缀带（预加载）的预设，将直接修改预设文件
+
+![preload001](./images/preload001.png)
+
+
+
+## 使用玩家预设
+
+我们提供的内置预设中，包括了玩家预设。
+
+玩家预设会在游戏开始时自动实例化并绑定MC的玩家实体。
+
+如果你要写的逻辑与玩家预设相关，你可以将相应的零件和预设挂接到玩家预设下。这样，即使在AddOn中，玩家预设也会正常加载。
+
+> 如果进行多人游戏，每个玩家实体都会绑定一个玩家预设，所以除非你的逻辑真的与玩家相关，否则还是推荐使用预加载。
+
+![preload002](./images/preload002.png)