Compiling AGS

Revision as of 09:06, 4 August 2022 by Monsieur'ouxx (talk | contribs) (→‎Introduction)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

(last update : mid-2021 : that is AGS 3.6.x)


Hello! Do you know what you're doing?

- Yes, I've already compiled one of AGS' components in the past (Engine in C++, Editor in c#, etc.). => Skip to "Getting started for each system".

- No, I need a bit of context to get me started => Keep reading "Introduction" below.

Introduction

If you're a game designer, you should never have to "build" AGS. All you want is to use the Editor to make the game (and compile your AGS scripts if you have any), then use the Engine to play it (you won't even notice that you're using the engine, as your game gets compiled into a neat little executable file).

Even if you have some very specific needs then you might want to program an Editor plugin or an Engine plugin. But you can just build that plugin on its own, without rebuilding the entire AGS source code (that's precisely why plugins were invented).


You'll want to rebuild AGS' sources (either the Editor in C# or the Engine in C++) only for two potential reasons:

  • You want to know very accurately how it works inside (e.g. because the plugin you're currently developing is rather complex and you don't know very well how to make it work with AGS built-in features)

OR

  • You want to implement new features into AGS itself, as a contributor to AGS, which is an open-sourced project. For example, you've decided to fix a bug from the tracker, or you're one of those coding wizards who are able to port the entire engine to a new platform.

Now that you know all that, here is how you get the AGS source code (Editor or Engine), and how you compile it.

AGS background

Once upon a time, there was a free piece of software called AGS, which was created and then maintained by only one man: Chris Jones, a.k.a. Pumaman on the AGS forums. This lasted for over 15 years. The source code was not open. Then, in 2012, AGS got open-sourced. Anyone could contribute. Even though the code was pretty damn good considering it had been maintained by only one guy for a decade and had lived through many technologies (DOS, Windows, complete refactoring of the Editor, etc.), some parts of it had become what one could call "spaghetti code".

In particular, some parts of the project, the "Native" parts, that were in charge of some low-level tasks (written in C++), were tightly linked to the VisualC9 libraries (the ones shipped with Visual Studio 2008, if you want to know). For several years after 2012, that bond was too intricate to be removed easily. The new support team was keeping that in a separate DLL, called "Native.dll".

Now in 2021 this isn't a problem any more. You can compile any part of AGS with your favorite compiler or IDE. But the Native project is more annoying than the others. Skip it if you don't absolutely need to modify it.

AGS is actually several projects

If you get the AGS sources and go to the /Solutions/ subfolder, you'll find the following solutions:

  • AGS.Editor.NoNative.sln - That's only the high-level, C# part of the Editor, which does most of the work.
  • AGS.Editor.Full.sln - That's the full Editor project, including the Native project (in C++) to build Native.dll.
  • AGS.Engine.sln - That's the AGS game engine in C++ (the one that actually plays the game).

Getting the sources

AGS source code is currently hosted on a git repository, on github : http://github.com/adventuregamestudio/ags You need to be familiar with git concepts to get the code, and then commit it back if you want to share your changes.

In a nutshell:

  • Install any kind of git client onto your machine. For example, if you use Visual Studio, there are some extensions that allow you to connect to a git repository directly from within the IDE. Otherwise, you can use any client you wish : https://git-scm.com/downloads/guis
  • Use this client to clone the ags repository onto your machine. You can get the connection string from the github website, on the right-hand side of the screen, under "HTTPS clone URL" : https://github.com/adventuregamestudio/ags.git
  • Wait for the cloning (download) to complete and then open one of the solution files mentionned in the previous section. For a start, I recommend the easier one : AGS.Editor.NoNative.sln

Get started for each system

Windows

  • Get the source code, as described in the previous section.
  • Get the free version of Visual Studio : Visual Studio Community 2019.
  • AGS.Editor.NoNative.sln - That's only the high-level, C# part of the Editor, which does most of the work.
  • You'll need to get the latest Native.dll file, already compiled.
- If you have a recent AGS already installed, you can take it from the regular Editor. Otherwise, download it from the AGS page.
- If you need a really, really recent Native.dll (nightly build?) then go to the forums (AGS Development --> Editor Development) and download the alpha version you need.
- Native.dll is the only file you need to continue. Put it in any folder of your choice.
  • Open the .sln file with Visual Studio. Expand the "AGSEditor" project, then expand "References". Remove the reference to "Native.dll", then add it again (right-click-->Add Reference...) and use the "browse" button to point to your Native.dll file.
  • Follow extra instructions from the readme : https://github.com/adventuregamestudio/ags/tree/master/Windows#building-ags-editor
  • If you still have issues, go to the forums (AGS Development --> Editor Development) and see if there is a recent thread devoted to compiling the Editor. Or try any thread about the latest unstable version of AGS.


  • AGS.Editor.Full.sln - That's the full Editor solution, including the project that generates Native.dll.
  • When you try to compile C++ (and the dev didn't think it through), the compiler might need you to provide a very specific version of the standard libraries. In the Visual Studio world that's called a C++ Toolset.
  • The issue with the Native project was that it absolutely required the VisualC9 toolset. That's the one that was coming with exactly Visual Studio 2008 SP1
  • In the past you couldn't use use the free ("Express") versions because in that version you can't change the toolset. There was no "General" -> "Platform Toolset" setting. You needed to use the real VS 2008 SP1.
  • Now in 2021 I think you can switch the toolset in the free Visual Studio Community 2019 .Google : "Visual Studio MSDN how to modify the target framework" (I didn't test it). And of course you need to download the VisualC9 toolset first. Use Google : "Visual Studio 2008 SP1" download.
  • Follow extra instructions from the readme : https://github.com/adventuregamestudio/ags/tree/master/Windows#building-ags-engine
  • If you still have issues, go to the forums (AGS Development --> Engine Development) and see if there is a recent thread devoted to compiling the Engine. Or try any thread about the latest unstable version of AGS.
  • AGS.Engine.sln - That's the AGS game engine (the one that actually plays the game).
  • Follow instructions from the readme : https://github.com/adventuregamestudio/ags/tree/master/Windows#building-ags-engine
  • ABOUT LIBRARIES: The readme provides a link to download the pre-compiled libraries but it's an old link. Ask on the forums to get a more recent libraries package containing SDL_sound.lib, etc.
  • If you still have issues, go to the forums (AGS Development --> Engine Development) and see if there is a recent thread devoted to compiling the Engine. Or try any thread about the latest unstable version of AGS.

Linux

You will find a lot of information in the Readme file in the git repository: http://github.com/adventuregamestudio/ags

MacOS

See the dedicated thread in the forums

Android

See the dedicated thread in the forums.