Skip to content

Manual

The Metro object provides a method for the Construct 2 projects to interface with Windows 8. This plugin is active only when the user exports the project as a “Windows 8 Metro app” with Construct 2.

This plugin provides a very quick and easy way to integrate into Windows 8. Just adding the plugin will give you the Preferences, About and Help pages in Windows 8 Settings Charm. In the standard Construct 2 plugin format, Metro plugin provides the following Properties, Conditions, Actions and Expressions.

[This plugin needs Windows 8 RTM & Construct2 r105. Also you should disable Mimify script while exporting from Construct2.]

 

Metro Properties

1.     Enabled

Set this to False when you want to run the project (preview the project) in Construct 2 or when you want to export it other than Windows 8 Metro app. This will make sure that the project does not use Windows 8 specific dependencies. Note that you might get JS errors when you have this property set as True and preview with Construct 2.

2.     Show Preferences, Show Help, Show Purchase and Show About

In Windows 8, users can invoke the Settings charm by swiping from the left edge on a touch screen or with Windows + C -> Settings. The Settings charm is context sensitive in Windows 8 ie, the charm applies to the currently running app. It provides standard options “Permissions” and “Rate and review”. The Metro object provides way for the game developer to add Preferences, Help and About options with ease.

The properties “Show Preferences”, “Show Help” and “Show About” will add the Preferences, Help and About options to the Settings charm. When user invokes the options, the corresponding HTML files provided by this plugin is loaded by Windows 8. Because it is a standard HTML file, you can edit it to suit your needs.

We will discuss about Preferences option a bit later. The Help page is ideal to add instructions to play the game. The About page is ideal to add details about yourself/your game development studio and provide links to your website/ Twitter/Facebook. When you have exported the game as the “Windows 8 Metro App” from Construct 2, edit the Settings-About.html and Settings-Help.html to your needs. Since it is just a html page, you will be able to customize it by changing the background color, header color, embed pictures etc,. to make it more appealing.

Windows 8 Settings Charm with Construct 2 plugin

With this plugin, you can get the options Preferences, Purchase, Help and About for free with no effort.

3.     Show Background Music Toggle, Show Sound Effects Toggle

These properties are valid only when Show Preferences is set to True. The Preferences page currently provides two options a Toggle switch for Background Music and one for Sound Effects. You can use these properties to select which Toggle switches you want to show for your game. This plugin provides triggers and expressions to find out the state when user changes the toggles.

4.     Show Reset Button

Presents a reset button in the Preferences pane. Valid only when Show Preferences described above is enabled. Construct 2 event sheet can listen for On Game Reset trigger described below when the user invoked the Reset button.

Peferences pane in Windows 8 Settings charm

You will get the Music control UI and option to Reset stored game data.

5.     Purchasing Test Mode

Set this to true when you want to test Trial/in app purchase capabilities for your app. Refer to this blog post on details. The following properties are deprecated. See the previously mentioned blog for more details. We have a more powerful system to support more than 1 in app purchase feature.

6. Sensors support[New]

When you game needs to use the Accelerometer, Inclinometer, Gyrometer or Light sensor you should turn on the corresponding properties to True. Caution: Set the properties to true only if you game uses them. Else it will cause unnecessary battery drain for your users. See the expressions below on how to get the values reported by the sensors.

Metro Conditions

1.     On Game Lost Focus

Triggered when the Metro game loses focus – this can happen when the user invokes the Charms, the game sent to background, system dialog pops up etc,.

Usage: Typically, games need to be paused when losing focus so that any unintended action does not happen in the game. For example  the Ghost Shooter sample above is paused and a Continue button is displayed.

2.     On Game Resized

In order to better handle Windows 8 resizing/snapping/scaling to different screen sizes, please follow this blog post. On Game Resized is not recommended anymore.

Windows 8 supports resizing a Metro app into a snapped state. This condition is triggered when the user snaps/unsnaps the app.

Usage: Refer to the WindowViewState expression to detect what the current state of the app is. If you want to keep it simple, you can pause your game when snapped and request the user to unsnap to continue the game. Also Refer Request Unsnap action.

3.     On User Toggled Background Music UI

This is triggered when the user toggles the Background Music Toggle button in the Settings Charm Preferences. Use this to actually turn off background music in the game in the event sheet.

