Making this repo more accessible and acknowledged

[FreeSlave]

Recently we had a discussion on FWGS discord servers about how we make this repo more popular among mod makers. While this repo contains source codes for a lot of mods that might be useful to mod-makers, it's still not well-known among common crowd and mostly used by Linux/Xash3D enthusiasts.

I propose the following steps:

• Change the name. hlsdk-xash3d sounds like it's exclusively for xash3d. It's not true for long since the time GoldSource input support was added to the client and VGUI has got returned. @nekonomicon suggested it should be called hlsdk-portable. I like this as it emphasizes on the strength of this hlsdk version.
• The README.md and the repo description must be clear about the goal of this hlsdk (be portable across engines and platforms and provide mods implementations).
• Build with GoldSource support by default. Minus one explicit action by a user in most cases. The only downside is that you must have SDL2 dev headers installed on Linux. Also those who are not interested in GoldSource input support, will need to turn it off themselves.
• Provide better build instructions. Android build instructions are missing, Windows ones are outdated. There are many mod-makers that are not programmers and they just want to change a small thing, like a HUD color, which doesn't require programmer's skills, so the main problem for them would be building. We must decide what is the best way for a typical user to build libraries (via cmake or waf) and write more detailed instructions accordingly (with direct links to cmake/python websites). Keep in mind that the majority of users are Windows users. Details about msbuild must be provided too. Probably instuctions should be moved to the Wiki as README.md is gonna be too bloated with all these details.
• Maybe we should provide Visual Studio projects, but considering there are different VS versions, it's probably better to stick to cmake. It has GUI on Windows and becomes more acknowledged among Windows users. Also adding another build system is going to lead to more maintanence costs.

How this repo should be advertised (a selling point):

• Portable. Among engines (GoldSource and Xash3D, both original Xash3D one and Xash3D FWGS) and among platforms.
• A lot of mods re-implemented. The universal codebase as each mod is a branch.
• Ready-to-use automated builds for mods (including user's mods if they're gonna fork the repo).
• A lot of fixed bugs. Probably we need make a list and place it somewhere, e.g. on repo Wiki page.

Probably we should make it more clear that automated builds won't work on Windows-XP. I can add a manual workflow that would allow building with msvc6. That means however that we have to support compile.bat as a build-system. Or come up with something better.

Also a manual build (or an automated one) for Android should be added. But it's really up to how well Android is gonna be supported in the new xash3d version, so we can get to it later (as well as to Android build instructions).

Other bits:

• I would like to rename .github/workflows/.github.yml to .github/workflows/build.yml. I didn't think it through when I was adding it, but it does not make much sense to have a hidden file in the hidden directory.
• I would like to rename utils/false_vgui to utils/fake_vgui just for grammatical correctness and clearer purpose.

Roadmap

I can write better instructions for Windows. Then instructions must be moved to Wiki. Note that currently I don't have rights for to modify Wiki.

Make it built with GoldSource input support by default. Again, I can do that, just need a confirmation.

Someone with proper rights can change the name and the description. Proposed description:

Portable Half-Life SDK. GoldSource and Xash3D. Crossplatform.

Wiki must be created with following pages:

