Running the game

This guide explains how to run the Pacman game with various command-line options and display configurations.

Basic usage

The game requires you to specify either fullscreen or windowed mode when launching.

Command syntax

./pacman [OPTIONS]

Available options

Option	Description	SDL Flags
`-f`	Fullscreen mode	`SDL_FULLSCREEN`
`-w`	Windowed mode	Default (no fullscreen)
`-h`	Display help	Shows usage information

Display modes

The game supports two primary display modes.

Windowed mode
Fullscreen mode

Launch the game in a window:

./pacman -w

Characteristics:

Runs in a 320x200 window
Allows switching to other applications
Maintains desktop resolution
Best for testing and development

Use case: Ideal when you want to play while keeping other windows accessible.

Launch the game in fullscreen:

./pacman -f

Characteristics:

Takes over entire display
Better performance
Authentic retro gaming experience
May change screen resolution

Use case: Best for immersive gameplay and optimal performance.

You must specify either -f or -w. Running ./pacman without options will display the help message and exit.

Resolution management

The game includes sophisticated resolution management to preserve your display configuration.

How it works

When the game starts, it automatically:

Detect primary monitor

Uses GLFW to detect your primary monitor and current video mode:

GLFWmonitor *monitor = glfwGetPrimaryMonitor();
const GLFWvidmode *mode = glfwGetVideoMode(monitor);

Saves: width, height, and refresh rate

Generate restoration script

Creates /tmp/restaurar_xrandr.sh with commands to restore:

Original resolution for each connected display
Relative position between monitors
Which display is the primary output

Run the game

The game runs with SDL 1.2 at 320x200 resolution

Restore on exit

Automatically executes the restoration script to return your display to its original state

Resolution restoration details

The restoration script generated at startup contains commands like:

#!/bin/bash
xrandr --output HDMI-1 --mode 1920x1080 --pos 0x0 --primary
xrandr --output DP-1 --mode 2560x1440 --pos 1920x0

This ensures your exact multi-monitor layout is preserved.

Multi-monitor setup

The game fully supports multi-monitor configurations.

Extended display mode

If you have multiple monitors in extended mode:

How multi-monitor restoration works

The game uses xrandr to query and save:

Each connected output - All active displays (HDMI, DisplayPort, etc.)
Resolution and position - Mode (e.g., 1920x1080) and position (e.g., +1920+0)
Primary display - Which monitor is marked as primary

The restoration script includes the --pos and --primary flags to restore the exact layout:

xrandr --output HDMI-1 --mode 1920x1080 --pos 0x0 --primary
xrandr --output DP-1 --mode 2560x1440 --pos 1920x0

This preserves your extended desktop across multiple displays.

Restoration timing

Resolution restoration may take 1-2 seconds, especially with multiple monitors. This is normal behavior as xrandr reconfigures each display.

Manual restoration

If the automatic restoration fails, you can manually run:

/tmp/restaurar_xrandr.sh

To inspect the restoration commands before running:

cat /tmp/restaurar_xrandr.sh

xrandr integration

The game relies on xrandr for display management on X11 systems.

Checking xrandr availability

When the game starts, it verifies xrandr is available:

int xrandr_disponible()
{
  if (access("/usr/bin/xrandr", X_OK) == 0)
    return 1;
  return (system("which xrandr > /dev/null 2>&1") == 0);
}

You’ll see one of these messages:

xrandr available
xrandr missing

✅ xrandr disponible. Se podrá guardar/restaurar la configuración de pantalla.
Resolución guardada: 1920x1080 @60Hz
📝 Script de restauración generado con disposición y salida primaria en /tmp/restaurar_xrandr.sh

⚠️  ADVERTENCIA: 'xrandr' no está disponible en el sistema.
No se podrá guardar ni restaurar la resolución automáticamente.

Installing xrandr

If xrandr is not available:

# Debian/Ubuntu
sudo apt install x11-utils

# Fedora/RHEL
sudo dnf install xorg-x11-utils

# Arch Linux
sudo pacman -S xorg-xrandr

Running examples

Common scenarios for launching the game.

Single monitor setup

For a typical single monitor configuration:

# Windowed mode - safe and convenient
./pacman -w

# Fullscreen mode - immersive experience
./pacman -f

Dual monitor extended desktop

With monitors arranged side-by-side (e.g., 1920x1080 + 1920x1080):

# Run in fullscreen on primary monitor
./pacman -f

# Your layout will be automatically restored on exit:
# Monitor 1 (primary): 1920x1080 at position 0x0
# Monitor 2: 1920x1080 at position 1920x0

Different resolution monitors

With mixed resolutions (e.g., 2560x1440 primary + 1920x1080 secondary):

./pacman -f

# Both monitors will restore to their original resolutions and positions

High refresh rate displays

For monitors with high refresh rates (e.g., 144Hz, 240Hz):

./pacman -f

