Quick Start Guide

Get your first NodeMod plugin running in minutes! This guide assumes you have already installed NodeMod on your server.

Your First Plugin

Let's create a simple "Hello World" plugin that demonstrates core NodeMod functionality.

Step 1: Set Up Your Plugin Project

Navigate to your plugins directory and set up the project:

cd /path/to/hlds/addons/nodemod/plugins

# Create package.json
cat > package.json << 'EOF'
{
  "name": "my-first-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"
  }
}
EOF

# Create TypeScript configuration
cat > tsconfig.json << 'EOF'
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
EOF

# Install dependencies
npm install

# Create source directory
mkdir -p src

Step 2: Create Your Plugin

Create src/index.ts with your first NodeMod plugin:

import nodemodCore from '@nodemod/core';

console.log('🚀 My First NodeMod Plugin Loading...');

// Send a welcome message to all players
nodemodCore.util.messageAll('🎮 Welcome to NodeMod!');

// Add a simple command that any player can use
nodemodCore.cmd.add({
  name: 'hello',
  description: 'Say hello to everyone',
  handler: (ctx) => {
    const playerName = ctx.client.name;
    nodemodCore.util.messageAll(`👋 ${playerName} says hello to everyone!`);
  }
});

// Add an admin-only command
nodemodCore.cmd.add({
  name: 'welcome',
  description: 'Send a welcome message',
  access: 'admin',
  handler: (ctx) => {
    nodemodCore.util.messageAll('🎉 Admin welcomes all players to the server!');
  }
});

// Handle player connections
nodemodCore.events.on('playerConnect', (player) => {
  console.log(`Player connected: ${player.name} (ID: ${player.id})`);
  
  // Welcome the new player
  setTimeout(() => {
    nodemodCore.util.message(player.id, `Welcome ${player.name}! Type "hello" to greet everyone.`);
  }, 2000);
});

// Handle player disconnections
nodemodCore.events.on('playerDisconnect', (player) => {
  console.log(`Player disconnected: ${player.name} (ID: ${player.id})`);
  nodemodCore.util.messageAll(`👋 ${player.name} has left the server`);
});

console.log('✅ My First NodeMod Plugin Loaded Successfully!');

Step 3: Build and Test

Build your plugin and start the server:

# Build the TypeScript to JavaScript
npm run build

# Start your Half-Life server
cd /path/to/hlds
./hlds_linux -game valve +map crossfire

Step 4: Test Your Plugin

Connect to your server and test the functionality:

1. Check console output - You should see plugin loading messages
2. Test the hello command - Type hello in chat
3. Test admin command - Type welcome (requires admin access)
4. Connect/disconnect - Watch the welcome messages

What You Just Built

Your first plugin demonstrates several key NodeMod concepts:

Commands System

nodemodCore.cmd.add({
  name: 'hello',           // Command name
  description: 'Say hello',// Help text
  handler: (ctx) => { }    // Function to run
});

Event Handling

nodemodCore.events.on('playerConnect', (player) => {
  // React to game events
});

Messaging System

// Message all players
nodemodCore.util.messageAll('Hello everyone!');

// Message specific player
nodemodCore.util.message(playerId, 'Hello player!');

Common Plugin Patterns

Conditional Logic

nodemodCore.cmd.add({
  name: 'stats',
  handler: (ctx) => {
    const player = nodemodCore.player.getById(ctx.client.id);
    if (!player) {
      nodemodCore.util.message(ctx.client.id, 'Error: Player not found');
      return;
    }
    
    nodemodCore.util.message(ctx.client.id, `Health: ${player.health}, Armor: ${player.armor}`);
  }
});

Timer-Based Actions

// Send periodic messages
setInterval(() => {
  const players = nodemodCore.player.getAll();
  if (players.length > 0) {
    nodemodCore.util.messageAll(`📊 Server has ${players.length} players online`);
  }
}, 300000); // Every 5 minutes

Development Workflow

For efficient development, use watch mode:

# Terminal 1 - Watch TypeScript compilation
npm run dev

# Terminal 2 - Restart server when needed
./hlds_linux -game valve +map crossfire

This automatically rebuilds your JavaScript when you modify TypeScript files.

Next Steps

Now that you have a working plugin:

1. Explore the API Reference - Learn about all available functions
2. Check out Examples - See common plugin patterns
3. Join the community - Share your plugins and get help

Troubleshooting

Plugin not loading?

• Check that npm run build completed successfully
• Verify dist/index.js exists
• Look for error messages in the server console

Commands not working?

• Make sure players have the correct access level for admin commands
• Check that command names don't conflict with existing game commands

Build errors?

• Run npm install to ensure dependencies are installed
• Check TypeScript errors with npx tsc --noEmit