stefanh-at / source-engine-vscode-extension

A vscode extension that adds intelligent support for source engine file types and operations

Source Engine Support for Vscode

Visual Studio Marketplace - OpenVSX Registry

Discord - Bugs

---

This extension adds intelligent syntax highlighting and additional tooling for Source Engine file formats.

Syntax highlighting

Available for:

• KeyValue files
  • .vdf .res .acf .kv .vmf .vmm .vmx
  • .txt files can be auto-detected as being KV files
• .vmt
• .fgd
• .qc
• .cfg
• lights.rad
• .vpc, .vgc
• .smd
• .fxc and _fxc.h

In-Editor compilation

Instead of juggling standalone tools or CLI programs, simply compile model (.qc) and captions (subtitles_english.txt) right inside of the extension.

KeyValue file auto-detection

In Source, many KeyValue files are saved with a .txt extension. Since not all .txt files should be treated as KeyValue files, this extension can auto-detect KeyValue files which end in .txt. Instead, KeyValue files are matched using a list of common keyvalue file names. (e.g.: gameinfo.txt, game_sounds_*.txt, subtitles_engish.txt...)

Full feature list

Here's a list of all the things that are implemented in this extension

General

• KeyValue syntax highlighting
• KeyValue semantic highlighting
• Auto-detect common file names like gameinfo.txt
• Semantic Tokenizer
• Error detection
• Duplicate key detection
• Support for #include and #base
• Support for conditionals (e.g.: [$Debug])

VMT

• .vmt syntax highlighting
• .vmt semantic highlighting with error detection and completions
• Parameter name completion
• Config for parameters
• Parameter value completion
• Parameter value validation dependent on parameter name
• Texture (vtf) file path completion and missing file detection
• Color value preview

FGD

• .fgd syntax highlighting
• UnifyFGD syntax support (Hammer Addons)

QC

• QC syntax highlighting
• Compile model button
  • Configuration for mdlcompile.exe
  • Configuration for game root path

Captions

• Captions syntax highlighting
• Captions markup highlighting (I, B, clr tags...)
• Captions color preview (clr tags)
• In-editor Compile captions button

CFG

• .cfg syntax highlighting

VPC

• .vpc and .vgc syntax highlighting

Lights.rad

• .rad file syntax highlighting

Soundscripts

• Soundscript syntax highlighting
• Soundscript snippets

SMD

• .smd syntax highlighting

FXC

• .fxc syntax highlighting
• _fxc.h syntax highlighting (Shader header files)

---

Sourcelib

This extension implements the features seen in sourcelib.

Contributing

This repository uses trunk based development, which means that all changes can be pushed straight to master. Every commit is automatically tested via the CI pipeline. Once a new version tag is pushed, the release is deployed.

As an outside contributor, please create your pull requests to merge to the master branch. Do not edit changelog.md or the feature listings in readme.md as the changelog will be handled later when releasing.

Make sure all workflows succeed. To validate locally:

npm run lint
npm run test

Compiling and testing locally

Users can just install this extension on the VSCode Marketplace, but developers might want to run the development build of the extension.

Prerequisites

1. Install NPM and NodeJS (>v12)
2. Install Visual Studio Code (Duh)
3. Clone the repository
4. Run npm install in the repository's folder, to install the dependencies

Testing

To start the unit tests, run npm run test. The project will be automatically compiled.

Benchmarking

To run the benchmark tests, run npm run benchmark. The project will be automatically compiled

Running the extension

1. To start the extension, first compile the project npm run build (Or npm run watch to auto-compile on every file change)
2. Open the repository in VSCode
3. Open the 'Run and Debug' tab
4. Select the 'Extension' run configuration on the dropdown on the top
5. Run by pressing F5

License

This project is licensed under the GNU Public License version 3: License

source-engine-vscode-extension's Issues

Incorrect KeyValues versioning

Valve's KeyValues format has 3 versions with very different syntaxes:

• KeyValues
• KeyValues2
• KeyValues3

The extension implements a mixture of KeyValues and KeyValues3 syntax which is incorrect for both:

• KeyValues1 doesn't support arrays [ ... ]
• KeyValues3's own example is not supported

Add hint to set up qc and caption compilers

When opening a qc, a hint could pop up to remind users to set up their compiler. Shouldn't be annoying but a little hint would be good otherwise people might not even know that the feature exists

Move default shader parameter out of package.json

Currently, all vmt shader parameters are in package.json, which makes that file really huge for pretty much no benefit.

The vmt language features should be moved into sourcelib anyway, so let's start with this.

There should still be a way to add additional custom shader parameters, but there is no real benefit in the ability to remove or replace the whole list.

VMT does not stand for Valve Material Type

