Nuclide
Software Development Kit for id Tech
Update Manager

Game and content update handler functions. More...

Classes

struct  updaterPackage_t
 Data holding Updater Package entries. More...
 

Enumerations

enum  updateType_t {
  UPDATE_NAME , UPDATE_CATEGORY , UPDATE_TITLE , UPDATE_VERSION ,
  UPDATE_DESCRIPTION , UPDATE_LICENSE , UPDATE_AUTHOR , UPDATE_WEBSITE ,
  UPDATE_STATE , UPDATE_ACTION , UPDATE_FILESIZE , UPDATE_PREVIEWIMAGE ,
  UPDATE_STATUSSTRING , UPDATE_DLPERCENTAGE
}
 Different options you can pass to Updates_GetInfo() to retrieve details about a given Update entry. More...
 
enum  updateState_t {
  UPDATESTATE_NONE , UPDATESTATE_DISABLED , UPDATESTATE_ENABLED , UPDATESTATE_CORRUPT ,
  UPDATESTATE_PENDING
}
 Return values from passing UPDATE_STATE to Updates_GetInfo() More...
 
enum  updateAction_t {
  UPDATEACTION_NONE , UPDATEACTION_INSTALL , UPDATEACTION_REINSTALL , UPDATEACTION_UNINSTALL ,
  UPDATEACTION_AUTOINSTALL , UPDATEACTION_DISABLE , UPDATEACTION_RETAIN
}
 Return values from passing UPDATE_ACTION to Updates_GetInfo() More...
 
enum  updaterStatus_t { UPDATER_NONE , UPDATER_UNAVAILABLE , UPDATER_PENDING , UPDATER_INITIALIZED }
 These are the possible return values from Updates_GetUpdaterStatus(). More...
 

Functions

void Updates_Init (void)
 Call this in order to contact the update server and fill the list of updates. More...
 
updaterStatus_t Updates_GetUpdaterStatus (void)
 Retrieve the status of the updater. More...
 
int Updates_GetPackageCount (void)
 Returns the total amount of updates available for the currently running game. More...
 
__variant Updates_GetInfo (int, updateType_t)
 Query a package (by ID) for its various info fields. More...
 
bool Updates_Available (void)
 Returns if our current game has updates available for any installed packages. More...
 
bool Updates_Toggle (int)
 Toggle the installation/disabling of an update. More...
 
bool Updates_Install (int)
 Mark an update as pending installion. More...
 
bool Updates_Remove (int)
 Mark an update as pending deletion. More...
 
bool Updates_Destroy (int)
 Mark an update as pending uninstallation. More...
 
bool Updates_ApplyPendingChanges (void)
 Apply all pending changes to packages. More...
 

Detailed Description

Game and content update handler functions.

The updater is an abstraction of the engine its own package manager. Not all packages the engine offers are related to the game you're currently running. Therefore we offer our own API within Nuclide to deal with game updates.

You want to call Updates_Init() once, after which Updates_GetUpdaterStatus() should be queried to determine when the Updater is ready. That is not necessary, but it might be helpful to throw up a loading screen while that is returning UPDATER_PENDING.

Once Updates_GetUpdaterStatus() reports UPDATER_INITIALIZED, you can expect the loading to be fully done.

The function Updates_GetPackageCount() will report the total amount of update packages available for the game. These are not 'new' updates, they contain every package associated with the game that can and should be installed and kept updated.

Use Updates_GetInfo() to retrieve metadata about individual packages.

Enumeration Type Documentation

◆ updateAction_t

Return values from passing UPDATE_ACTION to Updates_GetInfo()

Enumerator
UPDATEACTION_NONE 

Update is not marked for any change.

UPDATEACTION_INSTALL 

Update marked for installation.

UPDATEACTION_REINSTALL 

Update marked as needing re-installation.

UPDATEACTION_UNINSTALL 

Update marked for removal.

UPDATEACTION_AUTOINSTALL 

Update marked as needing to be installed, due to a dependency.

