Messages

Hi, my game is 32 bit game but when importing the sprites I imported all with remap palette I think. Is it always marked with a tick under "import alpha"? I'm not sure if it was unchecked before and if I checked it then. Is there any impact to import with remape palette if the game is 32 bit game?

The effect is only applied when both game is 8-bit and image is 8-bit.

I think the reason why this checkbox is ticked by default is because sprite manager is not programmed to have separate defaults for 8-bit and non-8bit games.

AFAIK most of the suspects so far had this in common:
a) they were not much active, mostly make 1 random post in few months, and usually their posts are too generic to be sure that they are invested in the conversation,
b) it was not clear whether they have any relation to AGS at all, as they don't ask any AGS technical questions and rarely comment on games (if ever).
c) were posting links that are vaguely related to the actual conversation.

Hello! Noticing a problem with the searching feature.

Normally, when I do a search for a word or phrase in my script, I press "control-F", select "look in current project", and then press enter. I can click on the results and them I am taken to the point in the script where word/phrase resides.

However, it now only works properly when searching in a standard script. For dialog scripts (meaning dialog that is written in the dialog editor), it just opens up the dialog script without highlighting the search result. Here are examples:

I tried this, and for me it finds the dialog line, but does not highlight it, just puts cursor there. Could you double check if that happens to you, or it does not even move to the line itself?

None, except for backwards compatibility, and this is in todo list to change in AGS 4 branch (maybe not documented, but definitely in mind).

Is there another way than Wait(); that doesn't block.So far what I use is a integer adding up and whenever the integer reaches a number it runs certain script.This way works but you have to place the script in an if statement.I'm looking for something that merely stops reading of the script for a set time without blocking the already running scripts such as animations and mouse cursor.

I am still not sure what the problem is, as Wait does that: it stops execution of the current script and does not block the active animations and the mouse cursor. Perhaps if you tell why you cannot use Wait, or expain your situation in more detail?

In general, if you need to wait until something, then it's one of the two solutions:
1. If you want to stop script right in the middle of the current function, then use Wait, and optionally some conditions to see at which point it needs to stop waiting.
2. Use timers, or any alternatives (like integer counters), and check in repeatedly_execute and similar functions to see when they are over.

The case 2 is also when you need player to keep ability to interact with things.

Is there a way to easily delay reading script without blocking?

Please elaborate?

Does drawing dynamic sprites have a baseline or z-order?

Dynamic sprites are just raw graphic, they dont have any baseline or position on their own. But they may be drawn on or assigned to an object, and object has a baseline or z-order.

Is there a plausible way to do costumes in AGS that are like extra layers/limbs?

Similar questions have been asked couple of times only recently, here are related discussions:
https://www.adventuregamestudio.co.uk/forums/index.php?topic=59912.0
https://www.adventuregamestudio.co.uk/forums/index.php?topic=59954.0

PS. I feel like we would benefit from a good tutorial and maybe an article in the manual on this topic.

I have this script here that seems to totally ignore the else statement.I'm trying to get the character to only be visible while speaking.So what's the problem with this?

Code: ags

  if(cfattymouth.Speaking)
  {
    cfattymouth.Transparency=0;
  }  
  else
  {
    cfattymouth.Transparency=100;
  }  

By the way.This is in repeatedly execute.

"repeatedly_execute" is not called during blocking actions, including blocking speech. Try placing this in "repeatedly_execute_always" instead.

More info on this: https://adventuregamestudio.github.io/ags-manual/RepExec.html

Started writing "Upgrade to 3.6.0" topic in the manual, in case someone needs an explanation on most noteable changes:
https://github.com/adventuregamestudio/ags-manual/wiki/UpgradeTo36
(work in progress)

Finally, I don't understand why you are making the game using 16-bit colors, this causes all sorts of hard to use alpha values, I don't know how things work in 16-bit

16-bit games don't use alpha on sprites themselves (they are created fully opaque), but they still may use Transparency property on objects.

[Editor:]

Updated to Beta 5
(use download links in the first post)

A bit unexpected, but this is suddenly a larger feature update, complementing improvements to Overlays in this version.
Additionally this update contains a way to set volume for the frame-linked sounds during animation (see below).
Normally this is not a good thing to add so much stuff while the version is already far in Beta, but some of these changes were in plans for 3.6.0 for a while now, and they appeared to be not too difficult to make. At the same time, I believe that's the last of the feature additions for 3.6.0 engine.