This extension (along with many other community tools) currently refers to .vmt files with the somewhat strange sounding name of Valve Material Type, but it should actually just be calling the format Valve Material.

According to Valve's original SDK documentation, VMT officially stands for Valve Material. The specific name Valve Material Type seems to have come about as a result of a VDC editor randomly changing this as part of a large page rewrite. Given that the editor provided no source for this, and I cannot find that name being used in any official place (SDKs, old docs, the tools themselves, etc.) I am inclined to believe that Valve Material is the correct name for the format.

I already changed this on the VDC a while back and nobody has objected to it despite several edits being made to the page since, so it seems like most people agree with my reasoning. Feel free to correct me if I'm wrong though and this name was used somewhere officially.

Captions compilation button

Add a button to the file editor toolbar to compile the current captions file.

Path to captioncompile.exe must be configured

Block comments do not work in qc

Currently the extension doesn't support it

"Invalid matrix format" on $phongfresnelranges

It claims to be in an incorrect format, but isn't. "$phongfresnelranges" "[.5 .5 1]" (This is a default file in TF2 and not a custom one)

I've also noticed that in this issue and the $color issue I posted previously, the quotes are sort of messing with this? When I removed the quotes it goes away. However at the same time WITH quotes, it will be made valid when I go from another file in VSC back to the file containing the phong parameter. (The $color parameter needs quotes so it's exempt from this case.) It's very strange, maybe something wrong with Intellisense? The quotes are needed because of spaces in the parameter so this is not optional.

Captions color preview doesn't work

The preview for <clr> tags no longer works

Improve caption compilation button error handling

The error handling is rudimentary, make it better.

Only captions files located in the compiler's game path seem to actually work. When compiling subtitles outside of the game project, error code 1 is returned. There should be some hints about this behavior.

Implement captions preview renderer

This sounds pretty complex, so idk if this will ever get done

Kv duplicate check detects duplicate key if they are in separate objects with the same name

visgroups {
  visgroup {
    name "Group 1"
  }
  visgroup {
    name "Group 2"
  }
}

The key name will be detected as a duplicate, since the scope of .visgroups.visgroup#name is the same.

Color Themes overriding syntax highlights.

When enabling my color theme it overwrites some of the highlights:

There's another extension called "Valve KeyValue Files Support" which does not have this issue:

Model compilation button

Add a button to compile a .qc file

VMT completions, hover tips, color and error inspection

Completion

• Auto-complete shader name
• Auto-complete shader parameter names
• • Automatically insert default value, if exists
• Auto-complete shader parameter values
• • List all textures for texture type
• • • Include internal render targets (_rt)
• • Read additional completions from config

Hover

• Hovering over shader parameter name shows description and info about the parameter
• Hovering over shader name shows shader description for shader

Color Hints

• Color hints for parameter values of type color

Error inspection

• Detect duplicate parameters
• Detect invalid parameter values
• • scalar is out of range, or not a number
• • int is not int
• • bool is not bool
• • texture is not found
• • color is not valid

Write user manual and improve readme to reflect features better

Add option to turn VMT param value number auto detection off

The value of a shader param, which is known to be a number, is highlighted to be a number even when placed in a string. Some people find this to be confusing, so an option should be added to configure that

FGD: comments within choices and flags keyvalues do not get highlighted as comments

This example is from HammerAddons worldspawn.fgd

Add support for #include, #base declarations

https://developer.valvesoftware.com/wiki/KeyValues

basically:
#include appends another file to the current one
#base merges another file into the current one (replacing existing key/value's)

I haven't seen them in use yet either, but it's a core feature of valve's keyvalue files (unless they removed it later on)

https://github.com/ValveSoftware/source-sdk-2013/blob/master/mp/src/tier1/KeyValues.cpp#L2238
https://github.com/ValveSoftware/source-sdk-2013/blob/master/mp/src/tier1/KeyValues.cpp#L2325

Incomplete HammerAddons FGD tags support

There currently seems to be some support for HammerAddons tags, but it's very limited. Single tags on keyvalues and I/O will be highlighted blue, but using multiple tags or inverted tags will cause the surrounding coloring to break.

For spawnflags and choices type keyvalues it's worse, adding the FGD tags at the end of the line will break coloring for the entire rest of the file past where the tag is located.

For reference, the full list of supported features can be found here

Valve QC integers and floats matches as strings

Hey, migrated today from atom to VSCode due I/O performace issues, so I've been here, thank you for the extension. I've seens is more powerful and handy than atom's counterpart

I've found that macros, anything that preceed a minus signal mathes wrong syntax color (same as string, i think?) so everything is tinted as the same color

I've been keep maintance of a local version for my atom, forked from CosignCosine/language-qc that matches with different syntaxes, but as i've seen I did a totaly different thing

