Allocations Payload (Clanforge)#

The Allocations Payload feature allows you to send any file as a payload with a server allocation request. This feature provides a way to configure games on a per-match basis. After the payload is uploaded through the Allocate V2 endpoint, you can retrieve it from the game process. After an allocation ends, the payload associated with that allocation is no longer available. Refer to Payload lifecycle.

Limitations#

The Allocations Payload feature has the following limitations:

• Payloads can't exceed 30 KB. The endpoint rejects allocations with a payload larger than the limit size with a status of 400.
• You can include a payload as part of an allocation of the Allocate V2 beta endpoint.
• You can remove payloads with the Deallocate V2 beta endpoint.

Payload lifecycle#

Payloads are temporary, session-based data tied to a specific allocation. After the allocation that a payload is linked to is deallocated, the payload is no longer available.

Payloads are retrievable until one of the following conditions is met:

• The game server is deallocated via the deallocation endpoint. When an allocation’s lifecycle is complete, Clanforge clears out any data related to the allocation UUID.
• The payload reaches its time to live (TTL). The allocation timeout value sets the payload TTL in the Fleet scaling settings, which is one hour by default if not set at the fleet level.

Sending the payload#

To send a file with an allocation request, set the X-Enable-Payload header to true. You can then attach the file to the body of the request. This file can be in any format and you can retrieve it throughout the lifecycle of the allocation.

https://api.multiplay.co.uk

Example request#

curl --location --request POST 'https://api.multiplay.com/cfp/v2/fleet/<fleetid>/server/allocate?regionid=<regionid>&profileid=<profileid>&uuid=<allocation_uuid>&project_guid=<project_guid>' \
--header 'Authorization: Basic YOUR_AUTH_CREDENTIALS'\
--header 'X-Enable-Payload: true' \
--header 'Content-Type: text/plain' \
--data-raw 'This can be anything.'

Example response#

{
    "success": true,
    "messages": [],
    "allocation": {
        "profileid": <profileid>,
        "uuid": "<uuid>",
        "regions": "<regionid>",
        "requested": "<requesteddate>",
        "created": "<createddate>",
        "fleetid": "<fleetid>"
    }
}

Retrieving the payload#

After the allocation request is complete, you can access the payload from the game server. Send a request to the payload proxy, which is available locally on the game server machine, to retrieve the payload file from the game server. The payload proxy is a service accessible at port 8086 and sits alongside the game server. Additionally, it retrieves payloads uploaded through the allocation endpoint.

Example request#

curl -X GET http://localhost:8086/payload/<allocation_uuid>

Example response#

HTTP/1.1 200 OK
Date: Mon, 26 Jul 2021 17:00:33 GMT
Content-Length: 23
Content-Type: text/plain; charset=utf-8
This can be anything.