## 扩展编辑器（Extensions） 扩展包是一些高度封装的功能模块，可以为GML添加额外的功能和常量，或能让游戏资源的分享变得更加方便。如果是添加额外功能的扩展包，这些方法可能让你的游戏更轻松与外部SDK或其它语言的代码对接（比如Android的Java代码），当然也包括GML语言。  通常情况下，第三方扩展都可以从 [YoYo的官方市场](https://marketplace.yoyogames.com/) 订阅和下载，而你订阅的扩展都会在[市场库](https://docs2.yoyogames.com/source/_build/2_interface/2_extras/marketplace.html) 窗口中列出并可以在此下载安装，你也可以在扩展一栏点击鼠标右键 选择 *从我的库中添加扩展（Add Existing From My Library）* 来进行操作. 如果你尚未从市场获取扩展包, 你也还是可以点击鼠标右键 并选择 *添加已有的（Add Existing）*. 如果你想使用以前老版GameMaker Studio创建的*.GMEZ文件，可以点击鼠标右键  选择 *导入文件（Import File）* 来进行添加。 **注意**: 传统格式 *.GEX 的扩展将不再支持导入Gamemaker Studio 2. 想了解更多关于使用和创建扩展包的信息请参阅以下部分： ### 使用扩展（Using Extensions） 一旦添加了扩展包，你就可以在项目组使用该扩展，但是你必须确保扩展属性与目标平台相匹配兼容，以下为各平台的扩展兼容说明： * **全平台All targets**: GML扩展，这些使用GameMaker Language制作的扩展可以兼容所有的目标平台. * **Windows平台 (PC, UWP及XBoxOne)**: 在该平台上可以使用DLL（动态链接库）文件 * **Mac OS**: 在Mac OS平台上可以使用经典的“Dylib”文件实现扩展. * **Ubuntu (Linux)**: 在Ubuntu上你必须确保扩展格式为“so”文件. * **Html5**: 该平台可用JavaScript扩展 . * **Android**: 本平台要求扩展的实现语言为Java或Android Framework SDK. * **iOS**: 用Objective C实现的扩展文件，并且必须拥有一个 *.m 文件和一个 *.h 头文件, 或是任何框架的，预编译的 *.a 原生文件 * **PlayStation**: 针对 PlayStation 3/4 你应该使用“.PRX”文件，不同的平台应提供符合对应规格的PRX文件，如果是PSVita则应当是“SUPRX”文件。 要修改某个扩展对应的平台或占位符时，你首先要打开扩展的属性（双击扩展或右键选择打开属性），然后在扩展属性中选择右侧的列表，选择你要对应的平台  **注意**: 如果你要导出到Mac OS或Ubuntu平台，可以保留“以ZIP包格式解压缩”选项 一旦你安装了扩展，就可以像使用GML语言一样去使用扩展中的函数和常量了，如果你的游戏是跨平台允许的（比如同时在Windows和Android都可安装运行），那么在调用扩展的特定功能之前你应当确保不会出现问题，比如 ```javascript switch(os_type)     {     case os_android:         call_android_extension_function(x, y, z);         break;     case os_windows:         call_windows_extension_function(x, y, z);         break;     } ``` 要注意，对于不同的平台而言，你的扩展可以共享函数名称，因此，如果你针对Windows和Android分别具有不同的扩展文件用来弹出提示消息，这两个文件可以使用相同的函数名来，而在实际使用时会仅调用自身平台对应扩展中的方法。 ### 创建扩展（Creating Extensions） 要创建扩展，首先要在资源树中扩展玄学上点击右键然后选择创建，这会打开一个主扩展属性窗口（如本页顶部的图片所示），在这里你可以添加所需的文件和函数，并可以在此为扩展设定名称（仅限字母/数字和下划线“_”）。你也可以根据需要来设置扩展的版本号。 要往扩展里添加文件你只需要点击菜单按钮 然后选择“占位符(placeholder)”文件或对应平台所需的实际文件即可  泛型（Generic）占位符可以是指除了特定平台所需的文件（如dll或so文件等）以外任何类型的文件，并且只有当需要被用来作为“链接器”给扩展关联特定的函数或常量时才会被使用（一般只适用于iOS和Android扩展，下文将具体说明）。你也可以添加“GML”和“JS”占位符文件来进行使用。 通常情况下，除了制作iOS或Android游戏，一般不会使用占位符，因此你可以选择“添加文件”选项，然后根据目标平台添加以下任何文件： * **.gml**: 这是用GML语言实现的可兼容全平台的扩展文件 * **.js**: 这是JavaScript扩展，仅兼容JS模块平台 (HTML5). * **.dll**: 动态链接库格式的文件仅适用于Windows、UWP和Xbox One平台（不同平台的dll文件各有不同）. * **.dylib**: 仅适用于Mac平台的扩展. * **.so**: 仅适用于Linux（Ubuntu等）平台. * **.prx**: 这是PS主机平台的扩展（不同版本的PS各文件也有区别）. 你会发现以上并没有**Android**和**iOS**的文件类型，这是因为这两个平台的设置方式稍有不同，后续你会看到具体的设置方式，但现在我们先来看看如何创建一个可以给全平台通用的GML扩展，这个创建过程基本类似。 首先，你需要创建将要使用的文件，对于GML扩展来说其实就是一个文本文件（保存文件时要确保后缀为.gml），具体格式如下 ```javascript #define c_alice_blue return make_color_rgb(240,248,255); #define instance_create_colour var i = instance_create_layer(argument0, argument1, argument2); with (i)     {     image_blend = argument3;     } return i; ``` 如上所见，我们用#define 来声明各个部分的开头，在上面的例子中我们定义了两个函数。你不需要为函数提供任何的参数字段，因为稍后会单独添加，而只要使用define和函数名称，然后添加GML进行匹配即可。如果你正在编写dll或js格式的扩展，这个过程基本类似，但要确保使用对应格式扩展的编程语言。 当你完成上述步骤以后，你需要将文件添加到扩展中，这将打开一个关联的“文件属性”的新窗口。  在这里你可以选择扩展对应的目标平台（如果是GML扩展则可以选择全部平台），以及重命名扩展或调整一些细节属性，稍后会进行介绍。首先我们通常会添加常量和函数，以便用户可以在项目代码中进行调用。因此你需要点击扩展菜单按钮  并选择你要添加的属性类型:  选择“添加函数（Add Function）后会允许你添加一个函数扩展，然后可以通过以下窗口设置这个函数的相关属性:  在上面的图片展，我们可以子函数编辑器中定义GML扩展脚本“instance_create_colour”的各项详细信息（函数编辑器不仅适用于定义GML函数，对于其他任何格式的扩展都是一样的）。比如函数的名称（即在项目中的调用名称），而且这个名称没必要和函数内的名称一致——你可以随便设置成你方便的名字——然后用“External Name”来进行关联。在这之下还有一段定义“Help”文本的区域，这是用于显示在代码编辑器底部的代码提示。 接下来你可以定义返回类型，它可以是一个“浮点数（double）”或一个“字符串（string）”，如果外部函数没有任何返回，也没有问题，最后则是这个函数需要传入的参数。 在添加参数时，参数同样可以是浮点数或字符串，并且你可以点击 来添加或点击来删除参数。要注意，如果你正在创建一个Windows的dll扩展文件，并且该方法有四个以上的参数，那所有的参数必须是相同类型。 一旦你完成了以上所有操作，你就可以在项目中调用这个扩展了，并且在调用时会有代码自动补全，同样也会有对应的高亮色。定义的函数可以设置为“初始化方法（Init Function）”或“结算方法（Final Function）”，这意味着他们将在游戏初始化（Init）时或结束时（Final）自动调用 > **重要提示！** 全平台都支持Init函数的调用，但不是所有的平台都支持Final函数调用，因为有些平台在关闭应用时不会给出任何回调和处理机制。主要是以下平台：iOS、Android、HTML 5、Playstation和Xbox one。 你还可以选择创建一个宏（Macro）。一个宏可以是一个常量值或单独的代码片段，比如我们可以从上面的示例个GML扩展中为“c_alice_blue”颜色移除已定义的函数，并将其改为宏：  这里的编辑器几乎都是 When working with multiple target platforms, it is worth noting that you can create a *single* extension with only one set of functions/macros which will work on *all* platforms. This is achieved by adding only one of the link libraries to your game as an extension and placing the other(s) into the list of **Proxy Files** from the Extension Properties window. For example, say you have a Windows extension with the dll "Haggis.dll". You would simply replicate this dll as a Mac DyLib, naming it "libHaggis.dylib" and making sure that the internal function names match those of the original Windows dll. This DyLib would then be added into the Proxy Files and set to export when the game is run on the Mac target, and *GameMaker Studio 2* will automatically use it when the extension functions are called. To add a proxy file, simply click the  button in the Extension Properties window for the extension and browse to the file location. Once it is added you may need to change the extension target to the appropriate module, and when you next run your game it will be included as a proxy for that platform. You can remove proxy files too by clicking the  button, which will remove the last one in the list each press. Once you have added your proxy files they will be stored in the YYP of your game, in the Extensions folder (you can find them easily by right-clicking  on the extension and selecting *Open in Explorer*), so if you need to edit them, you should edit the *copied* files that are bundled with the game and not the originals, as *GameMaker Studio 2* will be using the ones in the project for compiling your game. It is very important that your proxy files follow the naming conventions listed below, as *GameMaker Studio 2* will parse these names and assign the target module for the file according to its extension and name and will automatically link the files for you. If you do not follow these conventions your game may not work at runtime, as *GameMaker Studio 2* will not be able to work out which file to use or it will not load the file properly. The naming conventions for each target platform are given below: | Platform | Names | | Windows | **.dll. | | Linux | **.so, lib**.so,**_linux.so, lib**_linux.so | | Mac OSX | **.dylib, lib**.dylib | | HTML5 | **.js | | PS4 | **.prx, lib**.prx,**_ps4.prx, lib**_ps4.prx | | Xbox One | **_xboxone.dll | Using the conventions above, you would swap out the part for the name of the base file that you are adding the proxy files for. Android To create an extension for Android you have to do it in two parts. The first part would be to add the extension itself, along with the required files etc... and the second is to create the functions and macros/constants that the extension requires. The functions and constants are added using **placeholder** files to group them together, so you'd add a placeholder and then define the functions and macros as explained in the section above. To add the rest of the files though you need to first tick the *Android*check-box in the **Additional Features** section of the editor: Here you give the following details: * **ClassName**: Your extension can have multiple classes, with each class having its own functions and constants, so you should give it a name that reflects its purpose. * **Android Permissions**: Here you can add in any extra permissions that your extension requires. What these permissions are will depend entirely on the use that the extension has, and so you should check the [documentation supplied by Google](http://developer.android.com/reference/android/Manifest.permission.html) for the Android platform, or, if you are using a third party SDK, the documentation that comes with the SDK. To add a new permission you need to click the  button to add a placeholder permission, and then do a slow  click on that to edit it to what is required. You can remove permissions using the  button. * **Inject To Gradle Dependencies**: Here you can add any extra code that needs to be injected (added) into the Gradle build dependencies. * **Inject to AndroidManifest.xml Manifest**: Here you set any extra code to be injected (added) to the Android Manifest XML file when your game is built for testing or final release. Make sure to revise this (and your permissions) carefully before submitting any games to the store, as incorrect settings will cause your game to be failed for submission. * **Inject to AndroidManifest.xml Application**: Here you set any extra code to be injected (added) to the Android Manifest XML file under the Application heading when your game is built for testing or final release. Make sure to revise this (and your permissions) carefully before submitting any games to the store, as incorrect settings will cause your game to be failed for submission. * **Inject to AndroidManifest.xml RunnerActivity**: Here you set any extra code to be injected (added) to the Android Manifest XML file under the RunnerActivity heading when your game is built for testing or final release. Make sure to revise this (and your permissions) carefully before submitting any games to the store, as incorrect settings will cause your game to be failed for submission. Once you have set this up correctly, you will need to add the required files for your extension package to work. To do this you need to click on the buttons at the bottom, either *Add SDK* or *Add Source* and then browse to the files you wish to add. Added files will be stored in the *AndroidSource* directory along with your extension. You can open this location at any time by right clicking  on the extension and selecting *Open Extension Directory*. For more information on creating Android extensions, please see the [YoYo Games Knowledge Base](http://help.yoyogames.com/hc/en-us/articles/216755248-Creating-A-Native-Extension-For-Android-GMS-v1-3-). iOS To create an extension for iOS you have to do it in two parts. The first part would be to add the extension itself, along with the required files etc... and the second is to create the functions and macros/constants that the extension requires. The functions and constants are added using **placeholder** files to group them together, so you'd add a placeholder and then define the functions and macros as explained in the section above. To add the rest of the files though you need to first tick the *iOS* check-box in the **Additional Features** section of the editor: Here you give the following details: * **Linker Flags** / **Compiler Flags**: Some frameworks and third party SDKs require the addition of extra linker flags and compiler flags to work which can be specified here (see the documentation that accompanies the SDK or framework in question for details). * **ClassName**: Your extension can have multiple classes, with each class having its own functions and constants, so you should give it a name that reflects its purpose * **System Frameworks**: Here you can add in any iOS system frameworks to your extension. These are added by clicking the  button which will add a placeholder framework, which you can then edit by slow clicking  on it. You can find out more about available system frameworks [here](https://developer.apple.com/library/ios/documentation/miscellaneous/conceptual/iphoneostechoverview/iPhoneOSFrameworks/iPhoneOSFrameworks.html). To remove a system framework, simply select it and then click the  button. * **Inject to Info.plist**: Here you can add any code to be a injected into the info.plist file. * **3rd Party Frameworks and Bundles**: This section is for adding third party frameworks and SDK bundles. As with system frame works you click the  button to add them and then slow click to edit, and selecting them then clicking  will remove them (see the documentation that came with your chosen SDK for info on the framework name) . If the framework/SDK bundle is on your development Mac then you need to add the path into "*Enter framework path on Mac*" and click the button, or if the SDK or source code is on your PC use the *Add Source* button. If your extension has had any System Frameworks or 3rd Party Frameworks added, these will now be listed in the Extension Properties window, with each one having a check-box beside it. If you mark the check-box, you are enabling *weak* linking, which is useful should you need to "over-ride" any symbol from the included library with your own value, but it should be noted that doing so will slow linking down. For more information on creating iOS extensions, please see the [YoYo Games Knowledge Base](http://help.yoyogames.com/hc/en-us/articles/216755238-Creating-A-Native-Extension-For-iOS-GMS-v1-3-). ## YoYo Games 3rd Party Extensions Legacy versions of *GameMaker* had a lot of 3rd party functionality built in, but this was inefficient and difficult to maintain, since if any specific functionality was changed by the third party, then the whole *GameMaker* IDE and runtime would have to be updated. So, current versions have adopted the use of extensions packages to add third party support to your games. This means that you can add only those extra functions that you require and that you can even adapt and edit them to suit your specific needs. Most of these extensions will be downloaded and installed for you when you select a specific [Game Option](https://docs2.yoyogames.com/source/_build/2_interface/3_settings/game_options/index.html) (like*Facebook* or *Google Ads* for example), but you can find further information about them from the following YoYo Games **Knowledge Base** articles: 1. [3rd Party Extension Support](http://help.yoyogames.com/hc/en-us/articles/216753758-New-Extension-System-For-3rd-Party-Support-Ads-Facebook-Moga-etc-) You can find the extensions themselves from the following Marketplace page: 1. [YoYo Games Marketplace Assets](https://marketplace.yoyogames.com/publishers/23/yoyo-games) Note that these extensions come with a demo and a help file that explains how to use them, and as such their functions are not covered in the manual.