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.
- Download the .zip file from the latest release
- Unpack the downloaded .zip file to the
pluginsfolder 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.
You can enable the plugin per individual bot by adding EnableFreePackages to that bot's config file:
"EnableFreePackages": true,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.
A maximum of 30 packages can be activated per 1.5 hours. By default, this plugin will use at most 25 of those activations and will resume where it left off if it's ever interrupted. You can control this limit by adding FreePackagesLimit to your individual bot's config files of uint type:
"FreePackagesLimit": 25,Note
I don't recommend raising this value. The default is intentionally made lower than the actual limit to allow for you the ability to 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.
By default, the plugin will attempt to activate all free non-demo and 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,
"MinDaysOld": 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:
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"
Note
Demos are filtered out by default. This is because Steam will automatically remove all uninstalled demos from your account eventually. However if you specify in your Types that you do want demos, then they will be included for that filter.
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.
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.
List of Category IDs
| Category ID | Description |
|---|---|
| 1 | Multi-player |
| 2 | Single-player |
| 6 | Mods (require HL2) |
| 7 | Mods (require HL1) |
| 8 | Valve Anti-Cheat enabled |
| 9 | Co-op |
| 10 | Game demo |
| 12 | HDR available |
| 13 | Captions available |
| 14 | Commentary available |
| 15 | Stats |
| 16 | Includes Source SDK |
| 17 | Includes level editor |
| 18 | Partial Controller Support |
| 19 | Mods |
| 20 | MMO |
| 21 | Downloadable Content |
| 22 | Steam Achievements |
| 23 | Steam Cloud |
| 24 | Shared/Split Screen |
| 25 | Steam Leaderboards |
| 27 | Cross-Platform Multiplayer |
| 28 | Full controller support |
| 29 | Steam Trading Cards |
| 30 | Steam Workshop |
| 32 | Steam Turn Notifications |
| 33 | Native Steam Controller |
| 35 | In-App Purchases |
| 36 | Online PvP |
| 37 | Shared/Split Screen PvP |
| 38 | Online Co-op |
| 39 | Shared/Split Screen Co-op |
| 40 | SteamVR Collectibles |
| 41 | Remote Play on Phone |
| 42 | Remote Play on Tablet |
| 43 | Remote Play on TV |
| 44 | Remote Play Together |
| 45 | Cloud Gaming |
| 46 | Cloud Gaming (NVIDIA) |
| 47 | LAN PvP |
| 48 | LAN Co-op |
| 49 | PvP |
| 50 | Additional High-Quality Audio |
| 51 | Steam China Workshop |
| 52 | Tracked Controller Support |
| 53 | VR Supported |
| 54 | VR Only |
| 55 | PS4 Controller Support |
| 56 | PS4 Controller BT Support |
| 57 | PS5 Controller BT Support |
| 58 | PS5 Controller BT Support |
| 59 | Steam Input API Supported |
| 60 | Controller Preferred |
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.
List of Language IDs
| Language ID | Language |
|---|---|
"afrikaans" |
Afrikaans |
"albanian" |
Albanian |
"amharic" |
Amharic |
"arabic" |
Arabic |
"armenian" |
Armenian |
"assamese" |
Assamese |
"azerbaijani" |
Azerbaijani |
"bangla" |
Bangla |
"basque" |
Basque |
"belarusian" |
Belarusian |
"bosnian" |
Bosnian |
"bulgarian" |
Bulgarian |
"catalan" |
Catalan |
"cherokee" |
Cherokee |
"croatian" |
Croatian |
"czech" |
Czech |
"danish" |
Danish |
"dari" |
Dari |
"dutch" |
Dutch |
"english" |
English |
"estonian" |
Estonian |
"filipino" |
Filipino |
"finnish" |
Finnish |
"french" |
French |
"galician" |
Galician |
"georgian" |
Georgian |
"german" |
German |
"greek" |
Greek |
"gujarati" |
Gujarati |
"hausa" |
Hausa |
"hebrew" |
Hebrew |
"hindi" |
Hindi |
"hungarian" |
Hungarian |
"icelandic" |
Icelandic |
"igbo" |
Igbo |
"irish" |
Irish |
"italian" |
Italian |
"japanese" |
Japanese |
"kannada" |
Kannada |
"kazakh" |
Kazakh |
"khmer" |
Khmer |
"kinyarwanda" |
Kinyarwanda |
"konkani" |
Konkani |
"koreana" |
Korean |
"kyrgyz" |
Kyrgyz |
"kiche" |
K'iche' |
"latvian" |
Latvian |
"lithuanian" |
Lithuanian |
"luxembourgish" |
Luxembourgish |
"macedonian" |
Macedonian |
"malay" |
Malay |
"malayalam" |
Malayalam |
"maltese" |
Maltese |
"maori" |
Maori |
"marathi" |
Marathi |
"mongolian" |
Mongolian |
"nepali" |
Nepali |
"norwegian" |
Norwegian |
"odia" |
Odia |
"persian" |
Persian |
"polish" |
Polish |
"portuguese" |
Portuguese - Portugal |
"gurmukhi" |
Punjabi (Gurmukhi) |
"shahmukhi" |
Punjabi (Shahmukhi) |
"quechua" |
Quechua |
"romanian" |
Romanian |
"russian" |
Russian |
"scots" |
Scots |
"serbian" |
Serbian |
"schinese" |
Simplified Chinese |
"sindhi" |
Sindhi |
"sinhala" |
Sinhala |
"slovak" |
Slovak |
"slovenian" |
Slovenian |
"sorani" |
Sorani |
"sotho" |
Sotho |
"latam" |
Spanish - Latin America |
"spanish" |
Spanish - Spain |
"swahili" |
Swahili |
"swedish" |
Swedish |
"tajik" |
Tajik |
"tamil" |
Tamil |
"tatar" |
Tatar |
"telugu" |
Telugu |
"thai" |
Thai |
"tigrinya" |
Tigrinya |
"tchinese" |
Traditional Chinese |
"tswana" |
Tswana |
"turkish" |
Turkish |
"turkmen" |
Turkmen |
"ukrainian" |
Ukrainian |
"urdu" |
Urdu |
"uyghur" |
Uyghur |
"uzbek" |
Uzbek |
"valencian" |
Valencian |
"vietnamese" |
Vietnamese |
"welsh" |
Welsh |
"wolof" |
Wolof |
"xhosa" |
Xhosa |
"yoruba" |
Yoruba |
"zulu" |
Zulu |
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"
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.
List of Review Scores
| Review Score | Description | # of Reviews | % of Positive Reviews |
|---|---|---|---|
| 1 | Overwhelmingly Negative | 500+ | 0%-19% |
| 2 | Very Negative | 50-499 | 0%-19% |
| 3 | Negative | 1-49 | 0%-19% |
| 4 | Mostly Negative | - | 20%-39% |
| 5 | Mixed | - | 40%-69% |
| 6 | Mostly Positive | - | 70%-79% |
| 7 | Positive | 1-49 | 80%-100% |
| 8 | Very Positive | 50-499 | 80%-100% |
| 8 | Very Positive | 500+ | 80%-94% |
| 9 | Overwhelmingly Positive | 500+ | 95%-100% |
uint type with default value of 0. Packages must contain an app which was released on Steam within the last MinDaysOld days or they will not be added to your account. You can leave this at 0 to not filter by release date.
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".
List of Content Descriptor IDs
| Descriptor ID | Description |
|---|---|
| 1 | Some Nudity or Sexual Content |
| 2 | Frequent Violence or Gore |
| 3 | Adult Only Sexual Content |
| 4 | Frequent Nudity or Sexual Content |
| 5 | General Mature Content |
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.
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.
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.
HashSet<uint> type with default value of []. Packages containing apps with any of these AppIDs will not be added to your account.
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.
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.
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.
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.
bool type with default value of false. Free weekend packages will be ignored if set to true.
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.
uint type with default value of 0. Some or all playtests will be ignored based on the provided value.
List of Playtest Modes
| Playtest Modes | Description |
|---|---|
| 0 | Ignore all playtests |
| 1 | Include only unlimited playtests |
| 2 | Include only limited playtests |
| 3 | Include all playtests |
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.
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
- Free games or playtests which have English or French language support, and Puzzle or Programming tags
- Free DLC for games you own
"FreePackagesFilters": [{
"Types": ["Game"],
"Categories": [29],
"IgnoredContentDescriptors": [3, 4],
},{
"Types": ["Game"],
"Tags": [1664, 5432],
"Languages": ["english", "french"],
"PlaytestMode": 3,
},{
"Types": ["DLC"],
"IgnoredTypes": ["Game", "Application"],
}],While the plugin can be used passively, you can also manually import free packages from SteamDB using the importer userscript, or through the commands and IPC interface endpoints below.
| Command | Access | Description |
|---|---|---|
freepackages |
FamilySharing |
Prints version of plugin. |
queuestatus [Bots] |
Master |
Prints the status of the given bot's packages queue |
queuelicense [Bots] <Licenses> |
Master |
Adds given licenses, explained here, to the given bot's packages queue. Playtests cannot be added to the package queue using this command |
queuelicense^ [Bots] <Licenses> |
Master |
Adds given licenses, explained here, to the given bot's packages queue using that bot's package filters |
clearfreepackagesqueue [Bots] |
Master |
Removes everything from the given bot's packages queue |
| Command | Alias |
|---|---|
queuestatus |
qstatus |
queuestatus asf |
qsa |
queuelicense |
queuelicence, qlicense, qlicence |
queuelicense^ |
queuelicence^, qlicense^, qlicence^ |
| API | Method | Parameters | Description |
|---|---|---|---|
/Api/FreePackages/{botNames}/GetChangesSince/{changeNumber} |
GET |
Request changes for apps and packages since a given change number 1 | |
/Api/FreePackages/{botName}/GetOwnedApps |
GET |
showNames |
Retrieves all apps owned by the given bot |
/Api/FreePackages/{botName}/GetOwnedPackages |
GET |
Retrieves all packages owned by the given bot | |
/Api/FreePackages/{botNames}/GetProductInfo |
GET |
appIDs, packageIDs |
Request product information for a list of apps or packages 1 |
/Api/FreePackages/{botNames}/QueueLicenses |
POST |
appIDs, packageIDs, useFilter |
Adds the given appIDs and packageIDs to the given bot's package queue |
/Api/FreePackages/{botName}/RequestFreeAppLicense |
GET |
appIDs |
Request a free license for given appIDs |
/Api/FreePackages/{botName}/RequestFreeSubLicense |
GET |
subID |
Request a free license for given subID |
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}