How Does AGS Manage its Memory?

[TheMagician]

This is a question for those of you who know how AGS handles things internally. I would like to know how AGS handles objects, characters and hotspots from a memory-standpoint.

Since you can change properties of objects, characters and hotspots that are not in the currently loaded room I wonder whether AGS loads all of these assets into memory at the start of the game and always keeps them all in memory?

Or is there a more sophisticated system where resources are only loaded behind the scenes if a value needs to be changed?


Thank you!

[Crimson Wizard]

Since you can change properties of objects, characters and hotspots that are not in the currently loaded room

You are mistaken, AGS does not let you change anything in the unloaded room (room objects and hotspots).
Characters do not belong to the room, even though they may be "placed" in one, they are considered global objects.

In regards to the memory management:

Global objects (game settings, characters, guis, etc) are loaded once while the game is loaded. Their data is just their properties, not graphics. Graphics are loaded separately.

Compiled script modules are loaded once the game is loaded and kept in memory at all times as well.

Room data is loaded once a new room is entered. Room data is separated onto a saved and not saved part, where saved part remain in memory after room is exited and re-applied when you return to that room. The exception is "non-state-saving" rooms (ones with number 301 and higher) - these are never kept in memory after leaving them.
The part which is saved is object and hotspot states (enabled/disabled, assigned object image numbers, etc), but also values of all the room variables found in room script.

Compiled room scripts themselves are only loaded during the room, and unloaded after.

In the big games with large amount of global objects and large amount of visited rooms the accumulated amount of object data can become significant, but still not as big in relative terms. We are speaking maybe megabytes or few tens of megabytes top in extreme cases.

What can make the memory consumption actually big is:
1. Loaded graphics.
2. Allocated dynamic objects (ones created by a script command).

Graphics: AGS engine uses a "sprite cache" mechanism that streams sprites on demand and saves for the future. In practice "by demand" means "when they need to be displayed". Also, in the latest versions of AGS you can request to precache particular sprites by a script command.
The size of the sprite cache is limited by a config setting (you can see that in setup program too). Normally it will never go over this limit. The sprite cache keeps a history of sprite uses (known as "MRU list"). Whenever a new sprite has to be loaded while the sprite cache is already filled to the top - it unloads some sprites to free the space, starting with the sprites that were not used recently. In a regular situation this ensures that sprites and animations that are used often are kept all the time, and sprites that are used occasionally are getting replaced. (Of course there are edge cases, especially if the game requires too many new sprites at once.)

Besides normal sprites that are loaded automatically as described above, there are also Dynamic Sprites. These are fully managed by the game script (which you write), and are not counted towards the sprite cache limit. They are deleted only when you tell it to.

Finally, there are dynamic script allocations: dynamic arrays and managed struct instances. AGS has a single global "managed object pool" where these objects are kept, and they never get freed unless deleted by a script. It does not matter where such object was created: in a global script or a room script, it stays until deleted by a script (even if room in which script it was created in is unloaded).

EDIT:
Audio: engine has a rule according to which it may load an audio clip at once if it's small enough (couple of megs iirc). All the other clips are streamed, meaning they are opened from disk and read piece by piece as playback goes further.
There's a sound cache, but unlike the sprite cache it has a small size by default, and it's meant for small clips only (there's a config setting that tells the max size of a clip which may be put there). Larger clips are normally not kept in memory and are discarded after playing.

Videos are streamed, and never kept in memory after playback finishes.

[TheMagician]

This write-up was much more than I could have hoped for. Thank you very much for the time and effort you put into it!

I made my last game with AGS 15 years ago (and you already answered my questions back then) and I misremembered that objects, regions or hotspots could be accessed from other rooms. Thanks again for your work for this community!