4.     On User Toggle Sound Effects UI

This is triggered when the user toggles the Sound Effects Toggle button in the Settings Charm Preferences. Use this to turn off the sound effects in the game in the event sheet.

5.      Local/Roaming Key Exists

Check whether a value has been saved for a key in local/roaming app settings.

6.      On Game Reset

Triggered when the user has reset the game via the Settings-GamePreferences pane. When this is triggered, all the game state stored in local and roaming store is gone and it is best to restart the game.

7.      On Purchase Completed

Triggered when the user has completed a transaction from the store. This can either be purchasing of a full version of your app or a purchase of in app feature. On receiving this trigger, make sure to check the features purchased and activate accordingly. See example.

8.       Is in Trial mode

 Returns true if the app is currently in trial mode. For a free app this will always be true.  See example for usage.

9.       Is In-App feature purchased

Needs a featureId as argument. Returns true if the user has purchased the specified in app feature. For a free app this will always be true. See example for usage.

10.     Sensors availability

Is Accelerometer Available, Is Gyrometer Available, Is Inclinometer Available and Is Light Sensor Available conditions return true if the PC on which your game is running support those sensors. (Note that you will have to set the corresponding properties in Metro object’s property pane for the sensors to work.)

Metro Actions

1.     Invoke Settings Charm

Invokes the Settings Charm.

Usage: You could have a “Settings” sprite in your game and issue this Action in the OnObjectClicked condition of the sprite. Note that this is not strictly required since the user can always invoke the settings charm with Windows + i or swiping on the edge. This is to just give the user one another entry point to invoke the settings charm.

2.     Set Background Music UI State

If the game has it’s own UI to control Audio states (in addition to settings charm), use this to set the UI state in Settings Preferences charm.

3.     Set Sound Effects UI State

If the game has it’s own UI to control Audio states (in addition to settings charm), use this to set the UI state in Settings Preferences charm.

4.     Request Unsnap

Try to unsnap the game when in snapped state.

Usage: If your game is not designed to be run in the snapped mode of Windows 8, you can pause the game and show a button with this action when you are in snapped state.

5.      Update Live Tile

Update the Live Tile for the game with a message. A requirement is that the app should support wide tile. Please refer to this post on how to set up a wide tile.

Usage: Live tile is a useful way to update the user about the state of the game and invite them into playing your game again. This action can be used t post messages like scores, level cleared etc.,

6.      Set Local/Roaming Value

Store a value (string or number) for a key in local/roaming storage. If the key does not exist it is created, otherwise its value is simply updated.

7.      Remove Local/Roaming Value

Delete a key (and its associated value) from local/roaming storage. It will no longer exist after this action.

8.      Clear Local/Roaming Storage

Remove all the data stored in the local/roaming storage in the current Windows 8 PC for this game.

9.      Set Advertisement Visibility

Show or hide the advertisement with a specified id. See the blog post for usage.

10.    Request App Purchase

Initiate Windows 8 app purchase. When the user has purchased the game, Construct 2’s On Purchase Completed condition will be invoked. See example for usage.

11.    Request In-App Purchase

Initiate Windows 8 app purchase for an in app feature mentioned in the argument. When the user has purchased the feature, Construct 2’s On Purchase Completed condition will be invoked. See example for usage.

Metro Expressions

1.     BackgroundMusicUIState

Get the On/Off state of the Background Music Toggle switch in Preferences.

2.     SoundEffectsUIState

Get the On/Off state of the Sound Effects Toggle switch in Preferences.

3.     WindowViewState

Get the Game Window state – Snapped, Filled, FullScreenLandscape or FullScreenPortrait.

4.      Local/RoamingValue

Retrieve the value stored for a key in the local/roaming storage.

5.      AccelerationX, AccelerationY and AccelerationZ (Needs Accelerometer support in hardware)

Gets the g-force acceleration along the x-axis, y-axis and z-axis respectively as documented in MSDN.

6.     AngularVelocityX, AngularVelocityY and AngularVelocityY (Needs Gyrometer support in hardware)

Gets the angular velocity, in degrees per second, about the x-axis , y-axis and z-axis respectively as documented in MSDN.

