readme.md

August 12, 2026 · View on GitHub

GodotVMF (C# port)

This is a full C# rewrite of H2xDev/GodotVMF, an importer of VMF files into Godot Engine. Every GDScript file in the original addon, its plugin/importer core, and the entity scripts have been ported line-for-line to C#, so the whole plugin can be used from a C#-only Godot project without a GDScript dependency.

On top of the base addon, this fork also bundles the entity catalog that upstream ships separately:

All gameplay entities from H2xDev/GodotVMF-Entities
The demo-project entities from H2xDev/GodotVMF-Project-Template (func_door, func_button, func_door_rotating, func_tracktrain, ambient_generic, env_fade, env_shake, env_fog_controller, game_text, info_particle_system, info_player_start, path_track, point_teleport, point_viewcontrol, func_brush, ...)

so the addon works with a Hammer-built map out of the box, instead of requiring the entities to be copied in from two extra repos.

Highly recommended to use Hammer++ since it supports precised vertex data.

Features

Brushes geometry import (including UVs, materials IDs and smoothing groups)
Instances support
Native MDL support
Native VMT support
Native VTF support (only DXT1, DXT3, DXT5 supported)
Displacements import (with vertex data)
- WorldVertexTransition materials (blend textures) will be imported as WorldVertexTransitionMaterial
Entities support (full catalog bundled, see above)
Hammer's Input/Output system support
Surface props support
Material's compile properties support

Why a C# port?

The original GodotVMF is GDScript-first, which is a great fit for pure-GDScript projects but gets awkward once a project's gameplay code lives in C#: every entity hook ends up going through Call()/dynamic dispatch across the language boundary. This fork exists to remove that boundary entirely - the importer, the entity base classes and every shipped entity are plain C#, so a C# gameplay project can subclass, extend, and debug them like any other project script.

The behavior is intended to match upstream as closely as possible; divergences are bug fixes found while porting rather than deliberate redesigns.

Why detach from the GitHub fork network?

This repo has been detached from GitHub's fork network for H2xDev/GodotVMF and is now a standalone repository.

The codebase is fully different (C# vs GDScript) - staying marked as a "fork" implies a shared, diffable commit history with upstream that no longer exists here, which is misleading to anyone comparing the two repos.
Fork-network features (the upstream compare view, "N commits ahead/behind", suggested pull requests back to upstream) don't make sense across a full-language rewrite and mostly just produce noise or confusing diffs.
A standalone repo gets its own GitHub Insights/traffic stats and isn't subject to fork-network quirks tied to the parent repo (e.g. some visibility/network settings), and reads more clearly to newcomers as its own project rather than "yet another fork".
Credit and provenance aren't lost by detaching - they're preserved explicitly in this readme, in the Credits section and the Why a C# port? section above, rather than relying on GitHub's fork badge.

Versioning

Version strings follow <upstream-version>+cs.<port-revision> (SemVer build metadata), e.g. 2.2.11+cs.1:

The three-part base always equals the exact upstream GodotVMF tag this fork was last synced to.
+cs.N increments for each port-only release (bugfixes, entity fixes, etc.) cut between upstream syncs.
On the next upstream resync, the base is bumped to the new upstream version and the suffix resets to +cs.1.

2.2.11+cs.1   <- initial C# port of upstream v2.2.11
2.2.11+cs.2   <- port-only bugfix, still baseline v2.2.11
2.2.12+cs.1   <- resynced to upstream v2.2.12, port revision resets

Git tags mirror the version string with a v prefix (e.g. v2.2.11+cs.1). The current version is tracked in addons/godotvmf/plugin.cfg and can be bumped via the "Version Change" GitHub Actions workflow.

Made with the original tool

Echo Point by Lazy
Vampire Bloodlines map example by Rendara
SurfsUp by @bearlikelion
Team Fortress Jumper by Mickeon

Installation and Usage

Installation and map-side workflow is unchanged from upstream:

The only difference: since every upstream entity is already bundled and ported to C#, there's no separate GodotVMF-Entities or GodotVMF-Project-Template install step - just install this addon.

Do not use alongside the original GodotVMF

This fork and the original H2xDev/GodotVMF both define classes/scripts under the same entity names, so having both installed in the same project at once will cause script collisions (duplicate class names, ambiguous entity resolution, import errors). Use one or the other, not both.

If you're switching an existing project from the original addon to this port (or vice versa):

Remove the addon you're switching away from completely, including its addons/godotvmf folder.
Clean Godot's cached import files (the .godot folder) before reopening the project, since stale .import/cache data referencing the old scripts can cause errors or silently keep using outdated resources.
Re-import your VMF map(s) after switching, to make sure everything is regenerated against the newly installed addon.

Known issues

Extraction of materials and models from VPKs is not supported
Some of imported models may have wrong orientation
- Use Additional Rotation property in the MDL import options
Avoid importing a big bunch of models/materials at once it may cause the engine crash or import freeze. There's some issue with threaded import in the engine.
The FGD generator from upstream (compiling a FGD from entity source, see here) has not been ported yet, since it depended on parsing GDScript source directly.

Legality of use

If you would like to use the Source Engine SDK or other Valve Developer Tools for commercial use, please contact Valve at sourceengine@valvesoftware.com. There shouldn’t be any issues if you’re using it for non-commercial projects.

Contribution

If you have some ideas, suggestions regarding to quality or solutions of the problems above, feel free to contribute!

If you've added a new feature please add the relevant documentation.
Add yourself to the contributors section below

How to test the addon after adding new features or fixing some bugs

Install any of Source Engine Games (L4D, HL2, TF2)
Unpack all textures and models from VPKs
Decompile most complex maps
Try to import decompiled maps in Godot
Check for errors if they appear