UPDATEACTION_DISABLE 

Update has been marked for disabling.

UPDATEACTION_RETAIN 

Update has been marked as being retained.

◆ updaterStatus_t

These are the possible return values from Updates_GetUpdaterStatus().

That way you can put up a loading screen for when the updater is still initiliazing, or be notified of when an updater is not available at all.

Enumerator
UPDATER_NONE 

Nuclide's updater has not been initialized.

You need to call Updates_Init().

UPDATER_UNAVAILABLE 

Nuclide's updater is unavailable.

This may be due to the update server being offline.

UPDATER_PENDING 

Nuclide's updater is pending.

May change to UNAVAILABLE or INITIALIZED.

UPDATER_INITIALIZED 

Nuclide's updater is initialized and may have entries.

Use Updates_GetPackageCount() to query how many.

◆ updateState_t

Return values from passing UPDATE_STATE to Updates_GetInfo()

Enumerator
UPDATESTATE_NONE 

Update is not installed, or unavailable.

UPDATESTATE_DISABLED 

Update is installed, but disabled.

UPDATESTATE_ENABLED 

Update is installed and enabled.

UPDATESTATE_CORRUPT 

Update on disk is corrupted.

UPDATESTATE_PENDING 

Update is pending a change.

Usually when we're downloading it.

◆ updateType_t

Different options you can pass to Updates_GetInfo() to retrieve details about a given Update entry.

Enumerator
UPDATE_NAME 

(string) name of the package, for use with the pkg command.

UPDATE_CATEGORY 

(string) category text

UPDATE_TITLE 

(string) name of the package, for showing the user.

UPDATE_VERSION 

(string) version info (may have multiple with the same name but different versions)

UPDATE_DESCRIPTION 

(string) some blurb

UPDATE_LICENSE 

(string) what license its distributed under

UPDATE_AUTHOR 

(string) name of the person(s) who created it

UPDATE_WEBSITE 

(string) where to contribute/find out more info/etc

UPDATE_STATE 

(updateState_t) The current state of the update.

UPDATE_ACTION 

(updateAction_t) Pending action of the update.

UPDATE_FILESIZE 

(int) size to download in bytes.

UPDATE_PREVIEWIMAGE 

(string) Path to a preview image in 4:3 aspect ratio.

UPDATE_STATUSSTRING 

(string) Localizable string that gives you the update status.

UPDATE_DLPERCENTAGE 

(float) Download progress in percent (0-100).

Function Documentation

◆ Updates_ApplyPendingChanges()

bool Updates_ApplyPendingChanges ( void  )

Apply all pending changes to packages.

May return true/false if it succeeded in doing so.

◆ Updates_Available()

bool Updates_Available ( void  )

Returns if our current game has updates available for any installed packages.

◆ Updates_Destroy()

bool Updates_Destroy ( int  packageID)

Mark an update as pending uninstallation.

May return true/false if it succeeded in marking the package.

◆ Updates_GetInfo()

__variant Updates_GetInfo ( int  packageID,
updateType_t  fieldType 
)

Query a package (by ID) for its various info fields.

See updateType_t for available options.

◆ Updates_GetPackageCount()

int Updates_GetPackageCount ( void  )

Returns the total amount of updates available for the currently running game.

◆ Updates_GetUpdaterStatus()

updaterStatus_t Updates_GetUpdaterStatus ( void  )

Retrieve the status of the updater.

See updaterStatus_t for valid return values.

◆ Updates_Init()

void Updates_Init ( void  )

Call this in order to contact the update server and fill the list of updates.

◆ Updates_Install()

bool Updates_Install ( int  packageID)

Mark an update as pending installion.

May return true/false if it succeeded in marking the package.

◆ Updates_Remove()

bool Updates_Remove ( int  packageID)

Mark an update as pending deletion.

May return true/false if it succeeded in marking the package.

◆ Updates_Toggle()

bool Updates_Toggle ( int  packageID)

Toggle the installation/disabling of an update.

May return true/false if it succeeded in marking the package.