https://github.com/alh477/idtech4-demod

Idtech4 engine with advanced networking and audio. Forks of modernized versions of Idtech will be made later.
https://github.com/alh477/idtech4-demod
Last synced: 5 months ago
JSON representation
Idtech4 engine with advanced networking and audio. Forks of modernized versions of Idtech will be made later.
Host: GitHub
URL: https://github.com/alh477/idtech4-demod
Owner: ALH477
Created: 2025-09-02T03:16:24.000Z (11 months ago)
Default Branch: main
Last Pushed: 2025-09-02T03:25:33.000Z (11 months ago)
Last Synced: 2025-09-10T10:33:40.244Z (11 months ago)
Size: 16.6 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.markdown
Awesome Lists containing this project

README

          # idTech4-DeMoD: Enhanced idTech4 Fork with DSP Audio and DCF Networking for Petabyte Madness

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

[![Build Status](https://img.shields.io/badge/build-Alpha-brightgreen.svg)](https://github.com/DeMoD-LLC/idTech4-DeMoD)

[![Contributors](https://img.shields.io/badge/contributors-1-orange.svg)](https://github.com/DeMoD-LLC/idTech4-DeMoD/graphs/contributors)

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

## Project Overview

**idTech4-DeMoD** is a fork of the idTech4 engine (based on Dhewm3), crafted by **DeMoD LLC** specifically to power their upcoming horror/cyberpunk game *Petabyte Madness*. This fork integrates two advanced mods developed by DeMoD LLC: the **idTech4-DSP-Audio** mod for hardware-accelerated audio processing and the **IDTECH4-DCF-PLUGIN** for enhanced multiplayer networking. It combines real-time ray-traced audio effects with low-latency P2P networking, tailored for the immersive single-player and experimental multiplayer experience of *Petabyte Madness*. The fork maintains compatibility with idTech4’s core systems (e.g., OpenAL, async networking) while introducing modder-friendly tools, debug features, and robust error handling.

**Key Features**:

- **DSP Audio**: Hardware-accelerated audio via USB-connected DSP (e.g., TMS320C674x) with real-time ray tracing, reverb, occlusion, and distortion, designed to enhance the atmospheric depth of *Petabyte Madness*.

- **Audio Mode Zones**: Entity-based (`func_audio_mode`) spatial audio zones with smooth blending and scriptable events, perfect for dynamic horror/cyberpunk soundscapes.

- **Advanced Networking**: Low-latency P2P with DCF, supporting UDP/TCP/WebSocket/gRPC, zero-copy Protobuf serialization, and a standalone hub server for *Petabyte Madness* multiplayer.

- **Modder-Friendly**: Editor integration (D3Edit), debug tools (e.g., `audioModesDebug`, `dcf_status`), and extensive cVARs for modders extending *Petabyte Madness*.

- **Portability**: Seamless WebAssembly (WASM) support via Emscripten with WebSocket fallback, enabling browser-based play.

- **Alpha Status**: Version 1.0, optimized for single-player; multiplayer is experimental.

**Note**: This is an alpha release developed by DeMoD LLC for *Petabyte Madness*. Test thoroughly in large maps with `com_showFPS 1`. Multiplayer is untested; prioritize single-player.

## Table of Contents

- [Features](#features)

- [Installation](#installation)

- [Usage](#usage)

- [Architecture Overview](#architecture-overview)

- [Modifications](#modifications)

- [Optimization and Edge Cases](#optimization-and-edge-cases)

- [cVARs and Commands](#cvars-and-commands)

- [Debug Tools](#debug-tools)

- [Contributing](#contributing)

- [License](#license)

- [Resources and References](#resources-and-references)

## Features

### Audio (idTech4-DSP-Audio)

- **Hardware DSP**: Offloads ray tracing, convolution, and effects (e.g., reverb, distortion) to a USB DSP (TMS320C674x, VID:PID 0x0403:0x6010), enhancing *Petabyte Madness*’s immersive audio.

  - Up to 1000 stochastic rays per sound source with 5 bounces for occlusion/diffraction.

  - Uses TI DSPLIB for efficient FIR filtering.

- **Audio Mode Entities**: `func_audio_mode` defines spatial zones with modes (0-10, e.g., explore, combat) and radii.

  - Smooth blending (lerp) or step transitions between overlapping zones.

  - Scriptable events (`onPlayerEnter`, `onPlayerExit`) for custom audio cues in *Petabyte Madness*.

- **Robust Integration**: Hot-plug USB support, OpenAL fallback (`s_useDSP 0`), batched USB transfers.

- **Modder QoL**: D3Edit zone placement, debug visualizations (`audioModesDebug 2`), extensible DSP firmware.

### Networking (IDTECH4-DCF-PLUGIN)

- **Zero-Copy Networking**: Embeds `idBitMsg` in Protobuf for <0.1% CPU overhead, optimized for *Petabyte Madness* multiplayer.

- **Multi-Transport**: Supports UDP, TCP, WebSocket, and gRPC with frame-integrated health checks.

- **P2P and Hub**: Self-healing P2P with a standalone hub server for NAT traversal and relay.

- **WASM Support**: WebSocket fallback for browser compatibility via Emscripten.

- **Console Integration**: CLI commands (e.g., `dcf_status`) for peer health and transport switching.

### Player UX

- Smooth audio mode transitions (`s_audioModeBlendTime`) for *Petabyte Madness*’s dynamic environments.

- Toggleable zones (`s_audioModesEnabled 0`) for accessibility.

- Seamless multiplayer with hub relay or P2P (`net_dcf_mode 2`).

## Installation

### Prerequisites

- **Engine**: Dhewm3-based idTech4 fork.

- **DSP Hardware**: TMS320C674x-based PCB (e.g., OMAP-L138) with USB interface.

- **Dependencies**:

  - libusb-1.0 (`sudo apt install libusb-1.0-0-dev` or `vcpkg install libusb`).

  - Protobuf/gRPC (`sudo apt install libprotobuf-dev libgrpc++-dev`).

  - C++11+ compiler (e.g., GCC, MSVC).

  - CMake 3.10+.

  - Code Composer Studio (CCS) for DSP firmware.

  - Optional: Emscripten for WASM.

- **Tools**: D3Edit for map editing.

### Building idTech4-DeMoD

1. Clone repository:

   ```bash

   git clone https://github.com/DeMoD-LLC/idTech4-DeMoD.git

   cd idTech4-DeMoD

   ```

2. Copy mod files to source:

   - Audio: `neo/sound/snd_dsp.h`, `snd_dsp.cpp`, `snd_system.cpp`, `snd_world.cpp`, `def/audio_modes.def`.

   - Game: `neo/game/AudioModeEntity.h`, `AudioModeEntity.cpp`, `AudioModeManager.h`, `AudioModeManager.cpp`.

   - Networking: `neo/framework/async/dcf/idDCFNetwork.h`, `idDCFNetwork.cpp`, `dcf_transport.cpp`.

3. Update `neo/CMakeLists.txt`:

   ```cmake

   find_package(Protobuf REQUIRED)

   find_package(gRPC CONFIG REQUIRED)

   find_package(libusb-1.0 REQUIRED)

   add_library(idtech4_demod

       game/AudioModeEntity.cpp

       game/AudioModeManager.cpp

       sound/snd_dsp.cpp

       framework/async/dcf/idDCFNetwork.cpp

       framework/async/dcf/dcf_transport.cpp

   )

   target_link_libraries(idtech4_demod PRIVATE usb-1.0 protobuf::libprotobuf gRPC::grpc++)

   ```

4. Build:

   ```bash

   mkdir build && cd build

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

   make -j4

   ```

5. Install: Copy `build/dhewm3` to game directory.

### DSP Firmware Build

1. Create a CCS project for TMS320C674x.

2. Implement firmware (see [idTech4-DSP-Audio](#resources-and-references)).

3. Link TI DSPLIB and USB stack.

4. Flash via CCS.

### Hub Server Build

1. Navigate to hub:

   ```bash

   cd hub

   mkdir build && cd build

   cmake .. && make

   ```

### Generate Protos

```bash

./tools/generate_protos.sh

```

## Usage

### For Players

1. Connect DSP via USB (ensure drivers installed).

2. Launch game:

   ```bash

   ./dhewm3 +set s_useDSP 1 +set net_dcf_mode 2

   ```

3. Adjust settings:

   - Audio: `s_audioModesEnabled 0` (disable zones), `s_audioModeBlendTime 1.0` (slower transitions).

   - Networking: `dcf_set_transport 0` (UDP), `dcf_status` (peer health).

4. Run hub server (if needed):

   ```bash

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

   ```

   Connect: `+set net_dcf_hub localhost:50051`.

### For Modders

1. **Place Audio Zones**:

   - In D3Edit, spawn `func_audio_mode`. Set keys: `"mode" "1"`, `"radius" "512"`, `"priority" "1"`, `"blend_type" "0"`.

2. **Script Events**:

   ```script

   void onPlayerEnter(entity zone) {

       sys.println("Entered mode " + zone.getKey("mode"));

       sys.playSound("snd_custom_cue");

   }

   ```

3. **Debug**:

   - `audioModesDebug 2`: Draw red spheres for active zones.

   - `listAudioModes`: List zone details.

   - `dcf_status`: Show network peer status.

4. **Tune**:

   - Audio: `s_audioMaxZones 10` (smaller maps).

   - Networking: `net_dcf_hub` for relay server.

## Architecture Overview

The fork integrates DSP audio and DCF networking into idTech4’s core systems, tailored for *Petabyte Madness*. Audio processing offloads to a USB DSP, while networking wraps `idAsyncServer`/`idAsyncClient` with Protobuf/gRPC.

```mermaid

graph TD

    A[idTech4 Game Loop] -->|Audio Data| B[idSoundSystemLocal]

    B -->|Listener/Emitters| C[idAudioModeManager]

    C -->|Mode IDs| D[idSoundHardware_DSP]

    D -->|Scene Data| E[libusb Driver]

    E -->|Bulk Transfer| F[TMS320C674x DSP]

    F -->|Processed Audio| E --> D --> B

    A -->|Network Data| G[idDCFNetwork]

    G -->|Wrap Async| H[idAsyncServer/idAsyncClient]

    H -->|Protobuf| I[Transport: UDP/TCP/WebSocket/gRPC]

    I -->|Reroute Check| J[Peer Map]

    J -->|Relay| K[DCF Hub Server]

    I -->|WASM Fallback| L[WebSocket]

    subgraph "Audio"

        C -->|Spatial Query| M[gameLocal.clip]

        F --> N[Stochastic Ray Tracing]

        N --> O[Convolution via DSPLIB]

    end

    subgraph "Networking"

        J --> P[gRPC/UDP Heartbeat]

        K --> Q[Dynamic Peering]

    end

```

## Modifications

- **Sound**: `snd_dsp.h/cpp` (DSP comms), modified `snd_system.cpp`, `snd_world.cpp`.

- **Game**: `AudioModeEntity.h/cpp`, `AudioModeManager.h/cpp`, `audio_modes.def`.

- **Networking**: `idDCFNetwork.h/cpp`, `dcf_transport.cpp` in `neo/framework/async/dcf/`.

- **Common**: Replaced `idNetworkSystem` with `idDCFNetwork` in `common.cpp`.

## Optimization and Edge Cases

- **Audio**:

  - O(log n) spatial queries via `gameLocal.clip`.

  - Batched USB transfers, cached IRs on DSP.

  - DSP disconnect: Hot-plug retries (`s_dspReconnectInterval`), OpenAL fallback.

  - Overlapping zones: Priority-based lerp/step blending.

- **Networking**:

  - Zero-copy Protobuf, <0.1% CPU overhead.

  - Frame-integrated health checks, graceful degradation (e.g., UDP fallback).

  - Hub server scales to 100+ clients at <2% CPU.

- **Edge Cases**:

  - No DSP/zones: Default audio mode.

  - Large maps: Cap zones (`s_audioMaxZones`).

  - WASM: WebSocket fallback for browsers.

## cVARs and Commands

- **Audio**:

  - `s_useDSP` (bool, 0): Enable DSP.

  - `s_audioModesEnabled` (bool, 1): Enable zones.

  - `s_audioModeBlendTime` (float, 0.5): Blend duration (s).

  - `s_audioMaxZones` (int, 20): Max zones.

  - `s_dspReconnectInterval` (int, 5000): Hot-plug poll (ms).

- **Networking**:

  - `net_dcf_mode` (int, 0): 0=client, 1=server, 2=P2P.

  - `dcf_set_transport` (int, 0): 0=UDP, 1=TCP, 2=WebSocket, 3=gRPC.

  - `dcf_status`: Print peer health.

- **Debug**:

  - `audioModesDebug [0/1/2]`: 0=off, 1=list, 2=draw zones.

  - `listAudioModes`: Dump zone details.

## Debug Tools

- `audioModesDebug 2`: Visualize active zones (red spheres).

- `listAudioModes`: Log zone info (name, mode, radius, position).

- `dcf_status`: Display network peer status and transport.

- Profile: `com_showFPS 1`.

## Contributing

Fork, create a feature branch, and submit PRs. Guidelines:

- Follow idTech4 style (`id*` prefixes, no exceptions).

- Test on Dhewm3; include unit tests for DSP math and networking.

- Maintain >85% coverage.

- Report bugs via GitHub Issues.

- Contact info@demod.ltd for major changes.

## License

GNU General Public License v3.0 (GPL-3.0). See [LICENSE](LICENSE).

## Resources and References

- **Dhewm3**: [github.com/dhewm/dhewm3](https://github.com/dhewm/dhewm3).

- **idTech4-DSP-Audio**: [github.com/yourusername/idTech4-DSP-Audio](https://github.com/yourusername/idTech4-DSP-Audio).

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

- **TI Documentation**: TMS320C674x DSP Reference (SPRUFE8B), DSPLIB.

- **idTech4**: [Fabien Sanglard’s Doom 3 Code Review](https://fabiensanglard.net/doom3/).

- **libusb**: [libusb.info](https://libusb.info/).

- **Protobuf/gRPC**: [grpc.io](https://grpc.io/).

- **Audio Ray Tracing**: US Patent 8139780B2, vaRays concepts.

For support, open an issue or contact info@demod.ltd.
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/alh477/idtech4-demod

Awesome Lists containing this project

README