7.     PitchDegrees, RollDegress and YawDegrees  (Needs Inclinometer support in hardware)

Gets the rotation in degrees around the x-axis , y-axis and z-axis respectively as documented in MSDN.

8.     IlluminanceInLux (Needs LightSensor)

Gets the illuminance level in lux using Light Sensor

17 Comments

Leave a Comment
  1. Andrew Ames / Oct 2 2012 12:31 pm

    What difference does minifiy script being disabled make? I am having massive performance issues with my game when loading more than 50 of these very small sprites. In the browser i can load 2000 of these before the FPS drops, but get to around 50 in Win8 and FPS drops massively, I’m going to try not using minify script and pray to god this is the solution!

    • iunkn / Oct 3 2012 1:00 am

      Hi Andrew, to eliminate variables, can you try without the plugin and enable mimifier while exporting and see if you still have perf issue? If so, you might want to bring it up in Scirra forums.
      Edit: As seen from http://en.wikipedia.org/wiki/Minify, it looks like Mimifier cannot cause perf issues.

  2. Owen / Oct 10 2012 8:28 pm

    Hi Iunkn, I am trying to run your Metro Ghost Shooter example, but i’m having an issue. I’m using Construct 2 r105 and exporting the project to Visual Studio. I add the 4 settings html files, test purchase xml file and a test certificate into the project. The project then runs and builds just fine, but when i go into the settings charm menu the only option that works is permissions, all the others just result in the menu closing. There is no apparent error the settings menu just closes.

    I should say at this point that i am using Windows 8 Pro (I have access via my MSND account) rather than RTM as you suggest. Have you done any testing on Windows 8 Pro yet, would you expect everything to still work?

    • iunkn / Oct 10 2012 8:49 pm

      Windows 8 Pro should be good.

      Something’s missing here. You are not required to “add the 4 settings files and test purchase xml file” to the VS project. They should be already part of the exported project. Please PM me over through Scirra’s website and we will figure it out.

      I think the plugin installation did not go through well. Do you mind installing the plugin again and make sure all the files are copied over successfully?

      • Owen / Oct 11 2012 11:50 am

        Thanks for responding to me. I removed the plugin from my computer and reinstalled it manually, following the steps in your install.cmd file. Everything seems to work fine now, so i can only assume there was a problem with my initial install. Thanks for pointing me in the right direction.

        btw, excellent work on this plugin 🙂

  3. Michael / Dec 26 2012 9:32 pm

    Hi, thanks for all your work, very much appreciated!

    When trying to export to Win8 I get an error:
    Can’t open file ‘C:\Program Files\Construct 2\exporters\html5\metro\index-fs.html’

    Any thoughts?

    Using latest version of Construct 2 on Windows8 Pro.

    Regards
    Michael

    • Michael / Dec 28 2012 5:04 am

      Hi Iunkn, first Thanks for your time – much appreciated!

      Finally after a bit of playing around I uninstalled the plugin and Construct 2 then reinstalled both, as with Owen I had to manually copy the files for the plugin, however all is Ok with Construct 2 side of things, but get problems running in VS.

      When I run the game example from VS snapping and pausing works fine, but when Using the Settings pane I get an error:
      Quote – Exception is about to be caught by JavaScript library code at line 2351, column 21 in ms-appx://microsoft.winjs.1.0/js/base.js

      0x800c0005 – JavaScript runtime error: The system cannot locate the resource specified.

      If there is a handler for this exception, the program may be safely continued. – End Quote

      The line in question reads: req.send(options.data);

      The exception occurs when you choose any of the settings options except Permissions.

      Products being used:
      Windows 8 Pro
      Construct 2 r114
      VS Express for Windows 8

      Again any help is much appreciated.

      • iunkn / Jan 27 2013 6:24 pm

        @Michael, sorry for the troubles and delayed response. Do you still have the issues?

        • Michael / Jan 28 2013 9:44 pm

          Hello iunkin, thanks for your reply. I gathered from the delay and some recent posts on Scirra that you have been on vacation. I trust you had a great time and a welcomed rest!

          I was trying the plugin with a test app and run into the problems noted above. So all works fine, but when I select any of the options from the Settings Pane (except permissions) the above error occurs.

          There is also an error displayed in the output panel of VS when building the app (can’t remember what it is off-hand – the same error occurs using the Scirra plugin as well) so I don’t know if they are related.

          Anyway at the moment I am working on a real app for the store, so when I get up to the metro side of things I will go through your instructions meticulously so I can be certain I am not missing anything or doing something wrong, and then I will let you know how things go.

          Thanks again and nice to meet you!

  4. Michael / Feb 12 2013 5:17 am

    Hello iunkin,

    First thanks again for this plugin and your time – very much appreciated.

    Up to testing as win8 app now!

    The plugin works fine, the initial problems I had were due to bad installation…. all fine now – very nice work you have done there!

    Just a question about Request App Purchase:
    This also works as expected in the simulation except that once the purchase is complete the purchase option still remains operational in the purchase pane. Does this have to be disabled in Construct or does that get handled by the Store when the app is purchased for real once published?

    Thanks again in advance….

    Kind Regards
    Michael

    • Michael / Feb 13 2013 4:00 am

      Hello iunkin,

      again – thanks for great work on this plugin!

      Please ignore the above question – all understood now!

      Thanks for your time and effort – very much appreciated. 🙂

  5. Michael / Feb 14 2013 8:04 am

    Hello again iunkin,

    Another query about this awesome plugin.

    At present I am using WebStorage for my game, and it works fine with Win8 apps.

    So I was just wondering about the Local\Roaming Storage that comes with the Metro plugin.

    Is there an advantage to using that in place of WebStorage?

    Thanks for your time…

    • iunkn / Feb 14 2013 10:12 pm

      Hi Michael,
      the Local storage is very similar to WebStorage and you don’t have any additional benefits (except it is the recommended way for Windows Store apps.)

      Roaming Storage is very interesting because, once you store something in it, it ‘roams’ to all the PCs owned by the user (provided they sign in using Microsoft accounts). So, if a user plays a game in his tablet, you can roam things like unlocked levels and scores and they will be available when the game is played on the laptop. It is pretty cool 🙂

      • Michael / Feb 14 2013 11:15 pm

        Hello iunkin,
        thanks very much for your time, I hope all is well for you over there.

        Roaming sounds cool and would be a preferable option for the user experience I think.

        I’m just wondering what happens if the user is not signed in with MS account.

        In that case would the Roaming data get saved locally and Win8 updates it when they sign in?
        Or do we need to check that they are signed in and use Local storage if they are not?

        Thanks again.

        • iunkn / Feb 15 2013 5:59 pm

          It is all transparent. No special logic needed from app’s part to handle this. You can use Roaming storage and if the user is signed in with Microsoft account, it will roam. Else it has the same behavior as Local storage. As you can see, you can always use Roaming storage.

          • Michael / Feb 16 2013 3:09 am

            Hi iunkin,

            That’s great to know.

            I have implemented Roaming in my app and testing confirms what you are saying – this is easily the best choice for Win8 apps.

            Local\Roaming storage works as easily as WebStorage as you explain in the Plugin details, so again it is some very nice work on your part!

            Thanks for your time and expertise on this, and for responding to my questions.

            Regards Michael

  6. Michael / Apr 7 2013 3:21 pm

    Hello Again iunkin,

    First thanks for considering this post.

    I trust you are well, sorry to prevail on your time yet again…

    I have recently been testing a game, fine tuning it for release to the Microsoft Store and have come across a few glitches, that were not present before.

    The issues are related to the Charms bar.
    1) When you invoke the charms bar and choose any of the options except permissions, and then choose the back arrow the charms panel closes instead of going back to the default Settings Panel.

    2) When you opt to reset the game, the charm bar just closes without asking for confirmation and without performing the reset

    3) When testing the app purchase, again the charms panel just closes and the usual test purchase dialog does not appear.

    I have tried removing and reinstalling the plugin but to no avail.

    Note these have only shown up since installing the latest C2 beta (R124), previously they were working flawlessly.

    I have not changed any of the previous coding for the metro stuff in the game and I will not ship the app until a stable release of C2 is available, but I was just trying to determine if the current release has broken the plugin, or if it is something I have introduced unwittingly – although I can’t see how that is possible…

    I would greatly appreciate if you could to test if you have the same thing happening.

    Thanks in advance for your help.

    Kind Regards
    Michael

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s