AGS: an adventure game engine where the branch plan is the compatibility policy

An engine older than most of its users

Adventure Game Studio is described as the IDE and the engine meant for creating and running videogames of the adventure, or quest, genre. The history in the README is short and gives the project its character: it was created by Chris Jones back in 1999, open-sourced in 2011, and has been developed by contributors ever since.

That age is an asset in one way and a constraint in another. A tool that has been in continuous use for more than two decades has a settled workflow, a large body of finished games to look at, and a community that still produces them. The AGS website carries the forums, the games and the downloads, and the latest stable editor is distributed from there.

The licence is the Artistic License 2.0, and it covers both the Editor and the Engine, with the details in License.txt in the repository. The repository listing records it as a custom licence that GitHub cannot classify, which is a common outcome for that particular licence and is not a warning sign in itself.

The platform split is the first practical fact. The runtime engine is cross-platform, but the README is explicit that AGS Editor is only supported on MS Windows and on Windows emulators such as WINE. Someone producing a game for Linux, macOS or a phone writes the game on Windows.

The release history shows the project is very much alive. The listed tags are v3.6.3.15 as release candidate 4 on 2026-09-23, v3.6.3.14 as release candidate 3 on 2026-09-12, and v4.0.0.30 as AGS 4.0 alpha 34 on 2026-09-09, with the last push on 2026-10-20. Two generations are being released in parallel, which is unusual and worth understanding before you choose one.

Which branch you build on decides what is supported

The branches and releases section of the README is the most useful documentation in the project, and it answers a question that most engines leave vague: which code will still work in a year.

The master branch is where the next planned version is developed, and it may temporarily contain unstable or untested code. It currently corresponds to the 3.x generation and maintains backward compatibility with previous releases. According to the current plans, that branch should only receive improvements to the backend, system support and performance, with changes to data formats and game script kept to a strict minimum necessary to fill critical gaps.

The ags4 branch is where a future AGS 4.0 is developed, with greater changes and much of the old version support cut. The plan is that master will eventually be merged with ags4, with the backward compatible generation remaining as the ags3 branch, receiving only fixes and minor enhancements. The README is honest that there is still work to do in the 3.x line, so the exact moment of that merge is unknown.

Official releases get their own release-X.X.X branches, used to prepare the final code and to carry patches afterwards. And there is a constraint worth reading twice: because of the low number of active developers, the project tends to update only the one latest release branch, and if a bug is found in an older version, the advice is to update to the latest version first.

The consequence for a user is sharp. The master branch may contain changes to the game data format and new script functions, and the project cannot guarantee those will remain unchanged until the actual release. Only data formats and script APIs that are in published releases are supported, so if you want to make a game with this tool, the advice is to use one of the actual releases rather than a branch. That is a stronger guarantee than most engines give, and it is the reason the release-candidate tags matter here.

The runtime builds for seven platforms, and the Editor for one

The building and running section lists a platform-specific set of instructions, and the spread is a good advertisement for the engine.

There is a centralised CMake build, described in CMAKE.md, and then per platform directories for Android, iOS, Linux with a debian directory, Mac OS X, Windows, and an Emscripten web port. The PSP port is listed separately as no longer actively supported but possibly working with older code revisions, and there is a forum thread linked for each of the supported ones.

The directory listing in the repository matches that structure, with the platform directories sitting alongside the actual code: Editor/, Engine/, Common/, Compiler/, Script/, Plugins/, Tools/, Solutions/ and libsrc/, plus the CMake support directories and the ci/ folder. There is a version.json, an OPTIONS.md, a Changes.txt and a Copyright.txt at the root.

How you run a finished game is simple, and deliberately so. On desktop systems you either place the engine executable in the same directory as the game data and start it, or you pass the game location as a command line argument. On Android there is a game launcher app that may run any game, and it is also possible to build a signed APK for your own game.

Configuration lives in one file, and the README names it:

acsetup.cfg

On Windows you can also invoke a setup dialog by running the engine with the setup argument, and the list of configuration options and command line arguments is in OPTIONS.md. That is a small but pleasant design for a portable engine, where the same binary and one configuration file have to carry a game to another machine.

Old games, save files and plugins are where compatibility bites

The AGS game compatibility section is a careful document, and it is worth reading rather than skimming because it describes behaviour that will otherwise surprise you.

