Skip to main content

NodeMod Examples

This page provides code examples for NodeMod's core APIs - commands, events, players, CVARs, and more.

Looking for Admin Plugin Development?

If you want to create plugins for the AMX Mod X admin system (kick, ban, voting, permissions), see the Admin Plugin Development Guide instead. This page covers NodeMod's lower-level APIs.

For complete working examples, check out the Examples Repository on GitHub. For complete API documentation, see the API Reference.

Note: NodeMod runs standard Node.js code - you write scripts/modules that get imported from your main entry point, not traditional "plugins". The admin system has its own plugin loader for AMX Mod X-style functionality.

Command System​

Register and handle client/server commands:

import nodemodCore from '@nodemod/core';

const cmd = nodemodCore.cmd;

// Basic client command
cmd.registerClient('say_hello', (client: nodemod.Entity, args: string[]) => {
  const playerName = client.netname;
  nodemodCore.util.messageClient(client, `Hello ${playerName}!`);
});

// Command with arguments
cmd.registerClient('say_greet', (client: nodemod.Entity, args: string[]) => {
  const target = args[0] || 'World';
  nodemodCore.util.messageClient(client, `${client.netname} greets ${target}!`);
});

// Advanced command with full options
cmd.add({
  name: 'say_info',
  type: 'client',
  handler: (ctx: any) => {
    const message = `Player: ${ctx.client.netname}, Args: ${ctx.args.join(', ')}`;
    nodemodCore.util.messageClient(ctx.client, message);
  }
});

Event Handling​

Listen for game events with various patterns:

import nodemodCore from '@nodemod/core';

const events = nodemodCore.events;

// Basic event listener
events.on('dllClientConnect', (entity, name, address, rejectReason) => {
  console.log(`Player connecting: ${name} from ${address}`);
});

// Event with priority (higher priority executes first)
events.on('dllClientDisconnect', (entity) => {
  console.log(`Player ${entity.netname} disconnected`);
}, { priority: 10 });

// One-time event listener
events.once('dllServerActivate', (edict, edictCount, maxClients) => {
  console.log(`Server activated with max ${maxClients} clients`);
});

// Filtered event - only specific entities
events.filter('dllSpawn',
  (entity) => entity.classname === 'player',
  (entity) => {
    console.log(`Player ${entity.netname} spawned`);
  }
);

// Throttled event - max once per second
events.throttle('dllStartFrame', () => {
  const playerCount = nodemod.players.filter(p => p).length;
  console.log(`${playerCount} players online`);
}, 1000);

Player Management​

Work with connected players:

import nodemodCore from '@nodemod/core';

const player = nodemodCore.player;

// Get all connected players
nodemodCore.cmd.registerClient('players', (client) => {
  const allPlayers = player.getAll();

  if (allPlayers.length === 0) {
    nodemodCore.util.messageClient(client, 'No players connected');
    return;
  }

  let message = `Connected players (${allPlayers.length}):\n`;
  allPlayers.forEach(p => {
    message += `[${p.id}] ${p.name} - HP: ${p.health}, Frags: ${p.frags}\n`;
  });

  nodemodCore.util.messageClient(client, message);
});

// Find player by name or ID
nodemodCore.cmd.registerClient('playerinfo', (client, args) => {
  const searchTerm = args[0];
  let playerInfo = player.getById(parseInt(searchTerm)) || player.getByName(searchTerm);

  if (!playerInfo) {
    nodemodCore.util.messageClient(client, `Player '${searchTerm}' not found`);
    return;
  }

  const info = `Name: ${playerInfo.name}, Health: ${playerInfo.health}, Alive: ${playerInfo.isAlive}`;
  nodemodCore.util.messageClient(client, info);
});

// Teleport player
player.teleport(client, [x, y, z]);

// Modify player stats
player.setHealth(client, 150);
player.setArmor(client, 100);

Console Variables (CVARs)​

Register and manage server variables:

import nodemodCore from '@nodemod/core';

const cvar = nodemodCore.cvar;

// Register a new CVAR
cvar.register('my_plugin_enabled', '1', nodemod.FCVAR.SERVER, 'Enable my plugin');

// Get CVAR values
const strValue = cvar.getString('my_plugin_enabled');
const intValue = cvar.getInt('my_plugin_enabled');
const boolValue = cvar.getBool('my_plugin_enabled');

// Set CVAR value
cvar.setString('hostname', 'My Server');
cvar.setFloat('sv_gravity', 400);

// CVar wrapper for convenient access
const wrapped = cvar.wrap('my_plugin_enabled');
const value = wrapped.value;     // string
const intVal = wrapped.int;      // number
const floatVal = wrapped.float;  // number

// Watch for changes
cvar.watchVariable('sv_gravity', (current, previous, name) => {
  console.log(`Gravity changed from ${previous} to ${current}`);
}, 500);

Messaging​

Send messages to players:

import nodemodCore from '@nodemod/core';

const player = nodemodCore.player;

// Chat message to specific player
nodemodCore.util.sendChat('Hello!', playerEntity);

// Chat message to all players
nodemodCore.util.sendChat('Server announcement!', null);

// Console message
nodemod.eng.clientPrintf(playerEntity, nodemod.PRINT_TYPE.print_console, 'Console message\n');

// Center screen message
nodemod.eng.clientPrintf(playerEntity, nodemod.PRINT_TYPE.print_center, 'Center message');

// Different message types via player module
player.sendMessage(client, 'Chat message', 'chat');
player.sendMessage(client, 'HUD message', 'hud');
player.sendMessage(client, 'Center message', 'center');
player.sendMessage(client, 'Console message', 'console');

// Broadcast to all players
player.broadcast('Announcement to everyone!', 'chat');

Sound​

Play sounds:

import nodemodCore from '@nodemod/core';
import { SoundChannel } from '@nodemod/core/sound';

const sound = nodemodCore.sound;

// Emit sound with full options
sound.emitSound({
  entity: playerEntity,
  sound: 'weapons/knife_deploy1.wav',
  channel: SoundChannel.voice,
  volume: 0.8,
  pitch: 100
});

// Play sound to specific client
sound.emitClientSound(client, 'buttons/button1.wav');

// Ambient sound at position
sound.emitAmbientSound(
  [100, 200, 300],      // Position
  'ambience/wind1.wav', // Sound file
  0.5,                  // Volume
  2.0,                  // Attenuation
  0,                    // Flags
  90                    // Pitch
);

// Broadcast sound to all
sound.broadcastSound('events/achievement.wav', {
  volume: 0.9,
  pitch: 110
});

// Stop sound on entity
sound.stopSound(client, SoundChannel.voice);

Entity Operations​

Create and manipulate entities:

import nodemodCore from '@nodemod/core';

const entity = nodemodCore.entity;

// Find entities by class
const buttons = entity.find({ className: 'func_button' });

// Find spawn points
const spawns = entity.find({ className: 'info_player_deathmatch' });

// Create entity
const newEntity = nodemod.eng.createNamedEntity('info_target');
newEntity.origin = [100, 200, 300];
newEntity.targetname = 'my_target';

// Entity properties
newEntity.health = 100;
newEntity.solid = nodemod.SOLID.SOLID_BBOX;
newEntity.movetype = nodemod.MOVETYPE.MOVETYPE_NONE;

More Resources​