Achievements

The Achievement module allows the developer to grant achievements to the player, to clear achievements, and to determine if an achievement has been granted. It also allows the recording of progress towards an achievement.

By default, the achievement stores information in the persistent file. If Steam support is available and enabled, achievement information is automatically synchronized with Steam.

Steam support must be added to Ren'Py, to ensure that it is only distributed by creators that have been accepted to the Steam partner program. To install it, choose "preferences", "Install libraries", "Install Steam Support".

achievement.Sync(): An action that calls achievement.sync(). This is only sensitive if achievements are out of sync.

achievement.clear(name): Clears the achievement with name.

achievement.clear_all(): Clears all achievements.

achievement.get_progress(name): Returns the current progress towards the achievement identified with name, or 0 if no progress has been registered for it or if the achievement is not known.

achievement.grant(name): Grants the achievement with name, if it has not already been granted.

achievement.has(name): Returns true if the player has been granted the achievement with name.

achievement.progress(name, complete)

Reports progress towards the achievement with name, if that achievement has not been granted. The achievement must be defined with a completion amount.

name: The name of the achievement. This should be the name of the achievement, and not the stat.
complete: An integer giving the number of units completed towards the achievement.

achievement.register(name, **kwargs)

Registers an achievement. Achievements are not required to be registered, but doing so allows one to pass information to the backends.

name: The name of the achievement to register.

The following keyword parameters are optional.

steam: The name to use on steam. If not given, defaults to name.
stat_max: The integer value of the stat at which the achievement unlocks.
stat_modulo: If the progress modulo stat_max is 0, progress is displayed to the user. For example, if stat_modulo is 10, progress will be displayed to the user when it reaches 10, 20, 30, etc. If not given, this defaults to 0.

achievement.sync(): Synchronizes registered achievements between local storage and other backends. (For example, Steam.)

Variables that control achievements are:

achievement.steam_position = None: If not None, this sets the position of the steam notification popup. This must be a string, one of "top left", "top right", "bottom left", or "bottom right".

define config.steam_appid = None

If not None, this should be the Steam appid. Ren'Py will automatically set this appid when it starts. This needs to be set using the define statement:

define config.steam_appid = 12345

define config.automatic_steam_timeline = True

If true, when run under Steam, the game will automatically update the Steam Timeline.

This currently consists of:

Updating the state description to match save_name, if the variables is set.
Updating the game mode to reflect when the player is inside a menu.

Steamworks API

When Steam is available, a ctypes-based binding to the Steamworks API is available as achievement.steamapi. The binding is an instance of the steamapi module, as found here, and represents a machine translation of the C++ Steamworks API to Python.

In addition, a large number of functions are available in the achievement.steam object, if and only if the Steamworks API is available.

achievement.steam: If Steam initialized successfully, this is a namespace with high-level Steam methods. If Steam did not initialize, this is None. Always check that this is not None before calling a method.

Steam Apps

achievement.steam.dlc_installed(appid): Returns True if dlc is installed, or False otherwise.

achievement.steam.dlc_progress(appid): Reports the progress towards DLC download completion.

achievement.steam.get_app_build_id(): Returns the build ID of the installed game.

achievement.steam.get_current_beta_name(): Returns the name of the current beta, or None if it can't.

achievement.steam.get_current_game_language(): Return the name of the language the user has selected.

achievement.steam.get_steam_ui_language(): Return the name of the language the steam UI is using.

achievement.steam.install_dlc(appid): Requests the DLC with appid be installed.

achievement.steam.is_subscribed_app(appid): Returns true if the user owns the app with appid, and false otherwise.

achievement.steam.uninstall_dlc(appid): Requests that the DLC with appid be uninstalled.

Steam Overlay

achievement.steam.activate_overlay(dialog)

Activates the Steam overlay.

dialog: The dialog to open the overlay to. One of "Friends", "Community", "Players", "Settings", "OfficialGameGroup", "Stats", "Achievements"

achievement.steam.activate_overlay_to_store(appid, flag=None)

Opens the steam overlay to the store.

