Documentation

Support

Multiplay Hosting

Multiplay Hosting

Allocations Payload

Learn how allocation payloads pass game-specific data to your servers during allocation.
Read time 2 minutesLast updated 3 days ago
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.

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.

Example request

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

Example response

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