Skip to main content

​
Welcome contributors

Thank you for your interest in contributing to this classic Pacman clone! This project is built in C using SDL 1.2 and includes advanced features like resolution restoration with xrandr on Linux systems.

​
Setting up your development environment

1

Install required dependencies

On Debian/Ubuntu systems, install all necessary libraries:
sudo apt install libsdl1.2-dev libsdl-image1.2-dev libglfw3-dev libmikmod-dev x11-utils
x11-utils provides xrandr, which is required for resolution restoration features.
2

Clone the repository

git clone <repository-url>
cd pacman
3

Build the project

The project uses a traditional Makefile:
make
This will compile all source files in src/ and generate the pacman executable.
4

Test your build

Run the game to verify everything works:
./pacman -w  # Windowed mode
./pacman -f  # Fullscreen mode

​
Project structure

pacman/
├── Makefile           # Build configuration
├── src/
│   ├── main.c         # Entry point, xrandr resolution handling
│   ├── gfx.c          # SDL graphics initialization and rendering
│   ├── misc.c         # Game logic, sprite handling, AI
│   ├── mov_fig.c      # Character movement
│   ├── sprites.c      # Sprite management
│   ├── movefant.c     # Ghost movement algorithms
│   └── include/       # Header files
├── data/              # Game assets (sprites, images)
└── sound              # Audio flag file

​
Code style and conventions

Based on the existing codebase, please follow these conventions:

​
Naming conventions

  • Variables: Use snake_case for variables and functions 
    int resolucion_ancho = 0;
void guardarResolucionOriginal()
  • Constants: Use UPPER_CASE for preprocessor definitions 
    #define MAXX_A 32
#define RES_X 320
#define TRUE 1
  • Structs: Use lowercase names 
    struct fantasmas fan;
struct pcman pc;

​
Formatting

  • Indentation: Use 2 spaces (not tabs)
  • Braces: Opening brace on same line for functions 
    void init_gfx(void)
{
    // Function body
}
  • Line length: No strict limit, but keep it readable (typically under 100 characters)

​
Comments

  • Use Spanish or English for comments (the codebase contains both)
  • Add comments for complex logic, especially AI algorithms
  • Document any xrandr or resolution-specific code
// Crear script de restauración completo
FILE *fp = fopen(script_restauracion, "w");

​
Error handling

  • Always check return values from SDL functions
  • Print error messages to stderr with descriptive context
if (SDL_Init(SDL_INIT_VIDEO | SDL_INIT_TIMER) < 0)
{
    fprintf(stderr, "Couldn't initialize SDL: %s\n", SDL_GetError());
    exit(1);
}

​
Areas for contribution

Here are some ways you can contribute to the project:
  • Additional game modes (time trial, survival)
  • High score persistence (save to file)
  • Sound effects and music (using libmikmod)
  • Power-up variations
  • Additional levels with different layouts
  • Gamepad/joystick support
  • Resolution restoration issues on specific hardware
  • Multi-monitor edge cases
  • Memory leaks or segmentation faults
  • Timing issues on different refresh rates
  • Ghost AI pathfinding improvements
  • Optimize sprite rendering (see gfx.c:142)
  • Reduce CPU usage in game loop
  • Improve memory management
  • Profile and optimize hot paths
  • macOS support (replace xrandr with native APIs)
  • BSD compatibility
  • Wayland support (alternative to X11/xrandr)
  • Windows port (using different resolution APIs)
  • Code documentation and comments
  • Algorithm explanations (ghost AI)
  • Architecture diagrams
  • Gameplay guides
  • Translation of Spanish comments to English
  • Add function documentation
  • Refactor long functions (see misc.c:506 - 916 lines)
  • Improve error handling
  • Add input validation
  • Remove unused code (see commented sections)

​
Pull request process

1

Create a feature branch

git checkout -b feature/your-feature-name
Use descriptive branch names:
  • feature/ for new features
  • fix/ for bug fixes
  • docs/ for documentation
  • refactor/ for code improvements
2

Make your changes

  • Follow the code style conventions above
  • Test thoroughly in both windowed and fullscreen modes
  • Test with single and multiple monitors if changing resolution code
  • Keep commits focused and atomic
3

Test your changes

Before submitting:
# Clean build
make clean
make

# Test both modes
./pacman -w
./pacman -f
If you modified resolution or xrandr code, test on actual multi-monitor setups to ensure restoration works correctly.
4

Commit your changes

Write clear commit messages:
git add .
git commit -m "Add high score persistence feature"
Good commit message format:
  • Start with a verb (Add, Fix, Update, Refactor)
  • Be concise but descriptive
  • Reference issue numbers if applicable
5

Push and create pull request

git push origin feature/your-feature-name
Then create a pull request on the repository with:
  • Clear title describing the change
  • Description of what was changed and why
  • Screenshots/videos for visual changes
  • Testing steps you performed
  • Any breaking changes or compatibility notes

​
Building and cleaning

# Build the project
make

# Clean build artifacts
make clean

# This removes:
# - All .o object files
# - The pacman executable
The .gitignore is configured to exclude *.o, *~, and the pacman executable. Never commit these files.

​
Getting help

If you have questions or need help:
  • Review existing code in src/ for examples
  • Check the README.md for project overview
  • Open an issue for discussion before major changes
  • Reference SDL 1.2 documentation for graphics-related questions

​
Code of conduct

This project is for educational and personal use. Be respectful, constructive, and collaborative in all interactions.
Developed by amr using Debian Testing and classic C programming tools. Contributions are welcome to keep this project alive and improve it for the community!

Build docs developers (and LLMs) love

Get started for freeTalk to us