DOCSEARCHbyAlgolia
Submit Docs

Xash3D FWGS Documentation

repository·master·Indexed 25 days ago

https://github.com/fwgs/xash3d-fwgs

A highly modified game engine designed for compatibility with the Half-Life Engine (GoldSrc) with extended features. It supports Windows, Linux, BSD, Android, and iOS, offering improved multiplayer, various renderers, and advanced virtual filesystem support. The documentation covers installation, building from source across multiple platforms, engine porting guides, and debugging tools like minidumps.

Tokens
33.7K
Snippets
80
Records
205
Agent score
83%

What's inside Xash3D FWGS

  1. Supported network protocols in Xash3D FWGS

    master

    Xash3D FWGS supports several network protocols, though development and documentation focus on version 49.

    • Version 49: The primary protocol supported by Xash3D FWGS. This is the version covered in the technical documentation.
    • Version 48: Used in Xash3D FWGS 0.19 and earlier. This version is deprecated and scheduled for removal.
    • GoldSrc version 48: Used in the current GoldSource version.
    • Quake version 15: Used exclusively for demo playback within the Quake Wrapper mod.

    Note on Server Compatibility: The server side natively supports only the Xash3D 49 protocol. However, if you are running mods that write directly to engine internal messages, you can use the gsmrf bugcomp mode to convert GoldSrc 48 messages into Xash3D 49 on the fly.

  2. Understand the Steam API Broker Protocol

    master

    The Steam API Broker is a TCP-based binary protocol used by the Xash3D FWGS engine to communicate with a machine running a Steam client. This allows the engine to acquire necessary information to log in to Steam-protected multiplayer servers without requiring the Steamworks SDK to be linked directly or run on all supported platforms.

    Key Protocol Properties:

    • Single active session: Once a session is activated, the broker rejects all other TCP connections until the session is terminated.
    • Frame-based communication: All messages follow a consistent structure consisting of a header, length, and payload.
    • Stateful interactions: Commands affect the session state; certain commands are only valid in specific states.
    • Endianness: Numeric parameters are encoded in little-endian format.

  3. Configure Build and Clean steps in Qt Creator

    master

    To allow Qt Creator to build and clean the project using Waf, configure the following custom process steps in the Projects -> Build Settings tab:

    Build Steps

    Add two Custom Process Step entries:

    1. Configure Step:
      • Command: Your Python executable.
      • Arguments: The Waf configure command used during initial setup.
      • Working Directory: %{buildDir}/../ (or the directory containing the waf script).
    2. Build Step:
      • Command: Your Python executable.
      • Arguments: waf build
      • Working Directory: %{buildDir}/../

    Clean Steps

    Add one Custom Process Step:

    • Command: Your Python executable.
    • Arguments: waf clean
    • Working Directory: %{buildDir}/../

  4. Manage Steam API Broker Session Lifecycle

    master

    The broker operates through several states:

    1. IDLE: Initial state, accepts new TCP connections.
    2. ACTIVE: Session established via sb_gamedir. The broker rejects other connections. In this state, the client can request auth tickets via sb_connect or announce disconnects via sb_disconnect.
    3. RESTARTING: Triggered by sb_terminate to reset the Steam client state.

  5. Build Xash3D FWGS for PlayStation Vita

    master

    To build the engine from source for PSVita, you must first set up the VitaSDK and several dependencies (vitaGL, vita-rtld, and a specific SDL2 fork) before using waf to compile the engine.

    Build Workflow

    1. Prerequisites:
    2. Engine Compilation:
      • Use waf to configure and build the project.
      • Install the resulting .so files to a destination directory.
    3. Output:
      • The xash.vpk file will be located in build/engine/.

    Build Commands

    # 1. Build vitaGL
git clone https://github.com/Rinnegatamante/vitaGL.git
make -C vitaGL NO_TEX_COMBINER=1 HAVE_UNFLIPPED_FBOS=1 HAVE_PTHREAD=1 SINGLE_THREADED_GC=1 MATH_SPEEDHACK=1 DRAW_SPEEDHACK=1 HAVE_CUSTOM_HEAP=1 -j2 install

# 2. Build vita-rtld
git clone https://github.com/fgsfdsfgs/vita-rtld.git && cd vita-rtld
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j2 install

# 3. Build SDL2 fork
git clone https://github.com/Northfear/SDL.git && cd SDL
mkdir build && cd build
cmake -DCMAKE_TOOLCHAIN_FILE=${VITASDK}/share/vita.toolchain.cmake -DCMAKE_BUILD_TYPE=Release -DVIDEO_VITA_VGL=ON ..
make -j2 install

