Script API: Reform Debug() function

[ivan-mogilko]

There's a Debug() function in script, which purpose is to provide some arbitrary chosen information for diagnostic purposes. The detailed description may be found in the manual: https://adventuregamestudio.github.io/ags-manual/Globalfunctions_General.html#debug

In brief, it can do following:

1. Give all inventory.
2. Display some information about runtime engine and display mode.
3. Display room's mask on a half-translucent overlay (in older versions it displayed an opaque overlay which blocked the rest of the game).
4. Teleport to another room.
5. Toggle FPS counter.
6. Display character's current walking path.

There are 2 major issues with this function:

1. For a diagnostic script command it has a inconvenient and limiting interface, and hardcoded behavior. This makes it difficult to customize, changing the way it displays information, etc.
2. As a script command, this feature relies on game authors actually adding it to their game. This means that we cannot use this feature if we are testing/debugging a game where this command is not present in the game scripts.

Considering above makes me think that this command should not be in the script API. Instead, there are two things that may be done in parallel:

1. For a diagnostic script API, we should rather implement replacements that allow more precise information retrieval and fine tuning when displaying it. For the user convenience, some of its old behavior may be provided as script modules, or even part of the default templates.
2. For the engine's test runs, we should rather implement commands that work regardless of the game script; for instance, hotkey combinations that trigger if game is run in debug mode (--test) and display some kind of default information independent from the rest of the game logic.

---

In regards to the scripting API. If we look at existing options of Debug() function, these are available alternatives: Debug option	Alternative
Give all inventory	Trivially done by doing player.AddInventory() in a loop, iterating all inv items.
Display runtime info	There's System.RuntimeInfo for a while now, but it also relies on hardcoding a formatted string. A better option is recently added System.GetEngineString (see #2358).
Display room mask	May be done by getting a mask as a DrawingSurface, e.g. see GetDrawingSurfaceForWalkableArea, and painting that on an overlay. Perhaps a more direct option may be implemented as well.
Teleport to another room.	Teleport itself is trivial player.ChangeRoom() command, but we're lacking a way to give a list of room names in script. A workaround is to hardcode array of room names in a global script instead, but this is less convenient.
Toggle FPS counter.	None directly (but there's a command-line arg), yet FPS numbers may be retrieved using System.GetEngineInteger (see #2358).
Display character's current walking path.	None (a solution may be related to #1979).

[ericoporto]

The toggle fps counter is my most used feature probably ever, I would be glad if this function is not removed from script as it's very convenient to throw in a Debug(4, 1); in game_start, I use it so much I know it's numbers by heart. I use zero of other things, so I don't care about the rest, but I really think a script api function to show the fps counter is useful.

[ivan-mogilko]

Alright, I guess this suggestion may be expanded to 3 things:

1. Provide a low-level api for retrieval of diagnostic information. An existing example is System.GetEngineInteger.
2. Provide a convenience api for displaying diagnostic information in a default hardcoded way. For this I propose to replace Debug(n,n) with something more explicit, for example: System.DisplayFPS.
3. Provide a hotkey for the engine to be able to toggle this default info display, which works even if the game does not have anything scripted.

[ericoporto]

but we're lacking a way to give a list of room names in script

Uhm, random idea, have a way to retrieve a dict with all room numbers as keys and names as values - room numbers don't have to be consecutive so they won't work in an array. Something like Game.GetRoomsAsDict().

Other option would be Game.GetRoomName(int n) and have it return null if the room doesn't exist, but it's not clear up to which number to test since RoomCount wouldn't make sense.