> For the complete documentation index, see [llms.txt](https://smartui-docs.pixelperfectstudio.mx/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://smartui-docs.pixelperfectstudio.mx/miscellaneous-addons/newgrounds.io-plugin.md).
# Newgrounds.IO Plugin
## Introduction
[Newgrounds.com ](https://www.newgrounds.com/)is a popular online platform that allows users to create, share, and discover various forms of media, including animations, games, art, and music. Launched in 1995, it became known for its interactive content, user-generated works, and a supportive community of creators. The site also hosts forums and features competitions and collaborations, making it a hub for independent artists and developers to showcase their talents and engage with others.
In its game development branch, Newgrounds has supported indie game developers for years. They created NewgroundsIO, an API that allows developers to integrate their games with the platform, enabling features such as:
* User Authentication
* Leaderboards (a.k.a. Scoreboards)
* Medals
* Cloud-saved games
* Analytics and Referrals (a.k.a. Events and Loaders)
* Game protection (Host validation)
All of these features have proven to be valuable and relatively easy to use. The NGIO Plugin integrates all the mentioned features, simplifying its use with a set of ACEs and built-in functionality to seamlessly integrate with the platform.
Key enhancements available in this plugin include:
* **Login workflow simplified.** Call the Login and Logout ACEs and the plugin will do the rest.
* **Asyncronous calls**. Available actions are now async, you can queue actions one after another using the [**Wait for previous action**](https://www.construct.net/en/make-games/manuals/construct-3/system-reference/system-actions)**,** available in the System plugin.
* **Built-In Dialogs.** Speed up your development by calling the builtin [#show-medals](#show-medals "mention"), [#show-scoreboard](#show-scoreboard "mention"), and [#show-saved-slots](#show-saved-slots "mention") to interact immedatelly with your players.
{% hint style="info" %} **The plugin is available under an MIT License. Feel free to use it for any kind of project, including commercial use**
{% endhint %}
{% embed url="" %}
NewgroundsIO plugin overlays
{% endembed %}
## Built-In Dialogs
Built-in dialogs help speed up the integration process and save time by eliminating the need to develop a UI, allowing you to focus on the fun part. These modal dialogs are built using HTML and CSS at runtime. All of the built-in dialogs will display the favicon set for your game. Make sure to replace all the icon files in your Construct game to match the dialog headers.
{% hint style="warning" %}
Once a built-in dialog is called, the **Construct 3 runtime will be suspended** until the dialog closes. You can disable this feature in the plugin properties. Refer to[#properties](#properties "mention") for more details.
{% endhint %}
If you want to develop your own dialogs to display scoreboards, medals, and slots, the plugin offers a set of ACEs to retrieve and manage this information.
#### Medals Dialog
Present the medals available for your game. These must be configured in the API Tools section under medals. Make sure your player is logged in to display their medal information; otherwise, it will show the available medals, but not their unlock status.
Medals Dialog
Leaderboards / Score Boards
Show the list of players and their scores. The dialog automatically handles the player's profile picture and retrieves their names and scores.
Score Board / Leaderboard
#### Saved Slots
Display the list of slots available for your game. Newgrounds' cloud-save service offers a free tier that provides up to 3 slots. This dialog gives you a quick way to load the available data and trigger the events in your event sheets to react accordingly.
{% hint style="warning" %}
Before calling this dialog, always use the action [#queue-save-data](#queue-save-data "mention") and pass the current game's data to be saved. This ensures the dialog has the correct information to save whenever the player presses the save button.
{% endhint %}
{% hint style="success" %}
**Saved Slots dialog requires the ****player to login**.
{% endhint %}
Slots Data
## NGIO Plugin
NewgroundsIO API integration for Construct 3. This plugin uses a custom version of the official NewgroundsIO to make it work properly with Construct 3. Built-in dialogs to quickly manage medals, scores, and saved data.
Download
## Properties
| **Property** | **Description** |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Game Version` | Incremental version number. Update it for every new release so that NGIO detects a version change. |
| `Authentication` | Authentication and session data. |
| `App ID` | Application ID taken from your game's 'API Tools' tab. |
| `AES Key` | Encryption Key (AES-128/Base64). Taken from your game's 'API Tools' tab. |
| `NGIO Options` | Newgrounds API Additional configuration. |
| `Check Host License` | This feature lets you control which websites are allowed to host your work. |
| `Auto Log New View` | New views are automatically logged. |
| `Miscellaneous` | Additional convenience functionality. |
| `Prevent Defaults` | Prevents arrow and space keys from being propagated to the top window. Useful to keep the interactions within your game. |
| `Notifications` | Displays a built-in notification dialog for events such as unlocking a medal, saving in a slot, and logging in or out. Please note that notifications will automatically be shown if the player uses any of the built-in dialogs. Manual ACE-triggered notifications depend on this check. |
| `Suspend on Overlays` | Suspends the runtime and pauses all actions in your game while any built-in dialog is open. |
## Actions
***
### `Get Medal`
Read a medal by its Id. Use ***MedalID, MedalName, MedalDescription, MedalDifficulty, MedalIcon*** and ***MedalValue*** to retrieve its data.
| **Parameter** | **Description** |
| ------------- | ------------------- |
| `Medal ID` | Medal ID (numeric). |
### `Load Slot Data`
Retrieves the saved slot data, and triggers **On Loaded.**
| **Parameter** | **Description** |
| ------------- | ------------------ |
| `Slot ID` | Slot ID (numeric). |
### `Get Scores`
Retrieves the scores of the given Board ID and applies the filter criteria.
| **Parameter** | **Description** |
| ------------- | ----------------------------------------------------------------------------------- |
| `Board ID` | Board ID (numeric). |
| `Period` | Period of time to retrieve the data from. |
| `Tag` | Filter by tag (For scores posted with a specific tag). |
| `Social` | Check to retrieve scores from friends only. |
| `Skip` | Number of entries to skip. Use it for pagination (e.g., skip the first 20 entries). |
| `Limit` | Max number of score entries to retrieve. |
### `Load Author URL`
Loads the author's official web page. The official page must be registered in the **Events & Loaders** page of your game before you call this action.
### `Load More Games`
Loads Newgrounds' games page.
### `Load Official URL`
Loads the game's official web page. The official page must be registered in the **Events & Loaders** page of your game before you call this action.
### `Load Referral`
Loads a referral web page. The referrals must be registered in the **Events & Loaders** page of your game before you call this action.
| **Parameter** | **Description** |
| --------------- | ------------------------------------------------------------------- |
| `Referral Name` | The referral name registered and associated with a custom web page. |
### `Log Event`
Logs a custom event to your App Stats board. Newgrounds provides basic analytics capabilities for you to track your game's performance. Custom events must be created in the **Events & Loaders** page of your game before you log them.
| **Parameter** | **Description** |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| `Custom Event` | Event name. Useful events to consider: ***game-start, player-dead, level0-start, level0-end, game-finished.*** |
### `Login`
Open Newgrounds login page. Login times out after 60 seconds.
| **Parameter** | **Description** |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| `Window Mode` | Login window style. By default, a browser tab is used. Beware that some browsers may block popup windows. |
### `Logout`
Closes the session by logging out the user.
### `Post Score`
Posts a score to a given Board ID with specific criteria.
| **Parameter** | **Description** |
| ------------- | ---------------------------------------------- |
| `Board ID` | Board ID (numeric). |
| `Value` | Value to post to the given scoreboard. |
| `Tag` | **Optional** tag to identify the value posted. |
### `Queue Save Data`
Queues data to be saved later in the **Show Saved Slots** built-in dialog. If the user presses save, the queued data will be saved to the slot selected by the user.
| **Parameter** | **Description** |
| ------------- | --------------------------------------------------- |
| `Data` | String containing the data to be saved in the slot. |
### `Save Slot Data`
Saves the data to the given slot, and triggers **On Saved.**
| **Parameter** | **Description** |
| ------------- | --------------------------------------------------- |
| `Slot ID` | Slot ID (numeric). |
| `Data` | String containing the data to be saved in the slot. |
### `Show Medals`
Display a default modal dialog with all the game medals. If the user is logged in, only the medals awarded are displayed.
### `Show Saved Slots`
Displays a dialog containing the list of saved slots.
### `Show Scoreboard`
Display a default modal dialog with the scores for the given scoreboard.
| **Parameter** | **Description** |
| ------------- | ----------------------------------------------------------------------------------- |
| `Board ID` | Board ID (numeric). |
| `Period` | Period of time to retrieve the data from. |
| `Tag` | Filter by tag (For scores posted with a specific tag). |
| `Social` | Check to retrieve scores from friends only. |
| `Skip` | Number of entries to skip. Use it for pagination (e.g., skip the first 20 entries). |
| `Limit` | Max number of score entries to retrieve. |
### `Unlock Medal`
Unlocks a medal by its Id.
| **Parameter** | **Description** |
| ------------- | ------------------- |
| `Medal ID` | Medal ID (numeric). |
## Conditions
***
### `For Each Medal`
Iterates over the list of medals available.
### `For Each Saved Slot`
Iterates over all the available saved-slot metadata, not the data itself.
### `For Each Score`
Iterates over the last list of scores retrieved.
### `For Each Scoreboard`
Iterates over all the available scoreboards.
### `Is Logged In`
Indicates if the user is already logged in the NGIO session.
### `Is Ready`
Returns true if the NGIO API is ready. **Do not call any ACE before the API is ready.**
### `Is Secret Medal`
Indicates if the given medal is a secret medal (hidden).
| **Parameter** | **Description** |
| ------------- | ------------------- |
| `Medal ID` | Medal ID (numeric). |
### `Is Supporter`
Indicates if the user is a Newgrounds supporter.
### `Is Medal Unlocked`
Indicates if the given medal is unlocked.
| **Parameter** | **Description** |
| ------------- | ------------------- |
| `Medal ID` | Medal ID (numeric). |
### `Is Waiting`
Returns true if the API is waiting for an event response of any kind.
### `On Any Medal Unlocked`
Triggered when any medal is unlocked
### `On Error`
Triggered whenever the API fails after a call.
### `On Login Cancelled`
Triggered after the user cancels logging into Newgrounds.
### `On Login`
Triggered after the user successfully logs into Newgrounds.
### `On Logout`
Triggered after the user logs out of Newgrounds.
### `On Medal Unlocked`
Triggered when the indicated medal is unlocked
| **Parameter** | **Description** |
| ------------- | ------------------- |
| `Medal ID` | Medal ID (numeric). |
### `On Ready`
Triggered when NGIO API is initialized and ready to operate. **Do not call any ACE before the API is ready.**
### `On Loaded`
Triggered when the data is successfully retrieved after a **Get Saved Slot Data** call.
### `On Scores Posted`
Triggered when the score is posted after a **Post Scores** call.
### `On Scores Ready`
Triggered when the scores are ready after a **Get Scores** action call.
### `On Saved`
Triggered when the data is successfully saved after a **Save Slot Data** call.
### `On Version Mismatch`
Triggered when NGIO API finds a newer version of the game.
### `On Waiting Finished`
Triggered after the API is done waiting and changes its status.
### `On Waiting Start`
Triggered when the API is waiting for a response of any kind. Use this event to show a spinner or a 'please wait' message when needed.
## Expressions
***
### `SlotID`
Returns the current Slot ID.
### `SlotData`
Returns the last slot-data retrieved by Get Saved-Slot Data in a string in JSON format.
### `SlotSize`
Returns the current slot size in bytes.
### `SlotTimestamp`
Returns the current slot timestamp in milliseconds of the last save.
### `SlotURL`
Returns the URL containing the actual save data for this slot, or blank if this slot has no data.
### `IconLarge`
User icon (large).
### `IconMedium`
User icon (medium).
### `IconSmall`
User icon (small).
### `LastError`
Returns the last error message received by NGIO. This field populates for these triggers: On Scores Post Error, On Login Cancelled.
### `MedalDescription`
Medal Description.
### `MedalDifficulty`
Medal Difficulty.
### `MedalIcon`
Medal Icon.
### `MedalID`
Medal Id.
### `MedalName`
Medal Name.
### `MedalValue`
Medal Value.
### `MedalsAsJSON`
Returns the array of medals to a string in JSON format.
### `NewestVersion`
Returns the newest version number reported by NewgroundsIO API.
### `ScoreFormattedValue`
Scoreboard formatted value entry for the current user. Call first Get Scores.
### `ScoreTag`
Scoreboard entry tag. Call first Get Scores.
### `ScoreUserIconLarge`
Scoreboard User icon (large). Call first Get Scores.
### `ScoreUserIconMedium`
Scoreboard User icon (medium). Call first Get Scores.
### `ScoreUserIconSmall`
Scoreboard User icon (small). Call first Get Scores.
### `ScoreUserID`
Scoreboard entry user ID.
### `ScoreUserName`
Scoreboard entry user name. Call first Get Scores.
### `ScoreValue`
Scoreboard value entry for the current user. Call first Get Scores.
### `ScoreboardAsJSON`
Returns the array of scoreboards available to a string in JSON format.
### `ScoreboardID`
Returns the numeric Scoreboard ID. Call first Get Scores.
### `ScoreboardName`
Returns the Scoreboard Name. Call first Get Scores.
### `LastScoresAsJSON`
Returns the array of the last retrieved scores as a string in JSON format. This expression is valid only after a Get Scores action call.
### `UserID`
Returns the numeric user ID.
### `UserName`
Returns the user name.
**(c) Pixel Perfect Studio 2025**