Editor:
- Fixed extracting room template files (other than the blank template).
- Fixed editor displaying unhandled exception if the room script which user is trying to open was missing. Instead it will now open a blank script.

Compiler:
- Support using float literals when defining default values for function arguments.

Script API:
- Extended all Animate() commands by adding "volume" parameter, that defines relative volume of the frame-linked sounds for the duration of this animation.
- Added Character.AnimationVolume, defining relative volume of the frame-linked sounds.
- Added Overlay.CreateRoomGraphical and CreateRoomTextual. Use these two functions to create "room overlays": that is - overlays that display a sprite inside the room, sorted among other room objects, characters and walk-behinds.
- Added readonly Overlay.InRoom property that tells if this is a room or screen overlay.
- Extended Overlay.CreateGraphical() with a new "clone" parameter that tells whether to assign a sprite index, or make a sprite's copy owned exclusively by this overlay. The former will save program memory but make overlay update if the sprite is edited later. The latter is meant primarily for backwards compatibility. Overlay.CreateRoomGraphical has the same param. Default is false (don't clone).
- Added Overlay.Graphic property that lets you change overlay's sprite after it's created.

Engine:
- Perfomance improvement to overlays: engine will not make a sprite copy when they are created whenever possible (non-dynamic sprites), or when told not to by the script command that creates a custom overlay.
- When reporting script errors, engine will print callstack for all the active script "threads": for example, if there's Wait() function called and error happened in repeatedly_execute_always, then it will print both actual error's location, and Wait() call's location.
- Added "load_latest_save" and "show_fps" options to config (in "[misc]" category).
- Fixed overlay may fail to be created sometimes, if previously another overlay had been forcefully removed when changing rooms (this is an ancient bug which existed for many years).
- Fixes GUI controls not getting redrawn in correct locations if they were moved at runtime.
- Fixed script's String type could be stored in game saves with a wrong length.
- Fixed Game.InputBox() duplicating key input if new key handling mode is active.



NOTES: On Overlays

So, from this update 3.6.0 allows to dynamically create overlays not only "on screen", among GUIs, but also inside rooms - among the characters and objects. Overlays still remain a simplistic kind of object that does not have any automated behavior, so it won't interact with anything inside the room, but it still may be sorted among other objects there by manually setting Overlay.ZOrder. So, for example, if you'd like room overlay to change its "baseline" along with its vertical position, you will have to do something like this in rep-exec:

Code: ags

over.ZOrder = over.Y + over.Height;

In overall, I believe that room overlays open new possibilities in making temporary visual effects in the game, and also may help to script custom game elements from ground up (as they have no additional functionality on them).

On overlay's sprite cloning. This may not be well known, but for "historical reasons" (tm) overlays were doing a copy of the sprite when created. This was fine while overlays were limited to 20 in previous versions, but now when they are unlimited this could become an annoyance. So now, firstly, engine may decide when it is safe to not do a sprite copy (normally - when using regular non-dynamic sprites), and secondly Overlay.CreateGraphical now has an additional parameter which tells whether to make a copy of the sprite or not (not by default). This parameter may be used for backwards compatibility with some old scripts, where dynamic sprites are used to create an overlay and then discarded.

After the above change, it now makes sense to have Overlay.Graphic property, similar to Object.Graphic etc. This changes the overlay's sprite without having to recreate overlay.
Note that there's no Animate function for them, but you may script one yourself, using timers, and changing Overlay.Graphic.

NOTES: On Animation volume

Previously there was no way to choose the playback volume of sounds linked to the animation frames. The only related property was Character.ScaleVolume.
Now there are two ways to do this. First of all, there's Character.AnimationVolume. It sets the default relative volume of any frame sounds. For example, here's a primitive example of how you can make the footsteps volume depend on the character's X position in room:

Code: ags

player.AnimationVolume = player.x * 100 / Room.Width;

Secondly, each Animate() function (for Button, Character and Object) now has a "volume" parameter. Passing -1 (default) will ignore this, but when a 0-100 value is passed, that value overrides the frame sound volume.

EDIT: hmm, i just realized that maybe Animate() should not override Character.AnimationVolume, but also be relative to it... According to the idea that character is "sound emitter" with it's volume and Animate() is playing an individual sequence, then the volume of the sequence should not be louder than the volume of the emitter?

