Registration and Licensing
What is the Marmalade Attribution policy?
As a technology business we thrive by sharing details of the amazing apps and games that are made with Marmalade.
It is for this reason that we ask licencees to reference Marmalade in one or more of the following ways:
Marmalade Community Licence holders
- A Made with Marmalade splash screen will be displayed when your app loads. The splash screen will display automatically, and will remain on screen for a short time.
Marmalade Indie and Plus Licences
- Include the Made with Marmalade logo and our website address www.madewithmarmalade.com within the credits and/or about screen. If possible, this should link to www.madewithmarmalade.com.
- In the event that technical restrictions prevent the above, the wording "Made with Marmalade" and our website address www.madewithmarmalade.com should be included within the app credits and/or 'About' screen of your published app. If possible, this should link to our website www.madewithmarmalade.com.
- An optional Made with Marmalade splash screen will be displayed when your app loads. The splash screen will display automatically, and will remain on screen for a short time.
- Assets can be downloaded here.
Promoting apps that are made with Marmalade
We also request that we are able to reference your published app on our website, www.madewithmarmalade.com, and in promotional material about Marmalade. Wherever possible we will provide links back to your own site or digital stores where your app is available.
Once your app is available please send the following assets to firstname.lastname@example.org:
- Logo (high resolution)
- Game icon (high resolution)
- 2/3 in game screen shots (high resolution)
- Short description of your game (50 characters)
- Longer description of your game (100 words)
- Notable information (for example: #10 in Games Category, App Store, December 2012)
- Marketing contact details for future promotion opportunities
In some circumstances, we would like to be able to share your made with Marmalade app(s) with a wider audience by asking you to take part in marketing activity to promote Marmalade and cross-platform development, which would in turn help to drive sales and the distribution of your app(s).
I'm a student, what sort of cheap licences do you have for me?
We offer a free licence for students and educational institutions. Please contact us for more details.
I have not received the activation email for my account, what should I do?
Please check the "junk" email folder in your email client. If you cannot see the email please contact us.
How do I obtain a licence for my desktop development machine (or request a new one)?
On a PC you can request a licence using the "Marmalade Configuration" tool, once open you can use the "Request New Licence" option to obtain your licence. On a Mac use the "s3elicence" tool located in the "Applications" folder (e.g. Developer/Marmalade-SDK/version/). When asked for your username and password, these are the same as you would use to login to our web site.
How can I use my license on another computer?
It is possible to "Release" a licence so that it can be used on another computer. If you log in to the web site, go to "My Account" and scroll down to the option that allows you to release your licence. On the new computer you will need to use the Marmalade Configuration tool to request a new licence.
I have bought multiple licences for the Marmalade SDK, how do I allocate them?
Once you have purchased your licences you can manage them from the "My Account" section of the web site. From the "Manage Licences" section it is possible to invite users to obtain your licences as well as release licences for existing users so that they can be re-allocated.
How can I get a receipt for my licence purchase?
A receipt for your purchase is emailed when the transaction is completed but if you need another copy you can find this through your account on our web site.
Downloads, Updates and Support
Where can I find the latest version of the SDK?
The latest version of the SDK is available to download here.
Where and how can I get support for using the SDK?
The Community Answers section on our web site are is there for developers to ask questions and have discussions about the SDK. If you require dedicated support from Marmalade engineers you will need to purchase or upgrade to a Plus or Professional licence. You can find out more about licensing here.
What desktop platforms can be used for development?
Marmalade is supported on the following platforms:
- Microsoft Windows 8
- Microsoft Windows 7
- Microsoft Windows XP SP3 (or above)
- Mac OS X 10.6 (Snow Leopard) or above running on an Intel Mac
Note that Marmalade Mac is not yet at feature parity with Marmalade for Windows. In particular, the desktop Simulator lacks some of the configuration options available in the Windows version. See the documentation for more information.
When will such-and-such a feature be included in the SDK?
Marmalade's roadmap is very customer-driven. Forum requests and feedback are very welcome. Please check for existing threads relating to a certain feature first, and if possible add to an existing thread rather than starting a new one.
Professional licencees have dedicated technical support and can use their private ticket-based channel to discuss new features.
Marmalade Concepts and Features
Can a single build of an app really target any device? How does this work?
Marmalade builds your app as a single code binary that can run on all supported platforms and devices. The machine code in this binary runs unmodified on every target device, giving you the confidence that exactly the same code is running everywhere.
The app binary is packaged with assets and a platform-dependent binary into the appropriate package format. For example, the same binary and assets will go into an IPA file for iOS and an APK for android. Icons, splash screens and other package features can be specified in the project's MKB file.
How do I handle differences between the devices, like screen resolution, etc?
The system APIs provide reflection for most device capabilities, for example an app can query the device's screen width using s3eSurfaceGetInt(S3E_SURFACE_WIDTH). Marmalade apps use these APIs to customise themselves for the device.
For more abstract device differences the app can combine custom settings with conditional blocks in the ICF file, for example:
This has the advantage that further variations can be added in future (often without even recompiling the app).
The s3eDeviceInfo example is useful for identifying device information quickly. It displays basic information about the device and can be easily edited to add more properties. Note that a deployment of any app using a Debug loader will also output basic device information at the start of trace files.
How do I debug on device?
One of the main aims of Marmalade is to minimize the requirement for on-device debugging, which is slower and less reliable even on the best platforms. A fast, flexible and accurate desktop ARM emulator is included to allow debugging of the actual code that runs on device.
Generally, a debug version of the platform loader can be deployed that will output tracing. The exact method of retrieving this file depends on the platform.
Using Marmalade Mac, a fully native iOS build can be generated in XCode and debugged/profiled with the usual Apple tools.
Can I use native platform code in my app?
Yes, the EDK (Extensions Development Kit) allows developers to call native OS APIs from within their Marmalade apps. The EDK is currently supported for iOS, Android and Windows desktop. There is further information on using the EDK in the documentation here.
Use of native OS APIs is also supported on Android through the JNI (Java Native Interface) S3E Extension. This allows you to include Java code for Android, either directly in the C++ source files of your Marmalade app, or by building and executing standard Java source files and assets. Due to the flexible nature of the MKB system, you can use it to define a project for the native Java part of the process if you wish - i.e. it will include .java files and build them into a .jar that can be used by your C++ app.
Can I use the standard POSIX APIS such as , ?
Yes, Marmalade supports large parts of the POSIX API and also the BSD socket API. These are implemented via the underlying S3E APIs.
Do Marmalade apps leverage hardware-accelerated floating-point processing?
Yes, it is possible to create builds which use hardware enabled floating point support via the arm-fpu ICF setting, which is to be set as an MKB option. Note that a build prepared in this way will not run on devices without a FPU.
How can I fix my app to landscape or portrait aspect ratio?
The ICF setting [s3e] DispFixRotcan be used to fix the screen in a given aspect ratio. The following options are supported Free, Portrait, Landscape, FixedPortrait, FixedLandscape. Setting to Portrait, or Landscape prevents the app from automatically rotating between Portrait and Landscape to compensate for the device being physically rotated. FixedLandscape and FixedPortrait additionally disables flipping 180 degrees. Default "Free" is to set the screen to the native device orientation and follow any automatic rotation.
Does Marmalade support internationalisation (for example: Japanese, Chinese, Korean, ... characters)?
Marmalade does not include any support for switching strings/assets by language out of the box, but most common approaches will work fine.
Displaying non-Roman fonts can be achieved by using the IwGxFont module, which supports rendering of bitmap and TTF fonts, therefore supporting virtually any character set. Bitmap fonts are created using the Marmalade Studio Font Builder.
Note: Please be careful to save any text to be imported as a UTF-8 text file. (See the documentation of your editor on how to save files in this format.)
Is Marmalade just for games?
No. Marmalade's sweet spot is 'rich' apps, by which we mean any combination of: great graphics; audio processing; use of device APIs such as camera, GPS, and microphone; deep C/C++ codebase; or anything else that raises your app above the level of a simple mobile website wrapper. Marmalade's history is in games, so is used very widely in that particular industry.
Development Tools / Compilers
Which IDEs does Marmalade support?
Marmalade currently supports the following:
- Microsoft Visual Studio 2012
- Microsoft Visual Studio 2010
- Microsoft Visual Studio 2008
- XCode 4.3 and above
Which compilers does Marmalade support?
On Windows, Marmalade supports the Microsoft Visual Studio compiler (all versions) for x86 builds, Codesourcery GCC for ARM builds and ARM's RVCT (RealView Compiler Toolkit) for ARM builds. Marmalade Mac supports Apple GCC for x86 builds, and Codesourcery GCC for ARM builds.
Codesourcery's GCC is included in the both versions of SDK and does not need to be downloaded separately. When using the Simulator you'll typically be compiling with the x86 compiler, as this is best integrated with the respective IDE's on each platform. When deploying to device or running in the ARM emulator you'll use one of the ARM compilers.
When compiling on Windows, RVCT can deliver significant performance increases over GCC. Use of RVCT requires a commercial licence to be purchased from ARM.
ARM do however offer a free evaluation licence for RVCT is part of the RealView Development Suite (RVDS), which is compatible with Marmalade.
Android x86 and MIPS compilers are included specifically for targeting Android devices that utilise MIPS or x86 architectures.
How can I change the Marmalade Mac Simulator resolution, or other settings?
The Marmalade Mac Simulator does support resolution changes but does not yet provide the full configuration menus as found on the Windows PC version. This functionality will be added in a future version.
You can set most Simulator settings manually by editing the development.icf file in the data folder of your project.
When a project is launched in the Simulator, this file is generated if it does not exist and then updated whenever an option is changed. Options are read back in whenever the Simulator starts up. Therefore, to set values manually, you should:
- Run the app for the first time, to generate the development.icf file.
- Edit the file as desired (see below).
- Restart the app (Stop, Run in Xcode).
- Repeat whenever you need to change a setting.
The SurfaceWidth and SurfaceHeight settings will determine the surface size that the Simulator uses.
Why does the Simulator run slowly (low frame rate, slow start, CPU hogging) or not start at all?
The Simulator may run very slowly, in spite of the processing capability of the desktop machine. For example, it may run at a very low frame rate.
For most apps the Simulator will run flat out (unless you call s3eDeviceYieldUntilEvent or are limiting your frame-rate in some way) so it should not run slowly.
Simulator performance issues are usually due to graphics/GL driver/hardware issues on your desktop machine. In the Simulator menu, try selecting Preferences->Display->Use DirectX and see if that makes a difference. Try going to Preferences -> Display and unticking “Use off-screen buffer for GLES rendering”. This disables stretching of the OpenGL ES display which can cause issues on some drivers. Note that enabling this setting will have some side effects, notably resizing the window won't work and you will see a yellow screen at startup, but that should be replaced once your app draws its first frame.
Try going to Configuration - > GL... and changing the value of "GLES API supported". Check that this is correct for the version of OpenGL ES your app needs. Also note that some options are labelled as "POWERVR" and some "Qualcomm". When selected, drivers from the provider specified will be used; your graphics card may perform better using one compared to the other.
Always check that your graphics card drivers are up to date.
In extreme cases you can disable OpenGL ES altogether by selecting “None” from the GLES API drop down or adding [s3e] DisableGL=1 in your ICF file. Note that the SW renderer can produce significantly different output, so this is not an perfect solution.
Why do I get extra key events while debugging? Why can't I use print screen to take a screenshot?
The setting of "Use DirectInput in exclusive mode" in Preferences->Keyboard... determines the Simulator's style of integration with the desktop OS.
In non-exclusive mode (the default) the Simulator integrates more intuitively with the OS; for example, "Print Screen", and the use of Alt to access menus, work as expected. However, keys pressed during debugging are queued up and issued to the app when it resumes.
Exclusive mode has the opposite behaviour.
How do I change the IDE used to open MKB files?
In Windows, you can right click on an MKB file and chose to open with an IDE from a list of those that you currently have installed. Note that you can also choose here to build your app directly without using an IDE.
To change the default IDE used when you double-click an MKB, open the Marmalade Configuration Utility (from the Start Menu folder) and change the "Default Build Environment" setting.
Can I run MKBs from the command line?
Yes, MKBs can be invoked from the command line to build, run and deploy apps. See the documentation for more details.
Note that x86 builds on Windows will still require at least the command line tools from Visual Studio.
Marmalade for iOS
Can I use Objective C or native iOS code in Marmalade apps?
Yes, you can code in Objective C and use iOS APIs inside your own custom "extensions" using the Extensions Development Kit (EDK). The EDK allows you to code in C++ and Objective C, using standard iOS or third party frameworks and libraries, and expose them to the app through a C interface. The EDK provides your app with a function to check the availability of the extension on the target device – if running on iOS, the function will return true, and you can then make calls into the extension functionality. The extension library is statically linked into the iOS version of your app at deployment time.
Do I need a Mac to build, deploy and submit iOS apps?
You can fully build, deploy and install standard Marmalade apps for iOS using a Windows PC, with no need for a Mac. This includes all stages of app signing for both development and app store submission (generating certificate requests, obtaining certificates/profiles, signing apps). However, a Mac is currently required to upload final app builds to the App Store due to the store's dependency on the Mac App Loader. A Mac is also required if you want to *build* EDK extensions for iOS. Note that a Mac is not required if you simply wish to include pre-compiled EDK extension libraries for iOS.
How does Marmalade handle the differing screen resolutions and capabilities of iOS devices?
By default Marmalade deploys apps in "universal" mode so that they will run in native screen resolution on both iPhone/iPods and on iPads. You can specify for apps to be iPad-only or to run in 320x480 standard iPhone resolution on iPad via deployment options. Retina screen (640x960) support for iPhone 4 or newer must be enabled using the iOSScaleFactor ICF setting, but apps using this setting will still run in the native resolution on other devices.
Functionality that is only available on some devices can be queried at runtime through the relevant API. Marmalade's low level S3E APIs are designed so that they can always be called on any device and will simply return an appropriate error value if not supported, rather than causing a crash or exception.
How can I debug my app on an iOS device?
Marmalade Mac supports native device debugging, with live console output, breakpoint and code step-though, using Xcode and the --iphone option. Launch the app's MKB from the command line with "--iphone" to create a native iOS Xcode project with full iOS debugging features. Note that the compiled app uses a special static library version of the iOS loader, which means it will differ from a normal Marmalade app in subtle ways and is NOT supported for App Store submission. --iphone mode is useful for profiling and fixing bugs in EDK extensions. It is more productive to do as much debugging as possible on the desktop in the Marmalade Simulator rather than on device. Use S3E's trace and error output functionality with the console log provided by Xcode on Mac or the iPhone Configuration Utility on Windows.
Why does my Marmalade iOS app fail App Store submission with a "...the signature was invalid..." error?
certificate rather than a Distribution one. Check the details of the profile in Xcode, the iPhone Configuration Utility or the iPhone Developer portal.
Marmalade for Android (Platforms and Devices/Android)
How does Marmalade handle the differing screen resolutions and capabilities of Android devices?
There is a wide variety of Android devices with different screen resolutions, CPU and GPU capabilities, memory and hardware peripherals. This fragmentation is handled in two ways. The underlying functionality and capabilities of Android devices are exposed by the S3E API layer, and the Marmalade Studio modules such as IwGx are designed to support easy creation of code and assets that can “scale” across the range of devices you wish to support.
For any native Android OS functionality not exposed by the S3E layer, or that you wish to use a third party library, you can use the EDK to develop a wrapper module allowing your app to call through to the native code.
Do I need the Android SDK to develop Android apps using Marmalade?
While you do not need the Android SDK to create Android apps, it is highly recommend for serious development. If you download the Android SDK and install the device drivers, you can "Package, Install and Run" your app directly on the device and view the debug trace using the "Android Debugger Bridge". Additionally, if you wish to use the EDK to create extensions for Android, you will require the Android SDK and Android NDK.
Note that you do require the Java Development Kit (JDK) in order to deploy to Android; however, you do need it in order to use the EDK for creating Android extensions.
How do I debug apps on Android?
You can view the Android trace in real time using the Android Debugger Bridge (adb) from the Android SDK. Connect the device via USB and ensure the device drivers are installed (by following the Android SDK instructions). You can then use the command 'adb logcat' to view the trace of a debug build of your app. For more information see the Android Debug Bridge documentation.
If the device has memory card inserted, you can find the iwtrace.txt file at its root (/sdcard/iwtrace.txt).
Why do my textures appear white after suspending and resuming the on Android?
On Android the OpenGL ES context is sometimes lost while the app is in the background. You can solve this by using Marmalade’s IwGL abstraction, in which case the textures will automatically be restored on resume. Alternatively if you are using OpenGL ES APIs directly without IwGL, you will need to restore any lost OpenGL ES state (such as the textures) in the S3E_DEVICE_UNPAUSE callback.
How is screen rotation handled on Android devices?
On Android, the screen surface provided by s3eSurface is resized on rotation to match the new screen orientation. This means that s3eSurface functions will provide new values for the width and height of the surface as the device is rotated. The s3eSurface blit direction will not change as the surface rotates on Android devices.