mpq 0.1.0 → 0.2.0

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/jsonish.rb

@@ -0,0 +1,75 @@
+# MPQ files store some data in a serialized format that's strikingly similar to 
+# JSON, so I've called it **JSONish**. It's a fairly simple format, documented 
+# at http://github.com/GraylinKim/sc2reader/wiki/serialized.data and at 
+# http://teamliquid.net/forum/viewmessage.php?topic_id=117260&currentpage=3#45.
+module MPQ
+  module JSONish
+    
+    # `parse` is the public API here, the following two methods are simply 
+    # helpers.
+    def self.parse data
+      self.parse_recur String.new data
+    end
+  
+    # JSONish consists of strings, arrays, maps, and integers. The first byte 
+    # of each of these indicates which is about to follow.
+    def self.parse_recur data
+      case data.slice!(0).bytes.next
+    
+      # `02` indicates a string. The next byte is a variable-length integer 
+      # (see below) indicating the string's length, and the remaining bytes are 
+      # the string itself.
+      when 2
+        data.slice! 0, vlf(data)
+    
+      # `04` is an array, a list of values. Each value indicates its type, so 
+      # this is largely just a recursive process.
+      when 4
+        data.slice! 0, 2
+        (0...vlf(data)).map {|i| parse_recur data }
+    
+      # `05` starts a map, also known as a Hash or an object literal. It maps 
+      # keys to values. In JSONish, keys are always variable-length integers, 
+      # while values can be anything.
+      when 5
+        Hash.[]((0...vlf(data)).map do |i| 
+          [vlf(data), parse_recur(data)]
+        end)
+    
+      # `06` is a single-byte integer.
+      when 6
+        data.slice! 0
+    
+      # `07` is a four-byte integer in little-endian format.
+      when 7
+        data.slice!(0, 4).unpack("V")[0]
+    
+      # `09` is a standalone (i.e. not a key or length) variable-length integer.
+      when 9
+        vlf data
+    
+      # If there are other types in JSONish, we don't know about them.
+      else
+        nil
+      end
+    end
+  
+    # A variable-length integer is a concise serialization of an 
+    # arbitrary-precision integer. Each byte (except the last) sets the high bit 
+    # to `1` to indicate that the next byte is included in the integer. Seven 
+    # bits of each byte, plus all eight bits of the final byte, make up the 
+    # final number in little-endian format.
+    def self.vlf data
+      ret, shift = 0, 0
+      loop do
+        char = data.slice!(0)
+        return nil unless char
+        byte = char.bytes.next
+        ret += (byte & 0x7F) << (7 * shift)
+        break if byte & 0x80 == 0
+        shift += 1
+      end
+      (ret >> 1) * ((ret & 0x1) == 0 ? 1 : -1)
+    end
+  end
+end

data/lib/replay_file.rb

