Free Packages Plugin for ArchiSteamFarm

Introduction

This plugin finds free packages on Steam and adds them to your account.

This plugin works by listening for changes to Steam's PICS. The plugin can discover new packages as they're released, but is limited due to PICS not showing all old changes. As a result, the plugin can only discover packages that have changed recently, usually in the last ~12 hours.

Installation

• Download the .zip file from the latest release
• Unpack the downloaded .zip file to the plugins folder inside your ASF folder.
• (Re)start ASF, you should get a message indicating that the plugin loaded successfully.

[!NOTE] This plugin is only tested to work with ASF-generic. It may or may not work with other ASF variants, but feel free to report any issues you may encounter.

Usage

Enabling the plugin

You can enable the plugin per individual bot by adding EnableFreePackages to that bot's config file:

"EnableFreePackages": true,

Pausing package activations while playing a game

Under certain conditions, activating a free package while playing a game on Steam can cause the game to temporarily freeze. You can prevent the plugin from activating packages while you're in-game by adding PauseFreePackagesWhilePlaying to your individual bot's config file. It's recommended you use this for any account you play games on:

"PauseFreePackagesWhilePlaying": true,

[!NOTE] This applies when your account is playing a game outside of ASF, and does not apply when ASF is idling a game. Your library being locked through Family Sharing will also prevent package activation. You likely don't want to enable this if you run idle games 24/7, or your library is otherwise almost always in use, or you only run ASF rarely.

Changing the hourly package limit

A maximum of 50 packages can be activated per hour. By default, this plugin will use at most 40 of those hourly activations and will resume where it left off if it's ever interrupted. You can control this limit by adding FreePackagesPerHour to your individual bot's config files of uint type.

[!NOTE] I don't recommend raising this value. The default is 40 to let you manually redeem packages without having to fight with the plugin. It's also not always possible for the plugin to tell when it's being rate-limited, and so it's best to avoid ever getting rate-limited.

Enabling package filters

By default, the plugin will attempt to activate all free non-playtest packages. You can control what kinds of packages are activated by adding FreePackagesFilters to your individual bot's config files with the following structure:

"FreePackagesFilters": [{
  "Types": [],
  "Tags": [],
  "Categories": [],
  "Languages": [],
  "Systems": [],
  "MinReviewScore": 0,
  "IgnoredContentDescriptors": [],
  "IgnoredTypes": [],
  "IgnoredTags": [],
  "IgnoredCategories": [],
  "IgnoredAppIDs": [],
  "RequireAllTags": false,
  "RequireAllCategories": false,
  "ImportStoreFilters": false,
  "WishlistOnly": false,
  "IgnoreFreeWeekends": false,
  "NoCostOnly": false,
  "PlaytestMode": 0,
}],

All filter options are explained below:

Types

HashSet<string> type with default value of []. Packages must contain an app with one of the TypeNames specified here or they will not be added to your account. You can leave this empty to allow for all types. The available TypeNames for filtering are: "Game", "Application", "Tool", "Demo", "DLC", "Music", "Video"

Tags

HashSet<uint> type with default value of []. Packages must contain an app with at least one of these TagIDs or they will not be added to your account. You can leave this empty to allow for all tags. A list of tags can be found here. The TagID will be at the end of the URL. For example, the TagID for the Indie tag is 492.

[!NOTE] The "Profile Features Limited" tag presented by SteamDB is not a real tag that Steam uses. This plugin does not detect whether or not an app has limited profile features.

Categories

HashSet<uint> type with default value of []. Packages must contain an app with at least one of these CategoryIDs or they will not be added to your account. You can leave this empty to allow for all categories.

Languages

HashSet<string> type with default value of []. Packages must contain an app with support for at least one of these LanguageIDs or they will not be added to your account. You can leave this empty to allow for all languages.

Systems

