Achievement Viewer

🚀 Setup Instructions

1. Fork this Repository

Click the "Fork" button at the top right of this page.

2. Enable GitHub Pages

1. Go to your forked repository's Settings
2. Click Pages in the left sidebar
3. Under "Source", select Deploy from a branch
4. Under "Branch", select main (or master) and / (root)
5. Click Save
6. Wait 1-2 minutes for deployment

Your site will be available at: https://YOUR-USERNAME.github.io/REPO-NAME/

3. Upload your achievement files

1. Create a branch named 'user'. This branch will store all your achievement files.
2. Create folder structure: AppID/[Steam AppID]/
3. Example: AppID/730/ for Counter-Strike 2
4. Upload your supported achievement files
5. Commit and push to the branch
6. Your site will update automatically!

Supported Formats (only one is needed per game)

GBE fork achievement JSON Format

By default they are stored in: %AppData%\GSE Saves\{AppID} Your achievements.json should look like this:

{
  "Defeat_Mantis": {
    "earned": true,
    "earned_time": 1754144765
  },
  "Obtain_Archetype": {
    "earned": true,
    "earned_time": 1754144765
  }
}

Steam cached Achievement Watcher {AppID}.db files

By default they are stored in: %AppData%\Achievement Watcher\steam_cache\data and/or %AppData%\Achievement Watcher\steam_cache\user\{SteamID}\ A Steam label will be added automatically to these types of games.

Your {AppID}.db should look like this:

[
  {
    "apiname": "ACHIEVEMENT_reached_speed_1",
    "achieved": 0,
    "unlocktime": 0
  },
  {
    "apiname": "ACHIEVEMENT_spam_obstacles",
    "achieved": 0,
    "unlocktime": 0
  }
]

Verify It's Working

Visit your GitHub Pages URL and you should see your achievement viewer!

📁 Folder Structure

your-repo/ (main branch)
├── index.html                         # Main viewer page
├── hub.html                           # Hub viewer page
├── css/                               # Pages layout styles folder
│   ├── hub.css
│   └── styles.css
├── js/                                # Pages javascript code folder
│   ├── utils.js
│   ├── GameLoader.js
│   ├── GameRenderer.js
│   └── HubRenderer.js
└── .github/
    └── workflows/
        └── fetch-game-data.yml        # Automation workflow

The only important thing in the user branch below is the AppID folder, inside that the game's Steam AppID folder, inside that "Your achievement data".
All other files are optional or auto-generated.

your-repo/ (user branch)
├── AppID/                             # Achievement data folder
│   ├── 730/                           # Counter-Strike 2
│   │   ├── achievements.json          # Your achievement data (only one "Your achievement data" file is required)
│   │   └── game-info.json             # (Auto-generated) Auto-generated by workflow
│   ├── 570/                           # Dota 2
│   │   ├── 570.db                     # Your achievement data (only one "Your achievement data" file is required)
│   │   └── game-info.json             # (Auto-generated) Auto-generated by workflow
│   └── 928960/                        # Godfall
│       ├── achievements.json          # Your achievement data (only one "Your achievement data" file is required)
│       ├── Epic.platform              # (Optional) Platform indicator empty file (displays the text before ".platform" on the game card below AppID)
│       ├── blacklist                  # (Optional) Skipped achievements to display. You have to use achievement API names in every lines! (Useful in cases like with Godfall where Steam version has more achievements than Epic)
│       └── game-info.json             # (Auto-generated) Auto-generated by workflow
├── gamercard.html                     # (Optional) Displayed on the right side of "{User}'s summary". It can be any website's "gamercard"
├── game-data.json                     # (Auto-generated) Combined data, auto-generated by workflow
└── top_owners.json                    # (Auto-generated) Auto-generated and auto-updated by workflow

🔧 Customization

The viewer automatically uses:

• Your GitHub username in the header
• Your GitHub profile picture as the avatar

These are detected automatically from your repository URL!

🔄 Updating Achievement Data

Manual Update (only for the uploaded game)

1. Edit/replace files in AppID/[Steam AppID]/achievements.json
2. Commit and push changes
3. Site updates automatically within minutes

Automatic Update (for all games)

The workflow runs daily at midnight UTC, or manually:

1. Go to Actions tab
2. Select Fetch Steam Game Data
3. Click Run workflow

📊 What You Need vs What's Optional

Required (Minimum Setup):

✅ Supported achievement data file in AppID/[Steam AppID]/ with your unlocked achievement data ✅ GitHub Pages enabled

Optional (Enhanced Features):

⭐ You can see all optional files in the "AppID/appid" folder in this main branch. (remove .example from them and use them as it is written inside them)

📝 Notes

• Your GitHub Pages site is public by default
• No personal Steam account needed - just upload your achievement files
• The viewer works offline after initial load

🐛 Troubleshooting

No games showing?

• Check that your AppID/*/ folder has any supported format achievement data files as mentioned in the Supported Formats section.
• Verify the files are valid (use a json or db etc. validator, depending on the file)
• Check browser console for errors (F12)

Games show but no names/icons?

• Most likely Steam is using another Steam AppID for that game. (Example: for Dishonored the correct Steam AppID is 205100, because 217980 somehow doesn't work. You can check these things with SteamDB, you can check there if there are multiple AppIDs if you enter the game's name)

Profile picture not showing?

• Falls back to default Steam logo if GitHub avatar unavailable
• Check that your GitHub profile is public

Workflow not running?

• Verify the workflow file exists at .github/workflows/fetch-game-data.yml
• Check Actions tab for error messages

🎮 Features

• Automatic Steam Integration - Fetches game names, icons, and achievement details
• Hidden Achievement Support - Retrieves hidden achievement descriptions
• Rarity Display - Shows how many players have each achievement
• Golden Glow - Rare achievements (<10%) get a special animated effect
• Spoiler Protection - Hidden achievements show spoiler text (hover to reveal)
• Sorting Options - Sort by completion % or recent activity
• Perfect Games Tracking - Shows your 100% completed games
• Responsive Design - Works on desktop and mobile
• The Hub feature - A community interface. Everybody who forks the main repo automatically gets added to it.
• Compare achievements - From your profile go to the Hub ("Open Hub" button in the upper right) and press on the user you want to be compared to.
• Achievement groups - Achievements that were added later with a DLC or an update, it will be displayed in a new row.

📄 License

Free to use and modify!

---

At first this was made for GBE fork users.

Implemented and automatized the logic behind alex47exe's gse_fork_tools for hidden achievement retrieval.

Credit goes to darktakayanagi for the enhanced hidden achievement retrieval.

Credit goes to darktakayanagi for the Hub.