AssetUpdates (Mod Updates)

Updated for version ~4.0+.

Module Definition

The module is inherited from ModuleBase. So base parameters can be found there.

The purpose of this module is to provide updating of a mod or a mods assets.

Module name

The name of the module you use as the meta of the module definition is 'AssetUpdates' or 'ModAssetsModule' if _force_search is set to true in the module definition.

XML Structure

<AssetUpdates id provider use_local_dir use_local_path folder_name version_file>
    <custom_provider update_func download_file_func version_api_url download_info_url download_api_url/>
    <folder_name>
        <value_node value/>
        ...
    </folder_name>
    <optional_versions>
        ...
    </optional_versions>
</AssetUpdates>

<AssetUpdates id provider install_directory use_local_dir use_local_path folder_name version version_file important is_standalone>

Parameter
Type
Description

id

String/Number

The id of the mod on the server

provider

String

The provider of updates for the mod/assets. Currently implemented: modworkshop, github and Payday2Concepts

install_directory

String

The directory that contains the folder for the mod

use_local_path

Boolean

(Defaults to true) Determines if the folder of the mod should be used as the folder that is being updated

use_local_dir

Boolean

(Defaults to true) Determines if the location of the mod should be used as the installation directory

folder_name

String/Table

the folder name(s) that are being updated

version

String/Number

(Optional) The current version of the mod. Every time you update the mod, you should increase the version number. For example, from 1.11 to 1.12, just make sure the number is larger than the older one. Generally, you can use any string or number you want for updates. Version check for Modworkshop only checks if the version equals to the curent version and not if it's lower

version_file

String

(Optional) The version file which is used to determine the current version of the mod. Defaults to InstallDirectory/FirstFolderName/version.txt. To assign this you can do it as just a path relative to the InstallDirectory

important

Boolean

If set to true, every time the mod will receive an update, the game will notify the user with a dialog (By default, the update will show up in the updates counter in the main menu without notifying the user directly). Use it only if updating the mod is crucial (For example, BeardLib updates are important)

is_standalone

Boolean

(Defaults to true) Mostly used for custom maps. Where users can download them by joining a game. However, this shouldn't apply to all maps due to some maps needing assets/code which means the map cannot run without these important assets/code. Setting is_standalone to false will disable it. And, users will simply disconnect from the server if they don't have the map

dont_delete

Boolean

(Defaults to false) Doesn't delete the mod folder when updating. This is useful if your mod contains things users might want to change and you don't wish for that content to be deleted each update

branch

String

The github branch to get files from. only used if release is false

release

Boolean

If set to true, get the latest github release instead of latest commit

optional_versions

Table

A Table containing AssetUpdates Modules to be used as optional versions

Example

This example is what you would put inside your main node within your mod config

<AssetUpdates id="16212" provider="modworkshop" version="1.0"/>

Where id is the unique identifier on Modworkshop. So this example will update the directory of the mod with the mod with id '16212' and version being the current version set in the mod page on Modworkshop. You can set it as any string/number you'd like. Numbers are recommended.

The example is what you'll see in most mods. Some old mods may have use_local_path & use_local_dir set to true. These parameters are already set to true by default.

Github Example

For commit based updating:

<AssetUpdates id="Luffyyy/BeardLib-Editor" provider="github" branch="master"/>

The id for github provider updates is owner/repository and branch should be the branch you wish to update from, most of the time this should be master or main.

Upon the next commit, This will create a version_file in the root of your mod with the hash of the commit, you will want to add this to your .gitignore.

For release based updating:

<AssetUpdates id="simon-wh/PAYDAY-2-BeardLib" provider="github" release="true" version="4.4"/>

The version should be the same as the tag of the release.

Optional versions

This example showcases optional versions, which can be enabled in the mod settings in the BeardLib Mod Manager.

The optional versions table should contain AssetUpdates modules with their module name replaced with the name you wish to list in the settings menu. The root element will be the stable version.

