Usage

import com.newgrounds.API;
API.unlockMedal(medal_name:String, popup_x:Number, popup_y:Number);

• medal_name - The name pf the medal you want to unlock.
• popup_x - An optional x position for the default medal popup.
• popup_y - An optional y position for the default medal popup.

This call will unlock a medal for the local user. If the user is logged in to a site with Newgrounds API integration, the medal will be unlocked to their profile, otherwise the medal will be unlocked to an encrypted SharedObject.

If the medal was already unlocked by the user, this call will simply be ignored.

The medal popup is a movieclip that is embedded into the API Connector component. If you do not wish to use the default medal popup, you can disable it via the component parameters, and generate your own custom popup (see examples below for listening to medal events).

This command will immediately fire an UNLOCK_MEDAL event, and will also fire a MEDAL_UNLOCKED event when the server has unlocked the medal to the user's account. Note: medal events return Medal instances.

Examples

The following examples demonstrate how to unlock a medal called "My Medal" and catch the unlock event. Using the event listener is ideal because you can unlock the event from multiple objects, sprites, etc, but still catch them from a single, manageable script.

Actionscript 3.0

import com.newgrounds.API;
import com.newgrounds.APIEvent;
import com.newgrounds.Medal;


// This function will fire when the unlockMedal command is called
function onMedalUnlocked(event:APIEvent):void {
    if (event.success) {
        // get the medal instance
        var medal:Medal = event.data.medal;


        // trace out what medal was unlocked, and how many points it is worth.
        trace("You unlocked '"+medal.name+"'! (value: "+medal.value+" points)");
    }
}


// tell the API to use the above listener when a medal is unlocked.
API.addEventListener(APIEvent.MEDAL_UNLOCKED, onMedalUnlocked);


// Unlock the medal
API.unlockMedal("My Medal");

Actionscript 2.0

import com.newgrounds.API;
import com.newgrounds.APIEvent;
import com.newgrounds.Medal;


// This function will fire when the unlockMedal command is called
function onMedalUnlocked(event:APIEvent) {
    if (event.success) {
        // get the medal instance
        var medal:Medal = event.data.medal;


        // trace out what medal was unlocked, and how many points it is worth.
        trace("You unlocked '"+medal.name+"'! (value: "+medal.value+" points)");
    }
}


// tell the API to use the above listener when a medal is unlocked.
API.addEventListener(APIEvent.MEDAL_UNLOCKED, onMedalUnlocked, this);


// Unlock the medal
API.unlockMedal("My Medal");