Implement achievements in your game in a simple way and with minimal security practices.
- Requirements
- ✨Installation
- Getting started
- Ready
- Achievement structure
- Accessible variables
- Functions
- Signals
- ✌️You are welcome to
- 🤝Contribution guidelines
- 📇Contact us
📢 We don't currently give support to Godot 3+ as we focus on future stable versions from version 4 onwards
- Godot 4+
You can download this plugin from the official Godot asset library using the AssetLib tab in your godot editor. Once installed, you're ready to get started
To manually install the plugin, create an "addons" folder at the root of your Godot project and then download the contents from the "addons" folder of this repository
This plugin has also been written in CSHarp, you can find it on Achievements-CSharp
You can access this functionality using the class GodotParadiseAchievements where you can interact with your source file.
Before start you need to set few project settings that will be available after load the plugin:
Local source refers to the path of the local file that contains the achievements template. This file is read-only and is used solely to define the structure of the achievements in your game. For example: res://settings/achievements.json
Remote source on the other hand, refers to the path of the remote JSON file that also holds the achievements template. The same rules apply as for the local source, but this information is obtained from a remote URL. For example: https://myserver/achievements.json
Save directory is the location where the encrypted saved file, used to track achievement progress, will be created on the player's machine. By default, it utilizes OS.get_user_data_dir()/[project_name]
Save file name is the name of the encrypted file that tracks achievement progress. By default, it is named achievements.json
Password is the character set used for encrypting and decrypting the saved achievements file. By default, it generates a random string with a length of 25 characters. This length should be sufficient for most use cases, ensuring that players cannot alter their achievement progress accessing the file.
When this node becomes ready, it performs several actions:
- It connects itself to the
achievement_updatedsignal, which updates the encrypted file and checks if all achievements have been unlocked. If all achievements are unlocked, it emits theall_achievements_unlockedsignal. - It creates the save directory using the path defined in ProjectSettings.
- It prepares the achievements within the class by reading from the sources defined in ProjectSettings
- Sync the latest achievements update from the encrypted saved file if it exists
The JSON file must adhere to a specific structure in order to function correctly. While you can include additional custom properties tailored to your game, there are mandatory ones that must be present:
{
"achievement-name": {
"name": "MY achievement",
"description": "Kill 25 enemies",
"is_secret": false,
"count_goal": 25,
"current_progress": 0.0,
"icon_path": "res://assets/icon/my-achievement.png",
"unlocked": false,
"active": true
}
}It's important to note that not all achievements will have a count_goal requirement for unlocking progress. In cases where this requirement is not applicable, you should leave the count_goal value as zero. The logic and conditions for unlocking achievements are entirely determined by your game project.
This class serves as a helper for updating and unlocking achievements while emitting the appropriate signals for interaction.
- current_achievements: Dictionary = {}
- unlocked_achievements: Dictionary = {}
- achievements_keys: PackedStringArray = []
Retrieve the information from the desired achievement, if the name does not exist as key it will return an empty dictionary.
GodotEssentialsAchievements.get_achievement("orcs_party")
This function updates the properties of the selected achievement, with values from the data dictionary overriding the existing ones. This action also emits the achievement_updated signal.
GodotEssentialsAchievements.update_achievement("orcs_party", {"current_progress": 0.55})
If the achievement was not previously unlocked, this function changes the unlocked variable to true and emits the achievement_unlocked signal. This action directly unlocks the achievement without further checks.
GodotEssentialsAchievements.unlock_achievement("orcs_party")
Reset the achievement to a previous state. The current_progress and unlocked will be set to 0 and false respectively. You can pass as second parameter the data you want to update in this process.
This action also emits the achievement_reset and achievement_updated signals.
GodotEssentialsAchievements.reset_achievement("orcs_party", {"description": "An orc party was discovered"})
- achievement_unlocked(name: String, achievement: Dictionary)
- achievement_updated(name: String, achievement: Dictionary)
- achievement_reset(name: String, achievement: Dictionary)
- all_achievements_unlocked
GodotParadise is available for free.
If you're grateful for what we're doing, please consider a donation. Developing GodotParadise requires massive amount of time and knowledge, especially when it comes to Godot. Even $1 is highly appreciated and shows that you care. Thank you!
Thank you for your interest in Godot Paradise!
To ensure a smooth and collaborative contribution process, please review our contribution guidelines before getting started. These guidelines outline the standards and expectations we uphold in this project.
📓Code of Conduct: We strictly adhere to the Godot code of conduct in this project. As a contributor, it is important to respect and follow this code to maintain a positive and inclusive community.
If you have built a project, demo, script or example with this plugin let us know and we can publish it here in the repository to help us to improve and to know that what we do is useful.