Various tools for StraCraft 2 map making.

Installation

1. Download and install Python 3.14.3 or a higher version of Python 3.14.
2. Open terminal in the root directory of this repository.
3. Initialize virtual environment in directory .venv and activate it according to the tutorial.
4. Run python -m pip install -U pip ply to install necessary packages.

Usage

Map extractor

Extracts StarCraft 2 maps from Battle.net cache. Requires MPQ Editor for the work.

from sc2.map_extractor import MapExtractor

extractor = MapExtractor('E:\\Software\\MPQ Editor\\MPQEditor.exe', '.data')
for path, name in extractor.get_map_paths_with_names().items():
    print(f'{path.stem}: {name!r}')

Given the path to the map file in Battle.net cache or just map's hash, extractor can extract map's contents to the working directory.

from sc2.map_extractor import MapExtractor

mpq_editor_work_dir = '.data'
extractor = MapExtractor('E:\\Software\\MPQ Editor\\MPQEditor.exe', mpq_editor_work_dir)
map_hash = '78b514b5abcc568c7e94cd78c55a02c9fee93d05ae86694bf488c40949d926e5'
extractor.extract_map_by_hash(map_hash)

For more control over where and want to extract use method extract_map_contents.

Galaxy parser and formatter

Almost complete Galaxy compiler that checks syntax, performs type checking and generates AST.

Syntax errors and errors with include statements (file not found or circular reference) raise sc2.galaxy.parser.GalaxyParsingError. All other errors are logged using standard Python logging with error severity. There are a couple of warnings as well.

Once AST is formed, the code can be formatted using sc2.galaxy.formatter.GalaxyFormatter. Note: because Galaxy parser ignores comments, spaces and newlines, all of them are lost after reformatting.

from sc2.galaxy.parser import parse_file
from sc2.galaxy.formatter import GalaxyFormatter, FormattingRules

lookup_dirs = [
    '.data/mods',
    '.data/campaigns',
    ]
script_path = '.data/78b514b5abcc568c7e94cd78c55a02c9fee93d05ae86694bf488c40949d926e5/MapScript.galaxy'
ast = parse_file(script_path, lookup_directories=lookup_dirs)

rules = FormattingRules(empty_lines_between_multiline_globals=2)
formatter = GalaxyFormatter(rules)
formatted_code = formatter.format_ast(ast)
with open(script_path, 'w') as f:
    f.write(formatted_code)

Working with in-game strings

A simple interface for loading strings from files, updating string and then saving them back with full support of comments.

Here's an example of loading game strings in English, updating map's name and saving strings back.

from sc2.strings import *

game_string_file = (
    '.data/78b514b5abcc568c7e94cd78c55a02c9fee93d05ae86694bf488c40949d926e5'
    '/enUS.SC2Data/LocalizedData/GameStrings.txt'
)
game_strings = create_strings_mapping_from_files(game_string_file)

map_name = game_strings['DocInfo/Name']
map_name.value = 'New cool name'
map_name.comment = 'New cool comment'

save_strings_mapping_to_file(game_strings, game_string_file)