# fwgs/xash3d-fwgs architecture

> Architecture diagram of the GitHub repository fwgs/xash3d-fwgs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fwgs/xash3d-fwgs
- Repository: https://github.com/fwgs/xash3d-fwgs

## Overview

##### Project type and purpose
- This is a cross‑platform, modular C/C++ game engine (“Xash3D FWGS”) compatible with the Half‑Life engine and extensible by game developers. It includes core simulation, client‑side rendering and audio, a headless server, a virtual filesystem, multiple rendering backends, platform abstraction layers, and an Android UI wrapper.

##### File structure
- Top‑level modules:
- engine/ (core client, common, server, platform code)
- ref/ (renderer backends: OpenGL, GLES, software, null)
- filesystem/ (VFS implementation, .pak/.wad/.zip support, tests)
- public/ (shared libraries, utilities, unit tests)
- pm_shared/ (player‑movement definitions)
- game_launch/ (native Windows launcher UI)
- android/ (Android application wrapper, UI, services)
- 3rdparty/ (embedded external libs: bzip2, libogg, vorbis, opus, etc.)
- scripts/ & waf*/ (build and CI automation)
- Build system: Waf (wscript), CI scripts (.cirrus.yml, GitHub workflows).
- Platform abstraction: engine/platform/* (android, linux, win32, posix, etc.).

##### README for additional insights
- Explicit support for multiple renderers (OpenGL, GLESv1/v2, software).
- Virtual filesystem with .pk3/.pk3dir, case‑insensitive emulation.
- Server supports IPv6, voice chat, headless mode.
- Mobility API for touch, vibration.
- Build instructions emphasize waf configure/build on many platforms.

- Core Engine
- Simulation & game logic (engine/common, server, client)
- Networking & master servers
- Virtual filesystem (filesystem/)
- Plugin interfaces (render_api.h, eiface.h, vgui_api.h)
- Client Subsystem
- Input subsystem (keyboard, mouse, touch, gamepad)
- Audio subsystem (soundlib, Ogg/Opus, MP3)
- UI & VGUI (mainui_cpp)
- Renderer interface
- Renderer Backends (implement RenderAPI)
- OpenGL (ref/gl)
- GLESv1/GLESv2 (ref/gl4es, gl-wes-v2)
- Software rasterizer (ref/soft)
- Null renderer (ref/null)
- Server Subsystem
- Headless game server (engine/server)
- Voice chat, master‑server listing
- Platform Abstraction Layer
- OS-specific glue (engine/platform/*)
- File I/O, dynamic loading, threading, system calls
- Android UI Wrapper
- Java/Kotlin app (android/app/src)
- JNI bridge to native engine
- External/3rd‑party libraries
- Compression (bzip2, miniz)
- Audio (vorbis, opus)
- Backtrace, font, etc.
- Build & CI
- Waf build scripts, CI pipelines, cross‑compile scripts

b. Relationships & data flows
- Client → Core Engine: input events, requests simulation updates
- Core Engine → VFS: file loading (.pk3, .wad)
- Core Engine → Audio: play sounds/music
- Core Engine ↔ Server: game state replication over network
- Platform Layer underpins Client, Server, VFS, Renderer, Audio
- Android UI → JNI Bridge → Native Engine
- Build System orchestrates compilation of all C/C++ modules and Android wrapper

c. Architectural patterns & principles
- Modular “plugin” backends for rendering (Strategy pattern)
- Clear separation of concerns: engine core vs. platform vs. render vs. filesystem
- Abstraction layers for cross‑platform portability
- Use of virtual interfaces (RenderAPI, IFileSystem)

d. Key technologies & libraries
- C/C++ codebase, Waf build system
- OpenGL / GLES / software rasterization
- SDL2 for windowing/input on desktops
- JNI, Android SDK + Gradle for Android target
- Ogg Vorbis, Ogg Opus, libmpg for audio
- ZIP, BZ2 support via embedded libs

##### Detail
- Every subsystem (client, server, filesystem, renderers, platform, Android UI, third‑party).
- Interface boundaries (e.g., RenderAPI, IFileSystem).
- Keep it hierarchical: high‑level blocks drill down into major submodules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Engine"
        Simulation["Simulation & Game Logic"]:::core
        Networking["Networking & Master Server"]:::core
        PluginIF["Plugin Interfaces"]:::core
    end

    subgraph "Virtual FileSystem"
        VFS["VFS (.pk3/.wad/.zip)"]:::core
    end

    subgraph "Client Subsystem"
        Input["Input Subsystem"]:::core
        Audio["Audio Subsystem"]:::core
        UI["UI & VGUI"]:::core
        RendererIF["Renderer Interface"]:::core
    end

    subgraph "Renderers"
        OpenGL["OpenGL Renderer"]:::backend
        GLES["GLESv1/v2 Renderer"]:::backend
        Soft["Software Rasterizer"]:::backend
        NullR["Null Renderer"]:::backend
    end

    subgraph "Server Subsystem"
        Server["Headless Server"]:::core
    end

    subgraph "Platform Abstraction Layer"
        PLAT["Platform: POSIX/Win32/Android"]:::platform
    end

    subgraph "Android UI Wrapper"
        App["Android App"]:::platform
        JNI["JNI Bridge"]:::platform
    end

    subgraph "Third-Party Libraries"
        Third["Compression & Audio Libs"]:::ext
        VGUI3["VGUI Support"]:::ext
    end

    subgraph "Build & CI"
        Build["Waf & CI Scripts"]:::build
    end

    %% Connections
    Input -->|inputs| Simulation
    Simulation -->|draw calls| RendererIF
    Simulation -->|play sound| Audio
    Simulation -->|load assets| VFS
    Simulation -->|network state| Networking
    RendererIF -->|renders| OpenGL
    RendererIF -->|renders| GLES
    RendererIF -->|renders| Soft
    RendererIF -->|renders| NullR
    PLAT -->|supports| Simulation
    PLAT -->|supports| RendererIF
    PLAT -->|supports| Audio
    PLAT -->|supports| VFS
    App -->|UI calls| JNI
    JNI -->|native invoke| Simulation
    Build -->|compiles| Simulation
    Build -->|builds| OpenGL
    Build -->|builds| GLES
    Build -->|builds| Soft
    Build -->|builds| NullR
    Build -->|builds| VFS
    Build -->|builds| Server
    Build -->|builds| App

    %% Click Events
    click Simulation "https://github.com/fwgs/xash3d-fwgs/tree/master/engine/common/"
    click Networking "https://github.com/fwgs/xash3d-fwgs/blob/master/engine/common/masterlist.c"
    click PluginIF "https://github.com/fwgs/xash3d-fwgs/blob/master/common/render_api.h"
    click VFS "https://github.com/fwgs/xash3d-fwgs/tree/master/filesystem/"
    click Input "https://github.com/fwgs/xash3d-fwgs/blob/master/engine/client/input.c"
    click Audio "https://github.com/fwgs/xash3d-fwgs/tree/master/engine/client/soundlib/"
    click UI "https://github.com/fwgs/xash3d-fwgs/tree/master/engine/client/vgui/"
    click OpenGL "https://github.com/fwgs/xash3d-fwgs/tree/master/ref/gl/"
    click GLES "https://github.com/fwgs/xash3d-fwgs/tree/master/3rdparty/gl4es/"
    click Soft "https://github.com/fwgs/xash3d-fwgs/tree/master/ref/soft/"
    click NullR "https://github.com/fwgs/xash3d-fwgs/blob/master/ref/null/r_context.c"
    click Server "https://github.com/fwgs/xash3d-fwgs/tree/master/engine/server/"
    click PLAT "https://github.com/fwgs/xash3d-fwgs/tree/master/engine/platform/"
    click App "https://github.com/fwgs/xash3d-fwgs/tree/master/android/app/src/main/java/su/xash/engine/"
    click JNI "https://github.com/fwgs/xash3d-fwgs/blob/master/android/app/src/main/java/su/xash/engine/XashActivity.java"
    click Third "https://github.com/fwgs/xash3d-fwgs/tree/master/3rdparty/bzip2/"
    click VGUI3 "https://github.com/fwgs/xash3d-fwgs/tree/master/3rdparty/vgui_support/"
    click Build "https://github.com/fwgs/xash3d-fwgs/tree/master/wscript"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef backend fill:#c8e6c9,stroke:#388e3c,color:#1b5e20;
    classDef platform fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
    classDef ext fill:#e0e0e0,stroke:#9e9e9e,color:#424242;
    classDef build fill:#d1c4e9,stroke:#7e57c2,color:#311b92;
```
