Resource management

This article will show how the Resource Manager works and how to use it in the code.

Warning! This page shows the new resource management system introduced in Beta 4.8.0. Earlier versions had a different resource management system, with configuration files being handled by ConfigManager. That system will not be covered here.

Fundamentals

Let's start with establishing a few key components which are present in the Resource Manager.

Defining the resources

A resource is a file that is located anywhere within the game's directory - in its root, or hidden somewhere in a folder. Every resource has a type. For a .png file, this is Image, for an .ogg file, this is Sound, and for a .ttf file, this is FontFile.

However, most of the resources used in the game are sharing the same extension, that is .json. Because the resource placement does not determine its type, there is a mechanism in place which deduces of what type each given resource is.

Currently, it is done in a hacky way: The .json resource's type is deduced from its $schema field. Specifically, the part after the /schemas/ substring is considered. For example, "$schema": "../../../../schemas/color_palette.json" will transfer to color_palette.json, and as such map to the Color Palette type. All resource types can be created from paths to their schemas. This includes subfolders.

Note that the way in which the game resolves resource types is not set in stone yet and may change in future versions of the engine.

The full list of resource types is as follows:

String extracted from $schema field	Resource type
sprite.json	sprite
sound_event.json	soundEvent
music_track.json	music
particle.json	particle
font.json	font
color_palette.json	colorPalette
config/sphere.json	sphere
config/sphere_effect.json	sphereEffect
config/collectible.json	collectible
config/color_generator.json	colorGenerator
config/shooter.json	shooter
config/level.json	level
collectible_generator.json	collectibleGenerator
difficulty.json	difficulty
path_entity.json	pathEntity
score_event.json	scoreEvent
sphere_selector.json	sphereSelector
ui2/animation.json	ui2AnimationConfig
ui2/node.json	ui2NodeConfig
ui2/sequence.json	ui2SequenceConfig

Source: SCHEMA_TO_RESOURCE_MAP field in src/ResourceManager.lua.

Exceptions

Due to legacy code which is very hard to prune, there are quite a few exceptions to the placement-agnostic rule of files:

• UI1 files (ui/*.json) do not have schemas and must be contained in the ui directory.
• Name of the folder which contains maps is currently hardcoded to maps.

Resource paths

All resources can be referenced with an absolute path - that's the path to the file starting from the root game directory, including the extension. That's the most usual way of referencing all the resources in the game. For example:

sprites/game/ball_1.json

is a reference to a sprite laying exactly there.

However, this is not the way you should refer to map resources - while it works, there is another way to access them:

Map1:flame.json

will access the resource located at maps/Map1/flame.json.

For convenience, in the map directory, you can refer to resources inside of it by omitting the map name, internally called a namespace:

:flame.png

Resource loading

There are a few ways to trigger loading the resource:

• You can use the ResourceManager:get*(...) API functions to grab a resource from anywhere in the game. If that resource isn't already loaded, it will be immediately loaded at that moment. This is used for example in the game's loading screen.
• When the loading screen shows up, the UI script (ui/script.lua) is supposed to call the f.loadMain() function from the UI Manager API, which will in turn call Game:loadMain() and that will call ResourceManager:scanResources(). This function loads all resources from all game's folders, with the exclusion of the maps and config directories.

... To be continued ...