@@ -0,0 +1,205 @@
+# StarCraft 2 replay files are MPQ archives, with some data serialized as what 
+# I'm calling *JSONish*. We also use `bindata` as a DSL for some of the file 
+# contents.
+require 'bindata'
+require 'mpq'
+require 'jsonish'
+
+module MPQ
+  class SC2ReplayFile < Archive
+  
+    # Game length is given as the number of frames.
+    def game_length
+      @game_length ||= user_data[3] / FRAMES_PER_SECOND
+    end
+  
+    # These are the numbers you see in the bottom left of the game's menu. Use 
+    # the `build` to change features, etc. based on game version. Use the rest 
+    # when presenting a version to a person.
+    def game_version
+      @game_version ||= {
+        :major => user_data[1][1],
+        :minor => user_data[1][2],
+        :patch => user_data[1][3],
+        :build => user_data[1][4]
+      }
+    end
+  
+    # Player information is spread among a couple of files: the 
+    # `replay.details` file and the `replay.attributes.events` file. Here we 
+    # combine the information contained in each.
+    def players
+      return @players if defined? @players
+      @players = details[0].map do |player|
+        { :name => player[0],
+        
+          # This could probably be 'unknown' in some circumstances I haven't 
+          # yet checked.
+          :outcome => OUTCOMES[player[8]]
+        }
+      end
+    
+      # Unlike the `replay.initData` file, this method of determining race is
+      # the same across all localizations.
+      attributes.each do |attr|
+        case attr.id.to_i
+        when 0x01f4
+          @players[attr.player - 1][:type] = ATTRIBUTES[:player_type][attr.sval]
+        when 0x0bb9
+          @players[attr.player - 1][:race] = ATTRIBUTES[:player_race][attr.sval]
+        when 0x0bba
+          @players[attr.player - 1][:color] = 
+            ATTRIBUTES[:player_color][attr.sval]
+        end
+      end
+      @players
+    end
+  
+    # The localized map name. Should probably translate it.
+    def map_name
+      details[1]
+    end
+  
+    # The start date of the game, probably off by a time zone or ten.
+    def start_date
+=begin
+      FIXME: parse this as UTC (possibly requires use of time zone offset 
+      present in details).
+=end
+      Time.at((details[5] - 116444735995904000) / 1e7)
+    end
+  
+    # Two-uppercase-character abbreviation, like `NA`.
+    def realm
+      initdata.rest.split('s2ma')[1][2, 2]
+    end
+  
+    # Each of these getters are for information contained in the 
+    # `replay.attributes.events` file, but their exact position cannot be 
+    # assumed from file to file, so we might as well extract them all when 
+    # asked for any one of them.
+    %w[game_type game_speed category].each do |lazy_getter|
+      class_eval <<-EVAL
+        def #{lazy_getter}
+          parse_global_attributes unless defined? @#{lazy_getter}
+          @#{lazy_getter}
+        end
+      EVAL
+    end
+  
+    # Wrappers for deserializing some JSONish.
+    private
+    def user_data
+      @user_data ||= JSONish.parse @user_header.user_data
+    end
+  
+    def details
+      @details ||= JSONish.parse read_file "replay.details"
+    end
+  
+    # `replay.initData` has some useful information, but almost all of it can 
+    # be more reliably obtained elsewhere. All that's really useful here is the 
+    # realm the game was played in.
+    def initdata
+      @initdata ||= InitData.read read_file "replay.initData"
+    end
+  
+    class InitData < BinData::Record
+      uint8 :num_players
+      array :players, :initial_length => :num_players do
+        uint8 :player_name_length
+        string :player_name, :length => :player_name_length
+        skip :length => 5
+      end
+      string :unknown_24, :length => 24
+      uint8 :account_length
+      string :account, :length => :account_length
+      rest :rest
+    end
+  
+    # `replay.attributes.events` has plenty of handy information. Here we 
+    # simply deserialize all the attributes, taking into account a format 
+    # change that took place in build 17326, for later processing.
+    def attributes
+      return @attributes if defined? @attributes
+      data = read_file "replay.attributes.events"
+      data.slice! 0, (game_version[:build] < 17326 ? 4 : 5)
+      @attributes = []
+      data.slice!(0, 4).unpack("V")[0].times do
+        @attributes << Attribute.read(data.slice!(0, 13))
+      end
+      @attributes
+    end
+  
+    class Attribute < BinData::Record
+      endian :little
+    
+      string :header, :length => 4
+      uint32 :id
+      uint8  :player
+      string :val, :length => 4
+    
+      def sval
+        val.reverse
+      end
+    end
+  
+    # Several pieces of information come from `replay.attributes.events`, and 
+    # finding one of them is about as hard as finding all of them, so we just 
+    # find all of them here when asked.
+    def parse_global_attributes
+      attributes.each do |attr|
+        case attr.id.to_i
+        when 0x07d1
+          @game_type = attr.sval
+          @game_type = @game_type == 'Cust' ? :custom : @game_type[1, 3].to_sym
+        when 0x0bb8
+          @game_speed = ATTRIBUTES[:game_speed][attr.sval]
+        when 0x0bc1
+          @category = ATTRIBUTES[:category][attr.sval]
+        end
+      end
+    end
+  end
+end
+
+# Some translations for various values in replays.
+FRAMES_PER_SECOND = 16
+OUTCOMES = [:unknown, :win, :loss]
+ATTRIBUTES = {
+  :player_type => {"Humn" => :human, "Comp" => :computer},
+  :player_race => {
+    "RAND" => :random, "Terr" => :terran, "Prot" => :protoss, "Zerg" => :zerg
+  },
+  :player_color => {
+    "tc01" => :red,
+    "tc02" => :blue,
+    "tc03" => :teal,
+    "tc04" => :purple,
+    "tc05" => :yellow,
+    "tc06" => :orange,
+    "tc07" => :green,
+    "tc08" => :light_pink,
+    "tc09" => :violet,
+    "tc10" => :light_grey,
+    "tc11" => :dark_green,
+    "tc12" => :brown,
+    "tc13" => :light_green,
+    "tc14" => :dark_grey,
+    "tc15" => :pink
+  },
+  :game_speed => {
+    "Slor" => :slower,
+    "Slow" => :slow,
+    "Norm" => :normal,
+    "Fast" => :fast,
+    "Fasr" => :faster
+  },
+  :category => {
+    "Priv" => :private,
+    
+    # `Amm` is assumed to stand for "automatic matchmaker".
+    "Amm" => :ladder,
+    "Pub" => :public
+  }
+}

