Manual Content: Document how to prevent "Automatically remove unused assets" when compiling

[gnysek]

Description

2024.11 added Automatically remove unused assets when compiling option for game.

However, sometimes assets are get using string concatenation, like asset_get_index($"spr_npc_{npc_id}"). This way they don't be included if they aren't used in any of objects/sequences/rooms. There's no description or hint how to solve it, while there are ways.

Best way to include them is to add line like this somewhere in code:

var _used_assets = [spr_npc_1, spr_npc_2, spr_npc_3, ...];

and best place for this seems to be global scope script outside of any function (so it's removed from memory after game initialise, and not recreated later).

However, I'm 99% sure, that asset compilation happens before compilation, and before compilation optimisation, which means safest way to do it should be:

if (false) {
   var _used_assets = [spr_npc_1, spr_npc_2, spr_npc_3, ...];
}

As this way Asset compiler would include those resources, but compilation optimisation would not include that part of code at all.

As 2024.13 will be also getting optimisation to include such resources by their tag/asset type (proposal is: gml_pragma("compile_asset_tag", ">tag>");, etc. - check #8313 for futher info), so my proposal could be added together with additional info about that new pragma, which could be also referenced/linked on Game Options page in manual:

Manual Link

https://manual.gamemaker.io/beta/en/#t=Settings%2FGame_Options.htm

[YYBartT]

The "MarkTagAsUsed" pragma was already added to the description of the game option in #8313. Added an extra note to the asset_get_index() manual page that explains that an asset is considered "unused" and will be removed by the compiler if it's only referenced through this function. Also added that the "MarkTagAsUsed" pragma can be used to prevent removal of such assets and a second code example showing its use.

[mgeddesGM]

verified