Building AGS 4 engine on Windows (VS 2022)

[Monsieur OUXX]

EDIT - useless first post

[Monsieur OUXX]

I will use this thread to detail every step, one by one -- in the "explain it to me like I'm 5 yo" spirit.


Building

1a. Go to https://github.com/adventuregamestudio/ags
1b. (Note: we will choose the "fork" approach, not just cloning) Click on "fork" in the top right
1c. Untick "copy only the master branch" (because you want branch "ags4")
1d. Let git fork the repo to your very own https://github.com/mygitusername/ags

2a. Create a folder C:\source\ags\ags4
2b. Create a folder C:\source\ags\agslibs

3a. Install Visual Studio 2022
3b. Open VS2022. On the home page, choose "clone a repository"
3c. Repository location : Pick the path that was created earlier : https://github.com/mygitusername/ags.git (you can find it on the github page if you're not sure)
3d. Let VS clone the repo

4a. Inside VS, in the bottom-right of the window, use the dropdown to switch to branch "ags4"
4b. In the "solution Explorer" panel, open Engine.sln
4c. You might get a message from Visual Studio suggesting to let you install extra tools for C++. Let it open the "Visual Studio Installer", and install "Desktop Development with C++". Later, you can still access this with menu Tools-->Get tools and Features...

5a. Clean and rebuild the solution (right-click on the solution)
5b. Do you get error "The Windows SDK 8.1 was not found"? If yes, you need to install this set of libraries, to let your modern OS (windows 10? 11?) work with older C++ for older OS's. Google "install windows SDK 8.1 visual studio 2022". Eventually you'll find this Microsoft page : https://developer.microsoft.com/en-us/windows/downloads/sdk-archive/ Look for the windows 8.1 SDK and install it (it has an installer)

6. Restart your Visual Studio entirely (all windows) -- and even your computer, preferably.

7a. Re-open solution Engine.sln
7b. Build again
7c. Do you get error "MSB8020   The build tools for Visual Studio 2015 (Platform Toolset = 'v140') cannot be found. " ?
     If yes:
    - right-click project "Engine.App"-->"Properties"-->"Configuration Properties"-->"General"-->"Platform Toolset".
    - Click on the dropdown
    - Unfortunately, VS2022 does not let you install exactly the toolset v140. You'd need to revert to an older VS, like VS2017 if I recall.
    - Instead, choose "Visual Studio 2022 (v143)".  (Note: If it says, "not installed" then open the "Visual Studio Installer" and you'll find the toolset in tab "Individual component".)
7d. Repeat for project "Common.lib"

8a. Rebuild solution
8b. do you get error "Cannot open include file: 'crtdbg.h'" ?
      If yes:
      - It means that the projects fail to find the path to the Windows 10 SDK.
      - Check that the SDK is actually installed on your system. To do so, open the Visual Studio Installer and in tab "Individual components" look for Windows 10 SDK (any version).
      - Right-click on project "Engine.App"-->"Properties". Go to "VC++ Directories" as described here.
      - In "Include Directories", dropdown, "<Edit...>"
      - Add the folder fo your latest Windows 10 kit, for example C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0 as described here
      - REPEAT FOR PROJECT Common.lib

9a. Rebuild project Engine.App
9b. Do you get error "cannot open include file: 'stddef.h'"?
      If yes :
      - It means that yet another file from the Windows 10 SDK is in a folder where Visual Studio can't find it.
      - Similarly to previous section, add include directory to that file. for example C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\ucrt
      - REPEAT FOR PROJECT Common.ib

10a. Rebuild project Engine.App
10b. Do you get error "Cannot open include file 'SDL.h'" ?
        If yes:
       - It means that you don't have the SDL library.
       - It's time to install all the third-party libraries suggested by the AGS build instructions: SDL 2, theora, ogg, irrKlang, etc.
       - For each library, you'll need to do two steps : 1) get the source (for Visual Studio to find the important .h files) -- that's for compiling 2) get the statically-compiled libraries (.lib files) -- that's for linking
       - You don't need to install them one by one. AGS devs provide you with a ready-made package.
       - Get it from the address found here :  https://github.com/adventuregamestudio/ags/tree/master/Windows#build-requirements
         Direct link to package : https://github.com/adventuregamestudio/ags/releases/download/v.3.6.0.15/WinDevDependenciesVS.zip
         More links to more versions of the package : https://github.com/adventuregamestudio/ags/tags (each release has its own WinDevDependenciesVS.zip file)
       - Unzip WinDevDependenciesVS.zip into C:\source\ags\agslibs (you created that folder at the very beginning)
       - You now have folders such as C:\source\ags\agslibs\SDL2, C:\source\ags\agslibs\irrKlang, etc
       - Next section tells you how to use them

11a. Set include directories to the third-party libraries :
      - Right-click on project "Engine.App"-->"Properties". Go to "VC++ Directories" as described here.
      - In "Include Directories", dropdown, "<Edit...>"
      - Add the folder to SDL2's include files folder (probably C:\source\ags\agslibs\SDL2\include )
      - REPEAT FOR LIBRARY SDL_Sound  (probably  C:\source\ags\agslibs\SDL_sound\src )
      - REPEAT FOR LIBRARY irrKlang
      - REPEAT FOR LIBRARY ogg (contained in Xiph folder)

