[question] A bird's eye view of AGS Codebase

[ericoporto]

I have been wanting for a time now to write a little guide, a single page on the wiki here with a quick guide through the ags codebase. In the early days of the AGS source code release I wasn't around but looking around in ags forums it's clear people hacked around a lot their "forks" of the engine/editor, and a lot of these developments were useful for discussion and eventually evolved into things that make into the "main" code - like character facing a direction when changing room or more recently the blendmodes. With this in mind, I wanted to lower a little bit the barrier for people that want to take a shot at the code to fix that one annoying thing, even if for themselves only.

And for helping, my first thing in mind is a graph/drawing that represents a bit of the ags source code, and it can't be daunting, so some things have to be hidden. I also want the graph/drawing to be a bit change resistant, to avoid the need to update it often.

• Does the image above makes sense?
• What has to be in the image?
• What can be ommited?

Here's Godot graph approach to this question (for reference) https://docs.godotengine.org/en/stable/development/cpp/introduction_to_godot_development.html#architecture-diagram

---

also trying to come up with a description for the main directories:

main components

• Common: has components that are shared between native parts of the Editor and the Engine, and are expected to be available to the commandline Tools. They have a close relationship with the binary data formats that the Editor and the Tools have to generate and that the Engine knows how to read.
• Editor: the AGS Editor, contains both the rules of the current project format as the graphical editor used to create AGS games.
• Engine: the runtime capable of running ags games, it has to be able to interface and output graphics and sound for biggest amount of platforms as possible.
• Compiler: the ags compiler capable of transform AGS Script into AGS bytecode.
• Tools: AGS command line tools to read game project files and transform them in files that are used to build a binary AGS game.
• Plugins: Plugins that were often used in the past that were ported to be able to play old games.
• libsrc: libraries shared across different projects in the repository.

platform specifics

• Windows: Windows building instructions and code for the Editor installer.
• debian: Linux building instructions and debian packaging files.
• OSX: MacOS building instructions and specific files for shipping an .app game build.
• Android: Android building instructions and project files.
• iOS: iOS building instructions and project files.
• PSP: discontinued files to build the PSP port of the engine.

IDE and building

• Solutions: Visual Studio project files for the different parts of the codebase.
• CMake: CMake modules used for building AGS.
• Script: diverse scripts to help packaging an AGS release.
• ci: Dockerfiles used in continuous integration to create the environments to build AGS.

Edit: I noticed now I should probably add an entry on the wiki about docker and continuous integration :/

[messengerbag]

Just wanted to say that as someone who doesn't know the codebase, this does look very helpful to me. In the diagram, I'm curious about "main" and why it's separate from "AC".

[ericoporto]

"AC" means "Adventure Creator", the original 1997 name of AGS. When AGS was opensourced (I think in 2011), all the game logic of the entities was done in a twenty eight thousand lines file called ac.cpp, in the initial refactor it was created a directory called AC and it was split in smaller logical units for "entities in the engine", meaning room objects, characters, inventory items, hotspot logic, ... All this stuff today is inside of this directory, it's mostly things that are far away from metal (except sys_events.cpp). There's no AC namespace and there's nothing that strictly ties these files to each other, so other than some boilerplate in the files I am not sure how to logically tie them together.

"main" on the other hand is the entry point of the engine, so it needs to understand the things at the game "boot", meaning command line parameters, config files and game28.dta (the file that contains the initial state and config of everything, plus the global scripts and dialogs).

I may be explaining things wrong though (lots of AGS history), and I don't know how to neatly note these stuff in the graph - but maybe it's better to add a small note below. 🤔

[ivan-mogilko]

Many things in the project tree are just historical and remains of early refactoring attempt which in retrospect had number of mistakes.

For instance, "AC": the earliest code we've got from CJ contain only several files, and there was a huge ac.cpp around 30k in size, iirc. When splitting it I put most of game logic in "ac" subdir because of that. Later I started picking things out into what seemed to be more logical directory names.

The "game" subdirectory is a relatively recent addition, it contains refactored and tidied up classes and functions from "ac" related to game data. Because these were rewritten almost completely anyway I decided to also put them in an appropriately named directory. I was planning to move everything gradually to "game" as things get refactored, but it kind of halted there for now.

The "Common/core" subdirectory is a very early planning mistake, and imo should have been removed eventually. Some of its contents could go into "util", but not certain about platform and types.h There's even a stream base class (stream_api) which must be deleted later, because it's again a remains of some early idea that did not go as planned.

[ericoporto]

Added info here: https://github.com/adventuregamestudio/ags/wiki/Quick-source-code-introduction