Skip to main content

Getting Started with NodeMod

Welcome to NodeMod - the metamod plugin that brings Node.js 24.6.0 directly into Half-Life!

NodeMod enables you to write Half-Life server plugins using modern JavaScript and TypeScript, giving you access to the entire npm ecosystem while interacting with the classic GoldSrc engine.

What is NodeMod?​

NodeMod is a metamod plugin that embeds a full Node.js runtime into Half-Life servers. This allows you to:

  • Write server plugins using JavaScript or TypeScript
  • Use npm packages and modern JS features
  • Interact with Half-Life's engine, players, and entities through a rich API
  • Develop with familiar tools and workflows

System Requirements​

Server Requirements​

  • Half-Life Dedicated Server (HLDS) or Xash3D FWGS
  • Metamod installed and configured
  • Linux (32-bit x86 architecture)

Development Requirements​

  • Node.js version 18.0 or above
  • TypeScript (recommended for best development experience)

Quick Installation​

  1. Download the plugin: Get the latest libnodemod.so from the releases page

  2. Install to your server:

    # Create the nodemod directory structure
    mkdir -p /path/to/hlds/addons/nodemod/dlls
    mkdir -p /path/to/hlds/addons/nodemod/plugins

    # Copy the plugin
    cp libnodemod.so /path/to/hlds/addons/nodemod/dlls/

  3. Register with Metamod: Add this line to your addons/metamod/plugins.ini:

    linux addons/nodemod/dlls/libnodemod.so

Your First Plugin​

NodeMod runs a single entrypoint defined in your package.json. Here's how to set up your first plugin:

# Navigate to your plugins directory
cd /path/to/hlds/addons/nodemod/plugins

# Initialize with npm
npm init -y

# Install NodeMod core and TypeScript
npm install @nodemod/core
npm install -D typescript @types/node

Configure your package.json:

{
  "name": "my-nodemod-plugin",
  "version": "1.0.0",
  "main": "dist/index.js",
  "type": "commonjs",
  "scripts": {
    "build": "tsc",
    "build:watch": "tsc --watch",
    "clean": "rm -rf dist",
    "prebuild": "npm run clean",
    "dev": "npm run build:watch"
  },
  "dependencies": {
    "@nodemod/core": "^1.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "@types/node": "^20.0.0"
  }
}

Create a tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Create your main plugin file at src/index.ts:

import nodemodCore from '@nodemod/core';

// Send a welcome message when the plugin loads
nodemodCore.util.messageAll('🎮 NodeMod plugin is loaded!');

// Add a simple admin command
nodemodCore.cmd.add({
  name: 'hello',
  access: 'admin', 
  handler: (ctx) => {
    nodemodCore.util.messageAll(`Hello from ${ctx.client.name}!`);
  }
});

// Handle player connections
nodemodCore.events.on('playerConnect', (player) => {
  console.log(`Player ${player.name} connected`);
});

console.log('NodeMod plugin initialized!');

Build and run:

# Build your TypeScript to JavaScript
npm run build

# Start your Half-Life server - NodeMod will automatically run dist/index.js

Project Structure​

Your NodeMod plugin directory should look like this:

addons/nodemod/plugins/
├── package.json          # Main configuration with "main": "dist/index.js"
├── tsconfig.json         # TypeScript configuration
├── src/
│   └── index.ts          # Your TypeScript source code
├── dist/
│   └── index.js          # Built JavaScript (generated by tsc)
└── node_modules/         # npm dependencies

Development Workflow​

  1. Write TypeScript in the src/ directory
  2. Build with TypeScript compiler: npm run build
  3. Use watch mode during development: npm run dev
  4. NodeMod automatically loads dist/index.js when the server starts

Next Steps​