# Example saved configuration:
# Resolución guardada: 2560x1440 @144Hz
# Refresh rate will be restored along with resolution

Display configuration

Understanding the SDL configuration used by the game.

SDL flags

The game configures SDL with these flags:

// Windowed mode (-w)
sdl_flags = (SDL_SWSURFACE | SDL_HWPALETTE | SDL_DOUBLEBUF);

// Fullscreen mode (-f)
sdl_flags = (SDL_SWSURFACE | SDL_HWPALETTE | SDL_DOUBLEBUF | SDL_FULLSCREEN);

Understanding SDL flags

SDL_SWSURFACE - Use software rendering surface
SDL_HWPALETTE - Use hardware palette (for indexed color)
SDL_DOUBLEBUF - Enable double buffering to prevent tearing
SDL_FULLSCREEN - Set fullscreen video mode (with -f only)

Game resolution

The game renders at a fixed resolution:

#define RES_X 320
#define RES_Y 200
#define DEPTH 32

This creates an authentic retro gaming experience with 320x200 pixels at 32-bit color depth.

Exit behavior

Understanding what happens when you quit the game.

Normal exit

When you exit the game normally (ESC key or close window):

Resolution restoration executes
```
restaurarResolucionOriginal();
```
Script runs automatically
```
/tmp/restaurar_xrandr.sh
```
Display returns to original state
- All monitors restore their resolution
- Position and layout restored
- Primary monitor designation restored

Abnormal termination

If the game crashes or is forcibly killed:

If the game crashes before restoration runs, your display may remain in an altered state. Manually run /tmp/restaurar_xrandr.sh to restore your configuration.

Performance considerations

Optimizing game performance on different systems.

Fullscreen vs windowed

Fullscreen mode typically provides:

Lower input latency
Better frame pacing
Fewer context switches
Optimal for gameplay

Windowed mode is better for:

Development and debugging
Multi-tasking
Screen recording
Testing

Frame timing

The game uses a timer-based frame rate:

TimerStart(timerfunc, 18);

This sets approximately 18 ticks per second for game logic updates.

Troubleshooting

Common issues when running the game.

Game won’t start

Issue: No display mode specified Solution:

# Always specify -f or -w
./pacman -w  # NOT just ./pacman

Resolution not restored

Issue: Display stays at wrong resolution after exit Solution:

# Manually run restoration script
/tmp/restaurar_xrandr.sh

# Or reset to preferred resolution
xrandr --output HDMI-1 --mode 1920x1080 --rate 60

Multi-monitor layout broken

Issue: Monitors not in correct position after game Solution:

# Check if restoration script exists
ls -l /tmp/restaurar_xrandr.sh

# Examine script contents
cat /tmp/restaurar_xrandr.sh

# Run manually if needed
bash /tmp/restaurar_xrandr.sh

SDL initialization fails

Issue: Error message about SDL initialization Solution:

# Ensure X11 is running
echo $DISPLAY

# Verify SDL libraries are installed
ldd ./pacman | grep SDL

# Try windowed mode first
./pacman -w

Wayland compatibility

This game is designed for X11 and uses xrandr. On Wayland, you may need to run under XWayland. Some display management features may not work correctly.

To run on Wayland:

# Force XWayland
GDK_BACKEND=x11 ./pacman -w

Next steps

Now that you know how to run the game:

Learn the game controls and how to play
Explore the building guide to customize the game
Review the source code in src/main.c for initialization details

Getting Started

Guides

Technical Details

Reference

Development

​Basic usage

​Command syntax

​Available options

​Display modes

​Resolution management

​How it works

​Resolution restoration details

​Multi-monitor setup

​Extended display mode

​Restoration timing

​Manual restoration

​xrandr integration

​Checking xrandr availability

​Installing xrandr

​Running examples

​Single monitor setup

​Dual monitor extended desktop

​Different resolution monitors

​High refresh rate displays

​Display configuration

​SDL flags

​Game resolution

​Exit behavior

​Normal exit

​Abnormal termination

​Performance considerations

​Fullscreen vs windowed

​Frame timing

​Troubleshooting

​Game won’t start

​Resolution not restored

​Multi-monitor layout broken

​SDL initialization fails

​Wayland compatibility

​Next steps

Build docs developers (and LLMs) love

Basic usage

Command syntax

Available options

Display modes

Resolution management

How it works

Resolution restoration details

Multi-monitor setup

Extended display mode

Restoration timing

Manual restoration

xrandr integration

Checking xrandr availability

Installing xrandr

Running examples

Single monitor setup

Dual monitor extended desktop

Different resolution monitors

High refresh rate displays

Display configuration

SDL flags

Game resolution

Exit behavior

Normal exit

Abnormal termination

Performance considerations

Fullscreen vs windowed

Frame timing

Troubleshooting

Game won’t start

Resolution not restored

Multi-monitor layout broken

SDL initialization fails

Wayland compatibility

Next steps