Soon as understand how VSCode works I wish to contribute to Valve's QC, VMT and probably DMX formats.

Changing settings requires a restart

Currently, users need to restart vscode to apply any change to the settings, which adds a lot of unnecessary friction. Settings should be automatically updated in the extension

Rewrite kv formatter

• Standardize indents
  • Type as you go
• Standardize quotes
• Question form on how formatting should work
• Remove unnecessary spaces. Disabled by default
• Standardize shader names
  • Type as you go
• Standardize shader parameter slashes
  • Type as you go

Implement conditionals

Add QCI support

QC syntax highlighting doesn't support QCI files. QCI files are identical to QC files.

https://developer.valvesoftware.com/wiki/$include

FGD entry header is only colored for the first entity in a file

The headers of individual FGD entries only get highlighted if they are the first one in a file. Unsure if this is a result of only HammerAddons split FGDs being accounted for or just an accidental bug, but even within HammerAddons there are some cases where multiple definitions in one file are used, such as for Portal turrets to switch their model helper based on the game. Here you can see how only the first BaseClass is colored, the following two aren't (but it's keyvalues are):

Here's TF2's stock FGD, where you can also see only the first class being highlighted:

Additionally as seen in the first screenshot, comments don't seem to be colored outside of class definitions, inside they work fine.

FGD: Space after keyvalue/input/output type breaks syntax highlighting for the rest of the file

If the type of a keyvalue, input, or output is followed by a space, it breaks syntax highlighting for the rest of the file. Preceding spaces are fine.

Shader name completion, inspection and hover docs

"Invalid color value" for any rgb parameters when using Braces

Why are these marked as invalid when using the Brace version? $color "{78 104 203}"

I know that Brackets is one way of providing color values, but Braces are completely valid too, and allow you to more easily specify a range between 0-255 instead of 0.0 to 1.0. This is more of a minor nuisance than anything, but it's misleading for people who may not know the difference or know that the Braces are allowed too.

$rimlightboost incorrectly labelled as using Integer values instead of float values

$rimlightboost parameter in VMTs seems to give you a warning about not using integer values, however, it actually supports floating numbers.

FGD: Capitalizing flags or choices types breaks syntax highlighting

If a flags or choices type keyvalue has its type capitalized (as Flags/Choices or any other combination), the syntax highlighting will break for the rest of the file or until another one of these keyvalues with the type in lowercase. This causes a number of sections of Left 4 Dead 2's default FGD to appear wrong:

Warning when material texture file path is not found

Are there any plans to support qc files of GoldSrc?

They may be similar to the Soure Engine qc file format.
If it is already supported, please ignore, I don't know much about the Soure Engine.

Missing trailing " on $body

Conditionals dont work on object key

The conditionals only work when they're placed behind a kv paid but break when put between a key and a {

"Test" [$WIN]
{

}

Add support for multiple values in a kv

Keyvalues can have more than one value. Currently the tokenizer treats the next value as a new key

A new kv should only start on a newline

This is often used in files like scripts/soundmixers.txt

"Example" {
  key val1 val2 val3
}

Read additional completions for shader parameter values from config

Please upload 1.0.0 to OSVX

Please don't forget to update your extension on OpenVSX.

Kv strings dont auto close on unexpected newline leading to undefined behavior

This causes undefined behavior

"Key" "value

"

Publish to Open VSX registry.

There's a Open VSX registry which is used by code-server, openvscode-server, VSCodium. Would be nice to publish the extension there.

Implement playerclr for captions

https://developer.valvesoftware.com/wiki/Closed_Captions

Kv Code formatting

Add code formatting to properly indent lines

Ability to read vpks with a custom file system provider

Kv3 syntax object doesn't get detected when opening bracket is on another line

Works:

LightmappedGeneric {

}

Doesn't Work:

LightmappedGeneric
{

}

The regex should work, apparently tmLanguage only scans each line at a time?

FGD syntax highlighting no longer handles HammerAddons tags for keyvalues

Since some update, HammerAddons tags now cause keyvalues to stop receiving proper syntax highlighting:

kv_without_tags(boolean) : "Keyvalue without tags"
kv_with_tag[+srctools](boolean) : "Keyvalue with a tag"
kv_with_tags[P1, +P2](boolean) : "Keyvalue with multiple tags"
kv_with_not_tag[!HL2](boolean) : "Keyvalue with inverted tag"
kv_with_not_tag2[-EP2](boolean) : "Keyvalue with inverted tag using minus"

input in_without_tags(void) : "Input without tags"
input in_with_tags[P1, P2](void) : "Input with tags"

output out_without_tags(void) : "Output without tags"
output out_with_tags[P1, P2](void) : "Output with tags"

This still appears to work correctly for flags and choices: