Decompiling Maps: Difference between revisions

From Valve Developer Community
Jump to navigation Jump to search
No edit summary
 
(99 intermediate revisions by 33 users not shown)
Line 1: Line 1:
Decompiling is the process of taking a compiled level and generating a source that can be opened in a map editor. Decompiled levels mimic the original source, they are not exact reproductions. This makes them useful for learning, measurement, and inspection, but not direct recompilation. The original source is ideal for reproductions or modifications.
{{LanguageBar}}
 
[[Category:Level Design]]
Releasing reproductions, modifications, or approximations of another's work without permission nor credit is frowned upon and may be considered as a copyright violation.
[[Category:Tutorials]]
==Tools==
* [[Entspy|EntSpy]]
* [[BSPSource]]
* [[Vmex]]
* [[BSP2MAP]]
* [[MapFool]]
* [[xwad]]
* [[WinBSPC]]
* [[BSP Viewer]]


== Getting Dirty ==
'''Decompiling''' is the process of taking a compiled map file and generating a file that Hammer can open. Decompiled maps are not perfect recreations, because of format differences{{clarify}}, loss of data (such as missing {{ent|func_viscluster}} or {{ent|func_occluder}}, tools textures such as NPC Clip or Player Clip all replaced with either Nodraw or entirely replaced with NPC Clip/Player Clip which cause lighting issues or NPCs/players to get stuck in some area, and imprecise vertex position on complex brushes). This makes them useful for learning, measurement, and inspection, but not direct recompilation. The original source is ideal for reproductions or modifications.
The latest decompiler is called [[BSPSource]] and is written in Java. You need an updated version of the Java Runtime Environment (JRE), which can be downloaded from [http://java.sun.com/javase/downloads/ Sun] to run BSPSource. Once installed, you are ready to decompile your first map.  


== Extracting Valve maps ==
Releasing reproductions, modifications, or approximations of another's work without permission nor credit may be considered rude to the author, is largely frowned upon, and is in fact copyright infringement, which may have legal consequences depending on the source of the map. There are methods of preventing maps from being fully decompiled (obfuscating textures, keeping entities or VScript server-side, etc.), but these are rarely used because most people who decompile maps are doing so to learn from them rather than to steal.


# Install [[GCFScape]].
==Decompilers==
# After you install GCFScape, go to <code>File &gt;&gt; Open</code>.
==={{source2|4}}===
#* For {{csgo}}[[Counter-Strike: Global Offensive]] maps, open '''<code>\steamapps\common\Counter-Strike Global Offensive\csgo\pak01_dir.vpk</code>'''
*{{vrf|2}} (used to view the entities and other lumps on a map, decompiling to vmap, and exporting to glTF)
#* For {{css}}[[Counter-Strike: Source]] maps, open '''<code>\steamapps\counter-strike source shared.gcf</code>'''
==={{src|4}}===
#* For {{dods}}[[Day of Defeat: Source]] maps, open '''<code>\steamapps\day of defeat source.gcf</code>'''
*{{entspy|2}} (used to view and edit the entities of a BSP without recompiling)
#* For {{hl2}}[[Half-Life 2]] maps, open '''<code>\steamapps\half-life 2 content.gcf</code>'''
*{{bspsrc|2}} (open source map decompiler for Source engine maps, based on VMEX)
#* For {{hl2}}[[Half-Life 2: Deathmatch]] maps, open '''<code>\steamapps\half-life 2 deathmatch.gcf</code>'''
*{{vmex|2}} (decompiler for Source engine maps)
#* For {{ep1}}[[Half-Life 2: Episode One]] maps, open '''<code>\steamapps\half-life 2 episode one.gcf</code>'''
*{{mapfool|2}} (helps porting HL1 maps to Source)
#* For {{ep2}}[[Half-Life 2: Episode Two]] maps, open '''<code>\steamapps\episode two maps.gcf</code>'''
*[[xwad]] (command-line tool to convert texture formats)
#* For {{portal}}[[Portal]] maps, open '''<code>\steamapps\portal content.gcf</code>'''
==={{gldsrc|4}}===
#* For {{portal2}}[[Portal 2]] maps, open '''<code>steamapps\common\portal 2\portal2\pak01_dir.vpk</code>'''
; Recommended{{colon}}
#* For {{tf2}}[[Team Fortress 2]] maps, open '''<code>\steamapps\team fortress 2 content.gcf</code>'''
* {{hlusmd|2}}
#* For {{l4d}}[[Left 4 Dead]] maps, open '''<code>steamapps\common\left 4 dead\l4d\pak01_dir.vpk</code>'''
** Requires .NET 6.0 Runtime.
#* For {{l4d2}}[[Left 4 Dead 2]] maps, open '''<code>steamapps\common\left 4 dead 2\l4d2\pak01_dir.vpk</code>'''
* {{005|2}} (recommended for {{nightfire}} only)
{{note|Left 4 Dead, Left 4 Dead 2, and Portal 2 also have other folders for DLCs, for examples:
; The following decompilers below are no longer recommended, as it is no longer updated, outdated and/or produces inferior results{{colon}}
'''<code>steamapps\common\portal2\portal2_dlc1\pak01_dir.vpk</code>''', '''<code>steamapps\common\left 4 dead\l4d_dlc1\pak01_dir.vpk</code>''', '''<code>steamapps\common\left 4 dead 2\l4d2_dlc1\pak01_dir.vpk</code>''' .}}
* {{bspviewer|4}}
3. Browse the directory until you find a <code>\maps\</code> folder. Each location varies per game.<br />
** Requires .NET Framework v1.1 (included with .NET Framework 3.5 SP1)
4. Right-click on the BSP file you want, then click <code>Extract</code> or drag the file from the GCF into a folder.
:{{Note|In {{crafty|2}} (updated version of BSP Viewer which support both {{src|1}} and {{gldsrc|1}}), the BSP decompilation feature has been removed.}}
*{{mbspc|2}}
*{{b2m|2}}
*{{winbspc|2}}
{{warning|[[BSP2MAP]], [[MBSPC]], [[005]] and [[WinBSPC]] are unstable and may not compile correctly in the end; {{hlusmd|1}} instead. It will still require manual cleanup, but is significantly more accurate.}}
==Files==
Most maps do not need to be extracted, as they are located in the file system rather than VPK. The map files are normally located in a ''maps'' folder, for example <code>common\Team Fortress 2\tf\maps\</code> holds all the official Team Fortress 2 maps.
{{note|A few games may have extra maps sectioned into other mod folders, for example <code>Portal 2\portal2_dlc1\maps\</code>.}}
{{note|A few games use [[Patching_levels_with_lump_files|lump file edits]] to edit existing entities,  and [[Commentary_System|comment files]] to add new entities without recompiling maps. for example: {{l4d2}} adds [[info_remarkable]] entities and [[env_player_blocker]] entities this way.<br>
BSPSource is capable of reading the .lmp files and incorporate its data, but it will not load entities from the commentary files. Luckily you can convert commentary files back to VMF files by following [[Commentary_System#Converting_Commentary_back_to_VMF|these steps]]. and merging those entities into the decompiled map.}}


== Before You Go ==
==Before you go==
Before you take this jump to run off and decompile a map take a second or two to think, "What am I trying to learn/do?".
Before you take this jump to run off and decompile a map take a second or two to think, "What am I trying to learn/do?".
Read the included TXT files, you may just find the creator's e-mail, and that could be more helpful than you imagine.
Read the included TXT files, you may just find the creator's e-mail, and that could be more helpful than you imagine.


Some mappers will offer up help and advice, they may even go so far as to provide perfect examples of what you were trying to "borrow" from the map.
Some mappers will offer help and advice, they may even go so far as to provide examples of what you wanted to borrow from the map.
 
==Porting newer maps to older Source games==
Decompiled maps from [[Left 4 Dead 2]], [[Portal 2]], [[Counter-Strike: Global Offensive]], and [[Alien Swarm]] will crash when loaded in the Hammer for [[Half-Life 2]], [[Team Fortress 2]], [[Counter-Strike: Source]], [[Day of Defeat: Source]] and other games based on {{src13|1}}, [[Orange_Box_(engine_branch)|Orange Box branches]] ({{src07}} - {{src09}}/{{srcmp}}) or earlier. Opening the map in [[Left 4 Dead]] Hammer and re-saving it will automatically convert it to be compatible.
{{Note|This VMF incompatibility issue does not affect {{gmod|1}}, as it ran on heavily modified version of {{src13|1}} that support assets from {{l4dbranch|1}} and later. Garry's Mod ships with modified version of Hammer which fixed the issue, allowing you to load VMFs (or decompiled maps) from Left 4 Dead 2 and later branches.}}


== See Also ==
{{todo|Document how to fix this manually. It's caused by L4D2 changing the character used to separate output values, but I'm not sure what character it changed to.}}
* [[Porting Half-Life maps]]


[[Category:Level Design]]
==See also==
[[Category:Tutorials]]
*[[Porting GoldSrc content (maps, models, etc.) to Source]]
[[Category:Source]]

Latest revision as of 22:02, 11 October 2025

English (en)한국어 (ko)Русский (ru)中文 (zh)Translate (Translate)

Decompiling is the process of taking a compiled map file and generating a file that Hammer can open. Decompiled maps are not perfect recreations, because of format differences[Clarify], loss of data (such as missing func_viscluster or func_occluder, tools textures such as NPC Clip or Player Clip all replaced with either Nodraw or entirely replaced with NPC Clip/Player Clip which cause lighting issues or NPCs/players to get stuck in some area, and imprecise vertex position on complex brushes). This makes them useful for learning, measurement, and inspection, but not direct recompilation. The original source is ideal for reproductions or modifications.

Releasing reproductions, modifications, or approximations of another's work without permission nor credit may be considered rude to the author, is largely frowned upon, and is in fact copyright infringement, which may have legal consequences depending on the source of the map. There are methods of preventing maps from being fully decompiled (obfuscating textures, keeping entities or VScript server-side, etc.), but these are rarely used because most people who decompile maps are doing so to learn from them rather than to steal.

Decompilers

Source 2 Source 2

  • Source 2 Viewer Source 2 Viewer (used to view the entities and other lumps on a map, decompiling to vmap, and exporting to glTF)

Source Source

  • Entspy Entspy (used to view and edit the entities of a BSP without recompiling)
  • BSPSource BSPSource (open source map decompiler for Source engine maps, based on VMEX)
  • VMEX VMEX (decompiler for Source engine maps)
  • MapFool MapFool (helps porting HL1 maps to Source)
  • xwad (command-line tool to convert texture formats)

GoldSrc GoldSrc

Recommended:
The following decompilers below are no longer recommended, as it is no longer updated, outdated and/or produces inferior results:
  • BSP Viewer BSP Viewer
    • Requires .NET Framework v1.1 (included with .NET Framework 3.5 SP1)
Note.pngNote:In Crafty Crafty (updated version of BSP Viewer which support both Source and GoldSrc), the BSP decompilation feature has been removed.
Warning.pngWarning:BSP2MAP, MBSPC, 005 and WinBSPC are unstable and may not compile correctly in the end; Half-Life Unified SDK Map Decompiler instead. It will still require manual cleanup, but is significantly more accurate.

Files

Most maps do not need to be extracted, as they are located in the file system rather than VPK. The map files are normally located in a maps folder, for example common\Team Fortress 2\tf\maps\ holds all the official Team Fortress 2 maps.

Note.pngNote:A few games may have extra maps sectioned into other mod folders, for example Portal 2\portal2_dlc1\maps\.
Note.pngNote:A few games use lump file edits to edit existing entities, and comment files to add new entities without recompiling maps. for example: Left 4 Dead 2 adds info_remarkable entities and env_player_blocker entities this way.
BSPSource is capable of reading the .lmp files and incorporate its data, but it will not load entities from the commentary files. Luckily you can convert commentary files back to VMF files by following these steps. and merging those entities into the decompiled map.

Before you go

Before you take this jump to run off and decompile a map take a second or two to think, "What am I trying to learn/do?". Read the included TXT files, you may just find the creator's e-mail, and that could be more helpful than you imagine.

Some mappers will offer help and advice, they may even go so far as to provide examples of what you wanted to borrow from the map.

Porting newer maps to older Source games

Decompiled maps from Left 4 Dead 2, Portal 2, Counter-Strike: Global Offensive, and Alien Swarm will crash when loaded in the Hammer for Half-Life 2, Team Fortress 2, Counter-Strike: Source, Day of Defeat: Source and other games based on Source 2013, Orange Box branches (Source 2007 - Source 2009/Source Multiplayer) or earlier. Opening the map in Left 4 Dead Hammer and re-saving it will automatically convert it to be compatible.

Note.pngNote:This VMF incompatibility issue does not affect Garry's Mod, as it ran on heavily modified version of Source 2013 that support assets from Left 4 Dead engine branch and later. Garry's Mod ships with modified version of Hammer which fixed the issue, allowing you to load VMFs (or decompiled maps) from Left 4 Dead 2 and later branches.
Todo: Document how to fix this manually. It's caused by L4D2 changing the character used to separate output values, but I'm not sure what character it changed to.

See also

Retrieved from "https://developer.valvesoftware.com/w/index.php?title=Decompiling_Maps&oldid=490692"