[Download AGS 3.5.1 installer]

AGS 3.5.1 - Patch 11

Full release number: 3.5.1.18

Download AGS 3.5.1 installer

Download AGS 3.5.1 as a .zip archive

For Editor

Spoiler

VC 2015 redistributable needed for AGS Editor on Windows

Download Dark UI Theme for the editor

[close]

For Android

Spoiler

Android launcher (APK signed with Debug key), suitable for running any compatible AGS game

Native engine libraries, for making your own signed APKs

[close]

For Engine/Editor developers

Spoiler

AGS source code central repository

Debug symbols database (for analysing crash dumps)

[close]

Released: 6th May 2022

Previous stable version: AGS 3.5.0 P10 forum thread


This release is brought to you by:

- Alan v. Drake
- Crimson Wizard
- eri0o
- fernewelten (fixes)
- James Duong (implemented "--console-attach" option for Windows)
- Morgan Willcock
- Nick Sonneveld
- rofl0r
- Pablo Navarro (fixes)
- Thierry Crozat (bug fixing)
- vga256 (bug fixing)



Summary

3.5.1 is a minor update after 3.5.0, which contains mostly utility additions, fixes and perfomance improvements.



Changes in the Patch 11:

Editor:
- Fixed batch sprite export with "Set exported file as sprite source" option was assigning new source paths without file extension.

Engine:
- Perfomance fix: GUIs changing Transparency or Visible state should not redraw their surface.

Compatibility:
- Allow AudioClip.Play to to place clips on a crossfade channel, which is normally unaccessible from script. This prevents errors in some games that relied on this behavior.


Changes in the Patch 10:

Engine:
- Fixed crash when visible viewport does not have any linked camera.
- Fixed ListBox.FillSaveGameList() may include save slots with negative slot number (e.g. when the save file has "*.-01" extension).
- Fixed potential crash after failed RunAGSGame() call.
- Fixed search for the game data by GUID when restoring a save belonging to another game;
   this was implemented in 3.5.1, but appeared to not work correctly.


Changes in the Patch 9:

Editor:
- Removed restriction on max dialog topics in the project. The dialog limit in the engine was removed in 3.4.1, but remained in the Editor by oversight.
- Fixed Audio Clip items in the project tree not displaying their IDs right after being renamed.

Compiler:
- Fixed crash occuring when compiler tries to report "Already referenced name as import" error.

Engine:
- Added "--translation" and "--no-translation" command-line arguments.


Changes in the Patch 8:

Engine:
- Clearer error messages for Get/SetProperty functions.
- Fixed PlayFlic() command fails to start the video (regression in 3.5.1).
- Fixed DrawingSurface.DrawSurface() not applying transparency parameter correctly if the drawn surface has alpha channel.
- Fixed @OVERHOTSPOT@ is not updated immediately when character's name changes while cursor is above that character.

Templates:
- In BASS template fixed right click not dropping currently selected item if cursor was hovering over another item.


Changes in the Patch 7:

Editor:
- Added "Layout -> Reset to Defaults" menu command.
- Editor will now reset panel layout to default state if loading layout fail for any reason.
- Default config is now saved also when the game is run in debug mode (F5). This ensures that the test run is using the latest Default Setup, if the user's config has not been created yet.
- Editor will now display an error if user tried to reserve too many channels for audio types.
- Fixed Editor failing to start if user preferences file is corrupted.
- Fixed "Use old-style custom dialog options API" was not set when importing pre-3.4.0 projects.
- Fixed comboboxes' drop-down arrows were not painted with the right color from a color theme.

Engine:
- Fixed program crash occuring if the game reserved too many channels for audio types.
- Fixed potential crash occuring when player loads a save made in a multi-frame room, but the room was since edited and no longer has as many frames.
- Fixed character may have incorrect Frame (property) values while turning.


Changes in the Patch 6:

Editor:
- Added line numbers in the dialog script editor.
- Fixed Dialog script loosing changes if the pane is closed or redocked.
- Fixed controls arrangement on the Dialog pane getting broken when it's redocked.