• Home
• Build instructions for Windows
• Build instructions for Linux
• Build instructions for Android (when we figure out what to do with it)
• Build instructions on other platforms (e.g. FreeBSD. Can be done later as it's not so important)
• Build flags (with or without VGUI, with or without GoldSource input. Maybe building for x64)
• List of hlsdk bugfixes
• Building mods (also can feature the list of mods and the current state of each one)
• Forking this repo

[nekonomicon]

Maybe we should provide Visual Studio projects, but considering there are different VS versions, it's probably better to stick to cmake. It has GUI on Windows and becomes more acknowledged among Windows users. Also adding another build system is going to lead to more maintanence costs.

Really only cmake needed and may be compile.bat for msvc6.

Make it built with GoldSource input support by default. Again, I can do that, just need a confirmation.

By default for x86 windows and linux. And probably need to build with proprietary vgui by default for this platforms.

Wiki must be created with following pages:

We have mirror on https://git.mentality.rip. How migrate wiki to other resource? And need to have normal porting guide for mods on an old HLSDK versions.

I would like to rename utils/false_vgui to utils/fake_vgui just for grammatical correctness and clearer purpose.

@mittorn said, there probably will work an old behavior if swap bytes in structure.

[solidi]

Hi, mod maker here working on a retro-mod called Cold Ice Remastered. This ticket caught my eye because I had previously researched how to build for xash3d. My primary motivation is to port the mod to the xash3d Android app to make it fully playable on mobile.

I understand I need to build libraries specific to the architecture of the phones, and this is where the SDK will help but does not provide information on how to build for Android. My mod already works on PC/Desktop i386/Linux out of the box on xash3d desktop. The game libs that are being loaded are currently built on GitHub workflow for all architectures provided - see Cold Ice Remastered workflows here.

At this time, Cold Ice Remastered on xash3d will not load completely on Android because the mod game libs are not present for the target architecture, and I am left searching for how to specifically make for them while keeping the mod on the standard SDK. I have gone as far as investigating community attempts at it, specifically Expanded-arsenal but haven't fought through the compilation because it's genuinely a significant time investment.

It would be helpful to show an example of how to build Android in a GitHub workflow that generates the arm so libs as required for the Android architecture in this SDK, but at this time, I do not see it, and assume there is a crosslink here but no workflow either. I know Android needs specific SDK artifacts (building against NDK) and a specific toolchain that would take effort to get arranged in a pipeline. Still, if that's created here, it would give me some clues on how to port it to my mod - and specifically build the libs so the mod plays well on Android.

What is not clear to me at this time is if I also need to fork this SDK, in addition to the work being performed in the standard GitHub SDK provided by Valve. I'll assume it is not necessary and that there is some way to build the Valve Linux so libs that I am now, but target Android to load on xash3d app ok. But I may have this wrong.

So my goal checklist is the following:

1. Find a pipeline that is already building the android libs necessary on GitHub workflow for android from Valves standard SDK, or from this SDK.
2. Integrate that target building into my game lib repo as android.yaml
3. Integrate these so lib artifacts into the asset package pipeline for Cold Ice Remastered, so that those that wish to load on Android, can.
4. Somehow do the same as I did above for the game libs, to my bot lib.
5. Confirm that a PE load of my bot lib loads before the Android lib and bots generally work on mobile.
6. Let the user manually install the CIR zipped package on their xash3d apk install as they wish.
7. Claim victory and enjoy a mod that is 25 years old on a mobile device, which would be a true legacy

Thank you for reading. If we can shim Android support to play on xash3d for CIR, this would be a wonderful accomplishment.

[FreeSlave]

And probably need to build with proprietary vgui by default for this platforms.

Not sure about that. This requires initializing and dowloading submodules, and I would stick to a scenario when a user don't use git and just downloaded zip archive. Also most singleplayer mods don't need vgui. But building with vgui should be described somewhere.

We have mirror on https://git.mentality.rip/. How migrate wiki to other resource?

If it's a problem we can keep build instructions in README.md. We can use wiki for other stuff, like list of bugfixes.

@mittorn said, there probably will work an old behavior if swap bytes in structure.

I'm not sure what you mean

I also found out that steam-runtime repo is now docker/podman oriented instead of schroot. So instructions for building on Linux needs to be updated too. I still would keep instructions for building via schroot just to avoid making users install docker/podman as they are heavier alternatives than chroot.

[nekonomicon]

@solidi we have some troubles with android now: An old engine (Xash3D FWGS 0.19.2 and older) was compiled only for 32-bit architectures with an old ndk version r10e. But google currently required 64-bit libraries in play market plus arm chip vendors had plans to drop compatibility with 32-bit code in this year. And some changes in android ABI was made yet: https://github.com/FWGS/xash3d-fwgs/issues/90

Plus our an old android applications uses a little code parts on java. We have idea to remove java code and make some workaround for custom game menu on engine side. And we not ready to release new engine for android yet.

Anyway, new engine is not compatible with old engine.

I have gone as far as investigating community attempts at it, specifically Expanded-arsenal but haven't fought through the compilation because it's genuinely a significant time investment.

It's more like PoC for a while.

For old engine we have mod sample and Android.mk in this repo.

For compilation you need to have JDK, Android SDK and Android NDK r10e.

Find a pipeline that is already building the android libs necessary on GitHub workflow for android from Valves standard SDK, or from this SDK. Integrate that target building into my game lib repo as android.yaml

Example for travis: https://github.com/nekonomicon/AzureSheep-android/blob/master/.travis.yml

For standard SDK you need to make some changes specially for arm: https://github.com/FWGS/hlsdk-xash3d/commit/1ca34fcb4381682bd517612b530db22a1354a795 https://github.com/FWGS/hlsdk-xash3d/commit/617d75545f2ecb9b2d46cc30728dc37c9eb6d35e

char type defined as signed char for x86 and as unsigned char for arm. Plus unaligned access on arm can cause crashes.

And for 64-bit architectures need fixes for MAKE_STRING: https://github.com/FWGS/hlsdk-xash3d/blob/master/dlls/util.h#L38

If your mod uses vgui you need to link statically decompiled vgui and vgui_support.

Also, android uses selinux to prevent library loading from external directories, so you need to install android packages anyway.

For bot you can see an old solution for yapb and parabot: https://github.com/FWGS/cs16-client/blob/v1.32/android/src/in/celest/xash3d/cs16client/LauncherActivity.java#L155 https://github.com/yapb/yapb/blob/7d531ee4514fbbcb3c74908b4868c78447018057/source/interface.cpp#L3138 https://github.com/nekonomicon/Parabot/blob/master/android/src/su/xash/xash3d/LauncherActivity.java#L68 https://github.com/nekonomicon/Parabot/blob/master/dlls/h_export.cpp#L158

[nekonomicon]

Also, Xash3D FWGS provides mobility api with some new features like vibration: https://github.com/FWGS/hlsdk-xash3d/blob/invasion/engine/mobility_int.h

[FreeSlave]

Set GoldSource support by default. Also updated build instructions in https://github.com/FWGS/hlsdk-xash3d/pull/266

Next steps:

• Better description of the project.
• Comprehensive list of bugfixes (in the Wiki?)
• A note about mods in the branches. List of mods that we consider stable (can be located in the Wiki? Adding such list to the main repo history would make a mess as it also will need a maintenance). Merging the latest master into these branches.
• Instructions for using Steam Runtime with docker/podman.
• Maybe instructions on how to setup and build the project in Visual Studio Code?

[FreeSlave]

The list of bugfixes so far:

• Fixed an occasional bug when houndeyes stuck unable to do anything. Technical detail: now monster's Activity is set before the call to SetYawSpeed. Patch
• Monsters now play idle sounds as it's supposed by the code. Technical detail: the problem was a check for wrong variable. Patch
• Fixed a bug that caused talk monsters (scientists and security guards) to face a wrong direction during scripted sequence sometimes. Patch
• Fixed squad member removal. This bug affected houndeye attacks as their attack depends on percieved number of squad members. Patch
• Scientists now react to smells. Patch
• Tau-cannon (gauss) plays idle animations.
• Tau-cannon (gauss) beam color depends on the charge as it was before the prediction code was introduced in Half-Life. Patch
• Brought back gluon flare in singleplayer.
• Hand grenades don't stay primed after holster, preventing detonation after weapon switch. Patch
• Fixed flashlight battery appearing as depleted on restore.
• Fixed a potential overflow when reading sentences.txt. Patch
• Fixed beam attachment invalidated on restore (that led to visual bugs). Patch
• Fixed alien controllers facing wrong direction in non-combat state. Patch
• Fixed weapon deploy animations not playing sometimes on fast switching between weapons. Patch Patch2
• Fixed tripmine sometimes having wrong body on pickup Patch

Bugfix-related macros that can be enabled during the compilation.

• CROWBAR_DELAY_FIX fixes a bug when crowbar has a longer delay after the first hit.
• CROWBAR_FIX_RAPID_CROWBAR fixes a "rapid crowbar" bug when hitting corpses of killed monsters.
• GAUSS_OVERCHARGE_FIX fixes tau-cannon (gauss) charge sound not stopping after the overcharge.
• CROWBAR_IDLE_ANIM makes crowbar play idle animations.
• TRIPMINE_BEAM_DUPLICATION_FIX fixes tripmine's beam duplication on level transition.
• HANDGRENADE_DEPLOY_FIX makes handgrenade play draw animation after finishing a throw.
• WEAPONS_ANIMATION_TIMES_FIX fixes deploy and idle animation times of some weapons.

Bugfix-related server cvars.

• satchelfix: if set to 1, doors won't get blocked by satchels. Fixes an infamous exploit on crossfire map.
• explosionfix: if set to 1, explosion damage won't propagate through thin bruses.
• selfgauss: if set to 0, players won't hurt themselves with secondary attack when shooting thick brushes.

Anything you want to add?

[a1batross]

GitHub Wiki pages are completely useless. Just by cloning Git repository, you won't get any of the documentation. For example, engine has all the needed pages in Documentation/ folder in the root of repo, similar how it's done in Linux Kernel, U-Boot or BusyBox for example. It could also help, if we will migrate from GitHub to somewhere else in the future. (Microsoft making GitHub worse and worse every year from now, potentially stealing Open Source code in Copilot and many devs are leaving it)

I will rename it to hlsdk-portable. Are you fine with this?

The CI should publish binaries for all platforms for all branches, IMHO. It could be stored in GitHub Releases for now and could be used to point automatically at newer releases of reverse-engineered or rebased mods.

I suggest working on Android separately, it's a very special platform compared to everything else, we can't distribute libraries here as is, they should be repackaged into APKs with specific to Xash3D FWGS interface. mod-sample should be reworked considering modern Android development and added to this repo, instead of being a standalone obscure repository.

[FreeSlave]

GitHub Wiki pages are completely useless. Just by cloning Git repository, you won't get any of the documentation. For example, engine has all the needed pages in Documentation/ folder in the root of repo

I don't like having everything in the repository, because I don't want some information, like, the list of stable mods clog the history of branches. Wiki has an independent history and can be edited anytime. We also can add/update some additional information there, like setting up the project for specific IDE, which I don't see suitable to put in the main history. That's just my opinion, but I don't oppose if others agree to do the other way.

I will rename it to hlsdk-portable. Are you fine with this?

At least I am.

[Velaron]

Are you sure Windows build instructions should be that complicated? Using the VS developer command prompt is quite optional, and I never make any calls to msbuild directly. Just these 2 lines build the project fine:

cmake -A Win32 -S . -B build
cmake --build build --config Release

[FreeSlave]

@Velaron, oh, I forgot this approach works on Windows too. I think it didn't work for me in github workflow at some point, so I changed to msbuild. But it should work locally for sure. We can also rewrite instructions for Linux to use cmake both for configuring and building.

Using the VS developer command prompt is quite optional

If you installed cmake via Visual Studio Installer, it's not installed in PATH by default, so won't be available in common cmd. Developer command prompt sets the environment right.

Of course one can install cmake for Windows separately, but even then adding CMake to system PATH is unticked during the installation by default.

I guess someone who builds on Windows regularly should decide what are the best instructions for Windows users.

[a1batross]

@FreeSlave

I don't like having everything in the repository, because I don't want some information, like, the list of stable mods clog the history of branches.

But there isn't much of information. Text files are small, don't bloat up the code, and I don't think they be updated too often.

[FreeSlave]

@a1batross I understand. It just feels weird to have an intormation about other mods in the specific mod branch.

[nekonomicon]

May be will be better to have wiki in separate repository?

[a1batross]

@nekonomicon it's basically the same as GitHub Wikis, you can clone it, but what's the point if it's an extra step for docs?

[Velaron]

Maybe use Github Pages? Technically you get it when you clone the repo as a branch, and it doesn't need to be updated in every branch.

[FreeSlave]

Maybe use Github Pages?

Github pages need to be in html which is inconvenient.

[Velaron]

Maybe use Github Pages?

Github pages need to be in html which is inconvenient.

That's why static website generators and stuff exist

[a1batross]

HTML can be generated from markdown or rst documentation, depends on what you like. Though, HTML is unreadable for humans, and source must always present. It's all over about putting few text files into the repo. What's wrong about that?

[FreeSlave]

It's all over about putting few text files into the repo. What's wrong about that?

As I said I feel it's wrong for mod branches to have an information like a list of mods re-implemented on top of this SDK. In clean situation I would prefer a mod branch to include all commits from master, and not to be "behind" master.

Now imagine that a new mod branch is added (or we want to mark one of the existing branches as stable and include it in the list). If we have such list in the master and make a change, then ALL branches become one commit behind master. It also means that for the mod to be listed as stable on its own branch, the branch needs another merge after introducing the change in master.

You may call me a perfectionist, but it's also a question of cleanliness of the repository (and history). Seeing changes in master makes a user think that something was changed in the base hlsdk.

@nekonomicon is responsible for most mod branches in this repo, so maybe he should express his opinion on that matter. Like, would it be convenient to work one way or another.

[a1batross]

Forks and branches tends to have unrelated changes with the base, that how development is going on in decentralized architecture of Git.

And anybody who at least once worked with Git understands that.

[nekonomicon]

I think we can place build instructions and list of fixes under spoilers into readme.md.

[FreeSlave]

I think we can place build instructions and list of fixes under spoilers into readme.md.

What's about a list of supported mods?

[nekonomicon]

There external resource needed.

[FreeSlave]

There external resource needed.

I see Wiki as the best case.

Btw, can someone add Topics to repository details? I propose halflife, half-life, goldsource, goldsrc, xash3d, crossplatform

[FreeSlave]

I've updated the list of fixes in https://github.com/FWGS/hlsdk-portable/issues/263#issuecomment-1179632283

[FreeSlave]

I'm closing this issue as everything planned seems to be done. I still haven't tried building for Android but I saw instructions added.