{"id":21560404,"url":"https://github.com/icza/s2prot","last_synced_at":"2025-04-06T08:13:02.572Z","repository":{"id":11080506,"uuid":"64172752","full_name":"icza/s2prot","owner":"icza","description":"Decoder/parser of Blizzard's StarCraft II replay file format (*.SC2Replay)","archived":false,"fork":false,"pushed_at":"2024-12-07T07:23:36.000Z","size":359,"stargazers_count":62,"open_issues_count":1,"forks_count":16,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-30T07:08:11.117Z","etag":null,"topics":["command-line-tool","decoder","parser","replay","replay-header","sc2replay","starcraft-ii-replays"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/icza.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"icza"}},"created_at":"2016-07-25T22:44:47.000Z","updated_at":"2025-03-26T05:45:08.000Z","dependencies_parsed_at":"2023-02-16T17:00:57.060Z","dependency_job_id":"7758b458-a3fd-4ba1-bc22-9efb55c30539","html_url":"https://github.com/icza/s2prot","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icza%2Fs2prot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icza%2Fs2prot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icza%2Fs2prot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icza%2Fs2prot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/icza","download_url":"https://codeload.github.com/icza/s2prot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247451665,"owners_count":20940945,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line-tool","decoder","parser","replay","replay-header","sc2replay","starcraft-ii-replays"],"created_at":"2024-11-24T09:14:09.797Z","updated_at":"2025-04-06T08:13:02.544Z","avatar_url":"https://github.com/icza.png","language":"Go","funding_links":["https://github.com/sponsors/icza"],"categories":[],"sub_categories":[],"readme":"# s2prot\n\n![Build Status](https://github.com/icza/s2prot/actions/workflows/go.yml/badge.svg)\n[![Go Reference](https://pkg.go.dev/badge/github.com/icza/s2prot.svg)](https://pkg.go.dev/github.com/icza/s2prot)\n[![GoDoc](https://godoc.org/github.com/icza/s2prot?status.svg)](https://godoc.org/github.com/icza/s2prot)\n[![Go Report Card](https://goreportcard.com/badge/github.com/icza/s2prot)](https://goreportcard.com/report/github.com/icza/s2prot)\n[![codecov](https://codecov.io/gh/icza/s2prot/branch/master/graph/badge.svg)](https://codecov.io/gh/icza/s2prot)\n\nPackage `s2prot` is a decoder/parser of Blizzard's StarCraft II replay file format (*.SC2Replay).\n\n`s2prot` processes the \"raw\" data that can be decoded from replay files using an MPQ parser\nsuch as [github.com/icza/mpq](https://github.com/icza/mpq).\n\nThe package is designed to be used by other packages or apps, and is safe for concurrent use.\nThere is also an example CLI app that can be used standalone.\n\nParses all versions that were written with retail versions of StarCraft II (and some beta versions too).\n\n_Check out the sister project to parse StarCraft: Brood War replays: [screp](https://github.com/icza/screp)_\n\n## Using the `s2prot` CLI app\n\nThere is a command line application in the [cmd/s2prot](https://github.com/icza/s2prot/tree/master/cmd/s2prot) folder\nwhich can be used to parse and display information about a single replay file.\n\nThe extracted data is displayed using JSON representation.\n\nUsage is as simple as:\n\n\ts2prot [FLAGS] repfile.SC2Replay\n\nRun with `-h` to see a list of available flags.\n\nExample to parse a file called `sample.SC2Replay`, and display replay header, game metadata (included by default)\nand replay details:\n\n\ts2prot -details=true sample.SC2Relay\n\nOr simply:\n\n\ts2prot -details sample.SC2Relay\n\n## High-level Usage\n\n[![GoDoc](https://godoc.org/github.com/icza/s2prot/rep?status.svg)](https://godoc.org/github.com/icza/s2prot/rep)\n\nThe package `s2prot/rep` provides enumerations and types to model data structures\nof StarCraft II replays (*.SC2Replay) decoded by the `s2prot` package. These provide a higher level overview\nand much easier to use.\n\nThe below example code can be found in https://github.com/icza/s2prot/blob/master/_example/rep.go.\n\nInstall the latest version of the library:\n```\ngo get -u github.com/icza/s2prot/rep@master\n```\n\nTo open and parse a replay:\n\n\timport \"github.com/icza/s2prot/rep\"\n\n\tr, err := rep.NewFromFile(\"../../mpq/reps/lotv.SC2Replay\")\n\tif err != nil {\n\t\tfmt.Printf(\"Failed to open file: %v\\n\", err)\n\t\treturn\n\t}\n\tdefer r.Close()\n\nAnd that's all! We now have all the info from the replay! Printing some of it:\n\n\tfmt.Printf(\"Version:        %v\\n\", r.Header.VersionString())\n\tfmt.Printf(\"Loops:          %d\\n\", r.Header.Loops())\n\tfmt.Printf(\"Length:         %v\\n\", r.Header.Duration())\n\tfmt.Printf(\"Map:            %s\\n\", r.Details.Title())\n\tfmt.Printf(\"Game events:    %d\\n\", len(r.GameEvts))\n\tfmt.Printf(\"Message events: %d\\n\", len(r.MessageEvts))\n\tfmt.Printf(\"Tracker events: %d\\n\", len(r.TrackerEvts.Evts))\n\n\tfmt.Println(\"Players:\")\n\tfor _, p := range r.Details.Players() {\n\t\tfmt.Printf(\"\\tName: %-20s, Race: %c, Team: %d, Result: %v\\n\",\n\t\t\tp.Name, p.Race().Letter, p.TeamId()+1, p.Result())\n\t}\n\nOutput:\n\n\tVersion:        3.2.2.42253\n\tLoops:          13804\n\tLength:         14m22.75s\n\tMap:            Magma Mines\n\tGame events:    10461\n\tMessage events: 32\n\tTracker events: 1758\n\tPlayers:\n\t\tName: \u003cNoGy\u003eIMBarabba     , Race: P, Team: 1, Result: Defeat\n\t\tName: \u003cNoGy\u003eNova          , Race: T, Team: 1, Result: Defeat\n\t\tName: \u003c9KingS\u003eBiC         , Race: T, Team: 2, Result: Victory\n\t\tName: \u003c9KingS\u003eDakotaFannin, Race: P, Team: 2, Result: Victory\n\nTip: the `Struct` type defines a `String()` method which returns a nicely formatted JSON representation;\nthis is what most type are \"made of\":\n\n\tfmt.Printf(\"Full Header:\\n%v\\n\", r.Header)\n\nOutput:\n\n\tFull Header:\n\t{\n\t  \"dataBuildNum\": 42253,\n\t  \"elapsedGameLoops\": 13804,\n\t  \"ngdpRootKey\": {\n\t    \"data\": \"\\ufffd \\ufffd\\ufffd\\ufffd\\ufffd]\\ufffd\\ufffd\\ufffd\\ufffd\\ufffd\\ufffd\\ufffd\\ufffd\\ufffd\"\n\t  },\n\t  \"replayCompatibilityHash\": {\n\t    \"data\": \"\\ufffd\\ufffd\\ufffd'⌂\\u001fv\\ufffd%\\rEĪѓX\"\n\t  },\n\t  \"signature\": \"StarCraft II replay\\u001b11\",\n\t  \"type\": 2,\n\t  \"useScaledTime\": true,\n\t  \"version\": {\n\t    \"baseBuild\": 42253,\n\t    \"build\": 42253,\n\t    \"flags\": 1,\n\t    \"major\": 3,\n\t    \"minor\": 2,\n\t    \"revision\": 2\n\t  }\n\t}\n\n## Low-level Usage\n\n[![GoDoc](https://godoc.org/github.com/icza/s2prot?status.svg)](https://godoc.org/github.com/icza/s2prot)\n\nThe below example code can be found in https://github.com/icza/s2prot/blob/master/_example/s2prot.go.\n\nTo use `s2prot`, we need an MPQ parser to get content from a replay.\n\n\timport \"github.com/icza/mpq\"\n\n\tm, err := mpq.NewFromFile(\"../../mpq/reps/automm.SC2Replay\")\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer m.Close()\n\nReplay header (which is the MPQ User Data) can be decoded by `s2prot.DecodeHeader()`. Printing replay version:\n\n\theader := s2prot.DecodeHeader(m.UserData())\n\tver := header.Structv(\"version\")\n\tfmt.Printf(\"Version: %d.%d.%d.%d\\n\",\n\t\tver.Int(\"major\"), ver.Int(\"minor\"), ver.Int(\"revision\"), ver.Int(\"build\"))\n\t// Output: \"Version: 2.1.9.34644\"\n\nBase build is part of the replay header:\n\n\tbaseBuild := int(ver.Int(\"baseBuild\"))\n\tfmt.Printf(\"Base build: %d\\n\", baseBuild)\n\t// Output: \"Base build: 32283\"\n\nWhich can be used to obtain the proper instance of `Protocol`:\n\n\tp := s2prot.GetProtocol(baseBuild)\n\tif p == nil {\n\t\tpanic(\"Unknown base build!\")\n\t}\n\nWhich can now be used to decode all other info in the replay. To decode the Details and print the map name:\n\n\tdetailsData, err := m.FileByName(\"replay.details\")\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdetails := p.DecodeDetails(detailsData)\n\tfmt.Println(\"Map name:\", details.Stringv(\"title\"))\n\t// Output: \"Map name: Hills of Peshkov\"\n\nTip: We can of course print the whole decoded `header` which is a `Struct`:\n\n\tfmt.Printf(\"Full Header:\\n%v\\n\", header)\n\nWhich yields a JSON text similar to the one posted above (at High-level Usage).\n\n## Information sources\n\n- s2protocol: Blizzard's reference implementation in python: https://github.com/Blizzard/s2protocol\n\n- s2protocol implementation of the Scelight project: https://github.com/icza/scelight/tree/master/src-app/hu/scelight/sc2/rep/s2prot\n\n- Replay model of the Scelight project: https://github.com/icza/scelight/tree/master/src-app/hu/scelight/sc2/rep/model\n\n## License\n\nOpen-sourced under the [Apache License 2.0](https://github.com/icza/s2prot/blob/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficza%2Fs2prot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ficza%2Fs2prot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficza%2Fs2prot/lists"}