Images and Fivemanage

Last updated on

Download the image repository

On the machine you will use to upload, install Python 3.10 or newer, then clone or download:

git clone https://github.com/opx77-framework/opx_images.git opx_images
cd opx_images

This directory belongs on your upload machine. Do not put it in resources.load or treat it as a fourth Open77 resource.

opx_images/
  images/
    water.png
    clothing/
      ...
  upload-images.sh
  upload-images.bat

Keep all pictures under images/; the upload scripts scan every subdirectory recursively. Keep non-image files outside that directory. Each file must be at most 16 MiB.

Upload with your Fivemanage account key

Create an API key in your Fivemanage account with the permissions needed to upload and list files. Run the script from opx_images, not Infinity:

bash upload-images.sh

upload-images.bat

Paste the key when prompted. The scripts do not store it; automation can supply FIVEMANAGE_API_KEY instead. Uploads record the logical name, content hash and upload timestamp in metadata. The uploader reuses unchanged content and can resume an interrupted run. Old CDN uploads are not deleted automatically; your account's storage and bandwidth limits apply.

Use these scripts for the OPX image library: a manual dashboard upload without the OPX metadata will not become a named catalogue entry.

Put the key in Infinity too

On the game server, edit this server-only file:

OPX.Config.MODULES.images = {
	API_KEY = 'YOUR_FIVEMANAGE_API_KEY',
}

Use a key for the same Fivemanage account as the uploader. opx_images needs it to upload; opx_infinity needs it independently to list that account's files. Setting FIVEMANAGE_API_KEY for the upload script does not configure Infinity. Do not put the key in shared.lua, item definitions, the WebUI or a client script. Keep this file out of public configuration backups.

Enable outbound HTTP

Merge this section into the Open77 configuration used by your dedicated server. Preserve other hosts already allowed for your resources.

{
  "http": {
    "enabled": true,
    "allowedHosts": ["api.fivemanage.com"],
    "timeoutSeconds": 10,
    "maxResponseBytes": 1048576
  }
}

Restart the dedicated server after changing the HTTP configuration. Infinity's shipped manifest already declares its HTTP permission.

Check the result

Look for this server message, with your own image count:

[images] N public image URLs loaded

Open inventory in game. The existing item configuration stays a name:

IMAGE = 'water.png'
-- An image under images/clothing/ uses its relative name:
-- IMAGE = 'clothing/example.webp'

There is no per-item API call. Infinity lists the account at startup and every five minutes, then sends players a cached public mapping in bounded packets. A failed refresh keeps the previous complete catalogue. Duplicate logical names select the newest upload timestamp. Players receive URLs, never the API key.

For a new or replaced picture, keep its logical name, rerun the uploader and wait for the next catalogue refresh. No URL edit or framework rebuild is necessary.

Keep attribution from the asset repository when replacing or redistributing pictures.