Merge branch 'twhl-community:master' into nonfunctional-angelscript

.github/workflows/ci-cd.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: recursive
 
@@ -46,7 +46,7 @@ jobs:
         run: cmake --install ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: Linux-x86
           path: ${{env.GAME_NAME}}
@@ -56,7 +56,7 @@ jobs:
     runs-on: windows-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: recursive
 
@@ -81,7 +81,7 @@ jobs:
         run: cmake --install ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: Win32
           path: ${{env.GAME_NAME}}

BUILDING.md

@@ -1,13 +1,13 @@
 # Building this SDK
 
-This tutorial expects a strong grasp of the basics of command line interfaces, version control, build systems (CMake, Visual Studio, Makefiles) and C++.
+This tutorial expects a strong grasp of of C++, build systems like Visual Studio or Make (depending on the platform you're developing for), CMake, command line interfaces, version control systems (Git in particular) and package managers (vcpkg in particular).
 
 All instructions for Linux development are written to apply to Ubuntu. Substitute commands and actions as needed for your distribution. It is expected that you understand how to work with the Linux terminal and command line.
 
 ## Minimum requirements
 
 The minimum requirements for this project are:
-* [CMake 3.23 or newer](https://cmake.org/download/)
+* [CMake 3.23 or newer](https://cmake.org/download/) (**Note**: avoid versions 3.28 and 3.28.1 as they fail to download vcpkg dependencies. See [this](https://github.com/microsoft/vcpkg/issues/33904) issue for more information)
 
 ### For Windows development
 
@@ -21,7 +21,7 @@ The minimum requirements for this project are:
         * C++ profiling tools
         * Windows 10 SDK (select the latest version)
 
-Note: vcpkg uses the latest version of Visual Studio installed on your system to compile dependencies. Using an older version of Visual Studio to compile the SDK itself may cause compiler errors.
+> **Note**: vcpkg uses the latest version of Visual Studio installed on your system to compile dependencies. Using an older version of Visual Studio to compile the SDK itself may cause compiler errors. Always use the latest installed version of Visual Studio to build the SDK.
 
 ### For Linux development
 
@@ -39,13 +39,13 @@ Clone the repository. Since it uses submodules you will need to make sure they a
 The following git command will clone the repository with submodules into the directory `<current_dir>/halflife-unified-sdk`:
 ```sh
 cd path/to/where/you/want/source/code
-git clone --recurse-submodules https://github.com/SamVanheer/halflife-unified-sdk.git
+git clone --recurse-submodules https://github.com/twhl-community/halflife-unified-sdk.git
 ```
 
 It is recommended to put the source code directory in a directory of its own:
 ```sh
 cd path/to/directory/halflife-unified-sdk_dev
-git clone --recurse-submodules https://github.com/SamVanheer/halflife-unified-sdk.git
+git clone --recurse-submodules https://github.com/twhl-community/halflife-unified-sdk.git
 ```
 
 This makes it easier to group related directories and files together.

CMakeLists.txt

@@ -110,8 +110,11 @@ function(set_common_properties TARGET_NAME)
 		$<$<CXX_COMPILER_ID:Clang,AppleClang,GNU>:-fpermissive -fno-strict-aliasing -Wno-invalid-offsetof -march=pentium-m -mfpmath=387>
 
 		# flifetime-dse=1 is needed to disable a compiler optimization that optimizes out std::memset calls in CBaseEntity::operator new
-		# See https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-flifetime-dse for more information about the flifetime-dse flag
-		$<$<CXX_COMPILER_ID:GNU>:-flifetime-dse=1>
+		# See https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-flifetime-dse for more information about this flag
+		# fno-gnu-unique is needed to disable a compiler optimization that prevents dlclose from unloading mod dlls,
+		# causing them to retain state and crash when the engine tries to access memory in an invalid way
+		# See https://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#index-fno-gnu-unique for more information about this flag
+		$<$<CXX_COMPILER_ID:GNU>:-flifetime-dse=1 -fno-gnu-unique>
 
 		# Can't set warning level to W4 until the compiler can deal with std::visit containing static_assert, which currently causes false positive "Unreachable code" warnings
 		$<$<CXX_COMPILER_ID:MSVC>:/W3 /MP>

DEVELOPING.md

@@ -1,21 +1,30 @@
-# **Note**: The Unified SDK is still in development and not ready for use beyond alpha testing and feedback.
-
 # Developing with the Unified SDK
 
 ## Prerequisite knowledge
 
-You will need a working knowledge of command line interfaces, CMake and C++ to make a mod with this SDK.
+You will need a strong grasp of of C++, build systems like Visual Studio or Make (depending on the platform you're developing for), CMake, command line interfaces, version control systems (Git in particular) and package managers (vcpkg in particular).
 
 Various configuration files use JSON so an understanding of its syntax is recommended.
 
 Tools and scripts are written in C# so you will need to have an understanding of its syntax to modify them.
 
+This project uses vcpkg in manifest mode to acquire most third party dependencies, with the exception of dependencies shipped with the game itself (vgui1 and SDL2). You should use vcpkg to add any dependencies you need. If a dependency is not provided by vcpkg's own registry you can add it to the local filesystem registry in `vcpkg-configuration.json`.
+
+Note that the OpenAL library is a custom build that renames the dynamic library name to avoid conflicting with the engine's use of OpenAL on Linux. If you update OpenAL you must also update the patch used to rename the library.
+
+Also note that Github Actions performs a shallow clone of the vcpkg repository. When updating vcpkg make sure all dependencies are using the latest version, otherwise Github Actions will fail to locate the package information.
+
+You can use the local registry to reference an older version by copying the older version package definition from the vcpkg registry to the local registry, but do make note of transitive dependencies to avoid using multiple conflicting versions of the same package (e.g. `spdlog` references `fmtlib` which this project also directly references).
+
+Consult the vcpkg documentation before changing anything to ensure you understand how it works and how your changes will affect the project.
+
 Resources to learn these things:
 * [Command line](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/windows-commands)
 * [CMake](https://cliutils.gitlab.io/modern-cmake/)
 * [C++](https://www.learncpp.com/)
 * [C#](https://learn.microsoft.com/en-us/dotnet/csharp/)
 * [JSON](https://www.w3schools.com/js/js_json_syntax.asp)
+* [vcpkg](https://vcpkg.io/en/getting-started)
 
 > **Make sure to learn these things first so you understand how this SDK works!**
 
@@ -70,3 +79,9 @@ Original maps can't be redistributed, and changes made to SDK code require chang
 The [MapUpgrader](docs/tools/map-upgrader.md) tool is a standalone version of the installer's map upgrade functionality. It can be used to upgrade a map to the Unified SDK, provided that the map was made for the original version of Half-Life and not another mod or game.
 
 Most modders won't need to use these tools, but they are there to streamline the development process as much as possible.
+
+### Special note about Half-Life Uplink maps
+
+The Half-Life Uplink demo isn't available on Steam so the maps are included with the Unified SDK's mod installation.
+
+When packaging the installation the packager looks in the mod directory named `valve_uplink` for the Uplink maps. You will need to take the Uplink maps and place them in `valve_uplink/maps` for this to work.