Contributing

Welcome Contributors

CoD4 Unleashed Server is an open-source project that welcomes contributions from the community. Whether you’re fixing bugs, adding features, improving documentation, or creating plugins, your contributions help make the server better for everyone.

Project Information

Repository

The project is hosted on GitHub:

CoD4-Unleashed-Server

Main repository for CoD4 Unleashed Server source code

License

This project is released under the GNU Affero General Public License v3.0 (AGPL-3.0). Key points about AGPL-3.0:

You can freely use, modify, and distribute this software
If you modify the server and run it publicly, you must make your source code available
Any derivative works must also be licensed under AGPL-3.0
Network use is considered distribution (key difference from GPL)

Read the full license in the LICENSE file.

Ways to Contribute

Report Bugs

Found a bug? Open an issue on GitHub with detailed information

Fix Issues

Browse open issues and submit pull requests with fixes

Add Features

Implement new functionality or enhance existing features

Write Documentation

Improve docs, add examples, or create tutorials

Create Plugins

Develop plugins using the Plugin API

Test Changes

Test pull requests and provide feedback

Getting Started

Fork the repository

Create your own fork on GitHub:

# Clone your fork
git clone https://github.com/YOUR_USERNAME/CoD4-Unleashed-Server.git
cd CoD4-Unleashed-Server

# Add upstream remote
git remote add upstream https://github.com/atrX/CoD4-Unleashed-Server.git

Set up development environment

Install required dependencies for building:

# Debian/Ubuntu 64-bit
sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install nasm:i386 build-essential gcc-multilib g++-multilib libcurl4-openssl-dev:i386

# See Building from Source for more platforms

Create a branch

Create a feature branch for your changes:

git checkout -b feature/my-new-feature
# or
git checkout -b fix/bug-description

Make your changes

Write your code following the project conventions:

Follow existing code style
Add comments for complex logic
Update documentation if needed
Test your changes thoroughly

Build and test

Compile and test your changes:

# Build the project
./build_elf.sh

# Test the server
cd bin
./cod4u_lnx +set fs_game "" +map mp_crash

Commit your changes

Write clear commit messages:

git add .
git commit -m "Add feature: Brief description of change"

# Good commit message examples:
# "Fix memory leak in plugin handler"
# "Add support for custom HTTP headers"
# "Improve error handling in JSON parser"

Push and create pull request

Push your branch and create a PR:

git push origin feature/my-new-feature

Then open a pull request on GitHub with:

Clear description of changes
Why the change is needed
How to test it
Any related issue numbers

Code Guidelines

Code Style

The project uses consistent coding style across the codebase:

C Code Style

// Use K&R style bracing
if (condition)
{
    doSomething();
}

// Function definitions
void MyFunction(int param1, char *param2)
{
    // Function body
}

// Variable naming
int myVariable;          // camelCase for locals
static int g_globalVar;  // g_ prefix for globals

// Constants
#define MAX_PLAYERS 64   // UPPER_CASE

The project includes .clang-format configuration:

# Format code automatically
clang-format -i src/myfile.c

Assembly Code Style

; NASM style comments
; Clear section labels

section .text

global _MyFunction
_MyFunction:
    push ebp
    mov ebp, esp
    ; Function code
    pop ebp
    ret

GSC Code Style

// Function naming: camelCase
myFunction()
{
    // Variable naming: camelCase
    myVar = 123;
    
    // Clear conditionals
    if (isDefined(myVar))
    {
        // Code
    }
}

Editor Configuration

The project includes .editorconfig for consistent formatting:

root = true

[*]
charset = utf-8
indent_style = space
indent_size = 4
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

Most modern editors support EditorConfig automatically.

Code Quality

Compile without warnings

Fix all compiler warnings:

# Build with all warnings enabled
gcc -Wall -Wextra -Werror ...

Test thoroughly

Test your changes:

Test on both Linux and Windows if possible
Test with various configurations
Test with existing mods and plugins
Check for memory leaks with valgrind (Linux)

Document your code

Add documentation:

Comment complex algorithms
Document new functions
Update API documentation
Add usage examples

Developing Plugins

Plugin Development Setup

Get the plugin starter pack

The plugins/ directory contains:

readme.txt: Plugin API documentation
Example plugins
Plugin header files

Create your plugin

#include "plugin_includes.h"

// Plugin initialization
PLUGIN_ENTRY()
{
    Plugin_Printf("My Plugin loaded!\n");
    return 0;
}

// Event handler example
void OnTenSeconds()
{
    Plugin_Printf("Ten seconds passed\n");
}

Build your plugin

# Linux
gcc -m32 -shared -fPIC -o plugins/myplugin.so myplugin.c -Iplugins/

# Windows (MinGW)
gcc -m32 -shared -o plugins/myplugin.dll myplugin.c -Iplugins/ -Llib/ -lcom_plugin

Test your plugin

# In server console or config
loadplugin myplugin

# Check it loaded
pluginlist

Plugin API Guidelines

Memory Management: Always use Plugin_Malloc() and Plugin_Free() instead of standard malloc/free. The plugin system tracks allocations to prevent memory leaks when plugins are unloaded.

// CORRECT
void *data = Plugin_Malloc(1024);
// Use data...
Plugin_Free(data);

