🎮 Pacman Contribution Graph

Transform your GitHub/GitLab contribution graph into an interactive Pac-Man game!

Original Project: abozanona/pacman-contribution-graph
Enhanced Edition: DuyetBKU - Added light/dark theme variants for all themes

✨ Features

🎮 Interactive Game: Play Pac-Man on your contribution calendar
🎨 12 Color Themes: 6 theme families × 2 variants (light + dark)
- GitHub, GitLab, Dracula, Solarized, Monokai, React
📊 Multi-Platform Support: GitHub, GitLab, and more platforms
🎵 Optional Sound Effects: Classic Pac-Man audio
🚀 High Performance: Optimized canvas & SVG rendering
📦 Easy Integration: NPM package, CLI tool, or GitHub Action
⚡ Auto Light/Dark Mode: Detects your system preference

🚀 Quick Start

Option 1: NPM Package

npm install pacman-contribution-graph

<!DOCTYPE html>
<html>
	<head>
		<script src="node_modules/pacman-contribution-graph/dist/pacman-contribution-graph.min.js"></script>
	</head>
	<body>
		<canvas id="pacman-canvas" width="1166" height="174"></canvas>
		<script>
			const renderer = new PacmanRenderer({
				canvas: document.getElementById('pacman-canvas'),
				platform: 'github',
				username: 'your-username',
				gameTheme: 'react-dark',
				enableSounds: true
			});
			renderer.start();
		</script>
	</body>
</html>

Option 2: CLI Tool

Without installing (recommended):

npx pacman-contribution-graph \
  --platform github \
  --username torvalds \
  --gameTheme react-dark \
  --output pacman.svg

Or install globally:

npm install -g pacman-contribution-graph

pacman-contribution-graph \
  --platform github \
  --username torvalds \
  --gameTheme react-dark \
  --output pacman.svg

Option 3: GitHub Action (Automated SVG Generation)

Use this GitHub Action to automatically generate light + dark theme SVGs and display them in your README.

🎯 GitHub Action Setup (Step-by-Step)

Step 1: Fork This Repository

Fork to your GitHub account:
https://github.com/DuyetBKU/viz-pacman-github-profile

# Or clone and push to your own repo
git clone https://github.com/YOUR-USERNAME/viz-pacman-github-profile.git
cd viz-pacman-github-profile
git remote set-url origin https://github.com/YOUR-USERNAME/viz-pacman-github-profile.git

Step 2: Create `.github/workflows/pacman.yml`

Create the workflow file in your repository:

mkdir -p .github/workflows

Then create .github/workflows/pacman.yml:

name: generate pacman game

on:
    schedule:
        - cron: '0 */6 * * *' # Every 6 hours
    workflow_dispatch: # Manual trigger
    push:
        branches:
            - main

jobs:
    generate:
        permissions:
            contents: write
        runs-on: ubuntu-latest
        timeout-minutes: 10

        steps:
            - name: Checkout code
              uses: actions/checkout@v4

            - name: Create output branch if not exists
              run: |
                  git fetch --all
                  git branch -r | grep origin/output || git checkout --orphan output && git push origin output

            - name: Increase Node memory
              run: echo "NODE_OPTIONS=--max-old-space-size=8192" >> $GITHUB_ENV

            - name: Generate pacman graph (light & dark)
              uses: DuyetBKU/viz-pacman-github-profile@main
              with:
                  github_user_name: ${{ github.repository_owner }}
                  github_token: ${{ secrets.GITHUB_TOKEN }}
                  theme: react-dark
                  music: 'false'

            - name: Push to output branch
              uses: crazy-max/ghaction-github-pages@v3.1.0
              with:
                  target_branch: output
                  build_dir: dist
              env:
                  GITHUB_TOKEN: ${{ secrets.PERSONAL_TOKEN }}

Step 3: Create `PERSONAL_TOKEN` Secret

GitHub Actions needs a personal token to push SVG files to the output branch.

Go to: https://github.com/settings/tokens/new
Create New Personal Access Token (classic):
- Token name: PERSONAL_TOKEN
- Select scopes:
  - ✅ repo (full control of private repositories)
  - ✅ workflow (update GitHub Action workflows)