The third generation, which is what master and ags3 hold, supports importing and running all versions of AGS games made with AGS 2.50 and up, with the caveat that there may still be compatibility issues with very old games that were not uncovered and fixed yet. If you try to run an unsupported game, you get an error message reporting the original version of AGS it was made in and the data format index, which is useful when reporting a problem, and it is a much better failure mode than a crash.

Save files have a rule that is easy to miss. They are compatible between platforms only if they were created with the same version of the engine. The latest 3.x engine should normally read saves made by the 3.2.0 engine and above, but the README notes that this has not been tested for a while. In other words, saves are compatible across platforms only when the engine version matches, and reading older saves is best effort.

Plugins are the third constraint. Certain games require engine plugins, and if there is no plugin version for a particular platform, or no platform-independent replacement, the game will not load on that platform at all. That is a distribution decision with a hard technical consequence, and it is the kind of thing that decides whether a project can ship a Mac or Linux build at all.

Taken together, these rules describe a system with a broad import surface and a narrower sharing surface, which is a reasonable trade for a twenty-five-year-old file format and a genuinely useful thing to know before you plan a multi-platform release.

The SDL2 backend took away AVI and MPG playback

One change deserves its own section because it is a silent behaviour difference that can ruin an old game without any error message.

As of AGS 3.6.0, the Windows engine no longer supports playing AVI or MPG videos. The reason is given precisely: the decision was made while moving to a new SDL2 backend, because the old implementation was based on the DirectShow interface, which is Windows-only, and relied on codecs installed on the player's system. Other ports never supported these formats at all.

So the change is a side effect of a backend migration rather than a feature decision, and the consequence is asymmetric. On Windows a game that used to play an AVI now skips it, and on other platforms nothing changes, because those ports never played them.

The workaround is documented, and it has a sharp edge. You convert the avi or mpg file to OGV while keeping the full original filename, including the extension, and the engine then opens that file with its integrated OGV player instead.

There is a second, structural consequence in the same paragraph: the new backend no longer depends on codecs installed on the player's system. That is the right trade for a game you want to run on a machine you do not control, and it is the reason a video that used to play on Windows may now be skipped unless it is converted.

For anyone maintaining an older AGS title, this is the single change to check before shipping on 3.6 or later.

AGS 4 is a different bet, and it is still an alpha

The fourth generation lives on the ags4 branch, and its compatibility rules are narrower and its stability lower.

It formally supports importing games made with AGS 3.4.1 and above, but only if those games do not use any legacy features, which is a much smaller compatibility surface than the 2.50-and-up promise of the 3.x line. The 4.x engine should be able to read saves made with the 3.5.0 engine and above.

The release history shows where it stands: v4.0.0.30, labelled AGS 4.0 alpha 34, published on 2026-09-09, alongside the 3.6.3 release candidates. An alpha that has reached the thirties is an active alpha, and the two are being shipped in parallel, which suggests the project is trying to give existing users a maintained 3.x while the new generation matures.

The plan, as the README describes it, is that master will be merged with ags4 at some point, and the backward compatible generation will survive as the ags3 branch with fixes and minor enhancements only. The unknown is when, because there is still work to do in the 3.x line.

So the decision for a new project has two axes. If you are maintaining an existing AGS 3 game, take the latest 3.x release branch, because that is what the active developers patch, and because the compatibility promises are broad and documented. If you are starting something new and want the future version, ags4 is the branch to watch, accepting the narrower import rules, the alpha status and the absence of any promise about when the two lines merge.

One thing applies to both: the project supports only what is in published releases, so pin a release rather than a branch and keep a copy of the engine you built with.

Editorial conclusion

Adopt AGS if you are making an adventure game and want an established script-and-scene workflow with a runtime that ships for Windows, Linux, macOS, Android, iOS and the browser. Do not adopt it if you need an editor that runs natively outside Windows, because the README is explicit that the editor is Windows only, and do not build on the master branch if you intend to release, because the project says data formats and script APIs there may change. Before you commit, pick a published release rather than a branch, because only published releases are supported, and read the compatibility section for your target AGS version, particularly the save file rules and the video format change in 3.6.0.

Frequently asked questions

Official sources

1. adventuregamestudio/ags on GitHub
2. Issues
3. README
4. Releases