Modkit — StarCraft II modding for VS Code

GameData XML, Galaxy script, SC2Layout UI, and localization — with real cross-mod resolution. Modkit reads your mods and the shipped game data, so hovers, completions and go-to-definition answer with the value the engine would actually use, inherited through Core/Liberty/Void.

Around that sits the rest of the pipeline: a mod/archive browser, viewers for models, textures, audio, video, maps and replays, and a launcher that starts your map in the real game.

Alpha. Expect rough edges. Everything is built to be diagnosable — see Troubleshooting for the log, the resolution tracer and the diagnostics bundle.

Requirements

• VS Code 1.85 or newer.
• A StarCraft II install is optional. Extracted mod folders alone work; an install adds the base-game data your mod inherits from (Core, Liberty, Swarm, Void), read straight from CASC. Installs are auto-detected on Windows and macOS; on Linux, point modkit.sources at the install directory yourself.
• Disable talv.sc2layouts if you have it. Modkit supersedes it and claims the same language id and grammar — running both gives you duplicate diagnostics and inconsistent highlighting. Modkit warns about this once on startup. StarCraft II Mod Tools (talv.sc2galaxy) needs no action: Modkit ships as its pre-release, so it replaces that extension in place.

Features

GameData XML

• Squiggles on unknown fields, bad enum values and unresolved references.
• Completion for field names and for enum/ref values inside value="…".
• Hover showing the resolved value and which ancestor it came from.
• A CodeLens row on every entity: inherited peeks the fully-resolved field set (own + inherited), card opens a wiki-style entity card, graph opens an interactive relation graph, and one clickable lens per ancestor jumps to that ancestor's definition.
• Ctrl-click a reference to its definition, or an id to every usage — including matches in Trigger, Galaxy and Layout files.
• Modkit: Open Mod Wiki renders the whole mod as browsable pages.

Set "editor.gotoLocation.multipleDefinitions": "peek" if you want Ctrl-click to always show the usage peek instead of jumping to a single definition.

Galaxy script

Full language server, bundled — completion, diagnostics, navigation and the natives/TriggerLibs of the dependencies your mod actually resolves. Modkit: Verify Galaxy Script type-checks the active file on demand (also on its editor and Explorer context menus).

SC2Layout

Schema-backed completion, diagnostics, frame/property navigation and property-bind resolution. Modkit: Preview SC2Layout renders the layout. Set modkit.treeview.visible to true to add the SC2Layout DescTree and SC2Layout Element views to the sidebar — a merged tree of the UI as the game assembles it, with a property inspector; Reveal in DescTree jumps from the open file to its node.

Localization

A spreadsheet-style, locale-by-locale editor for GameStrings.txt and friends, with stale-translation tracking and machine translation. See Localization workflow.

Mods and archives

The Modkit container in the activity bar holds:

Archives open in place — Modkit: Explore Archive gives you a file tree with extract and insert, for .SC2Mod, .SC2Map, .SC2Campaign, .SC2Replay, MPQ, ZIP, 7z, tar and a long tail of other container formats. Files inside an archive open in the viewers below without being extracted first.

Viewers

Available from an editor tab, the Explorer context menu, or by opening a file from the archive tree.

Icon authoring has its own commands on .dds/.png files: DDS Export PNG, DDS Convert DXT5 Binary Alpha to DXT1, DDS Prepare SC2 Button Icon and Convert PNG Icon to DDS.

Running your map

Modkit: Launch SC2Map starts the map through SC2Switcher; Modkit: Configure Map Launch sets the install and default map. For repeatable runs add a modkit-sc2 launch configuration:

// .vscode/launch.json
{
  "type": "modkit-sc2",
  "request": "launch",
  "name": "Modkit: Launch SC2Map With Mod",
  "map": "Maps/MyMap.SC2Map",
  "testMod": "Mods\\MyMod.SC2Mod;ComponentList.SC2Components",
  "triggerDebug": true, // open the in-game trigger debugger
  "showErrors": true, // stream SC2Switcher output to the Modkit output channel
  "meleeMod": "Void",
  "difficulty": 2, // 0=VeryEasy … 3=Hard
  "speed": 2 // 0=Slower … 4=Faster
}

Getting started

Pick the setup that matches how you work, paste the settings, and check the startup banner.

Setup A — your own mods, local folders

