4.0 Beta 3.1. Основная функция оптимизатора — преобразование размещённого декора и юнитов в Galaxy с обратным восстановлением разметки из скрипта. JSON/XML для восстановления по умолчанию выключены и доступны как дополнительный режим в настройках.
Primary workflow: convert placed decor and eligible units to Galaxy, then rebuild native placements from that script. This release is a Beta.
StarCraft II Data Helper is a Windows desktop map optimizer with reversible
decor/unit conversion to Galaxy. It also analyzes and optimizes catalog XML in
.SC2Map, .SC2Mod, extracted component folders, and standalone XML files.
The main workflow is in Map Performance: preview placements, create an optimized map copy, and rebuild placements from its generated Galaxy when needed.
Download the latest build from Releases
- Analyze XML catalogs, references, duplicate bodies, unused chains, assets, localization, and archive metadata
- Build and update typed Data Collections for supported editor catalog objects
- Preview and safely remove unused data objects and whole unused data-object chains
- Find exact duplicate XML bodies, redirect references, and merge safely
- Preview and apply Rename To Standard operations for unit-family style data
- Run Import Cleanup for unused imported files in folders or archives
- Run Deep Cleanup for stale strings, redundant default fields/nodes, broken actor events, dependency review, and archive/helper trash
- Scan binary model-like imports for embedded asset references before deleting textures, sounds, layouts, or models
- Preview M3 geometry interactively and inspect standard materials, diffuse texture paths, UVs, skin weights, bones, rest transforms, and animation names
- Review asset-size/duplicate audits, trigger/Galaxy performance hotspots, and semantic duplicate data-object candidates
- Select real map Regions in Map Performance, preview eligible decor and units, and create a separate map copy with placements converted to callable Galaxy create/clear functions
- Show full XML source with syntax highlighting
- Open an Optimization Wizard for batch review before apply
- Check GitHub Releases for newer semantic versions; release builds also have a portable ZIP and an automatically built Windows installer
The Properties tab can now inspect the selected catalog object's effective
Data through the separately installed SC2Editor-MCP-Codex server. Click
Inspect effective Data (ModKit) after analyzing one .SC2Map or .SC2Mod.
The first click asks for that server's built dist/index.js; the location is
remembered in user settings. SC2_MODKIT_MCP_ENTRY overrides the saved path,
and SC2_MODKIT_NODE can select a Node.js executable (Node 22 or newer).
This read-only query shows inherited fields, the inheritance chain, the package snapshot revision, and the source catalog for each displayed field. It uses the installed game data and declared dependencies resolved by ModKit. The response is bounded to the first 24 fields by default; the optional field box requests up to 32 exact field names. For scalar fields the optimizer resolved with confidence, the panel compares its value with ModKit's effective value and marks differences for review. Omitted fields are counted. Reanalyze the source if it changes before comparing results. Missing or incomplete ModKit data is not evidence that an object is unused, and the optimizer's existing deletion/merge safety rules remain authoritative.
For a command-line check, run
SC2ModkitDataProbe <map-or-mod> <CType> <ID> <MCP-dist/index.js> [field ...].
To configure the GUI without its file picker, run
SC2ModkitDataProbe --configure-entry <MCP-dist/index.js> once.
This integration uses the public MCP protocol and does not bundle the ModKit
runtime or game assets. It uses effective Data functionality from
SC2Editor-MCP-Codex by VoVanRusLvSC2.
The catalog-domain mapping follows that project's Data module; its
attribution license is retained.
Map Performance is complete for the Region-based workflow: select Regions,
review the exact placements and Keep in map choices, then create an optimized
copy of the map. Each selected Region gets one Create_<RegionName>()
function that recreates its removed decor and eligible units; call it from your
GUI trigger when that area is needed. The matching Clear_<RegionName>()
removes the objects created by that function. Nothing is created automatically
at map start. The original map is left intact.
Large Regions use small internal DecorOpt_CreatePart_* helpers to stay within
Galaxy's function-size limit; triggers still call just one Create function per
Region.
The generated Galaxy code reapplies model variation and team color and uses the
placed object's world position, rotation, scale, and tint. Editor-only
HeightOffset and ForcePlacement flags do not by themselves exclude decor.
Nullable tint (NULL HDR) is retained as a native nullable color; it is never
replaced with explicit white. This matters for weather emitters and lights with
large HDR multipliers. Native terrain archive components stay unchanged.
An ObjectDoodad with a TerrainObject-style actor name or editor category is still
a placed visual actor; that name/category alone does not block conversion.
Ordinary cliffs, platforms, roads and ground-cover
doodads remain eligible for conversion; visual appearance is not a surface
classification. Local catalog footprint dependencies are checked separately. Terrain
archive components are preserved. Direct placement references in triggers/scripts
keep the referenced decor or unit in the map. Type names, spawn calls and group
loops do not block conversion by default. Broad type protection is optional:
Keep all types mentioned in triggers/scripts or CLI --keep-referenced-types.
Galaxy comments do not count as type references. Computed type names/custom
enumeration wrappers require manual Keep in map exclusions. Unit types to
keep explicitly preserves a whole type; the GUI default is CommandCenter.
The individual-unit chooser supports manual keep selections.
Initially hidden/UnitNoCreate placements available to AI stay native by default;
both conditions are required. Visible AI buildings remain eligible for conversion.
Keeping every Computer/Hostile building is a separate option, off by default,
using MapInfo controllers and the Structure attribute with local inheritance.
Exported nonzero model variants enable VariationPreload
and disable VariationFallback, with constant-ID model preloads before creation.
ModelData.xml changes are reversed exactly alongside actor data and preload data.
An unfiltered query for all units does not automatically exclude every type.
CLI --keep-doodad-id and --keep-doodad-type offer repeatable explicit exclusions
when a whole cinematic area should stay native.
The runtime uses the actor returned directly by ActorCreate, so creation of
child actors cannot redirect placement messages. Rotation,
pitch, and roll are converted from Objects radians to an explicit forward/up
basis and sent through NativeLib SetRotation, including zero rotation. The
full basis initializes the placement source before construction and is also
applied directly to the returned model actor after construction; all three
axes are retained for compound rotations.
XML Pitch rotates around model X and Roll around model Y, in the order
Rz(Rotation) * Rx(Pitch) * Ry(Roll). The earlier mapping swapped Pitch and
Roll, which tilted compound placements incorrectly even though a reverse
conversion could restore the original XML exactly. Regression checks now cover
each axis separately as well as KSP-3's large temple wall.
The placed-doodad rotation uses local model axes, while the actor-message parser
uses local -Y as forward. The conversion preserves that distinction; using
MakeModelFaceAngle directly adds an unwanted 90-degree model rotation.
Regression checks reconstruct the model orientation using the message parser's
basis and compare it with the placed-doodad loader's quaternion composition.
Model variant 0 is selected explicitly. Animation initialization belongs to the
original actor's runtime catalog: inherited events, event macros, animation
brackets, global loops, speeds and fog behavior remain under the game's control.
The export does not replace them with EditorAnim (an editor preview selector),
force a generic Stand, or replay creation events and duplicate their effects.
The model and its zero-based variant are passed as the first two content
parameters of ActorCreate, before model initialization. For explicit variants
of multi-variant models, the runtime also sends ModelSwap with that same model
link and index. Converted maps merge the exported actor/variant pairs into native
Preload.xml, preserving the source's other preload entries.
The placement loader also initializes position and rotation before constructing
the doodad's cached fog bounds. Creating at the origin and moving afterwards
leaves those bounds at the origin, which can pause animations and particles
even when the visible model has moved into the player's view.
Map conversion now adds a placement site and CopySource fields to each exported
actor type and copies initial bearings in a separate actor scope. Original actor
IDs and inherited token/event identity are retained (including ##id## links).
Initial transfer alone does not pin a doodad's world coordinates: its native
position getter can fall back to the scope position plus a height offset.
The exporter now explicitly sets XYZ on the created actor as well as the
placement source, before applying its full rotation and scale. This preserves
negative absolute heights for below-surface decor. Numeric/roundtrip checks
verify saved data, not the resulting appearance in the game.
No animation or fog flags are overridden. Clearing a region destroys its scopes
and their child actors. The generated Galaxy requires these fields in the
converted map's ActorData.xml; copying the Galaxy file alone is insufficient.
Restore returns the original actor catalog byte for byte (or removes it if
the source had none), and refuses to overwrite catalog edits made after export.
Stand, Stand 01 and Stand 02 are model animation clips, separate from the
placed model variation. Their choice remains with the original actor.
This path applies to all exported doodad types, including wind socks and snow
effects.
The runtime reads the effective Model link from the game catalog, so dependency
and custom-mod overrides do not depend on a particular local cache snapshot.
Exact random animation phase is not preserved. A convert/restore comparison
verifies saved placement data; it does
not execute Galaxy or prove that the game renders those placements identically.
Footprint/pathing objects, unknown placement fields, and referenced objects
stay in Objects; Preview shows the reason. Visual equivalence still requires
an Editor and in-game check for each map.
Choose units to keep in Objects... opens a searchable list grouped by unit
type. Check one unit or its type to keep it in Objects; units protected by
the safety rules are shown as already kept. The CLI supports repeatable
--keep-unit-id <id> and --keep-unit-type <type> options.
SC2DecorOptimizeMap <converted> <restored> --restore now imports native
placements from the executable SC2DataHelper Galaxy statements, without reading
a JSON Objects backup. XYZ comes from the absolute-world transform passed to
the creation helper. Original angle literals are preserved; older exports
without them are restored from the forward/up basis. Scale,
variant, team color, tint and units come from the creation/tint statements.
One compressed, short-line header block carries only object identity and editor
flags, not transforms; creation functions contain no per-object comments.
Incomplete, unsupported or duplicate-ID imports fail without creating a map.
Re-export older maps to obtain these identity annotations. The separate exact
backup rollback API remains available internally.
Restore JSON/XML files are off by default. The GUI checkbox Include restore
backup files (JSON/XML) persists this preference; the CLI equivalent is
--restore-sidecars. Without these files, Galaxy keeps the compact identity,
flags and actor-catalog cleanup annotations needed for a round trip. It does
not contain a duplicate Objects backup. The runtime ActorData.xml patch is
still required for initial world placement and is separate from restore
sidecars. Do not delete sidecars from older exports whose annotations were
stored externally; regenerate those maps instead.
The restored copy keeps public Galaxy entry points as no-op compatibility
functions, so existing GUI triggers compile without spawning duplicate actors.
Runtime recreation passes one literal transform string to the shared
creation helper, which sends SetPosition and SetRotation separately,
preserving absolute negative Z and avoiding additional Galaxy
fixed-point rounding. Before setting XYZ/rotation, each created doodad receives
HostSiteOpsSet ::Host with an empty operation list and held position/rotation.
This bypasses host placement adaptation on the created instance; native objects
of the same type keep their catalog host operations. ActorCreate has no
unit-style ignore-placement creation flag. This establishes explicit world bearings; an actual game
comparison is still required for catalog events, host operations and cinematic
behavior.
Runtime scope/unit arrays use disjoint slices sized by the total exported placements, rather than multiplying the largest region by the largest region ID. The helper uses the same bearings message before and after creation, avoiding duplicate XYZ/rotation constants. Catalog rollback data is split into short header lines as well. These checks reduce compiler pressure; passing the application tests is not an in-game Galaxy compilation check.
Explicit model variants use native Preload.xml actor entries with zero-based
Variations indices. Computed runtime PreloadModel calls are not used.
Galaxy-only export includes the matching .Preload.xml and actor data, which
must accompany the script. Restore verifies and restores the original preload.
For overlapping Regions, a placement belongs to the smaller Region. A unit
whose only extra editor flag is ForcePlacement is recreated with placement
restrictions ignored. Other unsupported unit fields keep that unit in Objects,
with the reason shown in Preview.
Only simple unit placements that can be recreated safely are moved. A direct
trigger or script reference to a specific unit (by its ID or name) keeps
that unit in the map. A reference to its unit type, such as
UnitGroup("CommandCenter", ...), keeps all placements of that type; Preview
names the referencing file. Comments, catalog definitions and preload entries
alone do not count as trigger references. Generic operations that enumerate
all units in a Region, without a concrete type, do not block conversion.
Such operations may see different
units before and after you call Create_<RegionName>(); check the
timing of your triggers and use Keep in map for units that must exist from
map start. Preview the result before applying the copy.
Нюанс для юнитов: блокирует перенос только прямая ссылка на конкретный юнит
по ID или имени. Действие триггера «все юниты в регионе» само по себе не
блокирует перенос каждого юнита. До вызова Create_<имя региона>() такие
юниты отсутствуют в копии карты; при необходимости оставьте конкретный юнит
через Keep in map.
The tool can create or update DataCollectionData.xml and preserve existing
collections instead of recreating the file from scratch.
Supported workflow:
- detect related families from real catalog links
- reuse existing
CDataCollection,CDataCollectionUnit,CDataCollectionAbil, andCDataCollectionUpgrade - add missing
DataRecordentries for supported real objects - keep existing records, metadata, and unrelated XML nodes
- update archive
(listfile)when needed - default to
UnitAbilWeaponmode, creating separate Unit, Ability, and Weapon collections where the data supports it
UnitAbilWeapon is the single optimized mode used by the application. Shared
unscoped objects receive one deterministic canonical owner instead of being
copied into every reachable collection. Unique owned child IDs can be
standardized as CollectionID@Role; remaining shared or non-standard objects
stay linked through explicit DataRecord entries.
The tool works with real SC2 object IDs. It can also handle non-standard naming
when the map already contains existing custom IDs outside the CollectionID@Child
style.
Destructive operations are preview-first and backup-first.
- No blind automatic deletion
- Duplicate merge redirects references before delete
- Unused-object cleanup skips unsafe rows instead of stopping the whole batch
- Rollback is used on apply failure
- Archive mode stays conservative when binary references cannot be proven
- Data Collection records are preserved even when related objects are deleted
- Standalone
.SC2Mod/.SC2Campaignsources protect public catalog IDs and imports that may be consumed by maps or mods outside the current analysis
Find catalog data objects with no incoming XML references and no script/text usage. Whitelisted, protected, and referenced objects are blocked. Linked unused subgraphs can be removed as chains when every incoming XML source is also part of the selected deletion set.
Detect exact duplicate normalized XML bodies for the same object type, preview reference redirects, then keep one object and remove the duplicate safely. Duplicate Merge is enabled by default in the Optimization Wizard.
Find unused imported files separately from catalog object cleanup. This covers
assets such as .dds, .m3, .ogg, .wav, .tga, .layout, and related
files when they are not referenced by Data XML, layouts, triggers, preload
data, or game strings. In archive mode the wizard materializes cleanup-relevant
archive entries into its workspace before apply. A direct .SC2Map can remove
proven unused imports from the packed file. For a standalone .SC2Mod or
.SC2Campaign, imports with no local reference remain review-only because an
external consumer can still use them.
Editor-managed map files such as Minimap.tga, LightingMap.tga, and
PreloadAssetDB.txt are protected even when normal XML references do not point
to them.
Binary model-like files such as .m3 are also scanned for printable embedded
asset paths. This protects textures and related imports that are referenced only
inside model payloads rather than in XML.
Find and optionally apply safe cleanup outside data-object and import deletion:
- stale localization lines for object IDs that no longer exist
- redundant attributes that duplicate a local parent object's value
- redundant direct XML child nodes that duplicate a local parent object's node
- broken actor event XML nodes that reference only missing typed IDs
- temporary, report, backup, and pending helper files
- dependency metadata as review-only candidates
Dependency removal is intentionally review-only because hidden editor/runtime links can break a map even when XML references look unused.
Deep Cleanup also reports review-only optimization hints that are useful for manual work but are not safe to auto-apply:
- byte-identical imported assets and unusually large imported assets
- frequent trigger/Galaxy timer patterns and unit-group scan hotspots
- semantic duplicate catalog objects that match after ignoring editor-only text, icon, tooltip, and category fields
These checks follow the same general direction as community SC2 tooling such as Talv's Plaxtony and sc2-galaxy-toolkit: Galaxy, Trigger XML, Layout XML, and GameData should be analyzed as structured SC2 data instead of treated only as plain text. This project does not vendor that TypeScript code.
Preview and apply rename plans for unit-family style data, including archive mode. This remains review-first because many maps use custom naming rules.
Build one batch plan, review every step, apply changes, refresh analysis, then close the wizard. One unsafe unused-chain row no longer cancels the whole apply; it is skipped and reported while the rest of the selected safe work continues.
Very large Data Collection plans remain available for inspection but are not preselected. This prevents a broad family-detection result from adding tens of thousands of records without explicit review; the remaining safe cleanup steps still run for large extension mods and asset packs.
Settings includes an explicit Closed Project / Aggressive standardization
option. It enables public ID/import changes for .SC2Mod and .SC2Campaign
sources, uses higher reviewed batch limits, and allows the rename-first,
Patterns-then-Records workflow. Enable it only when every consuming map/mod is
owned and will be updated together. The command-line equivalent is
SC2OptimizeMaps --closed-project <archive.SC2Mod>.
When archive optimization rewrites an MPQ-backed .SC2Map or .SC2Mod, the
archive writer also attempts a best-effort compact/repack after replacements or
deletions. If StormLib cannot safely compact a legacy archive, the already
verified rewrite is kept instead of failing a valid cleanup.
- Open an
.SC2Map,.SC2Mod, folder, or XML file - Run
Analyze - Review Data Collection, Unused Data Objects, Import Cleanup, Duplicate Merge, or Optimization
- Preview the change
- Apply only after checking the result
Requirements:
- Windows 10 or Windows 11
- CMake 3.24+
- Qt 6.5+ with
Widgets,Concurrent, andTest - Visual Studio 2022 or another C++20 compiler
$env:QT_ROOT = 'C:\Qt\6.8.2\msvc2022_64'
.\scripts\dev.ps1 -Action Test -Configuration Debug
.\scripts\dev.ps1 -Action Run -Configuration DebugRelease executable:
build/windows-msvc/Release/SC2DataHelper.exe
scripts/dev.ps1 is also the recommended entry point for VS Code and coding
agents. It uses the checked-in CMake preset instead of paths specific to one
computer. Install CMake, Visual Studio 2022 with C++ support, and a Qt kit;
set QT_ROOT to that kit before running it.
- Always test the optimized copy in StarCraft II Editor
- XML analysis cannot prove every binary/runtime reference inside archives
- This is a community project and is not affiliated with Blizzard Entertainment