From 44526f62a77df76193fdc9998b316555d35e7d53 Mon Sep 17 00:00:00 2001
From: Hugo Wainwright <wainwrighthugo@gmail.com>
Date: Fri, 9 Jun 2017 20:02:41 +0100
Subject: [PATCH] Updated HOWTO on how to support new sc2 build versions

---
 sc2reader/data/HOWTO    | 18 ------------------
 sc2reader/data/HOWTO.md | 16 ++++++++++++++++
 2 files changed, 16 insertions(+), 18 deletions(-)
 delete mode 100644 sc2reader/data/HOWTO
 create mode 100644 sc2reader/data/HOWTO.md

diff --git a/sc2reader/data/HOWTO b/sc2reader/data/HOWTO
deleted file mode 100644
index ba734b5b..00000000
--- a/sc2reader/data/HOWTO
+++ /dev/null
@@ -1,18 +0,0 @@
-Sometimes when a new version comes out, such as (3.4.0) 44401, Bliz will update the ids used to identify units and abilities.
-
-See dsjoerg's commits on Jul 13, 2016 to see what you need to modify to handle something like that: https://github.com/ggtracker/sc2reader/commits/upstream
-
-1 use the Galaxy Editor and Export Balance Data.
-2 To create the ability CSV file: ```find Balance\ Data -print0 | xargs -0 grep -h '<ability' | sort | uniq  | tr '="' ' ' | awk -v OFS=',' '{print $5, $3}' | sort -n```
-3 To create the unit CSV file:
-```
-import os
-from xml.etree import ElementTree
-balancedir = '/foo/bar/Balance Data'
-for i in os.listdir(balancedir):
-    if i.endswith(".xml"):
-      xml = ElementTree.parse(open(os.path.join(balancedir, i), 'r'))
-      print "{},{}".format(xml.findall('meta')[0].attrib['index'], xml.getroot().attrib['id'])
-```
-4 run `sc2reader/new_units.py` to find out what you need to add to `sc2reader/data/ability_lookup.csv`, and add it
-5 modify `sc2reader/data/__init__.py` and `sc2reader/resources.py` accordingly
diff --git a/sc2reader/data/HOWTO.md b/sc2reader/data/HOWTO.md
new file mode 100644
index 00000000..ab67031d
--- /dev/null
+++ b/sc2reader/data/HOWTO.md
@@ -0,0 +1,16 @@
+Supporting a new StarCraft II build version with updated balance data
+=====================================================================
+
+Sometimes when a new version comes out, such as (3.4.0) 44401, Blizzard will update the ids used to identify units and abilities.
+
+See dsjoerg's commits on Jul 13, 2016 for context on what needs to be modified to support these changes: https://github.com/ggtracker/sc2reader/commits/upstream
+
+Here are some detailed steps on how to add support for these new ids.
+
+1. Install and open the StarCraft II Editor, then navigate to `File` -> `Export Balance Data...` and select the expansion level for the balance data you wish to add, then select the directory which you wish to export the balance data to.
+2. Find out the build version this balance data correlates to. One method of doing this is to navigate to the s2protocol repo (https://github.com/Blizzard/s2protocol) and looking at the version of the latest protocol.
+At the time of writing, the latest build version is 53644.
+3. Execute `sc2reader/generate_build_data.py`, passing the expansion level selected in step 1, the build version determined in step 2, the directory the balance data was exported to in step 1, and the sc2reader project root directory as parameters.
+e.g. `python3 sc2reader/generate_build_data.py LotV 53644 balance_data/ sc2reader/`
+This will generate the necessary data files to support the new build version (namely, `53644_abilities.csv`, `53644_units.csv`, and updated versions of `ability_lookup.csv` and `unit_lookup.csv`).
+4. Finally, modify `sc2reader/data/__init__.py` and `sc2reader/resources.py` to register support for the new build version.