Nodemod

A Metamod plugin for integrating Node.js directly into Half-Life 1 engine. This plugin is intended as a more functional and convenient replacement for AMX Mod X or LuaMod. It is also compatible with Xash3D FWGS.

Note: The original Nodemod concept was created by TheEVolk. This version represents a complete modernization and enhancement of the project:

• Updated from legacy Node.js to Node.js v24.6.0
• Added all remaining engine and DLL functions
• Created GitHub organization and website
• Published npm packages and examples
• Provided compiled library distribution

Comprehensive documentation

More comprehensive documentation is available at https://nodemod.org/

Directory structure

|-- /
|-- deps                       # 3rdparty dependencies (Node.js v24.6.0)
|-- scripts                    # auxiliary scripts (generating the autocode)
|-- src                        # nodemod source files
|  |-- auto                    # auto-generated code
|  |  |-- dll_events.cpp       # events from gamedll
|  |  |-- dll_functions.cpp    # bindings to gamedll methods
|  |  |-- engine_events.cpp    # events from engine
|  |  |-- engine_functions.cpp # bindings to engine methods
|  |-- lib                     # nodemod library external api to metamod
|  |-- node                    # v8 and nodejs internal code and api
|  |-- structures              # structures between engine and jscode
|  |-- bindings                # util methods and core functional, passed to JS

Compilation

Note: Nodemod is currently locked to x86 architecture for compatibility with Half-Life servers.

Docker Build (Recommended)

./build-docker.sh               # Build Docker image
./build-node.sh                 # Build Node.js from source
./build-nodemod.sh              # Final the nodemod plugin

Manual Build

Pre-installing dependencies:

sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install gcc-multilib g++-multilib cmake ninja-build python3 python3-distutils

Building instructions:

git clone --recursive https://github.com/stevenlafl/xash3d-nodemod.git
cd xash3d-nodemod

# build node
./scripts/build-node-from-source.sh
# convert thin to fat archives
./scripts/fat_archive.sh deps/node/out/Release/obj.target

# build nodemod
cmake -E make_directory build
cd build
cmake .. --preset linux-x86-debug
cmake --build . --config Debug

Notes

The /auto folder is auto-generated by

node scripts/buildEvents.js

Installation and launch

1. You should make sure that Metamod is already installed on your server
2. Create a nodemod directory in addons
3. Download examples from https://github.com/nodemod/examples-goldsrc or create your own plugin using @nodemod/core
4. Extract the example to addons/nodemod/plugins
5. Create the addons/nodemod/dlls directory
6. Move the compiled libnodemod.so to the addons/nodemod/dlls directory
7. In plugins.ini from metamod, add the line linux addons/nodemod/dlls/libnodemod.so
8. In the plugins directory, install npm dependencies: npm i
9. Build TypeScript code: npm run build

Note: Currently, nodemod runs only one plugin - the script defined in the "main" field of addons/nodemod/plugins/package.json. Multi-plugin functionality is not yet implemented.

TypeScript

Complete typedefs and a helper library are available at @nodemod/core. The example repository contains an example on using typescript with a build process. Sourcecode for @nodemod/core is available at https://github.com/nodemod/core-goldsrc

Alternative workflow

You can run your TypeScript code without precompilation using the ts-node library.

1. Install ts-node: npm i ts-node
2. Pass there env variable to your start script: export NODE_OPTIONS="--loader ts-node/esm"
3. Make sure that the main field is in your package.json leads to a TS file

RoadMap

• Rigor testing
• Multi-plugin system

Credits

• TheEVolk (Maksim Nikiforov) - Original Nodemod creator
• iAmir (Amyr Aahmady) - For his samp-node project inspiration
• SNMetamorph - Code modernization to C++17 and build system refactoring
• stevenlafl (Steven Linn) - Complete modernization: Node.js v24.6.0 upgrade, added all engine/DLL functions, GitHub organization, npm packages, compiled distributions