Protogame Documentation Release latest Redpoint Games Apr 01, 2017 General Information 1 General Information 3 1.1 Frequently Asked Questions.......................................3 2 Basic Walkthroughs 7 2.1 Creating your first game.........................................7 2.2 Rendering textures............................................ 13 2.3 Add a player............................................... 20 2.4 Handling input.............................................. 27 3 Engine API 33 3.1 Core: Architecture............................................ 33 3.2 Core: Services and APIs......................................... 34 3.3 Asset Management............................................ 46 3.4 Audio................................................... 56 3.5 Graphics................................................. 58 3.6 Graphics: 2D Rendering......................................... 74 3.7 Graphics: 3D Rendering......................................... 77 3.8 Graphics: Caching............................................ 81 3.9 Events (Input).............................................. 82 3.10 Physics.................................................. 82 3.11 Level Management............................................ 86 3.12 Command Framework.......................................... 89 3.13 AI Framework.............................................. 89 3.14 Particle Systems............................................. 90 3.15 Networking: Multiplayer......................................... 90 3.16 Networking: Dedicated Servers..................................... 108 3.17 Scripting and Modding.......................................... 108 3.18 Hardware Sensors............................................ 109 3.19 UI Framework.............................................. 111 4 Engine Utilities 113 4.1 Analytics Reporting........................................... 113 4.2 Performance Profiling.......................................... 113 4.3 Compression Utilities.......................................... 114 4.4 Primitive Collisions........................................... 114 4.5 Image Processing............................................. 115 4.6 2D Platforming Utilities......................................... 118 i 4.7 Memory Pooling............................................. 118 4.8 Structure Utilities............................................. 122 4.9 Noise Generation............................................. 122 4.10 Math Utilities............................................... 122 4.11 Extension Methods............................................ 123 5 Third-Party APIs 129 5.1 MonoGame Framework......................................... 129 5.2 MonoGame Framework (Content Pipeline)............................... 406 6 Other Documentation 511 6.1 Internal Implementations......................................... 511 ii Protogame Documentation, Release latest Protogame is a cross-platform .NET game engine. It aims to allow developers to prototype games quickly during the early stages of development, and then scale those games into full projects. Protogame is fully open source and available under an MIT license. This documentation is organised into several sections, depending on what you need to achieve: • General Information • Basic Walkthroughs • Engine API • Engine Utilities • Third-Party APIs General Information 1 Protogame Documentation, Release latest 2 General Information CHAPTER 1 General Information Frequently Asked Questions If there is a question not answered here, ask @hachque on Twitter. How do I get started? We recommend reading the Creating your first game as this will guide you through the initial download and setup, and lead onto future tutorials which cover rendering, entities and handling input. What platforms are supported? Windows, Mac OS X and Linux are all currently supported and tested development platforms. These desktop platforms are also supported targets for running games made with Protogame. Android and Ouya are currently supported mobile platforms for running games. iOS support is expected in the future. MonoGame supports other platforms as well, such as PlayStation Mobile and Native Client. We don’t know whether Protogame will work on these platforms, but it’s likely they will work with some changes depending on platform limitations. For more information, refer to the table below. • “Supported” indicates that we actively develop and run games on this platform. • “Changes Needed” means that you would need to make changes to the engine for it to work. • An empty space means it’s not supported and / or we don’t know how well it will work. 3 Protogame Documentation, Release latest Platform Games can be developed on this platform Games can run on this platform Windows Supported Supported Mac OS X Supported Supported Linux Supported Supported Android Supported Ouya Supported iOS Supported Windows Phone Windows 8 (Metro) What platforms can compile assets? Asset compilation is needed to turn source information (such as PNG and FBX files) into a version of the texture, model or otherwise that is suitable for the game to use at runtime. Since each platform needs assets in different formats, you have to compile your assets for the target platforms. Support is determined by: • The type of asset • The platform you are targetting (for running the game) • The platform you are compiling the asset on (where you are developing) The general rule of thumb is, if you are developing on Windows, you can target all platforms. Windows has the strongest support for compiling assets and can target all available platforms that MonoGame supports. Linux support can compile all types of assets, although shaders require another computer running Windows for remote compilation (effects require DirectX to parse the shader language). Fonts must be under the /usr/share/fonts/truetype folder for them to be picked up, and the font name indicates the TTF filename. Font compilation is likely to change in the future, with font assets being specified from a source TTF instead of by name. You will need a Windows machine to compile shaders. See the Asset Management article for more information on compile assets, cross-compilation and compilation of shaders on non-Windows platforms. Missing MSVCR100.dll or MSVCP100.dll Compilation of model assets under Windows requires the Visual C++ runtime. FBX animations are not importing from Maya correctly The FBX importer has some restrictions about the structure of the animations that you import. These relate to “op- timizations” that Maya and other 3D modelling tools do in their export; unfortunately these optimizations are not compatible with the importer. The restrictions are as follows: • All bones in the hierarchy must have a joint offset. Maya is known to optimize hierarchy that doesn’t have a joint offset, and this causes transformations to be applied to the wrong node. • You must have at least one frame for each bone with a non-default value for translation, rotation and scaling. If you leave the default translation (0, 0, 0), rotation (0, 0, 0), scaling (1, 1, 1) for a given bone, and you export a rig with no animations, relevant nodes for the bone will not be exported and Protogame will not be able 4 Chapter 1. General Information Protogame Documentation, Release latest to re-apply the animation transformations because the target node does not exist. An easy solution to this issue is to have the base FBX file also contain an animation, so Maya will not remove the nodes required to re-apply the animation. Note that these restrictions only apply when you are dealing with animations. Non-animated FBX files will import just fine. Running games under Mono for Windows does not work Running Protogame-based games under Mono for Windows is not supported. Please use the Microsoft.NET runtime instead. This means that you should use Visual Studio Express instead of Xamarin Studio if your target is the Windows platform (i.e. on Windows use Xamarin Studio only if the runtime platform is Android or iOS). ‘FastDev directory creation failed’ when deploying to Android This appears to be a transient error with Xamarin Android. To fix this issue, right-click on the project for your game in Xamarin Studio and select “Options”. In the Options dialog that appears, under Build -> Android Build, uncheck the “Fast Assembly Deployment” option. 1.1. Frequently Asked Questions 5 Protogame Documentation, Release latest 6 Chapter 1. General Information CHAPTER 2 Basic Walkthroughs If you’re just starting out with Protogame, it is highly recommended that you follow the first walkthrough: Creating your first game. This will walk you through creating your first game with absolutely nothing installed or set up. Creating your first game Unlike other game engines, Protogame is not installed on your computer; instead it is a library that you download for each project. If you’ve ever used FlashPunk, you’ll be used to this way of working. Install an IDE It’s pretty safe to assume that you’ve already done this step, especially if you’ve been developing in C# before. You will need either Visual Studio, Xamarin Studio or MonoDevelop. You can also use command-line build tools such as msbuild or xbuild if you wish. Visual Studio Community If you are developing on Windows, then Visual Studio Community is highly recommended. You can download Visual Studio Community from the Visual Studio website. 7 Protogame Documentation, Release latest Xamarin Studio / MonoDevelop If you are developing on Mac OS X or Linux, or you want