Engine:
- Fixed filepaths in scripts that have backslashes ('\') fail on non-Windows systems.
   All the (script) File functions will now convert backslashes in filepaths into forward slashes for compatibility.
- Fixed engine was still creating standard directories for game saves and data, even if user provided the custom paths for these.
- Fixed TextBox control crashing the game if it's empty and player presses Backspace.
- Fixed controls on a fully transparent GUI were not interactive (this is an original AGS behavior, which was unintentionally changed in 3.5.0 by mistake).

Compatibility:
- When running 3.5.0 games, treat fully transparent GUI as non-interactable.
   In AGS transparent GUIs may be still interacted with, but 3.5.0 introduced an unintentional (and undocumented) change to this, which was reverted in 3.5.1.

Android:
- Support global engine's config file when the game is run from the Launcher: it's located in the AGS games' parent directory, same place where android.cfg is.

WinSetup:
- Added "Custom game shared data path" to complement "Custom save path" option.


Changes in the Patch 5:

Contained no changes and was a formal re-release with only fixed program build instructions for Linux.


Changes in the Patch 4:

Editor:
- Fixed swapping of inventory item's numeric ID could lead to errors.
- Fixed crash when importing pre-3.* games with multiple script modules.
- Renamed "Enforce object-based scripting" setting to "Enforce post-2.62 scripting". This is for clarity.

Compiler:
- Fixed potential memory corruption when user script reaches max nested if/else blocks.

Engine:
- Also tell module name and approximate source line when reporting script import errors for the variables and local functions.


Changes in the Patch 3:

Editor:
- Fixed sprite file over 2 GB could not be loaded (regression since the last patch).

Engine:
- Further improvement to GUI perfomance: don't redraw GUI when the mouse cursor is hovering over or interacting with controls not leading to an actual visual change.
- Fixed ListBox items could become unaccessible if its font or height is changed leading to a disabled scrollbar.


Changes in the Patch 2:

Engine:
- Fixed speech lipsync getting disabled after loading another game with RunAGSGame().
- Fixed MOD/XM clips fail to play (regression).
- Fixed certain OGV videos fail to play (regression).
- Fixed software renderer was not updating game screen correctly when running a game with legacy "letterboxed" feature (regression).


Changes in the Patch 1:

Editor:
- Fixed script compiler sometimes was not specifying actual Dialog number when reporting errors in the dialog scripts.

Engine:
- Fixed Game.TranslationFilename always returning empty string (regression).
- Fixed GUI controls which were toggled from disabled to enabled state not responding to the mouse clicks until the mouse is moved (regression).
- Fixed OpenGL did not apply a Linear filter when "Render sprites in screen resolution" option is off.


What is new in 3.5.1

Editor:
- Added "Attach game data to exe" option to General Settings. This lets you to package game data separately from the game.exe (only important on Windows at the moment).
- Deprecated "Limit display mode to 16-bit" property in Runtime Setup as it's no longer used by the engine.
- Display aspect ratio in game resolution dialog.
- Implemented classic Color Picker dialog for the Color type values in the property grid, instead of the default one which does not allow user-defined colors.
- Improved tab switching performance for script windows.
- Editor will now enforce full game rebuild after upgrading an older project, this ensures that all scripts are recompiled with the new version rules.
- Fixed room lists in property editor were not updated after room number is changed.
- Fixed importing pre-3.* projects broken by incorrect assignment of "Game file name" property.
- Fixed importing Characters and GUI without sprites still created empty sprite folders.
- Fixed crash when exporting/importing Characters with no Normal View.
- Fixed translation compiler did not correctly save some of the escaped sequences, such as "\n".

Scripting:
- Implemented correct parsing of a "const string" function return type.
- Fixed implementing imported functions was forbidden in the room scripts.

Script API:
- Added GUI.Shown readonly property that tells whether GUI is active on screen. This is primarily for GUIs with "Popup At Y" style, because they hide themselves regardless of Visible property. Note that since 3.5.0 GUI.Visible only tells a script-set value.
- File.Open() now supports $CONFIGFILE$ tag which will try to open user config file for reading or writing regardless of where config is located on disk.
- Added System.SaveConfigToFile() which writes current engine settings to the user config file. Only the options that can be changed at runtime are written back at the moment.
- GetTranslation() now returns "const string" (was "string"). This is to prevent modifying returned string using old-style string functions, such as StrCat(), as this string may be allocated in the internal engine memory for its own use.

Engine:
- Support loading audio and video from data packages larger than 2 GB.
- Improved game data loading times by introducing buffered file stream. Initial tests showed 3-4 times faster file reading.
- Improved game perfomance by not reupdating all of the GUIs each time anything changes, instead only affected GUI will be updated each time.
- Some improvement to general script perfomance.
- Some improvement to script Dictionary and Set types perfomance.
- Room Object's Graphic property now can be assigned a sprite with index over 32767 and up to 65535. This restriction is due to internal data format, which cannot be fully fixed without breaking compatibility with plugin API. This may still be worked around by assigning a View, as View's frames may contain sprites of any index available.
- Similarily, Object's View, Loop and Frame can now be assigned a value over 32767 and up to 65535; not that this was ever an issue...
- Removed arbitrary limit of 1000000 dynamic array elements (now supports over 2 billion).
- Dialogs with no enabled options left will be now stopped, instead of raising script error.
- Engine will not longer quit the game when failing to write a save, but simply display an error on screen (...why this was a thing in the first place?!).
- When restoring a save engine will now try to match game pack by GUID rather than using exe/pack name. This resolves potential problems when game package may have different name in distribution to another system. Also makes saves in multi-game collections more reliable.
- In Debug game mode allow to toggle infinite FPS mode (prior it could not be turned off).
- Expanded text parser error messages for easier debugging.
- Adjusted all the command-line options to have consistent prefix convention, where all full-name options must be preceded by double-dash, and one-letter options by single dash.
- Added "--localuserconf" command and similar global config option which tells engine to read and write user config in the game's directory rather than using standard platform path. Game dir must be writeable for this to work.
- Added "--conf" command which forces engine to read only explicit config file on startup.
- Added "--user-data-dir" and "--shared-data-dir" commands for setting save game directory and shared app data directory from command line (this corresponds to existing options in config).
- Fully configurable log output (in both game config and command line) allows to set up which message types and groups are printed by which output methods (sinks), including: file, system console, in-game console. "warnings.log" is now created only if file log was not requested by user.
- Added "--log-" set of command line options for setting up log output.
- Added "--tell-filepath" option for printing known engine's and game's file locations.
- Added "--tell-gameproperties" option for printing some of the game's general settings.
More information on log config and --tell commands currently may be found in following text file: OPTIONS.md
This has to be added to the manual eventually.
- Support proper lookup for Allegro 4 library resources (such as its own config and digital MIDI patches) in the game directory.
- Engine will no longer precreate directories for common files: saves, user config, shared files and so forth, - before actually having to write these. This ensures that no new directories are created on your disk without actual need. Also this fixed a problem that could happen if someone deleted e.g. a game's save directory while game was running.
- Fixed running game from another directory by passing its relative filename as command-line argument: in this case engine was incorrectly using its own directory to search for external game data, opening files for reading by script command, and so on.
- Fixed some of the engine's own hotkeys (such windowed/fullscreen mode toggle) not working during certain skippable game states.
- Fixed overlay was set to wrong position if it were using TextWindow gui and either its text or X, Y properties got changed.
- Fixed crash occuring when the speech is using text window gui with zero Padding and the speech text is an empty line.
- Fixed characters and room objects were not updating their looks if their current graphic was a Dynamic Sprite, and that sprite was modified with ChangeCanvasSize, CopyTransparencyMask, Crop, Flip, Resize, Rotate or Tint function.
- Fixed Views' frames keeping reference to deleted Dynamic Sprites causing crashes. Now they will be reset to dummy sprite 0 for safety.
- Fixed engine crash when button's graphic is set to sprite out of range.
- Fixed animated cursor's normal graphic reappearing in between animation frames if mouse mode is being repeatedly reassigned, for example in rep-exec script.
- Fixed certain interactions did not work with GUI if it was made fully transparent.
- Fixed ListBox.FillSaveGameList() search pattern, it included files which contain save filename pattern but do not exactly match; for example: "agssave.001_".
- Fixed engine was ignoring audio files in game directory when running games which use old audio system.
- Fixed crash in Direct3D and OpenGL renderers that occured if game uses a plugin that performs software drawing on screen, and one of the rooms is smaller than the game's resolution.
- Fixed Direct3D was assigning wrong fullscreen refresh rate sometimes, slowing alt-tabbing.
- Fixed "--test" mode was lost upon restoring a save.

Engine Plugin API:
- Added IAGSEngine::GetRenderStageDesc() function which returns current render stage parameters. As of this version these parameters include 3 transformation matrixes, allowing any 3D render plugin to stay compliant to engine's scene rendering.

Compatibility:
- Fixed engine was trying to read unnecessary data when loading pre-2.72 games.
- Fixed "upscale" mode for old games (was broken in 3.5.0). Also engine will now try to detect if "upscale" mode wanted by reading old config options (if they are present).
- Fixed GUI.Visible not returning expected values for GUIs with "Popup At Y" style in pre-3.5.0 games, breaking some older games logic.
- Fixed potential buffer overflow when reading pre-3.1.0 games with old dialog script texts.
- Fixed engine was applying player's position too early when ChangeRoom was called for 2.72 and earlier games, which could result in wrong placement in the new room if the character was walking right before the transition.

Android:
- Corrected game scanning in AGS launcher, now it will work consistently with the desktop ports, and detect any compatible game data files named "*.ags" or "*.exe".

OSX:
- When looking for game files engine will no longer use hardcoded filename, will search for any compatible pack file instead.

Windows:
- Windows version of the engine now reads global configuration file. It is looked up in "%USERPROFILE%/Saved Games/Adventure Game Studio/acsetup.cfg"
- Default log file location is now also in "%USERPROFILE%/Saved Games/Adventure Game Studio".
- Added "--no-message-box" command line option to hide message boxes when alerts are raised. These messages will be still printed to log (if one is enabled).
- Added "--console-attach" command line option to try attach to the parent process's console. This is useful if you run game from command line and want to see engine's log in the console.

WinSetup:
- Fixed changing fullscreen mode from "use current desktop" to explicit resolution on save.







Thanks to everyone who contributed to and tested this version!

"If you use FOLLOW_EXACTLY, then EAGERNESS has another meaning. If you pass 0, CHARID will be drawn in front of CHARTOFOLLOW; if you pass 1, it will be drawn behind"

So it seems there IS a parameter that takes care of the drawing order.

Ah. Well, I did not remember this. It does make sense now.

From the look of the engine code, this flag will automatically set baseline to main character's baseline + 1 or -1. In the end it's all about baselines, but FollowCharacter may do these things automatically.

EDIT: to think more about this, the "shadow"'s offset may also be achieved using LockViewOffset. So combining FollowCharacter with FOLLOW_EXACTLY and LockViewOffset to position second character's sprite in certain way may result in a good behavior.

This is why for best results such things should be adjusted in the script. The FollowCharacter alone may not be perfect, as it aligns by character's origin (middle-bottom point). That already may not be suitable for shadows, which may have to be positioned lower, or centered around character's feet. Personally I would not use FollowCharacter at all, but fine tune this by positioning characters in script (in repeatedly_execute and alike).

If you prefer FollowCharacter, then shadow may have to be shifted using character.z (which is a visual-only vertical offset), but its baseline likely have to be repeatedly set to main character's baseline + YOffset.

I've never used .FollowCharacter() with FOLLOW_EXACTLY, and I'm curious: how does AGS determine which character will be drawn on top?

It's not defined by FollowCharacter, the sorting rules in AGS are always the same: they are sorted by baseline, and if baselines are equal then it's "undefined" (results depend on random factor).

(It might also be a good idea to peruse the Scripting API in the manual once, to get a general idea of the available commands )

Yes that's true, I recommend everyone learning AGS to just open a list of script commands in each category and quickly scan through it to know what it can do. Then you may have an idea what to look for when you need something.

For changing the character looks (any character) you may use Character.ChangeView. That assumes that the sprites are prepared beforehand and arranged into several Views. For example, you may have one View per shadow type (angle).

In regards to general question of creating character's looks by combining several elements, there has been a short discussion on this recently:
https://www.adventuregamestudio.co.uk/forums/index.php?topic=59912.0

Perhaps it would be best to add this information to the manual, then you could just link manual whenever this question is asked on forums.

There's one important question that I forgot about, regarding the room overlays: what should happen to a room overlay when the room changes.

Variants probably are:
* it is removed; meaning it exists so long as player is in current room.
* it is kept but is not displayed until returning to the same room; that is owned by room.
* it is kept and transferred to another room as-is. This is dangerous, as there's a real chance of loosing control over the overlay, if its pointer is only in the previous room script: then the new room has no means to control it.

NOTE: right now all overlays are removed forcefully when changing rooms, that's a standard AGS behavior.