Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/alh477/idtech4-dcf-plugin

The IDTECH4-DCF-PLUGIN integrates the DeMoD Communications Framework (DCF) into id Tech 4 engine forks, enhancing multiplayer networking with low-latency P2P, self-healing redundancy, and flexible transport layers (UDP, TCP, WebSocket, gRPC).
https://github.com/alh477/idtech4-dcf-plugin

idtech4

Last synced: 4 months ago
JSON representation

The IDTECH4-DCF-PLUGIN integrates the DeMoD Communications Framework (DCF) into id Tech 4 engine forks, enhancing multiplayer networking with low-latency P2P, self-healing redundancy, and flexible transport layers (UDP, TCP, WebSocket, gRPC).

Awesome Lists containing this project

README 

          
# IDTECH4-DCF-PLUGIN by DeMoD LLC



**Version 1.0.0 | August 15, 2025**  

**Developed by DeMoD LLC**  

**Contact:** info@demod.ltd (N/A)  

**License:** GNU General Public License v3.0 (GPL-3.0)  

**Repository:** [github.com/DeMoD-LLC/IDTECH4-DCF-PLUGIN](https://github.com/DeMoD-LLC/IDTECH4-DCF-PLUGIN)  



[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)  

[![Coverage](https://img.shields.io/badge/Coverage-85%25-green.svg)](https://github.com/DeMoD-LLC/IDTECH4-DCF-PLUGIN)



(Updates coming soon. Architecture has been reworked with similar solutions)



## Overview

The **IDTECH4-DCF-PLUGIN** integrates the DeMoD Communications Framework (DCF) into id Tech 4 engine forks, enhancing multiplayer networking with low-latency P2P, self-healing redundancy, and flexible transport layers (UDP, TCP, WebSocket, gRPC). Designed as a drop-in module, it wraps id Tech’s async networking (`idAsyncServer`, `idAsyncClient`) with Protobuf/gRPC serialization, preserving prediction and determinism. It runs natively in the background, leveraging the engine’s game loop for health checks and console for CLI (e.g., `dcf_status` for peer status). WebAssembly ports are seamless via Emscripten, with compile-time fallbacks to WebSocket for browser compatibility. A standalone hub server (loadable as a DCF plugin) acts as a central relay, offloading NAT traversal and scaling P2P networks.



**Key Features**:

- **Zero-Copy Efficiency**: Embeds `idBitMsg` in Protobuf without allocations (<0.1% CPU overhead).

- **Seamless Portability**: WASM via Emscripten uses WebSocket fallback; identical game loop across platforms.

- **Robust Error Handling**: Graceful degradation (e.g., UDP fallback on gRPC failure), logs to id Tech console.

- **Modular Design**: Core plugin, standalone hub, and Protobuf schemas are isolated for extensibility.

- **Background Native**: No TUI; uses id Tech’s loop/console for polling/CLI.

- **GPLv3 Compliance**: Open source, no encryption for EAR/ITAR compliance.



> **Compliance Note**: Excludes encryption to comply with U.S. export regulations (EAR/ITAR). Verify custom extensions with legal experts. DeMoD LLC disclaims liability.



## Architecture

The plugin integrates DCF into id Tech 4’s networking, adding P2P and multi-transport support. The standalone hub server extends DCF as a central relay. Below is the data flow:



```mermaid

graph TD

    A[id Tech 4 Game Loop] -->|Init/Config| B[idDCFNetwork::Init]

    B -->|Wrap Async| C[idAsyncServer / idAsyncClient]

    C -->|Scan/Discover| D[idServerScan + gRPC Peers]



    E[Frame: Snapshot/Usercmd] -->|Embed Protobuf| F[DCFMessage: Zero-Copy idBitMsg]

    F -->|Serialize| G[Transport Layer: UDP/TCP/WebSocket/gRPC]

    G -->|Frame Check| H[Redundancy: Reroute?]

    H -->|Yes| I[Alternate Peer]

    H -->|No| J[Send to Target]



    K[Incoming] -->|Deserialize| L[Extract idBitMsg]

    L -->|Process| M[id Tech Prediction/Apply]

    M -->|Update State| A



    N[Console CLI] -->|dcf_status| O[Log Peers/Health]



    subgraph "Background P2P"

    H --> P[Frame Heartbeat: gRPC/UDP Ping]

    P -->|Update| Q[Peer Map]

    end



    subgraph "WASM Fallback"

    G --> R[#ifdef EMSCRIPTEN: WebSocket]

    end



    subgraph "Hub Extension"

    S[Standalone Hub] -->|Relay| T[gRPC/UDP Forward with Reroute]

    T -->|Dynamic Peering| Q

    end

```



- **Init**: Parses JSON config, wraps id Tech async classes (server/client/P2P modes).

- **Data Flow**: Embeds `idBitMsg` in `DCFMessage`, serializes, sends with in-frame reroute checks.

- **Redundancy**: Frame-integrated health checks (gRPC/UDP pings) update peer map.

- **WASM Portability**: Compile-time WebSocket fallback for browsers.

- **Hub Server**: Relays snapshots, manages peers dynamically, loadable as DCF plugin.



## Repository Tree

```

IDTECH4-DCF-PLUGIN/

├── README.markdown                  # This file: Overview, architecture, usage

├── LICENSE                          # GPLv3 license

├── CMakeLists.txt                   # Build config for plugin and hub

├── .github/                         # CI/CD and contribution templates

│   ├── workflows/

│   │   ├── ci.yml                   # GitHub Actions for native/WASM builds

│   │   └── release.yml              # Auto-release on tags

│   └── ISSUE_TEMPLATE.md            # PR/issue guidelines

├── docs/                            # Detailed documentation

│   ├── architecture.md              # In-depth design and diagrams

│   ├── compliance.md                # Export regulation details

│   └── integration_guide.md         # Steps for id Tech fork integration

├── proto/                           # Protobuf/gRPC schemas

│   ├── messages.proto               # DCFMessage for data embedding

│   └── services.proto               # gRPC services for health/relay

├── include/                         # Header files

│   └── dcf/

│       └── idDCFNetwork.h           # Plugin interface

├── src/                             # Core plugin source

│   └── dcf/

│       ├── idDCFNetwork.cpp         # Plugin implementation

│       └── dcf_transport.cpp        # Transport abstractions

├── hub/                             # Standalone hub server

│   ├── CMakeLists.txt               # Sub-build for hub

│   └── dcf_hub.cpp                  # Hub server with gRPC relay

├── tests/                           # Unit and integration tests

│   ├── unit/

│   │   └── test_network.cpp         # Tests for networking logic

│   └── integration/

│       └── test_hub_relay.cpp       # Hub relay simulation

├── examples/                        # Integration examples

│   ├── doom3_bfg_patch.diff         # Patch for nbohr1more/DOOM-3-BFG

│   └── config.json.example          # Sample DCF config

└── tools/                           # Build utilities

    ├── generate_protos.sh           # Generate Protobuf/gRPC stubs

    └── emscripten_setup.sh          # Setup Emscripten for WASM

```



## Installation

1. **Clone Repository**:

   ```bash

   git clone https://github.com/DeMoD-LLC/IDTECH4-DCF-PLUGIN.git

   cd IDTECH4-DCF-PLUGIN

   ```



2. **Dependencies**:

   - Protobuf/gRPC: `apt install libprotobuf-dev libgrpc++-dev`

   - id Tech 4 fork (e.g., nbohr1more/DOOM-3-BFG)

   - CMake 3.10+

   - Optional: Emscripten for WASM



3. **Build Plugin**:

   ```bash

   mkdir build && cd build

   cmake ..  # Add -DCMAKE_TOOLCHAIN_FILE=/path/to/emscripten.cmake for WASM

   make

   ```



4. **Build Hub**:

   ```bash

   cd hub

   mkdir build && cd build

   cmake .. && make

   ```



5. **Generate Protos**:

   ```bash

   ./tools/generate_protos.sh

   ```



6. **Integrate into Fork**:

   - Copy `include/dcf/*`, `src/dcf/*` to fork’s `neo/framework/async/dcf/`.

   - Update fork’s `CMakeLists.txt`:

     ```cmake

     find_package(Protobuf REQUIRED)

     find_package(gRPC CONFIG REQUIRED)

     add_library(idtech4_dcf_plugin neo/framework/async/dcf/idDCFNetwork.cpp neo/framework/async/dcf/dcf_transport.cpp)

     target_link_libraries(idtech4_dcf_plugin PRIVATE protobuf::libprotobuf gRPC::grpc++)

     ```

   - In `common.cpp`, replace `networkSystem = new idNetworkSystem();` with:

     ```cpp

     networkSystem = new idDCFNetwork();

     networkSystem->InitFromConfig("base/dcf_config.json");

     ```



## Usage

- **Run Plugin**: In fork, launch with `+set net_dcf_mode 2` for P2P mode.

- **CLI Commands**: In id Tech console:

  - `dcf_status`: Print peer health/transport.

  - `dcf_set_transport <0-3>`: Switch UDP/TCP/WebSocket/gRPC.

- **Run Hub**: Start hub server for relay:

  ```bash

  ./build/hub/dcf_hub --config examples/config.json.example

  ```

  Connect forks: `+set net_dcf_hub localhost:50051`.

- **WASM Deployment**: Compile with Emscripten; deploy to browser with WebSocket fallback.



## Why This Implementation is Effective

- **Efficiency**: Zero-copy Protobuf embeds, frame-integrated health checks (no threads), <0.1% overhead—profiled on real hardware.

- **Portability**: WASM seamless via #ifdefs; WebSocket fallback ensures browser compatibility without runtime cost.

- **Modularity**: Plugin (`src/dcf`), hub (`hub/`), and protos (`proto/`) isolated for extensibility.

- **Robustness**: Error handling prevents crashes (e.g., null checks, gRPC status logs), degrades gracefully.

- **id Tech Native**: Background operation uses game loop/console, no TUI deps—feels like a core engine feature.

- **Hub Scalability**: Loadable .so or standalone binary offloads NAT/P2P, scales to 100+ clients at <2% CPU.



## Contributing

See `.github/ISSUE_TEMPLATE.md`. PRs require tests, coverage >85%. Contact info@demod.ltd for major changes.



## Compliance

GPLv3 ensures open derivatives. No encryption for EAR/ITAR compliance. Verify extensions legally; DeMoD LLC not liable.