// WRONG - Will cause issues!
void *data = malloc(1024);  // DON'T DO THIS
free(data);                 // DON'T DO THIS

Available Plugin Events

Plugins can hook into various server events:

void OnTenSeconds()      // Called every 10 seconds
void OnOneSecond()        // Called every second  
void OnFrame()            // Called every frame
void OnPlayerConnect()    // Player connecting
void OnPlayerDisconnect() // Player disconnecting
void OnInfoRequest()      // Server info request
void OnPlayerSpawn()      // Player spawned
void OnPlayerKilled()     // Player killed
// See plugin documentation for full list

Plugin Types

Standard Plugin
Library Plugin
Script-Library Plugin

Regular plugin that can be loaded and unloaded:

PLUGIN_ENTRY() { ... }

Exports functions for other plugins (cannot be unloaded):

PLUGIN_EXPORT void MyExportedFunction() { ... }

Exports functions to GSC scripts (cannot be unloaded):

PLUGIN_EXPORT_SCRIPT void MyGSCFunction() { ... }

Pull Request Guidelines

Before Submitting

Checklist

Code compiles without errors or warnings
Changes are tested on Linux and/or Windows
Code follows project style guidelines
Comments added for complex logic
Documentation updated if needed
Commit messages are clear and descriptive
No unnecessary files included (binaries, IDE configs, etc.)
Changes are focused on a single issue/feature

PR Description Template

## Description
Brief description of what this PR does.

## Motivation
Why is this change needed? What problem does it solve?

## Changes
- List of specific changes made
- Breaking changes (if any)

## Testing
How was this tested?
- [ ] Tested on Linux
- [ ] Tested on Windows
- [ ] Tested with existing mods
- [ ] Tested with plugins

## Related Issues
Fixes #123
Related to #456

Review Process

Automated checks

GitHub Actions runs automated checks on your PR

Code review

Project maintainers review your code and provide feedback

Address feedback

Make requested changes and push updates to your branch

Approval and merge

Once approved, maintainers will merge your PR

Reporting Bugs

When reporting bugs, include:

System Information

Operating system and version
Server version (from console/log)
Architecture (32-bit/64-bit)
Build type (pre-built binary or compiled from source)

Bug Description

Clear description of the issue
Expected behavior vs actual behavior
When the issue started occurring
Frequency (always, sometimes, rarely)

Reproduction Steps

Step-by-step instructions to reproduce
Specific configuration or setup needed
Any relevant commands or actions

Logs and Output

# Include relevant log excerpts
# main/games_mp.log
# Console output
# Error messages

Additional Context

List of loaded plugins
Active mods or modifications
Recent changes to configuration
Screenshots or videos if applicable

Community

Getting Help

Forum

Ask questions and discuss with the community

Documentation

Official Scripting API reference

GitHub Issues

Report bugs and request features

GitHub Discussions

General discussions and questions

Stay Updated

Keep your fork in sync with upstream:

# Fetch upstream changes
git fetch upstream

# Merge into your main branch
git checkout main
git merge upstream/main

# Push to your fork
git push origin main

Recognition

Contributors are recognized in:

Project README
Release notes
Git commit history

Significant contributions may result in:

Collaborator status
Direct commit access
Project maintainer role

Questions?

If you have questions about contributing:

Check existing issues and discussions
Ask on the community forum
Open a GitHub discussion
Contact project maintainers

We appreciate all contributions, no matter how small. Even fixing typos or improving documentation helps make the project better!

Thank you for contributing to CoD4 Unleashed Server!

Additional Resources

Welcome Contributors

Project Information

Repository

CoD4-Unleashed-Server

License

Ways to Contribute

Report Bugs

Fix Issues

Add Features

Write Documentation

Create Plugins

Test Changes

Getting Started

Code Guidelines

Code Style

Editor Configuration

Code Quality

Developing Plugins

Plugin Development Setup

Plugin API Guidelines

Available Plugin Events

Plugin Types

Pull Request Guidelines

Before Submitting

PR Description Template

Review Process

Reporting Bugs

Community

Getting Help

Forum

Documentation

GitHub Issues

GitHub Discussions

Stay Updated

Recognition

Questions?

Build docs developers (and LLMs) love

Additional Resources

​Welcome Contributors

​Project Information

​Repository

CoD4-Unleashed-Server

​License

​Ways to Contribute

Report Bugs

Fix Issues

Add Features

Write Documentation

Create Plugins

Test Changes

​Getting Started

​Code Guidelines

​Code Style

​Editor Configuration

​Code Quality

​Developing Plugins

​Plugin Development Setup

​Plugin API Guidelines

​Available Plugin Events

​Plugin Types

​Pull Request Guidelines

​Before Submitting

​PR Description Template

​Review Process

​Reporting Bugs

​Community

​Getting Help

Forum

Documentation

GitHub Issues

GitHub Discussions

​Stay Updated

​Recognition

​Questions?

Build docs developers (and LLMs) love

Welcome Contributors

Project Information

Repository

License

Ways to Contribute

Getting Started

Code Guidelines

Code Style

Editor Configuration

Code Quality

Developing Plugins

Plugin Development Setup

Plugin API Guidelines

Available Plugin Events

Plugin Types

Pull Request Guidelines

Before Submitting

PR Description Template

Review Process

Reporting Bugs

Community

Getting Help

Stay Updated

Recognition

Questions?