00:00
00:00
Newgrounds Background Image Theme

aniMATING just joined the crew!

We need you on the team, too.

Support Newgrounds and get tons of perks for just $2.99!

Create a Free Account and then..

Become a Supporter!

Newgrounds Wiki: API

  • Package: com.newgrounds
  • Class: API
The main interface for the Newgrounds API.

Methods

These are the methods of API.

addEventListener

public static function addEventListener(eventType:String, listener:Function, priority:int, useWeakReference:Boolean):void
Registers an event listener object with the API so that the listeners receives notification of an event.
  • Parameters
    • eventType:String
      The type of the event. Should match an event type in APIEvent.

    • listener:Function
      The listener function that processes the event. The function must accept an event object as its only parameter.

    • priority:int
      The priority level of the event listener. The higher the number, the higher the priority. All listeners with priorty n are processed before listeners of priority n-1.

    • useWeakReference:Boolean
      Determines whether the reference to the listener is strong or weak. A strong reference prevents your listener from being garbage-collected.

      connect

      public static function connect(root:DisplayObject, apiId:String, encryptionKey:String, movieVersion:String):void
Initializes the Newgrounds API and starts a connection to the Newgrounds server. This should be called before any other API methods or properties.

After calling connect, the API will fire an API_CONNECTED event. If version control is enabled for the game and a new version is available, event.data.newVersion will be true.
  • Parameters
    • root:DisplayObject
      The root DisplayObject.

    • apiId:String
      The API ID for this movie, as shown on the API settings page.

    • encryptionKey:String
      The encryption key for this movie, as shown on the API settings page.

    • movieVersion:String

      createSaveFile

      public static function createSaveFile(groupName:String):SaveFile
Creates a new save file.
  • Parameters
    • groupName:String
      The name of the save group to which this file will belong.

  • Returns
    • SaveFile
      The newly created SaveFile, or null if an error occurred.

      createSaveQueryByDate

      public static function createSaveQueryByDate(groupName:String, sortDescending:Boolean):SaveQuery
Creates a save query that will list files sorted by date.
  • Parameters
    • groupName:String
      The name of the save group to query.

    • sortDescending:Boolean
      If true, newer files will be listed first. Otherwise, older files will be listed first.

  • Returns
Creates a save query that will search for save files by name.
  • Parameters
    • groupName:String
      The name of the save group to query.

    • filename:String
      The name to search for.

    • exactMatch:Boolean
      If true, the query only list files that have the exact name. Otherwise, the query lists files that contain the name.

    • sortDescending:Boolean
      If false, files will be listed in alphabetical order.

  • Returns
Creates a new save query that will list files sorted by rating.
  • Parameters
    • groupName:String
      The name of the save group to query.

    • ratingName:String
      The rating to sort by.

    • sortDescending:Boolean
      If true, the highest rating submissions will be listed first.

  • Returns
Creates a new save query.
  • Parameters
    • groupName:String
      The name of the save group to query.

  • Returns
    • SaveQuery
      The newly created save query, or null if an error occurred.

      disconnect

      public static function disconnect():void
Disconnects from the Newgrounds API.

getMedal

public static function getMedal(medalName:String):Medal
Returns the medal with the specified name. Returns null if no medal with that name exists for this game, or the API is disconnected.
  • Parameters
  • Returns
    • Medal
      The Medal object with the specified name.

      getSaveGroup

      public static function getSaveGroup(groupName:String):SaveGroup
Returns the save group with the specified name. Returns null if no save group with that name exists, or the API is disconnected.
  • Parameters
  • Returns
    • SaveGroup
      The SaveGroup object with the matching name, or null if the save group is not found.

      getScoreBoard

      public static function getScoreBoard(scoreBoardName:String):ScoreBoard
Returns the score board with the specified name. Returns null if no score board with that name exists for this game, or the API is disconnected.
  • Parameters
  • Returns
    • ScoreBoard
      The ScoreBoard object with the matching name.

      loadCustomLink

      public static function loadCustomLink(linkName:String):void
Loads a custom website in a new browser window. You can manage your custom websites on your API Settings page.
  • Parameters
    • linkName:String
      The name of the custom website to be loaded. This should match the name of a link on your API Settings page.

      loadLocal

      public static function loadLocal(saveId:String):Object
Loads data that was saved locally to this computer with saveLocal.
  • Parameters
    • saveId:String
      The id of the data to load.

  • Returns
    • Object
      The loaded data. Returns null if the data does not exist or could not be loaded.

      loadMySite

      public static function loadMySite():void
Loads your personal website in a new browser window. You can specify the URL for your site on your API Settings page.

loadNewgrounds

public static function loadNewgrounds():void
Loads newgrounds.com in a new browser window.

loadOfficialVersion

public static function loadOfficialVersion():void
Loads the official version of this game in a new browser window. The URL for the official version can be set on your API Settings pages.

loadSaveFile

public static function loadSaveFile(saveId:uint, loadContents:Boolean):void
Loads a save file with the specified save ID.
  • Parameters
    • saveId:uint
      The ID of the file to load.

    • loadContents:Boolean
      If true, the file contents will be loaded. Otherwise, only the file metadata will be loaded.

      loadScores

      public static function loadScores(scoreBoardName:String, period:String, firstResult:uint, numResults:uint, tag:String):ScoreBoard
Loads a list of scores from a score board. The API will fire a SCORES_LOADED event when the scores have loaded, or an error occurs.
  • Parameters
    • scoreBoardName:String
      The name of the score board that will load scores.

    • period:String
      The timeframe for which to load scores. Defaults to listing the best scores of all-time, ScoreBoard.ALL_TIME.

    • firstResult:uint
      The rank of the first result to load. Scores start from rank 1.

    • numResults:uint
      The number of scores to load.

    • tag:String
      Filter scores based on their tag. If tag is null, all scores will be listed. Otherwise, only scores with the matching tag will be listed.

  • Returns
    • ScoreBoard
      The ScoreBoard object with the matching name.

      logCustomEvent

      public static function logCustomEvent(eventName:String):void
