README
¶
screpdb
screpdb is an advanced Starcraft replay reporting tool.
Features
Filtering/finding replays by high-level semantic features & staging them for watching on the game client
Rich game events browser with map overlays
Build Order detection with charts and for comparing with progamer timings
Skill proxies measurements: Viewport Multitasking, Unit Production Cadence, First Unit Efficiency
Alias list support for progamer replays (built-in, editable, importable/exportable), and automatic aliasing for local user's player names
Sophisticated command de-duping on the early game to facilitate precise build order detection and timing comparisons
Alliance timeline and team stacking detection on multiplayer melee games
Installation
Download the latest release from the Releases page. See CHANGELOG.md for release notes.
As a convenience for non-technical Windows users, a special Windows GUI binary is included in releases (look for screpdb-dashboard).
⚠️ Warning: screpdb is currently distributed as a binary with full filesystem read/write access and unrestricted Internet access. Treat it as high-risk software and think twice before executing it. Safety guardrails are being investigated.
If you prefer to build from source, you'll need Go 1.25.2 or later:
git clone https://github.com/marianogappa/screpdb.git
cd screpdb
go build .
Developer features
- CLI for ingestion onto SQLite database. No need to use UI: just ingest and query the database.
./screpdb ingest
- `-i, --input-dir`: Input directory containing replay files (default: system replay directory)
- `-s, --sqlite-path`: SQLite database file path (default: screp.db)
- `-w, --watch`: Watch for new files and ingest them as they appear
- `-n, --stop-after-n-reps`: Stop after processing N replay files (0 = no limit)
- `-d, --up-to-yyyy-mm-dd`: Only process files up to this date (YYYY-MM-DD format)
- `-m, --up-to-n-months`: Only process files from the last N months (0 = no limit)
- `--store-right-clicks`: Store `Right Click` commands (disabled by default to reduce command-table volume)
- `--skip-hotkeys`: Skip storing `Hotkey` commands (disabled by default)
- `--clean`: Drop all non-dashboard tables before ingesting to start over (useful for migrations)
- MCP server: ask AI anything about any game/player.
./screpdb mcp
# Specify custom database file
./screpdb mcp -s /path/to/custom.db
- All UI functionality exposed as API: OpenAPI schema available
Running on Windows
The Windows binaries are not code-signed. On first launch you will see one or more of the following — none of them mean the binary is malicious:
- SmartScreen "Windows protected your PC" dialog. Click More info → Run anyway.
- Microsoft Defender or third-party antivirus may flag the binary as suspicious or silently quarantine it. Unsigned Go binaries that read files and make network requests are a known false-positive pattern. If the binary disappears from your Downloads folder, check Defender's Protection History and restore it (or add an exclusion).
- Enterprise machines running AppLocker or Windows Defender Application Control may block execution outright. There is no workaround without code signing.
The dashboard binary (screpdb-dashboard-windows-amd64.exe) is a GUI app — if you dismiss the SmartScreen dialog, it simply won't start and won't print any error.
You can always build from source to bypass these warnings.
Verifying downloads
Each release publishes a SHA256SUMS file and a SHA256SUMS.minisig minisign signature alongside the binaries.
Verify the checksum (Linux/macOS):
sha256sum -c SHA256SUMS --ignore-missing
Verify the checksum (Windows PowerShell):
Get-FileHash screpdb-windows-amd64.exe -Algorithm SHA256
# Compare the printed hash against the line in SHA256SUMS
Verify the signature (requires minisign):
minisign -Vm SHA256SUMS -P 'RWS9gPPOydPD/tR8JBOelXKhif526NoAKY18dau7QHR4dqg84QMhJ5L/'
License
This project is licensed under the MIT License. See the LICENSE file for details.
Contributing
Contributions welcome. Open a Pull Request or file an Issue.
Acknowledgments
- Built using the github.com/icza/screp library for StarCraft replay parsing. This project would have been impossible without András Belicza's work.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
windows-dashboard
command
|
|
|
internal
|
|
|
cmddedup
Package cmddedup removes duplicate research and upgrade commands from a replay's command stream.
|
Package cmddedup removes duplicate research and upgrade commands from a replay's command stream. |
|
cmdenrich
Package cmdenrich normalizes raw models.Command into a compact, enriched form (EnrichedCommand) that downstream analysis (marker detection, future predicates) can consume without re-discriminating action types or re-normalizing game quirks.
|
Package cmdenrich normalizes raw models.Command into a compact, enriched form (EnrichedCommand) that downstream analysis (marker detection, future predicates) can consume without re-discriminating action types or re-normalizing game quirks. |
|
dashboard/apigen
Package apigen provides primitives to interact with the openapi HTTP API.
|
Package apigen provides primitives to interact with the openapi HTTP API. |
|
earlyfilter
Package earlyfilter cleans the first ~5 minutes of a replay's command stream by simulating per-player resources (minerals, supply, workers) and dropping commands that were resource-impossible at the moment they were issued.
|
Package earlyfilter cleans the first ~5 minutes of a replay's command stream by simulating per-player resources (minerals, supply, workers) and dropping commands that were resource-impossible at the moment they were issued. |
|
patterns/markers
Package markers is the single source of truth for Marker definitions.
|
Package markers is the single source of truth for Marker definitions. |
|
patterns/phases
Package phases computes per-replay early/mid/late game phase boundaries from an in-memory enriched command stream.
|
Package phases computes per-replay early/mid/late game phase boundaries from an in-memory enriched command stream. |
|
profile
Package profile provides lightweight phase timing for replay ingestion.
|
Package profile provides lightweight phase timing for replay ingestion. |
|
scripts
|
|
|
debug_phases
command
debug_phases dumps the inputs phases.Compute sees for a single replay — first-occurrence seconds for every KindMakeUnit subject, every KindTech subject, and every KindUpgrade occurrence — followed by the (earlyEnd, midEnd) result.
|
debug_phases dumps the inputs phases.Compute sees for a single replay — first-occurrence seconds for every KindMakeUnit subject, every KindTech subject, and every KindUpgrade occurrence — followed by the (earlyEnd, midEnd) result. |
|
debug_polygons
command
debug_polygons renders a single replay's scmapanalyzer base polygons to an SVG, with optional points (e.g.
|
debug_polygons renders a single replay's scmapanalyzer base polygons to an SVG, with optional points (e.g. |
|
measure_stacking_drop
command
Throwaway tool: measure the drop in team-stacking detections between the pre-change "no inactivity filter" logic and the new effective-player logic.
|
Throwaway tool: measure the drop in team-stacking detections between the pre-change "no inactivity filter" logic and the new effective-player logic. |
Click to show internal directories.
Click to hide internal directories.