Difference between revisions of "LuaAPI/wesnoth/achievements"

From The Battle for Wesnoth Wiki
 
(8 intermediate revisions by 2 users not shown)
Line 9: Line 9:
 
* {{LuaGameOnly}} '''wesnoth.achievements.set'''(''content_for'',''id'')
 
* {{LuaGameOnly}} '''wesnoth.achievements.set'''(''content_for'',''id'')
  
−
* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
+
Sets the specified achievement as completed.
−
* '''id''': The id of the achievement.
 
  
−
Sets the specified achievement as completed. Unlike the [set_achievement] tag, this does not display a popup.
+
* ''content_for'': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
 +
* ''id'': The id of the achievement.
 +
 
 +
=== wesnoth.achievements.set_sub_achievement ===
 +
 
 +
{{DevFeature1.17|17}}
 +
 
 +
* {{LuaGameOnly}} '''wesnoth.achievements.set_sub_achievement'''(''content_for'',''id'',''sub_id'')
 +
 
 +
Sets the specified sub-achievement as completed.
 +
 
 +
* ''content_for'': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
 +
* ''id'': The id of the achievement.
 +
* ''sub_id'': The id of the sub-achievement.
  
 
=== wesnoth.achievements.has ===
 
=== wesnoth.achievements.has ===
Line 18: Line 30:
 
* {{LuaGameOnly}} '''wesnoth.achievements.has'''(''content_for'',''id'') → ''achieved?''
 
* {{LuaGameOnly}} '''wesnoth.achievements.has'''(''content_for'',''id'') → ''achieved?''
  
−
* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
+
Returns whether the specified achievement has been completed.
−
* '''id''': The id of the achievement.
 
  
−
Returns whether the specified achievement has been completed.
+
* ''content_for'': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
 +
* ''id'': The id of the achievement.
  
 
'''NOTE:''' This is not safe to use in online multiplayer since different players can have different achievements completed. As such it will always be treated as if the achievement is not completed.
 
'''NOTE:''' This is not safe to use in online multiplayer since different players can have different achievements completed. As such it will always be treated as if the achievement is not completed.
 +
 +
=== wesnoth.achievements.has_sub_achievement ===
 +
 +
{{DevFeature1.17|17}}
 +
 +
* {{LuaGameOnly}} '''wesnoth.achievements.has_sub_achievement'''(''content_for'',''id'',''sub_id'') → ''achieved?''
 +
 +
Returns whether the specified sub-achievement has been completed.
 +
 +
* ''content_for'': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
 +
* ''id'': The id of the achievement.
 +
* ''sub_id'': The id of the achievement.
 +
 +
'''NOTE:''' This is not safe to use in online multiplayer since different players can have different sub-achievements completed. As such it will always be treated as if the sub-achievement is not completed.
  
 
=== wesnoth.achievements.get ===
 
=== wesnoth.achievements.get ===
Line 29: Line 55:
 
* {{LuaGameOnly}} '''wesnoth.achievements.get'''(''content_for'',''id'') → ''cfg''
 
* {{LuaGameOnly}} '''wesnoth.achievements.get'''(''content_for'',''id'') → ''cfg''
  
−
Returns the contents of the [[AchievementsWML|[achievement]]] tag.
+
Returns the contents as described for the [[AchievementsWML|[achievement]]] tag including any sub-achievements, as well as the additional '''current_progress''' attribute. If a progressable achievement is completed, '''current_progress''' will be -1. If this is not a progressable achievement, then '''current_progress''' and '''max_progress''' will both be 0.
  
−
* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
+
* ''content_for'': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.
−
* '''id''': The id of the achievement.
+
* ''id'': The id of the achievement.
  
 
'''NOTE:''' While this can be used to retrieve the achievement's actual achievement status for a client in online multiplayer, this is also not safe to use in that situation for the same reason.
 
'''NOTE:''' While this can be used to retrieve the achievement's actual achievement status for a client in online multiplayer, this is also not safe to use in that situation for the same reason.
 +
 +
=== wesnoth.achievements.progress ===
 +
 +