Logs a custom event with the API. This method can be used for stat tracking and custom metrics in your game. You can view these stats on your API settings page.
  • Parameters
    • eventName:String
      The name of the custom event to log.

      postScore

      public static function postScore(scoreBoardName:String, numericScore:Number, tag:String):void
Submits a score to a score board. The API will fire a SCORE_POSTED event if the score was posted, or if there was an error. The player must be logged-in and playing on Newgrounds to submit a score. Only the player's best score is posted to the score board.
  • Parameters
    • scoreBoardName:String
      The name of the score board.

    • numericScore:Number
      The player's score.

    • tag:String


      removeEventListener

      public static function removeEventListener(eventType:String, listener:Function):void
Removes a listener from the API. If there is no matching listener registered, a call to this method has no effect.
  • Parameters
    • eventType:String
      The type of the event.

    • listener:Function
      The listener object to remove.

      saveLocal

      public static function saveLocal(saveId:String, saveData:Object):Boolean
Saves data locally to this computer. To save data to a Newgrounds account, use SaveFile.
  • Parameters
    • saveId:String
      An identifier for this data.

    • saveData:Object
      The data to save.

  • Returns
    • Boolean
      Returns true if the data was saved, false otherwise.

      stopPendingCommands

      public static function stopPendingCommands():void
Stops any pending API commands.

unlockMedal

public static function unlockMedal(medalName:String):void
Unlocks a medal. Medal names are case sensitive. The API will fire a MEDAL_UNLOCKED event on success or failure. If a user is logged-in and playing on Newgrounds, the medal will unlock on their account and be visible in their profile. If a user is not on Newgrounds or not logged-in, then the medal unlock will be stored locally on their computer.
  • Parameters
    • medalName:String
      The name of the medal to unlock.

      Properties

      These are the properties of API.

      adsApproved

      public static var adsApproved:Boolean;
Specifies whether ads have been approved for this game.

apiId

public static var apiId:String;
The API ID of the movie. The API ID is set when connect is called.

connected

public static var connected:Boolean;
Returns true if the API has connected successfully.

debugMode

public static var debugMode:String;
The debug mode of the movie. The debug mode allows you to easily test different use cases during development. If debugMode is set to RELEASE_MODE, then the API operates normally. If debugMode is set to DEBUG_MODE_LOGGED_IN, then the API operates as if a logged-in user was viewing the movie on Newgrounds. If a game is played on the web, debugMode will automatically turn off and revert to RELEASE_MODE. However, it is still a good practice to set debugMode to RELEASE_MODE before making your game publically available.

hasUserSession

public static var hasUserSession:Boolean;
Specifies whether the user is logged in.

hostDomain

public static var hostDomain:String;
The domain that is hosting the file.

hostURL

public static var hostURL:String;
The full URL to this file.

isNetworkHost

public static var isNetworkHost:Boolean;
isNetworkHost is true if the movie is hosted on the web, or false if the movie is running locally.

isNewgrounds

public static var isNewgrounds:Boolean;
Specifies whether the game is hosted on Newgrounds.

medals

public static var medals:Array;
Returns a list of the medals for this game. Returns an empty array if there are no medals, or the API has not connected.

publisherId

public static var publisherId:uint;
The publisher ID of the site that is hosting this game. If the game is hosted by an unknown publisher or running locally, publisherId is 0. If the game is hosted by Newgrounds, publisherId is 1.

saveGroups

public static var saveGroups:Array;
Returns a list of save groups for this game. Returns an empty array if this game has no save groups, or the API has not connected.

scoreBoards

public static var scoreBoards:Array;
Returns a list of scoreboards for this game. Returns an empty array if this game has no scoreboards, or the API has not connected.

sessionId

public static var sessionId:String;
The session ID of the user playing the game. If the user is not logged-in, session ID is 0.

userId

public static var userId:uint;
The ID of the user.

username

public static var username:String;
The username of the user.

Constants

These are the constants of API.

DEBUG_MODE_HOST_BLOCKED

public static const DEBUG_MODE_HOST_BLOCKED:String = "debugModeHostBlocked";
The DEBUG_MODE_NEW_VERSION debug setting will cause the API to operate as if sitelocking is enabled, and the file is hosted on a blocked domain. The API_CONNECTED event will fail with a HOST_BLOCKED error.

DEBUG_MODE_LOGGED_IN

public static const DEBUG_MODE_LOGGED_IN:String = "debugModeLoggedIn";
The DEBUG_MODE_LOGGED_OUT debug setting will cause the API to operate as if the user was on Newgrounds while logged-in.

DEBUG_MODE_LOGGED_OUT

public static const DEBUG_MODE_LOGGED_OUT:String = "debugModeLoggedOut";
The DEBUG_MODE_LOGGED_OUT debug setting will cause the API to operate as if the user was on Newgrounds, but not logged-in.

DEBUG_MODE_NEW_VERSION

public static const DEBUG_MODE_NEW_VERSION:String = "debugModeNewVersion";
The DEBUG_MODE_NEW_VERSION debug setting will cause the API to operate as if there is a new version of the movie available. The API_CONNECTED will have the newVersion flag set.

RELEASE_MODE

public static const RELEASE_MODE:String = "releaseMode";
The RELEASE_MODE debug setting will cause the API to operate normally, without any debug functionality.

VERSION

public static const VERSION:String = "3.0.4.3 beta AS3";
Specifies the version of the Newgrounds API. 11