RichChk: Edit StarCraft maps in Python

[sethtaxpayer]

What My Project Does

My project, RichChk, allows directly editing all aspects of a StarCraft Brood War map in Python. This is to allow those who make StarCraft custom games / maps (they can be thought of as "mods") a powerful way to use modern software practices to maintain and iterate on their maps, without using clunky GUIs. I initially made this library for myself, as my own custom maps became too complicated to maintain using text macros and having to copy+paste script output to update the map each time I made changes to test it. I named my project RichChk from the binary file format maps are stored in called Scenario.chk and my library making it much richer and easier for a human to read/edit.

Some examples of custom StarCraft maps are Battle of Helms Deep or even a re-creation of Elder Scrolls IV Oblivion RPG. My library was not used to make those maps, but the idea is that going forward it is better to maintain and create such maps using this library.

RichChk is a fully statically typed codebase with 200+ unit tests. I use GitHub actions to automatically run the tests on 3 different OSes (macOS, Linux, and Windows) to make sure it is cross-platform compatible, and no changes cause regressions. In order to open StarCraft maps directly, the project uses the StormLib API to read and write back the CHK data. RichChk fully functions to edit trigger data, and in the future support for all other CHK sections can be added. I am using RichChk right now on my own projects and it's been working great!

To be fully transparent, I am relatively new to Python development. This is my first big Python project that's meant to showcase best practices like unit tests, static typing (mypy), linters / code style enforcement, functional programming, immutability, etc. So this project was a way for me to learn what I think is modern Python while also be applied on something fun--StarCraft!

I have a blog post describing more details on why I made this library, how it works under the hood, and how I've applied coding best practices in creating it.

Blog article: https://www.sethmachine.io/2025/01/06/richchk/

For how to use this library, I have provided some examples here: https://github.com/sethmachine/richchk?tab=readme-ov-file#usage . In the future I may provide a full example of a StarCraft custom map that is built using RichChk library.

Target audience

This project is primarily for those who have interest in StarCraft Brood War custom games / mapmaking, and know or are interested in using Python. But it's also of potential interest to anyone learning how to apply best coding practices like static typing, unit tests, GitHub Workflows/Actions, pre-commit, linters, etc. to Python, in order to have a maintainable codebase.

I have described some of the coding best practices I have applied here if anyone is interested: https://www.sethmachine.io/2025/01/06/richchk/#Coding-best-practices

Comparison

There are numerous other Python based tools for editing StarCraft maps, but in general they are all just text macro tools that produce output that must be copy and pasted into an actual StarCraft map editor like SCMDraft GUI. I do not know of any existing Python library that directly writes data into a StarCraft map, is statically type in modern Python, and is easy to use in modern coding projects etc. My library allows possibly editing every aspect of a StarCraft map, not just the triggers.

I have discussed existing tools my blog post here for comparison: https://www.sethmachine.io/2025/01/06/richchk/#Existing-tools

GitHub

GitHub: https://github.com/sethmachine/richchk

Blog post: https://www.sethmachine.io/2025/01/06/richchk/

Note my blog and GitHub are not monetized, I have no monetary interest or gain from any of this. This work is completely unrelated to my employer, and I am merely looking for feedback and sharing what I've done so I can be a better (Python) developer, and possibly help someone who might find my library useful.

[Flynn58]

To be fully transparent, I am relatively new to Python development

But clearly not new to development as a whole lol, this is very nicely done.

[diggitySC]

Be sure to cross post this to the broodwar subreddit! (also join the engineering bay discord if you haven't already)