Getting started

This page explains the fundamental concept of the DL feature that's present in GTA: Underground. As said, UG-MP DL is not quite the same as SA-MP DL and thus if you have a server on 0.3DL you'll have to update your script to make it run on UG-MP DL.


How DL works?

You have two major components - the downloader and the file loader. You have to inform both of them about the files you want to use.

If you want players to download a file when they connect, you have to update assets.json. The downloader will then become aware of the new file. If you want to load a file, you have to use the natives listed below.

Things may not go well if you forget to list a file in assets.json but used the above natives to try and load said file. We want to add some debug output for this, but the truth is - when this happens crashes are almost garanteed as soon as the game tries to load the files that the client did not download (and won't have cached).
Working with the downloader

As said, in order to tell the game which files should be downloaded you must update assets.json. When players connect to your server they will receive a full list of assets through this file, and the game will check if any of the files have been cached. Should the player already have all the assets cached, the file loader will take over inmediately after and load all the necessary files. Here's an example of how a simple assets.json would look: 

[
	{
		"name": "Map DL - Test involving the Gostown map",
		"author": "Gostown Paradise team",
		"type": "map",
		"files": [
			"mapdl-testgostown/models/gostown6.img",
			"mapdl-testgostown/data/maps/*.IDE",
			"mapdl-testgostown/data/maps/*.IPL"
		]
	},
	{
		"name": "IMG DL - Test for custom vehicle paintjobs",
		"author": "dkluin",
		"type": "model",
		"files": [
			"imgdl-testpaintjobs/*.img"
		]
	}
]

As you can tell, it is possible to group certain assets together. The game will however only read the files property and anything else is considered as metadata. Wildcards and the like are supported - so if you want to make the game download all files in a certain folder you won't have to manually add all of them to your assets.json file. The paths are relative to the assets/ directory in your root server folder, but you can place them outside of your server directory if you really wanted to. We wouldn't recommend this, though.


Portforwarding

You will also need to make sure that you forward all traffic on the next port after your server port. By default, the server port is set to 7777, and the downloader server will thus use port 7778. The downloader server is a simple HTTP server and you can use a completely separate host if you wanted to through RedirectDownloadsTo. This is however a different subject altogether and will not be covered by this page.

Working with the file loader

The file loader will be invoked after the downloading process completes, and as said you also have to tell the file loader what to load. You can do this by using the natives listed below.

We strongly recommend you to only call them from OnGameModeInit, as calling each of these while already in-game will trigger the file loader to load it. This can be especially problematic when working with maps, as the file loader could have loaded the IMG before it has received information about all available IDEs, making the game unable to stream the IMG entries corresponding to the IDEs it did not yet get to load. This will cause the game to flood the chat with "failed to load" messages as it will think these models are on the disk; and not in an IMG archive.

Once you've told both the downloader and the file loader about your DL assets you can safely restart the server and check out your content. If you have any further questions please refer to our discord.