Installation guide

Quick Setup Tutorial

First step - installing main part of the plugin

There are two options:

• quick and easy installation via AssetLib (stable version);
• manual installation from Github (you can get experimental versions of the plugin).

AssetLib way:

1. Open your Godot project, go to AssetLib tab, click on the GodotVMF and click download:

2. Wait until the plugin finishes loading:

3. When the download is complete, you will see a window like this with a scary red inscription.

Don't worry, this is completely fine!

Just click the "Install" button.

4. After installation you will see a window about successful installation, but at the same time you will see a bunch of terrible red errors in the console.

Don't worry, this is also normal :)

5. But that's not all! Now we need to go and enable plugins. Go to the Project -> Project Settings tab.

In the window that opens, go to the Plugins tab and enable the checkboxes you need.

Important

FGD Generator is an optional helper tool.

It is not needed for the main part of the plugin to work.

You will see windows with reimporting assets - this is normal, wait for the download to finish.

6. Now we save all scenes and restart the project.

7. After restarting the project, the example scene should open without any problems:

8. Great, we've installed the plugin itself! At this point, you can already use it with the default settings, but it is recommended to read the rest of the article about configuring Hammer and the plugin config file.

Manual-Github way:

Move the addons/godotvmf folder into the same folder of your project and activate it in your project settings.

Important

Possibly you'll have errors once you installed the plugin. Just restart the project.
Project -> Reload Current Project

Second step - Hammer configuration

1. Download Source SDK Base 2013 (Singleplayer or Multiplayer).

2. Download Hammer++ and put all files into SDK Base 'hl2/bin' folder, for example: SteamFolder/steamapps/common/Source SDK Base 2013 Singleplayer/hl2/bin

Important

A regular Hammer should work too, but stability is not guaranteed.

The processing speed will be slower, the quality of the final geometry will be worse (vertex locations). This is because the brush geometry data format in the VMF file is slightly different.

3. Download the blank mod folder and put everything inside your project.

Warning

If you have issues with Hammer work - it may be related to shaders from the blank mod.

To fix these issues, replace the shaders from the blank mod with the current shaders of the project's 'hl2_misc_dir.vpk' from which you take Hammer.

For example, 'Team Fortress 2\hl2\hl2_misc_dir.vpk\shaders' or 'Half-Life 2\hl2\hl2_misc_dir.vpk\shaders'

To open .vpk files you can use GCFScape or VPKEdit (recommended).

4. Launch Hammer++ and configure it (Tools -> Options):

• Game Executable Directory - path_to_your_project
• Game Directory - path_to_your_project
• Hammer VMF Directory - path_to_your_project/mapsrc - usually some Source Engine developers create mapsrc folder where sources of maps are placed
• Prefab Directory - path_to_your_project/mapsrc/prefabs

5. That's it!

Important

You can also set Run Map settings to launch levels for testing directly without leaving Hammer:

https://github.com/H2xDev/GodotVMF/wiki/Launch-maps-from-hammer

Third step - Config file

Before work with the plugin you can create in the root of the project a file vmf.config.json.

Important

In the latest versions of the plugin (and without using materials-sync), the presence of this file is not required - default settings will be taken.

Default config:

{
	"gameinfo_path": "res://",
        "vtfcmd": "res://tools/vtfcmd/VTFCmd.exe", // ONLY IF YOU USE THE MATERIAL-SYNC TOOL!

	"import": {
		"scale": 0.02,
		"generate_collision": true,
		"generate_lightmap_uv2": true,
		"lightmap_texel_size": 0.4,
		"instances_folder": "res://instances",
		"entities_folder": "res://entities",
		"geometry_folder": "res://geometry",
		"use_navigation_mesh": true,
		"navigation_mesh_preset": "res://presets/navigation_mesh.tres",
		"entity_aliases": {
			"npc_ghost": "res://objects/npc_ghost/npc_ghost.tscn"
		}
	},

	"models": {
		"import": true,
		"lightmap_texel_size": 0.4,
		"target_folder": "res://"
	},

	"materials": {
		"import_mode": 1,
		"ignore": [
			"TOOLS/TOOLSNODRAW",
			"TOOLS/TOOLSSKYBOX",
			"TOOLS/TOOLSINVISIBLE"
		],
		"fallback_material": null,
		"default_texture_size": 512,
		"target_folder": "res://materials"
	}
}

• gameinfo_path - The source mod path where resources placed to work with hammer.

• import

  • scale - In case you need to convert Valve's metrics to yours.
  • generate_collision - If true then generates CollisionShape3D for imported geometry (except brush entities) by using trimesh shape.
  • generate_lightmap_uv2 - If true then generates UV2 to enable light baking.
  • lightmap_texel_size - Size of each texel in the lightmap for more precise light baking (use with caution, very low values can cause crash).
  • instances_folder - Path inside the project where imported instances be placed.
  • entities_folder - Path inside the project where importer will grab entities during import.
  • geometry_folder - Path where the importer will store any mesh or collision resource that is generated.
  • use_navigation_mesh - If true, then generates navigation mesh for the generated geometry
  • navigation_mesh_preset - Path to the NavigationMesh resource that will be used for generated navigation mesh instead of default settings
  • entity_aliases - In case you don't want to place some entities inside the entities folder you can use aliases

• models

  • import - If true then importer will try to import models from the mod's folder.
  • lightmap_texel_size - If true then generates UV2 for static props for light baking (global default value, can be overridden by eponymous keyvalue in prop_static entity, which can be manually added using Add button in object properties).
  • target_folder - Path inside the project where imported models be placed. In default config it's root because all model paths in prop_static already have models folder specified

• material

  • import_mode - The mode of importing materials
    • 0 - Use existing
    • 1 - Import directly from mod folder. Already imported materials will be ignored.
  • ignore - List of materials that should be ignored during import.
  • fallback_material - Path to the material *.tres that will be used as a fallback for ignored materials.
  • default_texture_size - The size of the texture that will be used in case of missing texture.
  • target_folder - Path inside the project where imported materials be placed.