Import

While games and versions should be covered in separate sections, importing is a complicated enough of a process to warrant a separate page. Importing is the process of pulling and providing metadata for various complex objects in Drop, namely games and versions.

Both games and versions in Drop are required to imported manually, due to them having additional metadata that must be user-provided.

Game metadata

Game metadata is provided by a series of backend 'metadata providers'. Drop unifies them all into a single API to import the metadata, and handle authentication seamlessly.

GET/api/v1/admin/import/gameSYSTEMACL: import:game:read

Fetch unimported games

This endpoint fetches all unimported games on the instance.

Request

GET

/api/v1/admin/import/game

curl -G http://localhost:3000/api/v1/admin/import/game \
  -H "Authorization: Bearer {token}"

Response

{
    "unimportedGames": [
        {
            "game": "Abiotic Factor",
            "library": {
                "id": "8dc4b769-090f-4aec-b73a-d8fafc84f418",
                "name": "Example Library",
                "backend": "Filesystem",
                "options": {
                    "baseDir": "./.data/library"
                },
                "working": true
            }
        },
        {
            "game": "Balatro",
            "library": {
                "id": "8dc4b769-090f-4aec-b73a-d8fafc84f418",
                "name": "Example Library",
                "backend": "Filesystem",
                "options": {
                    "baseDir": "./.data/library"
                },
                "working": true
            }
        },
        {
            "game": "SuperTuxKart",
            "library": {
                "id": "8dc4b769-090f-4aec-b73a-d8fafc84f418",
                "name": "Example Library",
                "backend": "Filesystem",
                "options": {
                    "baseDir": "./.data/library"
                },
                "working": true
            }
        }
    ]
}

GET/api/v1/admin/import/game/searchSYSTEMACL: import:game:read

Search metadata

This endpoint searches all metadata providers for a query.

Query parameters

Name
q
Type
string
Description
URL-encoded query you want to search.

Request

GET

/api/v1/admin/import/game/search

curl -G http://localhost:3000/api/v1/admin/import/game/search?q={query} \
  -H "Authorization: Bearer {token}"

Response

[
    {
        "id": "182101",
        "name": "Bird by Example",
        "icon": "https://images.igdb.com/igdb/image/upload/t_thumb/co587b.jpg",
        "description": "Deep Learning Bird RPG",
        "year": 0,
        "sourceId": "IGDB",
        "sourceName": "IGDB",
        "fuzzy": 1
    },
    {
        "id": "31640",
        "name": "Glory by Example",
        "icon": "",
        "description": "A story driven, visual novel inspired, narrative experience chronicling the mysteries of an artificial island city and the tragedy of its few remaining survivors following the downfall of mankind by a world-wide virus outbreak and subsequent global flood. *Based on the released novel!",
        "year": 2016,
        "sourceId": "IGDB",
        "sourceName": "IGDB",
        "fuzzy": 1
    },
    {
        "id": "289018",
        "name": "Example Block Game",
        "icon": "https://images.igdb.com/igdb/image/upload/t_thumb/co7u03.jpg",
        "description": "Example Block Game is an open source implementation of basic block stacking in Lua/LÖVE. Featuring its own standardized kick table, the game has over 7 modes in total to use as reference for implementing your own gamemodes in its extensible engine.\n\nIn most modes, gameplay continues until you top out. High scores are saved per mode and can be viewed at any time from the main menu.",
        "year": 2022,
        "sourceId": "IGDB",
        "sourceName": "IGDB",
        "fuzzy": 1
    }
]

POST/api/v1/admin/import/gameSYSTEMACL: import:game:new

Import game

This endpoint imports a game, optionally with metadata.

Request parameters

Name
library
Type
string
Description
The ID of the library you're importing from. Fetched from library.id on the GET endpoint.
Name
path
Type
string
Description
Path of the game you're importing. Fetched from the game on the GET endpoint.
Name
metadata
Type
object
Description
Optional, metadata to import from. It requires three fields if set:
{ "id": "game ID", "sourceId": "source ID", "name": "Name of game" }
All these properties are returned from the search endpoint. While you can guess these values, as they are generally the internal IDs of the respective platforms, they are internal values and are not recommended to be guessed.
For example, if you had the game already from IGDB, you may be able to use:
{ "id": "<IGDB ID>", "sourceId": "IGDB", "name": "<Name of game on IGDB>" }
Without searching for the game first. This is officially not recommended, but we are unlikely to break this behaviour.

Response

For the response and how to use task IDs, see Tasks. You need the import:game:read ACL to connect.

Request

POST

/api/v1/admin/import/game

curl -X POST http://localhost:3000/api/v1/admin/import/game \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d "{ ... }"

Response

{
    "taskId": "..."
}

Versions

Versions, in Drop, require a lot of metadata to be imported correctly, due to the various configurations that Drop supports. For that reason, the import endpoint is split into multiple by purpose.

