alh477/dcf-shim repository overview

⁠DCF Standalone Shim

High-Performance Protocol Bridge for HydraMesh Compatibility

Copyright (c) 2026 DeMoD LLC. All rights reserved.

Licensed under the BSD-3-Clause License⁠.

⁠Overview

The DCF Standalone Shim is a lightweight, asynchronous UDP relay designed to bridge the gap between legacy game engine network protocols (e.g., Zandronum, Doom, Quake) and the DeMoD Communications Framework (DCF) HydraMesh binary protocol.

It functions as a bidirectional tunnel that:

Ingress (Legacy -> DCF): Wraps raw UDP datagrams into HydraMesh-compliant ProtoMessage envelopes.

1. Egress (DCF -> Legacy): Unwraps HydraMesh packets and forwards the raw payloads back to the game client.

This architecture allows developers to integrate legacy systems into a DCF mesh without modifying the original game source code or the core DCF node logic.

⁠Features

• Zero-Latency Overhead: Built with Rust and the Tokio async runtime for high-throughput packet processing.
• Automatic Session Tracking: Dynamically tracks and updates the active game client address to handle NAT traversal and session reconnections.
• Binary Protocol Compliance: Implements the 17-byte HydraMesh binary header (Type/Sequence/Timestamp/Length).
• Minimal Footprint: Standalone binary with no external heavy dependencies, optimized for sidecar container deployments.

⁠Quick Start

⁠1. Requirements

• Rust: 1.83+ (Alpine-compatible)
• Docker: (Optional) for containerized deployment

⁠2. Manual Build

cargo build --release

⁠3. Execution

To bridge a Zandronum client (port 9999) to a local DCF Node (port 7777):

./target/release/dcf-shim --ingress-port 9999 --node-target 127.0.0.1:7777

⁠Docker Deployment

The shim is best deployed as a sidecar container alongside your DCF node.

⁠Build the Image

docker build -t demod/dcf-shim:latest .

⁠Run with Host Networking

To ensure minimal latency and direct access to local DCF nodes:

docker run -d --name dcf-shim \
  --network host \
  demod/dcf-shim:latest \
  --ingress-port 9999 \
  --node-target 127.0.0.1:7777

⁠Configuration Reference

⁠Technical Specifications

⁠Protocol Wrapping

The shim utilizes Message Type 2 (AUDIO) for raw byte transport. This type is optimized for high-frequency data streams and allows the core DCF Node to handle game data without requiring a specific protobuf schema for every game event.

⁠Header Structure

All packets forwarded to the Node contain the standard 17-byte HydraMesh header:

• Type: 1 Byte (0x02)
• Sequence: 4 Bytes (Big-Endian)
• Timestamp: 8 Bytes (Big-Endian, microseconds)
• Payload Length: 4 Bytes (Big-Endian)

⁠License

BSD 3-Clause License

Copyright (c) 2026, DeMoD LLC All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.