Debugging NodeMod Plugins

NodeMod supports full Node.js debugging capabilities using the built-in inspector module. This allows you to debug your Half-Life plugins with modern development tools like Chrome DevTools or VS Code.

Setting Up Debug Mode

To enable debugging in your NodeMod plugin, add the following code to your main plugin file:

import nodemodCore from '@nodemod/core';
import inspector from 'inspector';

// Expose nodemodCore globally for debugging
(global as any).nodemodCore = nodemodCore;

// Start the inspector on port 9229
inspector.open(9229, 'localhost');

// Your plugin code here...
console.log('NodeMod plugin loaded with debugging enabled!');

// Keep the plugin running for testing purposes
process.stdin.resume();

Key Components Explained

Inspector Module

The Node.js inspector module provides access to the V8 debugging protocol:

• inspector.open(9229, 'localhost') - Opens the debug port on localhost:9229
• This allows external debuggers to connect to your running plugin

Global NodeMod Access

(global as any).nodemodCore = nodemodCore;

Exposing nodemodCore globally allows you to inspect and interact with the Half-Life engine from the debugger console.

Process Management

process.stdin.resume();

This is crucial - it keeps the Node.js process alive during debugging sessions. Without this, the plugin may exit immediately after initialization.

Connecting Your Debugger

Chrome DevTools

1. Open Chrome and navigate to chrome://inspect
2. Click "Open dedicated DevTools for Node"
3. Your NodeMod plugin should appear in the Remote Target list
4. Click "inspect" to start debugging

VS Code

1. Create a .vscode/launch.json configuration:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to NodeMod",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "address": "localhost",
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/path/to/your/plugin"
    }
  ]
}

2. Start your Half-Life server with the debugger-enabled plugin
3. In VS Code, press F5 or use "Run and Debug" to attach

Debugging Features

Once connected, you have full access to:

• Set breakpoints in your TypeScript/JavaScript code
• Step through execution line by line
• Inspect variables and object properties
• Evaluate expressions in the console
• Access nodemodCore functions directly from the console
• Monitor engine state in real-time

Example Debug Session

// In your plugin
import nodemodCore from '@nodemod/core';
import inspector from 'inspector';

(global as any).nodemodCore = nodemodCore;
inspector.open(9229, 'localhost');

// Set a breakpoint here
nodemodCore.on('player_connect', (player) => {
  console.log(`Player ${player.netname} connected`);
  // Inspect player object in debugger
  debugger; // Explicit breakpoint
});

process.stdin.resume();

In the debugger console, you can then execute:

// Access the Half-Life engine directly
nodemodCore.players.length
nodemodCore.engine.getMapName()
nodemodCore.dll.getAllEntities()

Production Considerations

Remember to remove or conditionally disable debugging code in production:

const DEBUG_MODE = process.env.NODE_ENV === 'development';

if (DEBUG_MODE) {
  (global as any).nodemodCore = nodemodCore;
  inspector.open(9229, 'localhost');
  process.stdin.resume();
}

Troubleshooting

Port already in use: Change the port number if 9229 is occupied:

inspector.open(9230, 'localhost'); // Use different port

Can't connect: Ensure your Half-Life server allows the debugging port through any firewalls.

Plugin exits immediately: Make sure you have process.stdin.resume() to keep the process alive.