## 擴展編輯器（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.