HashSet<string> type with default value of []. Packages must contain an app with support for one of the SystemNames specified here or they will not be added to your account. You can leave this empty to allow for all systems. The available SystemNames for filtering are: "Windows", "MacOS", "Linux", "DeckVerified", "DeckPlayable", "DeckUnsupported", "DeckUnknown"

MinReviewScore

uint type with default value of 0. Packages must contain an app with a ReviewScore greater than or equal to this or they will not be added to your account. You can leave this at 0 to allow for all values. A ReviewScore may range from 1 to 9 and is not the same as the percentage of positive reviews. Refer to the list below for more information. This filter is not applied to demos or playtests as they can't normally be reviewed.

IgnoredContentDescriptors

HashSet<uint> type with default value of []. Packages containing apps with any of the ContentDescriptorIDs specified here will not be added to your account. Detailed information about content descriptors can be found here under "Mature Content Filtering".

IgnoredTypes

HashSet<string> type with default value of []. Packages containing apps with any of the TypeNames specified here will not be added to your account. Refer to Types for more information about TypeNames.

IgnoredTags

HashSet<uint> type with default value of []. Packages containing apps with any of these TagIDs will not be added to your account. Refer to Tags for more information about TagIDs.

IgnoredCategories

HashSet<uint> type with default value of []. Packages containing apps with any of these CategoryIDs will not be added to your account. Refer to Categories for more information about CategoryIDs.

IgnoredAppIDs

HashSet<uint> type with default value of []. Packages containing apps with any of these AppIDs will not be added to your account.

RequireAllTags

bool type with default value of false. If set to true, packages must contain an app with all of the TagIDs specified in the Tags filter or they will not be added to your account.

RequireAllCategories

bool type with default value of false. If set to true, packages must contain an app with all of the CategoryIDs specified in the Categories filter or they will not be added to your account.

ImportStoreFilters

bool type with default value of false. If set to true, the filter will also use the ignored games, ignored tags, and ignored content descriptor settings you use on the Steam storefront.

WishlistOnly

bool type with default value of false. If set to true, packages must contain an app your account has wishlisted or followed on the Steam storefront or they will not be added to your account.

IgnoreFreeWeekends

bool type with default value of false. Free weekend packages will be ignored if set to true.

NoCostOnly

bool type with default value of false. If set to true, only "No Cost" packages will be added to your account. "No Cost" packages tend to be those which are free for only a limited time, and can also sometimes give a +1 to your owned games count.

PlaytestMode

uint type with default value of 0. Some or all playtests will be ignored based on the provided value.

[!NOTE] Only one of your bots may use the PlaytestMode filter option. As some playtests have a limited number of slots, this is an artificial restriction I've put in place to limit how many slots a single person can occupy.

[!NOTE] If you use PauseFreePackagesWhilePlaying, be aware that when it comes to limited playtests, the plugin cannot control when the playtest package is added to your account. When or if this happens is decided by the game's developer, and so it's possible that a package will be added to your account while you're playing a game.

Using multiple package filters

You can define as many filters as you'd like, and packages that pass any one of your filters will be added to your account. For example, with the three filters below we can allow for any of:

• Free Games with Steam Trading Cards, but without nudity, and ignoring free weekends
• Free Games or Playtests which have English or French language support, and Puzzle or Programming tags
• All Free DLC

"FreePackagesFilters": [{
  "Types": ["Game"],
  "Categories": [29],
  "IgnoredContentDescriptors": [3, 4],
  "IgnoreFreeWeekends": true,
},{
  "Types": ["Game"],
  "Tags": [1664, 5432],
  "Languages": ["english", "french"],
  "PlaytestMode": 3,
},{
  "Types": ["DLC"],
}],

Importing packages

While the plugin is meant to be used passively, you can also import free packages from SteamDB using this userscript.

Commands

Command Aliases

IPC Interface

[^1]: Responses are not dependent on the account used to make these requests. You may provide multiple botNames, and the first available bot will be used to make the request.