Allocations Payload
Note: The content on this page pertains to Multiplay Hosting. Refer to Allocations Payload (Clanforge) for the Clanforge version of this page.
The Allocations Payload feature allows you to send any file as a payload with a server allocation request, which provides a configurable way to configure games on a per match basis. After the payload is uploaded through the ProcessAllocation V1 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 within the Multiplay ProcessAllocation V1 endpoint.
- You can remove payloads with the ProcessDeallocation V1 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, Multiplay Hosting 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 payload value, include the payload
string value in the request body, and the payload is available throughout the lifecycle of the allocation.
Multiplay API URL:
https://multiplay.services.api.unity.com
Example request
curl --location --request POST 'https://multiplay.services.api.unity.com/v1/allocations/projects/<projectid>/environments/<environmentid>/fleets/<fleetid>/allocations' \
--header 'Authorization: Basic YOUR_AUTH_CREDENTIALS' \
--header 'Content-Type: application/json' \
--data-raw '{
allocationId: "<allocation_uuid>"",
buildConfigurationId: <build_config_id>,
regionId: "<region_id>"",
payload: "this can be anything"
}'
Example response
{
"allocationId": "<allocation_uuid>",
"href": "string"
}
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 service accessible at port 8086
and sits alongside the game server. It retrieves payloads uploaded through the allocation endpoint.
Note: Use the server.json file to get a server’s allocation UUID.
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.