Search this manual

Fetching project files

Fetching local project files in scripting sometimes requires some adjustment to your code. Suppose you import myfile.txt to the Files folder in the Project Bar. Using fetch("myfile.txt") is able to retrieve that on all modern platforms Construct supports. However in some legacy cases it may not work.

Why some platforms are different

Some types of exports don't actually run on a web server and can't use relative URLs. For example some older Android apps internally run on a file: scheme, which has strict security restrictions which prevent your app being able to fetch local files normally.

Getting the correct URL

To solve this, Construct provides a method to convert the URL in to one that you can directly fetch. This is done with the getProjectFileUrl() method of IAssetManager.

An example on using it is shown below.

async function OnBeforeProjectStart(runtime)
{
	// Get the correct URL to fetch
	const textFileUrl = await runtime.assets.getProjectFileUrl("myfile.txt");

	// Now fetch that URL normally
	const response = await fetch(textFileUrl);
	const fetchedText = await response.text();

	// ... do something with fetchedText ...
}

Most platforms should work normally, but in case you need to support older legacy platforms, this pattern should be used for loading local project file by any means. That includes setting the src of a new Image to load an image file; creating a Web Worker from a script file; using XMLHttpRequest instead of fetch; and so on. First use getProjectFileUrl() to look up the real URL to retrieve, and then proceed to load it normally like you would have otherwise, but with the adjusted URL.

Some more details

Once you export your project to the web, you can once again fetch project files like "myfile.txt" directly, since the project is now uploaded to a web server and that URL will work as expected. So once exported, getProjectFileUrl() just returns the same URL you gave it since nothing needs to be changed.

In mobile apps where the fetch might not normally work, Construct automatically detects if the given URL will work, and returns that if so, else substitutes it for a different URL that can be loaded instead. This ensures it works even in non-web exports where fetches might not normally work.

What URL does Construct use instead? When it has to substitute the URL, it will use a blob URL instead. This is a randomly generated URL that begins with blob:, e.g. blob:https://preview.construct.net/3c1ca690-91cc-4120-bf6a-ddc02d8a22a3. This is basically a URL that refers to a local file, which means it can be fetched as if it was on the Internet, but it actually just loads something on the same device. Internally Construct represents local files with Blobs, and these URLs are generated by URL.createObjectURL(). In some cases you may see these types of URLs being shown in developer tools or while debugging, and it just means it's loading a local resource instead of getting something over the Internet.

Construct 3 Manual 2022-07-20