Copy the generated token (⚠️ Copy immediately, won't show again)
Go to your repo: Settings → Secrets and variables → Actions
Click New repository secret:
- Name: PERSONAL_TOKEN
- Value: (paste your token)
Click Add secret

Step 4: Create `output` Branch

This branch will store the generated SVG files separately from your main code.

# Option 1: Via command line
git checkout --orphan output
git commit --allow-empty -m "Initial output branch"
git push origin output

# Option 2: Via GitHub web interface
# Settings → Branches → New branch → Type "output"

Step 5: Trigger Workflow

Go to Actions tab in your repo
Select "generate pacman game" workflow
Click "Run workflow" → select main branch → "Run workflow"
Wait 30 seconds for SVG generation to complete ✅

Step 6: Verify Generated Files

Check if files were created:

Light theme: https://raw.githubusercontent.com/YOUR-USERNAME/viz-pacman-github-profile/output/dist/pacman-contribution-graph-light.svg
Dark theme: https://raw.githubusercontent.com/YOUR-USERNAME/viz-pacman-github-profile/output/dist/pacman-contribution-graph-dark.svg

Replace YOUR-USERNAME with your actual GitHub username.

📸 Display in Your README

Option 1: Auto Light/Dark Mode (Recommended)

This will automatically show dark theme on dark mode, light theme on light mode:

<div align="center">
	<h2>📊 My Contribution Activity</h2>

	<picture>
		<source
			media="(prefers-color-scheme: dark)"
			srcset="
				https://raw.githubusercontent.com/YOUR-USERNAME/viz-pacman-github-profile/output/dist/pacman-contribution-graph-dark.svg
			"
		/>
		<source
			media="(prefers-color-scheme: light)"
			srcset="
				https://raw.githubusercontent.com/YOUR-USERNAME/viz-pacman-github-profile/output/dist/pacman-contribution-graph-light.svg
			"
		/>
		<img
			alt="Pacman Contribution Graph"
			src="https://raw.githubusercontent.com/YOUR-USERNAME/viz-pacman-github-profile/output/dist/pacman-contribution-graph-light.svg"
		/>
	</picture>
</div>

Option 2: Always Dark Theme

![Pacman Dark](https://raw.githubusercontent.com/YOUR-USERNAME/viz-pacman-github-profile/output/dist/pacman-contribution-graph-dark.svg)

Option 3: Always Light Theme

![Pacman Light](https://raw.githubusercontent.com/YOUR-USERNAME/viz-pacman-github-profile/output/dist/pacman-contribution-graph-light.svg)

Option 4: Show Both Side by Side

<div align="center">
	<h3>Light Theme</h3>
	<img
		alt="Light"
		src="https://raw.githubusercontent.com/YOUR-USERNAME/viz-pacman-github-profile/output/dist/pacman-contribution-graph-light.svg"
		width="100%"
	/>

	<h3>Dark Theme</h3>
	<img
		alt="Dark"
		src="https://raw.githubusercontent.com/YOUR-USERNAME/viz-pacman-github-profile/output/dist/pacman-contribution-graph-dark.svg"
		width="100%"
	/>
</div>

🎨 Complete Theme List

Theme ID	Style	Light	Dark
GitHub	GitHub colors	`github-light`	`github-dark`
GitLab	GitLab colors	`gitlab-light`	`gitlab-dark`
React	React cyan	`react-light`	`react-dark`
Dracula	Dracula theme	`dracula-light`	`dracula-dark`
Solarized	Solarized colors	`solarized-light`	`solarized-dark`
Monokai	Monokai neon	`monokai-light`	`monokai-dark`

⚙️ Configuration Options

CLI Options

npx pacman-contribution-graph \
  --platform github|gitlab \
  --username YOUR_USERNAME \
  --gameTheme github-light|github-dark|... \
  --output output.svg \
  --music true|false

JavaScript Options

new PacmanRenderer({
	// Required
	canvas: HTMLCanvasElement,
	platform: 'github' | 'gitlab',
	username: string,

	// Optional
	gameTheme: string, // Default: 'github-light'
	enableSounds: boolean, // Default: false
	gameSpeed: number, // 0.5-2, Default: 1
	outputFormat: 'canvas' | 'svg',
	githubSettings: {
		accessToken: string // For private contributions
	}
});

🎮 Game Controls In Future!

Input	Action
⬆️ ⬇️ ⬅️ ➡️	Move Pac-Man
🍒 Eat dots	Score points
👻 Avoid ghosts	Don't get caught
⭐ Eat ghosts	Score big when scared

❓ Troubleshooting

Workflow fails with "Permission denied" on output branch

Solution: Ensure PERSONAL_TOKEN is set correctly in Secrets:

Go to Settings → Secrets and variables → Actions
Check that PERSONAL_TOKEN exists and is a valid GitHub token

SVG shows light theme but I expected dark

Solution: Make sure you're using the correct SVG URL:

Dark: ...pacman-contribution-graph-dark.svg
Light: ...pacman-contribution-graph-light.svg

Action fails with "Node out of memory"

Solution: Already handled in workflow with:

- name: Increase Node memory
  run: echo "NODE_OPTIONS=--max-old-space-size=8192" >> $GITHUB_ENV

If still failing, increase further:

run: echo "NODE_OPTIONS=--max-old-space-size=16384" >> $GITHUB_ENV

How do I change the theme?

Edit .github/workflows/pacman.yml:

- name: Generate pacman graph (light & dark)
  uses: DuyetBKU/viz-pacman-github-profile@main
  with:
      theme: react-dark # ← Change this to: github-light, gitlab-dark, dracula-light, etc.

Then re-run the workflow.

🛠️ Development

Setup & Build

git clone https://github.com/DuyetBKU/viz-pacman-github-profile.git
cd viz-pacman-github-profile
npm install
npm run build

Project Structure

src/
├── core/              # Game engine & theme definitions
├── movement/          # Ghost AI logic
├── providers/         # GitHub/GitLab API integration
├── renderers/         # Canvas & SVG rendering
└── utils/             # Helper functions

github-action/        # GitHub Action implementation
cli/                  # CLI tool
dist/                 # Compiled output (50KB minified)

Key Technologies

TypeScript - Type-safe development
Webpack 5 - Module bundling
Canvas/SVG - Graphics rendering
GitHub API - Data source

📊 Performance Stats

Metric	Value
Bundle Size	50KB minified (~15KB gzip)
Canvas Performance	60 FPS
SVG Performance	5 FPS
Themes Available	12 (6 × light/dark)
Grid Size	53 weeks × 7 days

🔗 Useful Links

📦 NPM Package: https://www.npmjs.com/package/pacman-contribution-graph
🔧 GitHub Action: https://github.com/DuyetBKU/viz-pacman-github-profile
💾 SVG Output: https://github.com/DuyetBKU/.github (output branch)
🎨 Color Themes: See constants in src/core/constants.ts

📄 License

MIT License - Feel free to use, modify, and distribute

🙏 Credits

Original Creator: abozanona
Enhanced by: DuyetBKU
Inspired by: Retro gaming and the joy of open-source contributions

🎉 Ready to Play?

# Quick start with CLI
npx pacman-contribution-graph --platform github --username YOUR_USERNAME --output pacman.svg

# Or install globally
npm install -g pacman-contribution-graph
pacman-contribution-graph --username YOUR_USERNAME

Display in your README and watch your contributions turn into a fun game! 🎮👾

Made with ❤️ and lots of 👻

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🎮 Pacman Contribution Graph

✨ Features

🚀 Quick Start

Option 1: NPM Package

Option 2: CLI Tool

Option 3: GitHub Action (Automated SVG Generation)

🎯 GitHub Action Setup (Step-by-Step)

Step 1: Fork This Repository

Step 2: Create `.github/workflows/pacman.yml`

Step 3: Create `PERSONAL_TOKEN` Secret

Step 4: Create `output` Branch

Step 5: Trigger Workflow

Step 6: Verify Generated Files

📸 Display in Your README

Option 1: Auto Light/Dark Mode (Recommended)

Option 2: Always Dark Theme

Option 3: Always Light Theme

Option 4: Show Both Side by Side

🎨 Complete Theme List

⚙️ Configuration Options

CLI Options

JavaScript Options

🎮 Game Controls In Future!

❓ Troubleshooting

Workflow fails with "Permission denied" on output branch

SVG shows light theme but I expected dark

Action fails with "Node out of memory"

How do I change the theme?

🛠️ Development

Setup & Build

Project Structure

Key Technologies

📊 Performance Stats

🔗 Useful Links

📄 License

🙏 Credits

🎉 Ready to Play?

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🎮 Pacman Contribution Graph

✨ Features

🚀 Quick Start

Option 1: NPM Package

Option 2: CLI Tool

Option 3: GitHub Action (Automated SVG Generation)

🎯 GitHub Action Setup (Step-by-Step)

Step 1: Fork This Repository

Step 2: Create .github/workflows/pacman.yml

Step 3: Create PERSONAL_TOKEN Secret

Step 4: Create output Branch

Step 5: Trigger Workflow

Step 6: Verify Generated Files

📸 Display in Your README

Option 1: Auto Light/Dark Mode (Recommended)

Option 2: Always Dark Theme

Option 3: Always Light Theme

Option 4: Show Both Side by Side

🎨 Complete Theme List

⚙️ Configuration Options

CLI Options

JavaScript Options

🎮 Game Controls In Future!

❓ Troubleshooting

Workflow fails with "Permission denied" on output branch

SVG shows light theme but I expected dark

Action fails with "Node out of memory"

How do I change the theme?

🛠️ Development

Setup & Build

Project Structure

Key Technologies

📊 Performance Stats

🔗 Useful Links

📄 License

🙏 Credits

🎉 Ready to Play?

Step 2: Create `.github/workflows/pacman.yml`

Step 3: Create `PERSONAL_TOKEN` Secret

Step 4: Create `output` Branch