<AssetUpdates provider="github" custom_name="GitHub Update" branch="master" id="simon-wh/PAYDAY-2-BeardLib" dont_delete="true">
    <optional_versions>
        <alpha provider="github" branch="testing-alpha" id="simon-wh/PAYDAY-2-BeardLib" />
        <beta provider="github" branch="testing-beta" id="simon-wh/PAYDAY-2-BeardLib" />
        <latest-stable id="14924" version="4.8" provider="modworkshop" important="true" version_is_number="true"/>
    </optional_versions>
</AssetUpdates>

Custom providers

You can either ask the current developers of BeardLib if they can add your site as a provider. Or, use custom providers feature of the module.

To make custom providers you need to have an API in your website. BeardLib will need to communicate with your API to get the version, mod files.

Providers are defined inside the module itself.

Since this is a more complicated topic, we'll start with an XML example:

    <AssetUpdates id="MyMod" version="1.0">
        <custom_provider version_api_url="mycoolwebsite.com/api/check_version/$id$" download_url="mycoolwebsite.com/api/download/$id$"/>
    </AssetUpdates>

<custom_provider check_func download_url/>

In the future a module will be added to add a provider instead of repeating it in the module. Pay attention to the dollar signs in the URL, these will be replaced.

For example, $id$ in this case, will turn into MyMod

Parameter
Type
Description

version_api_url

String

The URL that checks the version. If you don't use a custom check_func function, the function will expect the URL to return the latest version. It will then compare the version to the current version

download_url

String

The URL that will download the file. If you have something more special you'll need to handle it yourself in download_file_func

version_is_number

Boolean

[Defaults to false] Determines whether the versions are a number. This will force all versions to be a number so no string versions!

check_func

String or Function (in classes)

String path to a function (self.Func for example) or a function if defined inside a provider class. The function must deal with the version check all by itself. Use the BLT function dohttpreq to do communication with the web. See the providers inside BeardLib to understand more how it works

download_file_func

String or Function (in classes)

Exactly like check_func rules but this will donwload the update

page_url

String

The page of the mod for users to get more information. Used in the mods manager

Creating a provider class

At the moment, it's possible to create a class for custom providers. The class acts like "custom_provider" only the functions have to be actual functions and not a path to the function. And you can use them like normal providers in the modules themselves.

Example of payday2concepts website (built in BeardLib):

ModAssetsModule._providers.payday2concepts = {}
local pd2c = ModAssetsModule._providers.payday2concepts
pd2c.version_api_url = "http://payday2concepts.net/crimenet/checkversion/$id$.txt"
pd2c.download_url = "http://payday2concepts.net/crimenet/downloads/$id$.zip"
pd2c.version_is_number = true

You'll have to create these early enough so BeardLib mods can use it.

Having more than one update module in the mod.

At the moment, BeardLib adds updates into mods manager as single mod updates and does not account for individual updates. This will be changed in the future.

Functions

Get

Function
Return Type
Description

GetMainInstallDir()

String

Returns the path of the primary installation directory for the mod. i.e. The directory that contains that version file

Other

Function
Description

CheckVersion()

Checks the version if the mod/assets are updated

RetrieveCurrentVersion()

Sets self.version to the current version

PrepareForUpdate()

Called by the check function (or _CheckVersion()) to let BeardLib know there's an update. This informs the mods manager & informs the user if important is set to true

_CheckVersion()

The default version check function if the provider doesn't have one set

DownloadAssets()

Downloads the mod/assets

_DownloadAssets()

The default download function if the provider doesn't have download_file_func set

ViewMod()

Opens the page of the mod in the provider's site. Don't call this if provider doesn't have page_url set

StoreDownloadedAssets(String data, String id)

The function that recieves the downloaded file and stores it. data is the data string of the file, basically all of the bytes and pieces of it. id is the ID of the download; the function doesn't use it.

PreviousAdding your own modulesNextClasses

Last updated