1. File → Open Folder on the folder that contains your .SC2Mod / .SC2Map folders (or on a single component folder).
2. Tell Modkit where mods resolve from — Modkit: Configure Sources does this from the command palette, or edit the setting directly:

// .vscode/settings.json (workspace) or your User settings
{
  "modkit.sources": [
    { "type": "mods", "path": "${workspaceFolder}/Mods" },
    { "type": "casc", "path": "C:/Program Files (x86)/StarCraft II" }
  ]
}

• path accepts ${workspaceFolder}, ${workspaceFolder:Name}, ${env:VAR}, ${userHome} and plain workspace-relative paths, so a committed .vscode/settings.json doesn't hardcode machine paths.
• Sources merge across scopes (User ∪ Workspace ∪ Folder) — a project adding its own sources no longer wipes your global ones. Use "priority" (lower = tried first) to reorder, and "disabled": true to drop an inherited entry.
• The base game (casc) always resolves last regardless of order, so your mod's files win.
• Only mods and casc (plus the casc-cache layer) are actively supported. The zip / json / http source types still work but are frozen — no new investment.

Leave modkit.sources empty and the first time Modkit needs a mod it offers the SC2 installs and standard mod folders it detects. Asked once, never repeated.

Setup B — the real game install (CASC)

{
  "modkit.sources": [{ "type": "casc", "path": "C:/Program Files (x86)/StarCraft II" }],
  "modkit.casc.cacheMode": "parsed"
}

modkit.autoDetectInstall is on by default, so an installed SC2 is picked up even with no casc source listed. Modkit: Detect StarCraft II Install adds it explicitly.

Cache modes (modkit.casc.cacheMode)

Cache lives at %LOCALAPPDATA%/modkit/casc-cache (override with modkit.casc.cachePath or the MODKIT_CASC_CACHE env var). Modkit: CASC Cache Settings shows live cache size and a full-extraction estimate, with Materialize / Clear / Open-folder actions — also available as Modkit: Materialize SC2 Data, Modkit: Clear CASC Cache and Modkit: Open CASC Cache Folder.

modkit.json — pinning a multi-archive project

A workspace holding several archives is ambiguous: Modkit can't tell which one is the project, so Galaxy dependency resolution stays limited until you pin one. When that happens it offers to write a modkit.json for you; Modkit: Set Project Archive does the same on demand.

{
  "archives": {
    "root": "Mods/MyMod/Data-01.SC2Mod", // relative paths resolve against this file
    "exclude": ["scratchpad/**"],        // never scanned for archives
    "respectGitignore": true             // default; false if your built map is gitignored
  }
}

Comments and trailing commas are allowed. Discovery skips gitignored directories by default, so a build or scratch copy of your mod tree won't shadow the real one. Editing the file takes effect on save — no reload. Run modkit schema (from the modkit CLI) to write the JSON schema locally if your editor isn't VS Code.

A healthy startup

Open Output → Modkit. Activation logs one banner:

Modkit v2.1.0 activating
  workspace roots: C:\dev\my-mod
  sources (2): mods:C:/dev/my-mod/Mods (workspace); casc:C:/Program Files (x86)/StarCraft II (global)
  CASC install: C:\Program Files (x86)\StarCraft II
  cache: C:\Users\you\AppData\Local\modkit\casc-cache (mode: parsed, extraction backend: auto)
  log file: C:\Users\you\AppData\Roaming\Code\User\globalStorage\...\logs\modkit.log
  init timings: casc-cache=3ms, panels=11ms, mod-tree=24ms, activate-return=31ms

Check that sources (N) lists what you expect — a source you set but don't see was dropped as invalid or by a disabled tombstone. Then that CASC install is a real path rather than (none detected) if you want base-game data, and that cache points where you think it does, in the mode you set.

No banner in a plain project is correct. Modkit doesn't activate without SC2 content. It starts on the first .galaxy / .SC2Layout file, any file inside an .SC2Mod/.SC2Map folder, an archive browsed from the VFS, or the Modkit sidebar.

Localization workflow

