GAMMA Locker (Standalone)

GAMMA Locker is a local loadout planner and locker manager for STALKER GAMMA that can parse savegames (.scop / .scoc) to extract weapon IDs from your run. Depending on what is present in the save data, this can also surface weapons linked to stashes that are not opened yet in normal gameplay.

Code-Only Distribution (Community Model)

This project is distributed as code only.

• We publish Python source code and project configuration.
• Each user generates their own local data/icons by scraping their own GAMMA/MO2 installation.
• Mod assets (DDS textures, extracted icons, etc.) are not shipped in releases.

---

Included Files

• app.py – Streamlit web UI (locker, search, strategy planner)
• save_reader.py – Savegame parser (.scop / .scoc)
• scraper.py – local data/icon extractor from game/mod files
• pyproject.toml – dependencies and project metadata
• paths_config.json – central path configuration for app + scraper
• paths_config.py – internal config loader (community users normally do not edit this file)
• ingame_stats_overrides.json – optional manual overrides with in-game stats (preferred by scorer when present)
• start_gamma_locker.sh / .ps1 / .bat – bootstrap launchers (auto-setup + start)
• docs/branding/* – logo assets for README/release branding
• loadout_lab_data/.gitkeep – placeholder for local runtime data

---

Features

Locker Management

• Add/remove weapons
• Bulk removal via checkboxes
• Save/load local locker state
• Rolling 3-layer backups + restore
• Import/export locker JSON
• Empty-state quick actions (save import + starter random set)

Savegame Import

• Read savegames from SAVE_DIR
• Add-all or replace-all from save
• Selective import
• Can reveal weapon IDs present in save data, including stash-related entries (when present)
• Variant-aware matching for save tokens (suffix/prefix fallback)
• Import summary feedback (new, already present, found)

Weapon Search

• Multi-keyword search by ID/name
• Preview icons and stats
• Direct add/remove from results
• Melee/knife/axe entries filtered out
• Render limit control + performance hint for large result sets

Strategy Planner

• Builds strict triad sets:
  • 1 Sidearm
  • 1 Primary (Power): Sniper, LMG, or heavy calibers.
  • 1 Secondary (Workhorse): Assault Rifles, SMGs, or Shotguns.
• Drafting Scheme & Priority (Tiers):
  • 🟩 GREEN: Flawless — No role deficits; unique Sidearm/Power/Workhorse.
  • 🟦 BLUE: Single Deficit — One role reused (may include hybrid workhorse variants).
  • 🟧 ORANGE: Double Deficit — Two roles reused (may include hybrid workhorse variants).
  • 🟥 RED: Multiple Redundancies — Heavy reuse until all weapons are drafted.
• Modes: Balanced (targets role-average total) and Maxxed (aims for highest total score).
• Sampling: For redundant sets (Tiers 2-5), the system samples uniformly from available weapon combinations within the same tier to ensure variety.
• Coverage: Drafting guarantees full locker utilization.
• Badge-based classification: Sets are tagged with their tier badge and descriptive label.
• Sorting, set search, and random roll available.

Scoring Logic

• Raw: base formula from scraper/LTX values (hit * rpm / rec + mag * 0.5).
• Cal-Adjusted: same base formula with caliber weighting on damage.
• Unified score: equals Cal-Adjusted and is the single weapon score used in both Balanced and Maxxed.
• UI displays a normalized 0-100 score for readability; draft logic uses the unified score internally.
• Maxxed strategy picks highest total set score for unique sets; redundant sets are sampled uniformly.
• Balanced strategy picks sets closest to the role-average target total (same two-phase flow).
• Planner labels explicitly show the active ranking basis (Balanced vs Maxxed).

Icon Handling

• RGBA compositing on black background
• Per-icon R/B swap detection for mixed DDS exports
• Fallback handling for invalid/transparent icons
• Automatic crop/pad fixes for oversized or double-width icon exports

Lean UX Helpers

• Startup health check in sidebar (paths_config.json, weapons_stats.csv, icons/*.png)
• Remembered UI defaults (assignment mode, set sorting, set search, search render limit)
• Locker filters (role-based + hide redundant) and optional score heatmap

---

Screenshots

1) My Locker (start screen)

Shows the locker overview where you manage your current weapon pool.

2) Weapon Search

Shows keyword-based search with quick add/remove actions and result stats.

3) Set Score Distribution

Histogram of generated set scores to compare quality spread across builds.

4) Weapons per Role & Most Common Calibers

Role distribution and caliber frequency charts for your current locker.

5) Random Roll Example

Example output after using the random loadout roll in the planner.

Legal & Asset Credits

• Weapon icons shown in screenshots are game/mod-derived assets from STALKER Anomaly / STALKER GAMMA installations.
• These visuals are displayed for documentation/context only; this repository does not redistribute raw game archives.
• Users should only generate and use icon/data exports from their own legally obtained installation and follow the original game/mod terms.

---

Requirements

• Python 3.10+
• Recommended environment: Linux / WSL
• Python packages:
  • streamlit
  • pandas
  • numpy
  • pillow
  • altair
  • tqdm
• Optional for scraper.py:
  • ImageMagick (convert)

Dependencies are installed automatically by the bootstrap launchers.

---

First-Time Setup (Required)

0) Configure your local paths once

Edit paths_config.json and set the paths for your installation:

• save_dir → your Anomaly/GAMMA savegames folder
• scan_paths → roots to scan for weapon .ltx data
• text_paths → roots/folders for localization XML files
• texture_paths → roots/folders that contain weapon icon .dds textures

Both app.py and scraper.py read this file, so the community only needs to change paths in one place.

Why both JSON and Python?

• paths_config.json is the only user-facing config file.
• paths_config.py is only a tiny shared loader to avoid duplicated parsing logic in multiple scripts.
• Practical rule: change JSON values only; leave Python loader as-is.

Before running the app for real usage, generate local data from your own installation:

python3 scraper.py

This creates local runtime artifacts such as:

• loadout_lab_data/weapons_stats.csv
• loadout_lab_data/icons/*.png

If these are missing, the app cannot provide meaningful output.

---

Run GAMMA Locker (Bootstrap Launcher)

From this folder:

Linux / WSL

bash start_gamma_locker.sh

Windows (PowerShell)

pwsh -File .\\start_gamma_locker.ps1

Windows (double-click)

• Run start_gamma_locker.bat

The launcher will:

• create .venv if missing
• update pip
• install project dependencies
• start Streamlit (app.py)

Then open http://localhost:8501.

---

Important Paths to Configure

All user-specific paths are configured in one file:

paths_config.json

No code edits are required for normal path setup.

Optional: use exact in-game stats

If you want scoring to use exactly the values shown in-game for specific weapons, add entries to:

ingame_stats_overrides.json

Supported fields per weapon id: accuracy, handling, damage, fire_rate, mag_size, max_range, muzzle_velocity, reliability, recoil_control.

You can also use a name matcher key to target all variants with the same display name:

"name:AK-74 \"PMC\"": { "damage": 37, "fire_rate": 650, "mag_size": 45, "recoil_control": 61 }

When an override exists, the app marks that weapon as Source: ingame override in the raw-stats inspector and shows those values exactly as an in-game snapshot. Overrides are display-only in ranking-safe mode (they do not change scoring).

---

Typical User Flow

1. Run python3 scraper.py
2. Start app: bash start_gamma_locker.sh (or a Windows launcher)
3. Use Weapon Search to build locker
4. Optionally import from savegame
5. Open Strategy Planner
6. Choose Balanced or Maxxed
7. Sort/filter sets and roll random loadouts

---

Troubleshooting

App does not start

• Check Python version: python3 --version (Linux/WSL) or py -3 --version (Windows)
• Re-run the bootstrap launcher

No savegames detected

• Verify SAVE_DIR
• Confirm .scop/.scoc files exist

Missing or incorrect icons

• Re-run python3 scraper.py
• Modded texture packs can change icon sources; some edge cases may still require manual tweaks

Slow first load

• Normal with large icon/data sets

---

Community Release Workflow

• Keep repository code-only
• Do not publish generated loadout_lab_data artifacts
• Tag releases with source + docs only

Download & Verify (SHA256)

Latest release page:

• https://github.com/phiwi/gamma-locker/releases/latest

Example (Linux/macOS):

curl -L -o gamma-locker.zip https://github.com/phiwi/gamma-locker/releases/download/v1.3.9/gamma-locker-1.3.9-code-only.zip
sha256sum gamma-locker.zip

Example (PowerShell):

Invoke-WebRequest -Uri "https://github.com/phiwi/gamma-locker/releases/download/v1.3.9/gamma-locker-1.3.9-code-only.zip" -OutFile "gamma-locker.zip"
Get-FileHash .\gamma-locker.zip -Algorithm SHA256

Expected SHA256 for v1.3.9:

• 9046c355e5f7559b532b7dea2d06f8c469528fd9c6521ab5f3e92adba735234f

---

Useful Commands

# Generate local data
python3 scraper.py

# Run app (Linux/WSL bootstrap)
bash start_gamma_locker.sh

# Run app (PowerShell bootstrap)
pwsh -File .\\start_gamma_locker.ps1

# Build release ZIP (Linux/WSL)
bash release.sh

# Build release ZIP (PowerShell)
pwsh -File release.ps1