BETA

This tutorial assumes you already have a Wick project you want to add the Newgrounds.io API to, and that it is open in another browser tab. It also assumes you have some programming knowledge.

Using Newgrounds.io Widgets in Wick Editor

Step 1: Download The .wick File

Click Here to download Newgrounds.io Widgets.1.0.0.wick.

Step 2: Load the .wick File

Open http://wickeditor.com/wick-editor/ in a new browser tab.

Select 'Open Project' from the File menu, then open the Newgrounds.io Widgets.1.0.0.wick file.

Hit 'Ok' when asked 'Open a new project? All unsaved changes to the current project will be lost!'.

Note: If you explore this project, it has a lot of helpful text and comments. You man be able to figure out more advanced ways of using these widgets than what we do in this tutorial. Go for it!

Step 3: Set up the API Connector

The API Connector is a Clip containing most of the JavaScript code used by the Newgrounds.io API.

Right click on the Clip (It's the Tankman with the red gear icon) and select 'Copy'.

Create a new Layer in your Wick project, and name it 'API Connector'. Add a frame in your new layer, then paste the API Connector Clip to the stage.

By default, the connector will be configured for a test project. You will need to select the API Connector Clip you just pasted, and edit it's JavaScript.

Change the values for 'appID' and 'encryptionKey' to match what's on the API Tools page of your Newgrounds Project.

When your game is ready for production testing, be sure and change 'debugMode' to false as well.

Step 4: Implement Version Control and Host Licensing

* If you are using this feature, be sure to configure 'Game Protection' and 'Version Control' sections of your Newgrounds Project's API Tools section.

* If you are NOT using these features, skip to Step 5

In the Newgrounds.io Widgets project, jump to the 'Checking host & version' frame, and edit it's JavaScript.

Copy the code, and paste it into your Project wherever you are doing the version and host check. We recommend doing this before your title screen.

Change the value of 'var version' to match the current version of your game.

Further in the script are some if/else clauses with helpful comments. Update the code in these to handle the different situations this check can end in.

If the check says the host is bad, or the version is old, use something like root.gotoAndStop('bad_version') to take the player to a frame with details on where to play the latest official version.

Step 5: Get the Player Logged In

Before you try unlocking any medals, or posting any scores, the player must be logged in with their Newgrounds account.

In the Newgrounds.io Widgets project, jump to the 'Logging The Player In' frame. Copy the 'NEWGROUNDS Passport' clip, and paste it wherever you want the login widget to appear in your Wick game.

Go back to the Newgrounds.io Widgets project, select the 'Logging The Player In' frame and edit it's JavaScript.

Copy and paste the example code into the same frame you pasted the 'NEWGROUNDS Passport' clip.

Go through the pasted script and put in any code you need to handle all the possible login events.

If you need to verify that the user logged in later in your game code, simply use: if (ngio.user) { /* do stuff */ }.

If the user is logged in, you have access to all the following: ngio.user.id, ngio.user.name, ngio.user.url and ngio.user.supporter. You can use this info to display their name, link to their userpage, and even unlock special supporter-only features in your game.

Users can choose to let your game remember their login, so they will sign in automatically the next time they play. Because of this, you should also put a 'sign out' button in your game so they can choose to revoke that automatic login. See the 'Logging The Player Out' frame for an example button.

Step 6: Handling Medals

If your game doesn't use this feature, skip to Step 7

In the Newgrounds.io Widgets project, jump to the 'Unlocking medals' frame.

Note: If your game runs at less than 45fps, jump to the 'lower fps version' frame instead.

Copy the medal component clip.

In your game project, add a new layer and name it 'Medal Unlock'. Move this so it's the top layer. Add a keyframe at frame 1, and stretch it so it's as long as your entire timeline.

Paste the medal component. You can move it somewhere off the main stage, or simply lock and hide this layer. When unlocking medals, this clip will position itself automatically. This clip has to be on the stage, and loaded if you want it to be seen when a medal is unlocked.

When your game code is ready to unlock a medal, simply call ngio.unlockMedal(medal_id);.

By default, the medal unlock clip plays at the bottom-center of the screen. If this is not an ideal location, you can pass a new position when you do the unlock, like so: ngio.unlockMedal(medal_id, {x: x_position, y: y_position});.

To see if the player has already unlocked a medal, check: ngio.medalUnlocked(medal_id).

Step 7: Using Scoreboards

If your game doesn't use this feature, you are done!

In the Newgrounds.io Widgets project, jump to the 'Posting High Scores' frame and edit it's JavaScript.

This code contains examples of different ways you can post a score, and even verify it posted properly. Copy the code you want to use, and paste it into your game, being sure to change 'scoreboard_id' and 'my_score' to the appropriate values.

Note: When setting up your scoreboards on your Newgrounds Project (and selecting a score format), it will mention that all scores must be posted as integer values. This means if you are using a money-based score, for example, and you wanted to post a score of $209.99, you would need to post it as 20999.

Back in the Newgrounds.io Widgets project, jump to the 'Showing High Scores' frame. Copy the scoreboard clip.

In your game, paste the clip into whatever frame you want to show scores on. Select the clip and edit it's JavaScript.

The JavaScript shows a few examples of how to load scores onto the table. Use whichever example suits your needs, being sure to change 'scoreboard_id' to the proper value.

You can paste this clip on a unique frame for every different scoreboard you may need.