Open a LocalizedData/*.txt file (e.g. enUS.SC2Data/LocalizedData/GameStrings.txt) and run Modkit: Open Strings Table for a locale-by-locale editor — with the syntax highlighting, completion and validation the raw .txt editor has. Inside the table, the tree button switches between flat columns and a namespace tree; Modkit: Open Strings as Text goes back to the raw file.

Comparison baseline (the ⇄ button / "Review" filter)

The table tracks a source locale — the mod's primary authoring language — against every other locale. Source strings keep changing during development, and translators need to know which already-translated strings are now stale.

Click ⇄ to pick what to diff the current source text against: a git commit, a saved cache file, or a browsed file. Rows whose source text changed since that baseline get a review badge and appear under the Review filter, so a translator jumps straight to what needs re-translating.

A baseline needs a snapshot of the source strings from some earlier point. Save source strings cache (next to the Review filter) freezes the current source text as that snapshot, written to .modkit/strings-cache/<mod>/<locale>.SC2Data/LocalizedData/<file>.txt under the workspace root. Typical use: finish a batch of enUS edits, save the cache, hand off — translators then pick that cache (or a git commit) as the baseline to see what changed since they last translated. Modkit: Extract Changed Strings (since git ref)… produces the same delta as a file.

Worth it only when you need "what changed since X": for a small mod with infrequent source edits it's overhead. Comparing against a git commit shells out to git show — fast, but needs the workspace to be a git repo with that commit available locally.

Machine translation

The table can fill a target locale's empty cells from the source locale. You pick the provider per run; only Google Translate works with no configuration. The AI providers (openai, anthropic, gemini, codex, openai-compatible) need modkit.translate.aiApiKey and modkit.translate.aiModel, and take an optional modkit.translate.aiPrompt / aiContext / aiContextFile so translations match your mod's tone and glossary. Results land in the table unsaved — review before writing.

Settings

Everything is under Settings → Modkit. The ones worth knowing:

"modkit.locale": "enus",           // locale used to resolve strings
"modkit.enable": true,             // master switch
"modkit.maxGraphHops": 1,          // relation-graph depth
"modkit.cascAsFallbackBase": true, // fall back to CASC for unresolved base mods
"modkit.autoDetectInstall": true,  // pick up an installed SC2 without a casc source
"modkit.disabledMods": [],         // mods never loaded
"modkit.treeview.visible": false,  // show the SC2Layout DescTree views
"modkit.log.level": "warning"      // error | warning | info | debug | trace

Individual features can be switched off with modkit.modules.* — completion, diagnostics, hover, codeLens, navigation, galaxy, layouts, strings, dds, modelInspect, mapView, archiveView, zip. Useful for isolating a misbehaving surface without disabling the whole extension.

Troubleshooting

"It can't find my dependency"

Run Modkit: Explain mod resolution with a file of the affected mod open. It re-runs resolution with tracing forced on and prints, per dependency, every source it probed — in order, with hit/miss and timing:

Explain mod resolution: file:C:/dev/my-mod/Mods/MyMod.SC2Mod
  Liberty.SC2Mod
    miss mods0 (miss) (2ms)
    HIT  casc1 -> casc1:mods/liberty.sc2mod (14ms)
  MyDep.SC2Mod
    miss mods0 (miss) (1ms)
    miss casc1 (miss) (9ms)
  UNRESOLVED: MyDep.SC2Mod

That tells you directly whether the name is wrong or the source is missing.

Turning up the logs

{
  "modkit.log.level": "debug",
  "modkit.log.categories": { "vfs.resolve": "trace" } // just the resolver, at trace
}

Effective immediately, no reload. Categories are the modkit·… path on each log line (casc, vfs.resolve, mod.load, lsp.<lang>, viewer.<kind>, webview.<name>).

A rotating debug-level log is always written to disk regardless of the visible level — that file is what to attach to a bug report. Modkit: Open Log File / Modkit: Open Logs Folder.

Filing a bug

Modkit: Export Diagnostics writes a .zip with the debug log, versions, effective merged config, detected install, loaded mods and load order, and the last resolver trace. It offers to redact your home directory — take that option when sharing publicly.

Errors surface as "<scope> failed: <message>" with an [Open Logs] button; the log line carries the full stack, a stable error code and structured context. Shipped builds include source maps, so stacks point at TypeScript files.

Credits

Built by Visceroid and Talv.

Modkit builds on work by others:

• WhiteoutLib by Fernando Sahmkow (BSD-3-Clause) — the native CASC extraction backend, and the format structure work behind several of the archive and model readers.
• m3studio by Solstice245 — the structures.xml-driven approach the M3 model parser descends from.