# 4. Build Xash3D
./waf configure -T release --psvita
./waf build
./waf install --destdir=xash3d

  6. Set up PlayStation Vita for Xash3D FWGS

    master

    Before installing Xash3D FWGS on a PSVita, ensure your device is configured for homebrew and has the necessary system plugins installed.

    Prerequisites

    1. Homebrew Setup: Ensure your PSVita is set up to run homebrew applications.
    2. Install kubridge: Install kubridge (version 0.1 is recommended).
      • Note: Manual installation is recommended over using EasyPlugin.
      • Copy kubridge.suprx to your taiHEN plugins folder (e.g., ux0:/tai or ur0:/tai).
      • Add it to your config.txt under the *KERNEL section.
    3. Install libshacccg.suprx: Follow the external guide to extract and install libshacccg.suprx for shader compilation support.
    *KERNEL
ux0:tai/kubridge.skprx

  7. Load Xash3D FWGS project in Qt Creator

    master
    1. Enable Plugin: Ensure the Compilation Databases plugin is enabled. Go to Help -> About Plugins..., find it under the Build Systems category, check the box, and restart the IDE.
    2. Open Project: Use File -> Open File or Project... and select the compile_commands.json file located in your build directory.
    3. Configure: When prompted, click Configure Project.
    4. Fix Root Directory: If the project tree appears empty, right-click the project root (e.g., build [master]), select Change Root Directory, and choose the Xash3D FWGS repository root directory.

  8. Port client-side code

    master

    To port client-side code to Xash3D FWGS, follow these steps:

    • Redefine all DLLEXPORT defines as empty (wrap under _WIN32 if Windows compatibility is required).
    • Remove hud_servers.cpp and Servers_Init/Servers_Shutdown from hud.cpp.
    • Fix case-sensitivity in includes (e.g., change STDIO.H to stdio.h).
    • Replace broken DECLARE_MESSAGE and DECLARE_COMMAND macros with fixed versions from hlsdk-portable's cl_util.h.
    • Add #include <ctype.h> for tolower and isspace functions.
    • Add #include <string.h> for memcpy, strcpy, etc.
    • Use in_defs.h from hlsdk-portable.
    • Add input_xash3d.cpp from the hlsdk-portable project to fix input handling.

  9. Access source code for XDM mod version 3.0.4.3

    master

    The source code for XDM version 3.0.4.3 is obfuscated within an SFX-archive. To access it, follow these steps:

    1. Download the SFX-archive from ModDB.
    2. Extract the archive.
    3. Open client.dll in a HEX-editor and patch the header: change the string Win! to Rar!.
    4. Extract the resulting file using unrar with the password iamtheone.

  10. Create command Aliases

    master

    Aliases allow you to define new commands or create complex command sequences. You can also use aliases to hook existing commands by unaliasing the original, running your custom sequence, and then re-aliasing it.

    alias wnext "invnext;wait;wait;+attack;wait;-attack"

# Hooking an existing command
alias invnext1 "unalias invnext;wnext;alias invnext invnext1"
alias invnext invnext1

  11. Use the Touch Controls Visual Editor

    master

    Xash3D features a built-in visual editor to customize touch controls and create custom menus without manual file editing.

    Entering Edit Mode

    1. Launch Xash3D and start the game.
    2. Click the gear icon or execute the command touch_enableedit.

    Editor Operations

    • Moving buttons: Click a button, drag it to the desired location, and release.
    • Resizing buttons: Place your first finger on the top-left corner of the button and use a second finger to resize it.
    • Hiding/Showing buttons: Select a button (it will turn red) and use the menu to:
      • Close: Exits edit mode using touch_disableedit.
      • Reset: Resets the button to default values.
      • Hide/Show: Toggles visibility using touch_hide <name> or touch_show <name>.

    Grid Settings

    • Change the number of grid cells with touch_grid_count (default is 50).
    • Disable the grid with touch_grid_enable 0.
    touch_enableedit
touch_disableedit
touch_grid_count 50
touch_grid_enable 0

  12. Loop MP3 files in Xash3D FWGS

    master

    You can enable looping for MP3 files by adding a custom text tag to the file's metadata. The tag name must be LOOP_START or LOOPSTART in the description field, and the value must be the loop time point expressed in raw samples.

    For example, setting the value to 0 will cause the sound file to replay from the beginning indefinitely.