appid: The appid to open.
flag: One of achievement.steam.STORE_NONE, .STORE_ADD_TO_CART, or .STORE_ADD_TO_CART_AND_SHOW.

achievement.steam.activate_overlay_to_web_page(url): Activates the Steam overlay, and opens the web page at url.

achievement.steam.is_overlay_enabled(): Returns true if the steam overlay is enabled. (This might take a while to return true once the game starts.)

achievement.steam.overlay_needs_present(): Returns true if the steam overlay is enabled. (This might take a while to return true once the game starts.)

achievement.steam.set_overlay_notification_position(position): Sets the position of the steam overlay. Position should be one of achievement.steam.POSITION_TOP_LEFT, .POSITION_TOP_RIGHT, .POSITION_BOTTOM_LEFT, or .POSITION_BOTTOM_RIGHT.

Steam Stats

achievement.steam.clear_achievement(name): Clears the achievement with name. Call _renpysteam.store_stats() to push this change to the server.

achievement.steam.get_achievement(name): Gets the state of the achievements with name. This returns True if the achievement has been granted, False if it hasn't, and None if the achievement is unknown or an error occurs.

achievement.steam.get_float_stat(name): Returns the value of the stat with name, or None if no such stat exits.

achievement.steam.get_int_stat(name): Returns the value of the stat with name, or None if no such stat exits.

achievement.steam.grant_achievement(name): Grants the achievement with name. Call _renpysteam.store_stats() to push this change to the server.

achievement.steam.indicate_achievement_progress(name, cur_progress, max_progress): Indicates achievement progress to the user. This does not unlock the achievement.

achievement.steam.list_achievements(): Returns a list of achievement names.

achievement.steam.retrieve_stats(): Retrieves achievements and statistics from Steam.

achievement.steam.set_float_stat(name, value): Sets the value of the stat with name, which must have the type of FLOAT. Call _renpysteam.store_stats() to push this change to the server.

achievement.steam.set_int_stat(name, value): Sets the value of the stat with name, which must have the type of INT. Call _renpysteam.store_stats() to push this change to the server.

achievement.steam.store_stats(): Stores statistics and achievements on the Steam server.

Steam Timeline

achievement.steam.add_timeline_event(icon, title, description, priority=0, start_offset=0.0, duration=0.0, possible_clip=None)

Adds an event to the timeline.

icon: The icon to display for the event. This should be a string giving one of the standard steam icons, or one you uploaded to Steam.
title: The title of the event.
description: The description of the event.
priority: The priority of the event, used to resolve conflicts. This should be an interger between 0 and 1000.
start_offset: The offset of the start of the event from the current time, in seconds.
duration: The duration of the event, in seconds.
possible_clip: This determines if the event can be clipped. This should be one of the achievement.steam.CLIP_PRIORITY... constants: CLIP_PRIORITY_NONE, CLIP_PRIORITY_STANDARD, or CLIP_PRIORITY_FEATURED.

achievement.steam.clear_timeline_state_description(time_delta): Clears the description of the current state in the timeline.

achievement.steam.set_timeline_state_description(description, time_delta=0.0)

Sets the description of the current state in the timeline.

description: A string giving the description of the current state.
time_delta: The time since the last state change.

Steam User

achievement.steam.cancel_ticket(): Cancels the ticket returned by achievement.steam.get_session_ticket().

achievement.steam.get_account_id(): Returns the user's account ID.

achievement.steam.get_csteam_id(): Returns the user's full CSteamID as a 64-bit number.

achievement.steam.get_game_badge_level(series, foil): Gets the level of the users Steam badge for your game.

achievement.steam.get_persona_name(): Returns the user's publicly-visible name.

achievement.steam.get_session_ticket(): Gets a ticket that can be sent to the server to authenticate this user.

Steam Workshop

achievement.steam.get_subscribed_item_path(item_id)

Returns the path where an item of user-generated content was installed. Returns None if the item was not installed.

item_id: The item id.

achievement.steam.get_subscribed_items(): Returns a list of the item ids the user has subscribed to in the steam workshop.