Debugging NodeMod

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

Setting Up Debug Mode

To enable debugging, add the following code to your main entry 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 code here...
console.log('NodeMod loaded with debugging enabled!');

// Keep the process running for debugging
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 NodeMod instance

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, NodeMod 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. NodeMod 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/nodemod/plugins"
    }
  ]
}

2. Start your Half-Life server with debugging enabled
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

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.

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