Newgrounds.IO Plugin

NewgroundsIO API integration for Construct 3.

Introduction

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, available in the System plugin.

• Built-In Dialogs. Speed up your development by calling the builtin #Show Medals, #Show Scoreboard, and #Show Saved Slots to interact immedatelly with your players.

The plugin is available under an MIT License. Feel free to use it for any kind of project, including commercial use

NewgroundsIO plugin overlays

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.

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 for more details.

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.

Before calling this dialog, always use the action #Queue Save Data 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.

Saved Slots dialog requires the player to login.

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

https://store.pixelperfectstudio.mx/product/newgrounds-io/

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