AGS 4 refactor/rewrite master ticket

[ghost]

Following is a rough outline of the major things that need to be rewritten/refactored in AGS 4.0. The purpose of this list is to bring attention to significant issues.

Other ideas could be added in comments. But if something is not mentioned here that does not mean you cannot refactor it.

If you are currently planning on starting refactor over a (relatively) large piece of code, please either comment below or open an issue to let other devepers know. Please, do not hesitate to ask questions, or discuss better course of code change, AGS code is rather twisted one, and we'd want to go into one direction when cleaning it out.

---

Plugin API

• Remove all parts of API that allow direct access to the engine's memory (game data structs). If we want to keep the main Engine interface compatible with the few popular plugins for the time being, then we cannot delete interface functions, but we may disable them (make them return NULL or throw "unsupported"/"deprecated" exception).
• Redesign Plugin API to allow more freedom in customizing it in the future. There should not be any direct memory access to neither data or script functions.
• Ideally, plugins should be able to use Script API through same safe mechanism as interpreter currently does (this might mean that interpreter's script function handling also has to be modified to achieve mutually convenient design).

---

Script API

• There is still a bunch of data exported to script as raw variables instead of properties. We do have a potential way to handle this safely (see this topic in wiki), but this is inconvenient and serves only as the last measure (and to support legacy script). I believe each of these variables should be substituted by a property. (If legacy support will be added back sometime, it will remap variables to these). For example, see global variables such as "game" in script API, - that one has a lot of variables in it.
• Remove legacy audio system and make sure new one is consistent, convenient and covers all use cases from old one.

---

Game objects

• AGS features number of game types exposed to script (Character, etc) using managed pool system, where game objects are registered and their number of references counted. For historical reasons most of game types have 2 or even 3 separate classes in code that represent them, one for internal game logic (characters have 2, because of plugin API) and 1 or 2 for the script export. This situation is explained on the wiki page. Ideally we'd have one class per game object, that handles both internal logic and script link. Such object should be reference counted (number of references changed when object is assigned to pointers in script), and if the game restricts object from deletion, it would take 1 extra fixed reference for itself. Achieving this would bring us close to creating game objects in script at runtime.
• Make number of game objects unrestricted.

---

Code structure

• Need to better separate code between "Game Logic" and "Engine/System" domains. IMHO we should aim to have engine data and update loop independent of game's, which may allow to, for example, safely fallback in case of any unhandled game's error and let restore last saved game without relaunching the program. Similar to how emulators and virtual machines may run and change games on fly (even if we won't have that as a feature).
• Probably there should be Engine class which groups data related strictly to the engine, and manages necessary utilities (runs script interpreter, etc), System class that provides backend utilities (currently known as IPlatformDriver), and Game class, that runs the game and connects to everything else game-related.
• Separate "game speed" (the time at which minimal animation update takes place), script update event speed and render event speed, and let game creator set all three these.

[monkey0506]

@rofl0r while many of the things that were implemented as plugins prior to AGS becoming open-source are within the scope of the engine, not all plugins are appropriate for inclusion in the engine's codebase. Namely, AGSteam (Steam API), AGSGalaxy (GOG Galaxy API), and ags2clientstub (stub for both AGSteam and AGSGalaxy) should not be merged into the engine, IMO. It represents an entirely separate array of issues if there are changes in the Steam or Galaxy APIs which I feel go well beyond the scope of the engine developers/maintainers.

Granted, that's just one very specific example, but in order for those plugins to function, there has to be some interoperability between the game engine and the external API libraries. These plugins don't need much functionality directly from the engine (primarily just access to the game loop and key press events (game loop is simulated by the final screen draw event), but the game scripts have to be able to call arbitrary code to set achievements or get leaderboard info, for example.

[ivan-mogilko]

I shall close this, as the issue is stalling. It was really just a rough starting draft. Some things mentioned in the ticket have been accomplished, others are planned and have their respective issues opened or recorded in wiki, few things are maybe not interesting anymore.