Skip to main content

Installation Guide

This guide covers installing NodeMod on your Half-Life server and setting up the development environment.

Server Requirements​

Supported Platforms​

  • HLDS Anniversary - Official Valve anniversary edition
  • HLDS steam_legacy beta - Steam legacy beta branch
  • ReHLDS - Community reimplementation of HLDS
  • Xash3D FWGS - Cross-platform Half-Life engine
  • Operating System: Linux (32-bit x86 architecture)

Prerequisites​

  • Metamod variant - One of the following:
    • Metamod - Original metamod
    • Metamod-P - Metamod Plus
    • Metamod-R - Metamod Redux
  • Half-Life game files - Valid Half-Life installation
  • Library dependencies - NodeMod is statically linked, so no additional Node.js installation required

Installing NodeMod​

Step 1: Download NodeMod​

Download the latest release from GitHub:

wget https://github.com/nodemod/nodemod-goldsrc/releases/download/v1.0.0/libnodemod.tar.gz
tar -xzf libnodemod.tar.gz

This will extract libnodemod.so and any additional files.

Or build from source following the instructions in the NodeMod repository.

Step 2: Create Directory Structure​

Create the required directory structure in your Half-Life server:

# Navigate to your Half-Life server directory and mod directory
cd /path/to/your-hlds-server/your-mod-dir

# Create NodeMod directories
mkdir -p addons/nodemod/dlls
mkdir -p addons/nodemod/plugins

Step 3: Install the Plugin​

Copy the NodeMod plugin to the dlls directory:

cp libnodemod.so addons/nodemod/dlls/
chmod +x addons/nodemod/dlls/libnodemod.so

Step 4: Register with Metamod​

Add NodeMod to your metamod plugins list by editing addons/metamod/plugins.ini:

# Add this line to plugins.ini
linux addons/nodemod/dlls/libnodemod.so

Step 5: Set Up Plugin Directory​

Navigate to the plugins directory and initialize your plugin project:

cd addons/nodemod/plugins

# Initialize npm project
npm init -y

# Install NodeMod core library
npm install @nodemod/core

# Install TypeScript development dependencies
npm install -D typescript @types/node

Plugin Directory Structure​

Your NodeMod installation should look like this:

your-hlds-server/
├── your-mod-dir/               # e.g., valve, cstrike, dmc, etc.
│   ├── addons/
│   │   ├── metamod/
│   │   │   └── plugins.ini     # Contains NodeMod registration
│   │   └── nodemod/
│   │       ├── dlls/
│   │       │   └── libnodemod.so    # NodeMod metamod plugin
│   │       └── plugins/             # Your plugin code lives here
│   │           ├── package.json     # Main plugin configuration
│   │           ├── tsconfig.json    # TypeScript configuration
│   │           ├── src/
│   │           │   └── index.ts     # Plugin entry point
│   │           ├── dist/
│   │           │   └── index.js     # Compiled plugin (auto-generated)
│   │           └── node_modules/    # npm dependencies
│   └── ... (other mod files)
├── hlds_linux                  # Half-Life server executable
└── ... (other Half-Life files)

Verification​

Start your Half-Life server to verify NodeMod is working:

./hlds_linux -game valve +map crossfire

You should see NodeMod initialization messages in the server console:

NodeMod: Initializing Node.js runtime...
NodeMod: Loading plugin from addons/nodemod/plugins/dist/index.js
NodeMod: Plugin loaded successfully

Troubleshooting​

Common Issues​

Plugin not loading

  • Verify plugins.ini contains the correct path to libnodemod.so
  • Check file permissions on libnodemod.so (should be executable)
  • Ensure metamod is installed and working

JavaScript errors

  • Make sure you've run npm run build to compile your TypeScript
  • Check that package.json has "main": "dist/index.js"
  • Verify Node.js modules are installed with npm install

Permission denied

  • Ensure the server process has read/write access to the addons/nodemod directory
  • Check that libnodemod.so has execute permissions

Debug Mode​

For debugging, you can run the server with additional logging:

./hlds_linux -game valve +map crossfire +developer 1

Next Steps​

Once NodeMod is installed and running:

  1. Create your first plugin following the Quick Start Guide
  2. Explore the API Reference to understand available features
  3. Check out Examples for common plugin patterns