Custom Resource Servers

Setting up a resource server

Setting up a resource server for your game server allows you to override any client data available in the stock game: icons, textures, 3D, sounds, text, font, pretty much anything.

A resource server consists of two parts: the actual file server, which is a standard HTTP server (Apache, nginx, anything works) and a file list provider endpoint

Setting up a file list provider endpoint

The purpose of a file list provider endpoint is to tell the client which resources are the most recent and where they can be found; the client then checks the local listing and downloads the files it needs to refresh.

The endpoint is a standard HTTP URL you must provide in your perpetuum.ini like so:

{
  "ListenerPort": 17700,
  [...]
  "ResourceServerURL": "http://my.server.url/",
  [...]
}

In the above example, the URL will be called as http://my.server.url/?language=0&client=0

The endpoint should return a GenXY string something like this, according to the language and client numbers above: (for detailed explanation see below)

#resources=[
  |myFile=[
    |version=i2
    |language=i0
    |client=i0
    |path=$myFile.dat
    |compression=i0
    |size=i1234
    |hash=ib6ab339a 
  ]
  |otherFile=[
    |version=i8
    |language=i0
    |client=i0
    |path=$otherFile.jpg
    |compression=i0
    |size=i2345
    |hash=icc68b9c4 
  ]
]
#rootURLs=[
  |a0=[|url=http://my.distributed.url/path/]
  |a1=[|url=http://another.url/different/path/]
]

resources

This required array contains all the files; the key (e.g. myFile in the above example) is what the client will treat as the (internal) filename. All fields are required unless noted.

• version - Standard integer value that indicates the revision of the file; if a client has an instance of this resource with a lower version number, it will download the new one and replace the local one.
• language - The integer ID of the language the client (for the language list see here); your endpoint should return localized versions of a resource if they're available, or English (0) if not.
• client - Client type; deprecated.
• path - The path of the file to download from. This can be either absolute or relative; for relative paths, they will be appended to the endpoint URL (e.g. in the above example, http://my.server.url/otherFile.jpg)
• compression - If 0, the resourced is stored and downloaded uncompressed. If 1, the resource is compressed with the DEFLATE algorithm (i.e. Zlib), with a four byte integer value of the original size prepended, so [4 byte uncompressed size][N bytes of compressed data].
• size - The size of the file to be downloaded in bytes. This is only used for updating the progress bar proportionally.
• hash - Optional. A 32-bit CRC hash of the file; only used if the client wants to do a hash-check during update.

rootURLs

This optional array contains additional servers to download from, for load-balancing options; if present, the client randomly uses one of these URLs as the root instead of the endpoint. Note that this means that if you use mirrors, but your file list server is also your file server, you must specify the endpoint in this list as well.