12a. Rebuild project Engine.App
      - Now the compilation step succeeds, but the next step (linking) fails with error LNK1104   cannot open file 'SDL2.lib'   
      - You need to tell VS where to find the .lib files. It's similar to the previous section, for include files.
      - Right-click on project "Engine.App"-->"Properties". Go to "Library Directories"
      - In "Library Directories", dropdown, "<Edit...>"
      - Add the folder to SDL2's lib files folder (probably C:\source\ags\agslibs\SDL2\lib\x86 ). Notice how you could have chosen folder x64, but I'm almost certain that you're compiling for 32-bits, not 64-bits.
      - REPEAT FOR LIBRARY SDL_Sound  (probably  C:\source\ags\agslibs\SDL_sound\build\Release )
      - REPEAT FOR LIBRARY Lib Ogg (contained in Xiph folder -- probably C:\source\ags\agslibs\Xiph )

13a. Rebuild project Engine.App
13b. Do you get error "LNK1104   cannot open file 'libucrtd.lib'"?
        If yes :
       - again, the Windows 10 could not be found, but this time it's not the .h files, it's the lib files.
       - Repeat steps from before, adding an entry to the "Library Directories" pointing to something like C:\Program Files (x86)\Windows Kits\10\Lib\10.0.19041.0\ucrt\x86 Notice how you could have chosen folder x64 or arm, but I'm almost certain that you're compiling for 32-bits.

12.a Rebuild project Common.lib
        At this point everything compiled fine for me, I didn't need to add more paths to additional include files or .lib files.


Trying it out

1a. In Visual Studio, right-click on project Engine.App and select "set as startup project"
1b. In Visual Studio, click button "Local windows Debugger" at the top of the screen, to run the AGS engine in debug mode.
1c. Do you get error "The code execution cannot proceed because SDL2.dll was not found" ?
      If yes:
     - It means that you need to copy SDL2.dll to the engine's execution folder.
     - the execution folder is where acwin.exe went after you built it.
     - Go to C:\source\ags\Solutions\.build\Debug and locate acwin.exe (If your build was successful, it is present in the folder, and the modified date matches your last build)
     - Get SDL2.dll from the SDl website : https://www.libsdl.org/download-2.0.php then SDL2-2.0.22-win32-x86.zip
     - put it in C:\source\ags\Solutions\.build\Debug

2a. In Visual Studio, click again on button "Local windows Debugger"
2b. do you get error "ERROR: Unable to determine game data"?
     If yes:
     - It means that the AGS engine started successfully, but has no game to run!
     - You need to obtain an AGS game (any game!). Usually they come as a .exe file, but under the hood they really are a .ags file that contains the game data, meant to be run by acwin.exe
     - If you don't have a .ags file handy, follow the next steps to create a dummy game to test.

3a. Create a dummy game data
    - Create folder C:\games\ags
    - Get the most recent version of AGS 3.x (preferably, the .zip file for convenience)
    - Open the Editor
    - Create a new game (e.g. the Sierra template)
    - Create it in C:\games\ags\testgame
    - Build the game
    - Open folder C:\games\ags\testgame\Compiled\Data
    - Observe how it now contains file testgame.ags That is your game for testing

4a. Copy testgame.ags to the engine's execution folder : C:\source\ags\Solutions\.build\Debug
4b. Tell the engine to use it at startup :
      - Right-click on project "Engine.App"-->"Properties"-->"Configuration Properties"-->"Debugging"
      - In "Command arguments", enter "C:\games\ags\testgame\Compiled\Data\testgame.ags" (leave the double quotes around it to avoid problems with white spaces in the path)

5a. In Visual Studio, click again on button "Local windows Debugger". The game shoudl run successfully!
5b. Stop the game. Open source file "main.cpp". Just after instruction "init_debug(...);", add the following line : Debug::Printf(kDbgMsg_Alert, "Hello from my modified engine");
5c. Put a breakpoint on that new line.
5d. Run the project again. It stops on the breakpoint. In Visual Studio, look at panel "Output". If you continue the execution now, you wil see "AGS: Hello from my modified engine" appear in that panel.

Success! You're running a modified version of the AGS engine, and you are able to debug it with breakpoints.


About changes

the steps above caused a change in each of the two project files ( Common.Lib.vcxproj and Engine.App.vcxproj ). I you ever decide to merge back your changes to the AGS main repo/branch, you might be asked to revert those changes:

    <PlatformToolset>v140v143</PlatformToolset>

[eri0o]

I haven't read a thing because you are adding too many steps, but around step 10 when using the VS Dependencies prebuilt, just create the props variables in your user environment variables on Windows and it should work

[Crimson Wizard]

I haven't read a thing because you are adding too many steps, but around step 10 when using the VS Dependencies prebuilt, just create the props variables in your user environment variables on Windows and it should work

Alternatively you may do this in MSVS "user macros", as mentioned in the readme:
https://docs.microsoft.com/en-us/cpp/build/working-with-project-properties?view=msvc-160#user-defined-macros
at least this worked in the previous versions of the VS, never used 2022 one.

[eri0o]

I use the environment variables because then I can sideload multiple Visual Studios and it will work

[Crimson Wizard]

I use the environment variables because then I can sideload multiple Visual Studios and it will work

Oh, these are not shared then. I did not notice that.

[eri0o]

uhm... Maybe actually they are now that I think of... But then they are not shared if you have multiple versions of ags checked simultaneously - cloned the code in more than one place.

(but I also have trouble navigating VS menus so... there's that too.)