Engine executes post-script action before finishing running callback in all modules

[ivan-mogilko]

Problem
Within AGS script there are several commands that change overall game state drastically, and these are not executed instantly when met in script, but scheduled to be executed after current script callback finishes and returns control to the engine. Examples are: ChangeRoom, RestoreGameSlot, and few more.

However, it became apparent that these commands are still executed too early if engine is processing same callback in multiple script modules. Instead of waiting until all module callbacks are called, the scheduled commands are executed as soon as the latest callback has returned to the engine.

For example, if there's on_mouse_click in two or more script modules, and the first module's callback results in ChangeRoom call, then ChangeRoom will be executed right after first callback, a new room is loaded, but then engine continues processing callbacks in remaining modules with the same parameters, which does not make much sense anymore because the room has changed.
This can potentially lead to various obscure bugs in the game, as callback function from first modules will be run in the old room and callbacks from other modules will be run in the new room.

The reason this problem was not documented earlier is probably that it's not easy to realize, as the game must have particular setup to cause noticeable errors.

Real-life example on forums: https://www.adventuregamestudio.co.uk/forums/index.php?topic=58479.msg636629836

AGS Version
Probably, any known version. Was tested in 3.5.0.

To Reproduce

1. Start with the new blank game.
2. Create 2 rooms (number 1 and 2), and import some backgrounds to be able to visually distinct them.
3. Make sure there are at least 2 script modules, for example, GlobalScript and CustomModule above it.
4. Put following script into CustomModule.asc:

function on_key_press(eKeyCode key) {
    if (key == eKeySpace) {
        player.ChangeRoom(2);
    }
}

5. Put following script into GlobalScript.asc:

function on_key_press(eKeyCode key) {
    if (key == eKeySpace) {
        DrawingSurface* ds = Room.GetDrawingSurfaceForBackground();
        ds.DrawingColor = 10;
        ds.DrawRectangle(0, 0, 100, 100);
        ds.Release();
    }
}

6. Now run the game and press Space key. You may be expecting that the rectangle will be drawn in the first room and then game goes to room 2, but what happens is: game goes to room 2 and draws rectangle there.

Expected behavior
I believe that the scheduled post-script actions, such as ChangeRoom, must be postponed to run only after current callback was run in all the modules. What engine is currently doing may result in an unpredictable script behavior.

Alternate solution
If engine finds the scheduled event like above, it also runs ClaimEvent after script callback... but I'm not sure if it's going to be a reliable solution.

[ericoporto]

I believe this is something that is better to change in ags4 since this is easier to change breaking backwards compatibility.

[ivan-mogilko]

Labeled for ags4 instead. In addition to this problem, there are also related issues in the event system design. For instance, it's currently impossible to implement "dialog start" event, as dialog is starting immediately after current callback is finished, so there is no time left to execute anything else in between. I think it's worth to review the script event/callback design in ags4.