GET/api/v1/admin/import/versionSYSTEMACL: import:version:read

Fetch unimported versions

This endpoint fetches all unimported versions on the instance.

Query parameters

Name
id
Type
string
Description
The game ID to fetch the unimported versions from.

Request

GET

/api/v1/admin/import/version

curl -G http://localhost:3000/api/v1/admin/import/version?id={game id} \
  -H "Authorization: Bearer {token}"

Response

{
    "versionName",
    "version2Name",
    "thatOtherVersion"
}

GET/api/v1/admin/import/version/preloadSYSTEMACL: import:version:read

Fetch unimported version 'preload' (metadata)

This endpoint fetches helpful metadata for unimported versions, and takes guesses on the type of version it is.

You could thereotically use this endpoint to auto-import versions, but Drop opts for a manual process.

Query parameters

Name
id
Type
string
Description
The game ID of the unimported version to fetch preload information for.
Name
version
Type
string
Description
The version name of the unimported version to fetch preload information for. The version name is the name of the folder or .zip file on disk.

Response properties

This endpoint returns a sorted list of launch/setup command guesses.

Name
filename
Type
string
Description
The relative filename of the executable (includes folders, like SubDir/MyGame.exe).
Name
platform
Type
string
Description
The platform this guess is for. Currently either "Windows", "Linux", or "macOS"
Name
match
Type
number
Description
How closely the name of the executable matches the name of the game. It's used to make educated guesses on which executable is the right one, as games usually name their executables the same as the game name.

Request

GET

/api/v1/admin/import/version/preload

curl -G http://localhost:3000/api/v1/admin/import/version/preload?id={game id}&version={version name} \
  -H "Authorization: Bearer {token}"

Response

[
    {
        "filename": "run.sh",
        "platform": "Linux",
        "match": 0.332
    },
    {
        "filename": "MyGame",
        "platform": "Windows",
        "match": 0.1
    }
]

POST/api/v1/admin/import/versionSYSTEMACL: import:version:new

Portable, import version

This way of using this endpoint is to import the game as a portable executable, meaning that there are separate launch commands, and an optional setup command.

Request parameters

Name
id
Type
string
Description
The game ID of the unimported version, to import.
Name
version
Type
string
Description
The version name of the unimported version, to import. See above comment (preload) about what it is.
Name
platform
Type
string
Description
The platform this version is for. Must be, currently, either "Windows", "Linux", or "macOS". The value is technically capitalisation insensitive, but use proper capitalisation where possible.
Name
delta
Type
boolean
Description
Whether or not this version is a 'delta' version. Read more about delta versions on the main docs: Version deltas & ordering
Name
onlySetup
Type
boolean
Description
Set as false for this example.
Name
launch
Type
string
Description
The command to launch the game.
Name
launchArgs
Type
string
Description
Additional arguments to pass to the game.
Name
setup
Type
string
Description
Optional, a command to set up the game. If it returns successfully, the game is considered successfully installed, and clients will allow the user to run the launch command.
Name
setupArgs
Type
string
Description
Optional, additional arguments to pass to the setup executable.
Name
umuId
Type
string
Description
Optional, override the UMU ID for this game. Read more on the UMU database.

Response

For the response and how to use task IDs, see Tasks. You need the import:version:read ACL to connect.

Request

GET

/api/v1/admin/import/version

curl -X POST http://localhost:3000/api/v1/admin/import/version \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d "{ ... }"

Response

{
    "taskId": "..."
}

POST/api/v1/admin/import/versionSYSTEMACL: import:version:new

Setup-only, import version

This way of using this endpoint is to import the game as a setup-only executable, meaning that Drop just executes an installer and that's it. This is how many repacked and GOG games come, but it is recommended you install/unpack them first and then add them as portable games.

Request parameters

Name
id
Type
string
Description
The game ID of the unimported version.
Name
version
Type
string
Description
The version name of the unimported version.
Name
platform
Type
string
Description
The platform this version is for. Must be, currently, either "Windows", "Linux", or "macOS". Capitalisation is technically insensitive, but use proper capitalisation where possible.
Name
delta
Type
boolean
Description
Whether or not this version is a 'delta' version. See above note on how delta versions work.
Name
onlySetup
Type
boolean
Description
Set as true for this example.
Name
launch
Type
string
Description
Not required for this example.
Name
launchArgs
Type
string
Description
Not required for this example.
Name
setup
Type
string
Description
A command to set up the game. Users will be able to run it multiple times, the installer should repair the installation.
Name
setupArgs
Type
string
Description
Optional, additional arguments to pass to the setup executable. Likely more important for setup-only versions.
Name
umuId
Type
string
Description
Optional, override the UMU ID for this game. See above for documentation on UMU IDs.

Response

See above on the returned task ID and required ACL.

Request

GET

/api/v1/admin/import/version

curl -X POST http://localhost:3000/api/v1/admin/import/version \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d "{ ... }"

Response

{
    "taskId": "..."
}