gd-achievements
Achievement System Plugin for Godot Engine ver. 3
How to install in your project?
Copy from GitHub repository
The main part of the plugin is located in addons/gd-achievements
. Copy this folder to your addons
folder within your project (or, if you don’t have an addons
folder, copy it from here). You will also want to include the gd-achievements
folder on the root of the project. It includes the notification
scene and sample achievements.json
which you may want to edit yourself.
After that don’t forget to enable it in “Project Settings -> Plugins”
It should be done automatically, but ensure that “addons\gd-achievements\scripts\achievements_manager.gd” is added as a singleton/autoload
(Project -> Project Settings -> AutoLoad -> <path_to_achievements_manager.gd> -> Add)
Download from Godot Asset Library
Find this plugin and install it like you want (from editor directly or from website). Remember to install BOTH the addons/gd-achievements
and the gd-achievements
folders.
https://godotengine.org/asset-library/asset/1004
How to add custom achievements?
1. Generate JSON via Python script;
Open “achievements_generator.py”. To make file, generator require to write main name of your achievement, short description and Godot’s path to icon.
Easiest way to get path is pressing right mouse button to you icon and press “copy path”.
Icon size must be: 150x150px
2. Place your new “achievements.json” in the “res://gd_achievements” folder
As you can see, the structure of JSON file is simple and you can use fields like you want.
The mandatory default fields are:
name: String
- The name of your achievementgoal: int
- The maximum progress of your achievement, at which point it’ll be marked as achieved (only for progress achievements)current_progress: int
- The current progress of your achievement. (only for progress achievements. in your file, it should always be set to 0)icon_path: String
- The path of the icon that shows up in the achievement notificationachieved: bool
- Wether or not the achievement is complete
You can add or remove the others to your liking.
3. Open your Godot project, place “AchievementNotifications” node to scene you want
Also, you can change additional node’s options from Inspector:
Show Time
- How much time achievement’s notficaton will shown in seconds;Show End Time
- Time between when the end animation starts playing and when the AchievementSystem will delete the notification node;Global Sound
- What sound will play for all achievements;Global Sound Volume
.Grow direction
(Up, Down, Left, Right) - The relative position where other achievements will show up if more than one would appear at the same timePosition
(Top Left, Bottom Left, Top Right, Bottom Right) - The position on the screen where your achievements will start appearing
To get the achievements, you will need to call the singleton AchievementManager
. There are two functions you can use, depending on the type of achievement you’re handling.
progress_achievement(key, progress)
- If your achievement has a progression number (i.e., die 100 times), you can call this function with the amount you want to add to the progress. It checks thecurrent_progress
of an achievement against it’sgoal
, if it’s higher, it will trigger the notification and mark your achievement asachieved: true
unlock_achievement(key)
- Instantly unlocks an achievement (if it’s not already unlocked) and triggers the notification
As a result you’ll see something like this
AchievementManager API
All methods can be called from the AchievementManager
singleton:
progress_achievement(key, progress)
- see above-
unlock_achievement(key)
- see above -
get_all_achievements()
- returns a dictionary (indexed by key) of all the achievements you have in the game -
get_achievement(key)
- returns the full dictionary of your achievement. the mandatory data an achievement has is:key: String
- The key of your achievement (same as the one you used to get the achievement)name: String
- The name of your achievementgoal: int
- The maximum progress of your achievement, at which point it’ll be marked as achieved (only for progress achievements)current_progress: int
- The current progress of your achievement (only for progress achievements)icon_path: String
- The path of the icon that shows up in the achievement notificationachieved: bool
- Wether or not the achievement is complete
-
reset_achievements()
- debug function, resets all received achievements by setting “achieved” field to 0 for all achievements.
Customize Notifications
If you want to customize your notifications, you can create your own to replace the default one. You can modify the one in gd-achievements/achievements_notification.tscn
or create a new one with the same name. The AchievementSystem will automatically call the following methods on your custom notification, so it must include them in a script on the root node:
set_achievement(achievement)
- This function will pass the achievement data when the notification is triggered. This way you can programatically set the name, icon, or whatever custom property you have added to the notification.on_show()
- This function will be called when the notification appears on screen, in case you want to trigger an animationon_hide()
- This function will be called before the notification leaves the screen, in case you want to trigger an animation
Upgrade from v1.0.x
In order to upgrade, please do the following:
-
Copy your personal files from addons/gd-achievements (If you added new sounds or icons to this folder, move them somewhere else if you want to keep them. Also, move your achievements.json file to the root folder once more)
-
Remove the old gd-achievements version (Simply remove
addons/gd-achievements
andachievements_generator.py
if you still have them) -
Install new version (see “How to install in your project?”)
-
Run achievements_generator.py in the same folder as your achievements.json
If you followed these steps correctly, both these files should be in the root folder of your project. If they aren’t, make sure to move them accordingly. When you run achievements_generator.py with an old achievements.json file, you will get a prompt asking you if you’d like to update it. You will be asked to provide a new key
for each achievement. You may also update the icon_path
here, if you wish.
- Move your achievements.json file to the
gd-achievements
folder (NOT theaddons/gd-achievements
folder, the new one created in the root)
Q/A
I have an error “The Identifier “AchievementsManager” is not declared in the current scope”!
Check that “addons/gd-achievements/scripts/achievements_manager.gd” file activated as singleton (check How to install in your project?)
Plugin doesn’t work on Android devices
You must add to your exporter .json
format for non-resources export:
Export => Click on Android Presets => Go to Resources tab
and set .json
as filter for resources to export.
Thanks to Dark8Ghost for the found fix
I’ll accept all problems and suggestions that you write in the repository on GitHub on “Issues” section
Описание
Плагин для поддержки системы достижений в Godot Engine 3