data/mpq.gemspec

@@ -0,0 +1,78 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{mpq}
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Nolan Waite"]
+  s.date = %q{2011-06-16}
+  s.description = %q{Read files and metadata from MPQ archives}
+  s.email = %q{nolan@nolanw.ca}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "lib/jsonish.rb",
+    "lib/mpq.rb",
+    "lib/replay_file.rb",
+    "mpq.gemspec",
+    "test/helper.rb",
+    "test/some.SC2Replay",
+    "test/test_jsonish.rb",
+    "test/test_mpq.rb",
+    "test/test_replay_file.rb"
+  ]
+  s.homepage = %q{http://github.com/nolanw/mpq}
+  s.licenses = ["WTFPL"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.7.2}
+  s.summary = %q{Read files and metadata from MPQ archives}
+  s.test_files = [
+    "test/helper.rb",
+    "test/test_jsonish.rb",
+    "test/test_mpq.rb",
+    "test/test_replay_file.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<bindata>, ["~> 1.3.1"])
+      s.add_runtime_dependency(%q<bzip2-ruby>, ["~> 0.2.7"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_development_dependency(%q<rocco>, ["~> 0.6"])
+      s.add_runtime_dependency(%q<bindata>, [">= 1.3.1"])
+      s.add_development_dependency(%q<rocco>, [">= 0.6"])
+    else
+      s.add_dependency(%q<bindata>, ["~> 1.3.1"])
+      s.add_dependency(%q<bzip2-ruby>, ["~> 0.2.7"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_dependency(%q<rocco>, ["~> 0.6"])
+      s.add_dependency(%q<bindata>, [">= 1.3.1"])
+      s.add_dependency(%q<rocco>, [">= 0.6"])
+    end
+  else
+    s.add_dependency(%q<bindata>, ["~> 1.3.1"])
+    s.add_dependency(%q<bzip2-ruby>, ["~> 0.2.7"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+    s.add_dependency(%q<rocco>, ["~> 0.6"])
+    s.add_dependency(%q<bindata>, [">= 1.3.1"])
+    s.add_dependency(%q<rocco>, [">= 0.6"])
+  end
+end
+

data/test/test_jsonish.rb

@@ -0,0 +1,40 @@
+$:.unshift File.expand_path(File.join File.dirname(__FILE__), '..', 'src')
+require "jsonish"
+require "test/unit"
+
+class TestJSONish < Test::Unit::TestCase
+  def test_vlf
+    assert_equal 0,        MPQ::JSONish.vlf("\x00")
+    assert_equal 0,        MPQ::JSONish.vlf("\x01")
+    assert_equal 1,        MPQ::JSONish.vlf("\x02")
+    assert_equal -1,       MPQ::JSONish.vlf("\x03")
+    assert_equal 2,        MPQ::JSONish.vlf("\x04")
+    assert_equal 63,       MPQ::JSONish.vlf("\x7e")
+    assert_equal -63,      MPQ::JSONish.vlf("\x7f")
+    assert_equal nil,      MPQ::JSONish.vlf("\x80")
+    assert_equal 0,        MPQ::JSONish.vlf("\x80\x00")
+    assert_equal 64,       MPQ::JSONish.vlf("\x80\x01")
+    assert_equal -64,      MPQ::JSONish.vlf("\x81\x01")
+    assert_equal 65,       MPQ::JSONish.vlf("\x82\x01")
+    assert_equal 128,      MPQ::JSONish.vlf("\x80\x02")
+    assert_equal -128,     MPQ::JSONish.vlf("\x81\x02")
+    assert_equal 18092,    MPQ::JSONish.vlf("\xd8\x9a\x02")
+    assert_equal 18317,    MPQ::JSONish.vlf("\x9a\x9e\x02")
+    assert_equal 16777216, MPQ::JSONish.vlf("\x80\x80\x80\x10")
+  end
+  
+  def test_parse
+    assert_equal "hi", MPQ::JSONish.parse("\x02\x04\x68\x69")
+    assert_equal "Pille", MPQ::JSONish.parse("\x02\x0a\x50\x69\x6c\x6c\x65")
+    assert_equal(["Pille", "\x2a", "\xa6", "\x8d"], 
+      MPQ::JSONish.parse("\x04\x00\x01\x08\x02\x0A\x50\x69\x6C\x6C\x65" +
+                    "\x06\x2A\x06\xA6\x06\x8D"))
+    assert_equal({0 => "hi"}, 
+      MPQ::JSONish.parse("\x05\x02\x00\x02\x04\x68\x69"))
+    assert_equal({0 => "hi", 1 => "hi"}, 
+      MPQ::JSONish.parse("\x05\x04\x00\x02\x04\x68\x69\x02\x02\x04\x68\x69"))
+    assert_equal({0 => 1, 1 => 2, 4 => 3}, 
+      MPQ::JSONish.parse("\x05\x06\x00\x09\x02\x02\x09\x04\x08\x09\x06"))
+    assert_equal 76, MPQ::JSONish.parse("\x06\x4C").ord
+  end
+end

data/test/test_replay_file.rb

@@ -0,0 +1,59 @@
+require 'replay_file'
+require 'test/unit'
+require 'time'
+
+class TestReplayFile < Test::Unit::TestCase
+  def setup
+    @file = File.new File.join(File.dirname(__FILE__), "some.SC2Replay")
+    @replay = MPQ::SC2ReplayFile.new @file
+  end
+  
+  def teardown
+    @file.close
+  end
+  
+  def test_game_version
+    assert_equal 1, @replay.game_version[:major]
+    assert_equal 3, @replay.game_version[:minor]
+    assert_equal 18317, @replay.game_version[:build]
+  end
+  
+  def test_game_length
+    assert_equal 1260, @replay.game_length
+  end
+  
+  def test_players
+    names = @replay.players.map{|p| p[:name]}
+    assert names.include? "ESCGoOdy"
+    goody = @replay.players[names.index "ESCGoOdy"]
+    assert_equal :terran, goody[:race]
+    assert_equal :purple, goody[:color]
+    assert_equal :human, goody[:type]
+  end
+  
+  def test_map_name
+    assert_equal "The Shattered Temple", @replay.map_name
+  end
+  
+  def test_start_date
+    # FIXME: should be parsed as UTC, and this test should reflect that.
+    assert (Time.parse("2011-04-24 10:09:18 -0600") - 
+            @replay.start_date).abs < 1
+  end
+  
+  def test_realm
+    assert_equal "EU", @replay.realm
+  end
+  
+  def test_game_type
+    assert_equal :"1v1", @replay.game_type
+  end
+  
+  def test_game_speed
+    assert_equal :faster, @replay.game_speed
+  end
+  
+  def test_category
+    assert_equal :private, @replay.category
+  end
+end

metadata

@@ -2,7 +2,7 @@
 name: mpq
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Nolan Waite
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-01 00:00:00 Z
+date: 2011-06-16 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: bindata
@@ -105,10 +105,15 @@ files:
 - README.md
 - Rakefile
 - VERSION
+- lib/jsonish.rb
 - lib/mpq.rb
+- lib/replay_file.rb
+- mpq.gemspec
 - test/helper.rb
 - test/some.SC2Replay
+- test/test_jsonish.rb
 - test/test_mpq.rb
+- test/test_replay_file.rb
 homepage: http://github.com/nolanw/mpq
 licenses: 
 - WTFPL
@@ -122,7 +127,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -4446640813622028280
+      hash: -1950555829179380990
       segments: 
       - 0
       version: "0"
@@ -141,4 +146,6 @@ specification_version: 3
 summary: Read files and metadata from MPQ archives
 test_files: 
 - test/helper.rb
+- test/test_jsonish.rb
 - test/test_mpq.rb
+- test/test_replay_file.rb