gh-space-shooter 1.0.4

A CLI tool that visualizes GitHub contribution graphs as gamified GIFs

gh-space-shooter 🚀

Transform your GitHub contribution graph into an epic space shooter game!

Usage

Onetime Generation

A web interface is available for on-demand GIF generation without installing anything locally.

GitHub Action

Automatically update your game GIF daily using GitHub Actions! Add this workflow to your repository at .github/workflows/update-game.yml:

name: Update Space Shooter Game

on:
  schedule:
    - cron: '0 0 * * *'  # Daily at midnight UTC
  workflow_dispatch:  # Allow manual trigger

permissions:
  contents: write

jobs:
  update-game:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: czl9707/gh-space-shooter@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          output-path: 'game.gif'
          # write-dataurl-to: 'README.md'   # for dataurl generation.
          strategy: 'random'

Then display it in your README:

![My GitHub Game](game.gif)

Action Inputs:

• github-token (required): GitHub token for fetching contributions
• username (optional): Username to generate game for (defaults to repo owner)
• output-path (optional): Where to save the animation, supports .gif or .webp (default: gh-space-shooter.gif)
• strategy (optional): Attack pattern - column, row, or random (default: random)
• fps (optional): Frames per second for the animation (default: 40)
• write-dataurl-to (optional): Write WebP as HTML <img> data URL to text file
• commit-message (optional): Commit message for the update

From PyPI

pip install gh-space-shooter

From Source

# Clone the repository
git clone https://github.com/yourusername/gh-space-shooter.git
cd gh-space-shooter

# Install with uv
uv sync

# Or with pip
pip install -e .

Setup

1. Create a GitHub Personal Access Token:

   • Go to https://github.com/settings/tokens
   • Click "Generate new token (classic)"
   • Select scopes: read:user
   • Copy the generated token

2. Set up your environment:

   # Copy the example env file
   touch .env
   echo "GH_TOKEN=your_token_here" >> .env
   

   Alternatively, export the token directly:

   export GH_TOKEN=your_token_here
   

CLI Usage

Generate Your Game Animation (GIF or WebP)

Transform your GitHub contributions into an epic space shooter!

# Basic usage - generates username-gh-space-shooter.gif
gh-space-shooter <username>

# Examples
gh-space-shooter torvalds
gh-space-shooter octocat

# Specify custom output filename (GIF or WebP)
gh-space-shooter torvalds --output my-epic-game.gif
gh-space-shooter torvalds -o my-game.webp

# Choose enemy attack strategy
gh-space-shooter torvalds --strategy row      # Enemies attack in rows
gh-space-shooter torvalds -s random           # Random chaos (default)

# Adjust animation frame rate
gh-space-shooter torvalds --fps 25            # Lower Frame rate, Smaller file size
gh-space-shooter torvalds --fps 40            # Default Frame rate, Larger file size

# Stop the animation earlier
gh-space-shooter torvalds --max-frame 200     # Stop after 200 frames

This creates an animated GIF showing:

• Your contribution graph as enemies (more contributions = stronger enemies)
• A Galaga-style spaceship battling through your coding history
• Enemy attack patterns based on your chosen strategy
• Smooth animations with randomized particle effects
• Your contribution stats displayed in the console

Generate Data URL (for embedding in HTML/Markdown)

For direct embedding in READMEs or HTML files, use --write-dataurl-to to generate a WebP data URL wrapped in an HTML <img> tag:

# Generate data URL and write to README.md
gh-space-shooter torvalds --write-dataurl-to README.md

# Short form
gh-space-shooter torvalds -wdt README.md

Using section markers: To use this feature, add section markers to your file where you want the game to appear:

# My Profile

<!--START_SECTION:space-shooter-->
<!--END_SECTION:space-shooter-->

## About Me

This will:

• Create new files with content wrapped in section markers, if file not present.
• Replace content between existing markers (preserving surrounding content)
• Raise error if markers are missing or in wrong order (no silent fallback)

Advanced Options

# Save raw contribution data to JSON
gh-space-shooter torvalds --raw-output data.json

# Load from previously saved JSON (saves API rate limits)
gh-space-shooter --raw-input data.json --output game.webp

# Combine options
gh-space-shooter torvalds -o game.webp -ro data.json -s column

# Generate data URL with custom strategy
gh-space-shooter torvalds -wdt README.md -s column

Data Format

When saved to JSON, the data includes:

{
  "username": "torvalds",
  "total_contributions": 1234,
  "weeks": [
    {
      "days": [
        {
          "date": "2024-01-01",
          "count": 5,
          "level": 2
        }
      ]
    }
  ]
}

License

MIT