* {{LuaGameOnly}} '''wesnoth.achievements.progress'''(''content_for'',''id'',[''amount'',[''limit'']]) → ''number''
 +
 +
Progresses an achievement by ''amount'' up to either the achievement's completion or ''limit'', whichever is smaller, and returns the new current progress of the achievement. If the achievement's current progress is already above ''limit'', then it remains unchanged.
 +
 +
Both ''limit'' and ''amount'' are optional. If a ''limit'' is not provided, then the achievement is allowed to progress until it is completed. If both are omitted, then the achievement is not progressed and it simply returns the current progress of the achievement. The return value can have the following values:
 +
 +
* '''0 or higher''': this is the achievement's current progress.
 +
* '''-1''': this achievement is already completed.
 +
 +
'''NOTE''': The achievement's current progress returned by this function is not safe to use in online multiplayer for the same reason that '''wesnoth.achievements.has''' and '''wesnoth.achievements.get''' are unsafe.

Latest revision as of 05:12, 18 May 2023

(Version 1.17.13 and later only)

Achievements

wesnoth.achievements.set

  • ♟ wesnoth.achievements.set(content_for,id)

Sets the specified achievement as completed.

  • content_for: The [achievements_group] that this achievement is part of.
  • id: The id of the achievement.

wesnoth.achievements.set_sub_achievement

(Version 1.17.17 and later only)

  • ♟ wesnoth.achievements.set_sub_achievement(content_for,id,sub_id)

Sets the specified sub-achievement as completed.

  • content_for: The [achievements_group] that this achievement is part of.
  • id: The id of the achievement.
  • sub_id: The id of the sub-achievement.

wesnoth.achievements.has

  • ♟ wesnoth.achievements.has(content_for,id) → achieved?

Returns whether the specified achievement has been completed.

  • content_for: The [achievements_group] that this achievement is part of.
  • id: The id of the achievement.

NOTE: This is not safe to use in online multiplayer since different players can have different achievements completed. As such it will always be treated as if the achievement is not completed.

wesnoth.achievements.has_sub_achievement

(Version 1.17.17 and later only)

  • ♟ wesnoth.achievements.has_sub_achievement(content_for,id,sub_id) → achieved?

Returns whether the specified sub-achievement has been completed.

  • content_for: The [achievements_group] that this achievement is part of.
  • id: The id of the achievement.
  • sub_id: The id of the achievement.

NOTE: This is not safe to use in online multiplayer since different players can have different sub-achievements completed. As such it will always be treated as if the sub-achievement is not completed.

wesnoth.achievements.get

  • ♟ wesnoth.achievements.get(content_for,id) → cfg

Returns the contents as described for the [achievement] tag including any sub-achievements, as well as the additional current_progress attribute. If a progressable achievement is completed, current_progress will be -1. If this is not a progressable achievement, then current_progress and max_progress will both be 0.

  • content_for: The [achievements_group] that this achievement is part of.
  • id: The id of the achievement.

NOTE: While this can be used to retrieve the achievement's actual achievement status for a client in online multiplayer, this is also not safe to use in that situation for the same reason.

wesnoth.achievements.progress

  • ♟ wesnoth.achievements.progress(content_for,id,[amount,[limit]]) → number

Progresses an achievement by amount up to either the achievement's completion or limit, whichever is smaller, and returns the new current progress of the achievement. If the achievement's current progress is already above limit, then it remains unchanged.

Both limit and amount are optional. If a limit is not provided, then the achievement is allowed to progress until it is completed. If both are omitted, then the achievement is not progressed and it simply returns the current progress of the achievement. The return value can have the following values:

  • 0 or higher: this is the achievement's current progress.
  • -1: this achievement is already completed.

NOTE: The achievement's current progress returned by this function is not safe to use in online multiplayer for the same reason that wesnoth.achievements.has and wesnoth.achievements.get are unsafe.

Retrieved from "https://wiki.wesnoth.org/index.php?title=LuaAPI/wesnoth/achievements&oldid=71229"
This page was last edited on 18 May 2023, at 05:12.