Installation Guide

Welcome to NodeMod - a metamod plugin that brings Node.js and a complete AMX Mod X admin system to Half-Life servers!

What You Get

NodeMod comes as a complete package with:

• Full AMX Mod X Admin System - Kick, ban, slay, slap, map changes, voting, chat commands, and more
• Familiar Configuration - Same users.ini, plugins.ini, and amxx.cfg format you know
• Multi-language Support - Localization files included
• Extensible with JavaScript/TypeScript - Write custom scripts using modern development tools

Supported Platforms

Architecture	Download	Platforms
x86 (32-bit)	nodemod_x86.tar.gz	HLDS, ReHLDS, Xash3D FWGS
x64 (64-bit)	nodemod_x64.tar.gz	Xash3D FWGS

Installation

Step 1: Download NodeMod

Download the appropriate package from the releases page:

# For 64-bit servers (Xash3D FWGS)
wget https://github.com/nodemod/nodemod-goldsrc/releases/latest/download/nodemod_x64.tar.gz

# For 32-bit servers (HLDS, ReHLDS)
wget https://github.com/nodemod/nodemod-goldsrc/releases/latest/download/nodemod_x86.tar.gz

Step 2: Extract to Your Mod Directory

Navigate to your mod directory (e.g., valve, cstrike, dmc) and extract:

cd /path/to/hlds/valve
tar -xzf /path/to/nodemod_x64.tar.gz

This creates the complete addons/nodemod/ structure with everything pre-configured.

Step 3: Install Metamod (if not already installed)

NodeMod runs as a metamod plugin. If you don't have metamod:

1. Download Metamod-R (recommended) or Metamod
2. Extract to addons/metamod/
3. Edit your mod's liblist.gam file, changing:

   gamedll_linux "dlls/hl.so"

   to:

   gamedll_linux "addons/metamod/dlls/metamod.so"

Step 4: Register NodeMod with Metamod

Add NodeMod to addons/metamod/plugins.ini:

linux addons/nodemod/dlls/libnodemod.so

Step 5: Configure Admin Accounts

Edit addons/nodemod/configs/users.ini to add your admins:

; Format: "auth" "password" "access_flags" "account_flags"
;
; Access flags (what admin can do):
;   a - immunity    b - reservation   c - kick
;   d - ban         e - slay/slap     f - map change
;   g - cvars       h - configs       i - chat
;   j - vote        k - password      l - rcon
;
; Account flags (how admin authenticates):
;   c - SteamID     d - IP address    e - no password needed

; Example: Full admin via SteamID
"STEAM_0:0:123456" "" "abcdefghijklmnop" "ce"

; Example: Moderator via IP (kick/ban only)
"192.168.1.100" "" "cd" "de"

See the Admin System Guide for complete flag documentation.

Step 6: Start Your Server

./hlds_linux -game valve +map crossfire

You should see NodeMod initialize:

[NodeMod] Initializing Node.js runtime...
[NodeMod] Loading plugin from addons/nodemod/plugins/dist/index.js
[AMXX] Admin Base Plugin initialized
[AMXX] Loaded 1 admin from file

Test admin commands in the console:

amx_help

Using the Admin System

Once installed, you have access to all AMX Mod X commands:

Command	Description
amx_kick <player>	Kick a player
amx_ban <player> <minutes>	Ban a player
amx_slay <player>	Kill a player
amx_map <mapname>	Change map
amx_vote <question> <option1> <option2>	Start a vote
amx_help	List available commands
@ <message>	Admin-only chat

See the full Admin System Guide for all commands and configuration options.

Directory Structure

After installation, your mod directory should look like:

your-mod-dir/                    # e.g., valve, cstrike
├── liblist.gam                  # Modified to load metamod
├── addons/
│   ├── metamod/
│   │   ├── dlls/
│   │   │   └── metamod.so
│   │   └── plugins.ini          # Lists nodemod
│   └── nodemod/
│       ├── dlls/
│       │   └── libnodemod.so    # NodeMod plugin
│       ├── configs/
│       │   ├── users.ini        # Admin accounts
│       │   ├── plugins.ini      # Enabled admin plugins
│       │   ├── amxx.cfg         # Admin system settings
│       │   ├── maps.ini         # Map rotation
│       │   ├── cmds.ini         # Custom commands
│       │   └── ...
│       ├── data/
│       │   └── lang/            # Localization (30+ files)
│       ├── logs/                # Server logs
│       └── plugins/
│           ├── package.json
│           ├── tsconfig.json
│           ├── dist/            # Compiled plugins (ready to use)
│           ├── src/             # TypeScript source
│           └── node_modules/    # Dependencies (included)
└── ...

Configuration Files

plugins.ini - Enabled Plugins

Controls which admin plugins are loaded:

; Admin Base - Always one has to be activated
admin           ; admin base (required for any admin-related)

; Basic
admincmd        ; basic admin console commands
adminhelp       ; help command for admin console commands
adminslots      ; slot reservation

; Menus
menufront       ; front-end for admin menus
plmenu          ; players menu (kick, ban, client cmds.)
mapsmenu        ; maps menu (vote, changelevel)

; Chat / Messages
adminchat       ; console chat commands
adminvote       ; vote commands

; Map related
nextmap         ; displays next map in mapcycle
mapchooser      ; allows to vote for next map

amxx.cfg - Admin Settings

Common settings:

amx_mode 1                    // Admin auth mode (1=normal, 2=strict)
amx_show_activity 2           // Show admin actions (0=none, 1=admins, 2=all)
amx_vote_ratio 0.02           // Minimum vote ratio
amx_vote_time 10              // Vote duration in seconds

Troubleshooting

NodeMod not loading

1. Check metamod is working:

   meta list

   Should show NodeMod in the list.

2. Verify file permissions:

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

3. Check plugins.ini path is correct

Admin commands not working

1. Verify your SteamID in users.ini matches your actual SteamID
2. Check the server console for authentication messages
3. Run amx_reloadadmins after editing users.ini

JavaScript errors

If you see JavaScript errors in the console:

1. The pre-built plugins should work out of the box
2. If you modified source files, run npm run build in the plugins directory
3. Check that package.json has "main": "dist/index.js"

Updating NodeMod

To update to a new version:

1. Download the new release
2. Back up your configs/ directory
3. Extract the new package (it will overwrite dlls/ and plugins/)
4. Restore your configs/ if needed

Your users.ini and other config files are preserved during normal extraction since they already exist.

---

Go Deeper: Custom Development

Want to extend NodeMod? NodeMod is built on Node.js, so you can write custom scripts using JavaScript or TypeScript.

Development Requirements

• Node.js 18.0 or above (for development only - not needed on the server)
• TypeScript (recommended)

Creating a Custom Script

The source code is in addons/nodemod/plugins/src/. You can modify existing files or add your own:

// addons/nodemod/plugins/src/myplugin.ts
import nodemodCore from '@nodemod/core';

// Register a custom command
nodemodCore.cmd.registerClient('hello', (client, args) => {
  if (!client) return;
  nodemodCore.util.messageClient(client, `Hello, ${client.netname}!`);
});

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

console.log('My custom script loaded!');

Import your script in src/index.ts:

import './myplugin';

Build and restart:

cd addons/nodemod/plugins
npm run build

Learn More

• Quick Start Guide - Detailed development guide
• Examples - Code examples for all APIs
• API Reference - Complete API documentation
• Admin Plugin Development - Creating AMX Mod X admin plugins