Syntax highlighting for Quake 2 configuration files (Vanilla, Q2PRO, OpenFFA, OpenTDM, CTF, 3ZB2, Yamagi Quake II)
Syntax highlighting for Quake II configuration files. With support for modern source ports Q2PRO and Yamagi Quake II, game modifications OpenFFA & OpenTDM (widely used for multiplayer servers and modern successors of OSP Tourney DM), Yamagi CTF and Yamagi 3rd Zigock Bot II.
Note: This extension would work as a stand-alone, but for better colorizing the user should change the color theme to
Quake 2 Config Dark Color Theme.
This extension provides only basic Syntax Highlighting (no Semantic highlighting).
Should work with any VS Code theme (see Known Issues).
Example for VS Code default dark+ theme:
Example for VS Code default light+ theme:
Quake 2 Config Dark Color Theme:
For people who need to reading & writing Quake 2 configuration files:
- for any Quake 2 gamer;
- for Q2-server administrators.
How to Use?
- Install Visual Studio Code (an open-source, cross-platform editor) or use it online. There is also an option to create a portable VS Code.
- Install the extension.
- Go to the Menu: View > Extensions, input "quake2" into the search field, choose "Quake II Syntax Highlighting" and install it.
- Optional: there is a second dependency extension
amokmen.quake2-config-theme-dark which will be automatically installed. Use it for better colorization (it's a specially created color theme). Change the VS Code theme to "Quake II Config Dark Theme" by going to Menu: File > Preferences > Color Theme.
- Open a Quake 2 configuration file in the Editor by going to Menu: File > Open File. The file can have a .cfg extension, no extension, or any other extension.
- To make VS Code understand that the current file is a "Quake 2 configuration":
- Press Select Language Mode at the bottom of the Editor's interface and choose the "q2config" language;
- Or go to Menu: View > Command Palette, input "Change language mode" and choose the "q2config" language.
Syntax highlighting works for:
- Console commands (e.g., "bind", "set", "alias");
- Console variables (cvars) (e.g., "sensitivity", "rcon_password");
- Keyboard key names (e.g., special names like "SPACE", "KP_HOME", "SEMICOLON", "MWHEELUP", "F1" or usual keys like "q", "1", ".");
- Strings (single and double quoted);
- Numbers (in different formats);
- Comments (in-line, single-line, block).
Syntax highlighting doesn't work for:
- Cvars created by the user;
- Aliases (new commands) created by the user.
There are a few useful snippets (for execution just input short prefix of snippet and choose snippet in list):
- "dj" - Double Jump (to perform jump tricks);
- "zoom" - Zooming and changing sensitivity while button is pressed;
- "fish" - Fish-eye (wider observation);
- "line" - Choosing 'best' available weapon from pre-set order;
- "" - drops for TDM;
- "" - drops for CTF;
- "" - semi-automated Rocket Jump (user should view at ground by himself).
New in Q2PRO - triggers, so snippets to use with:
- "" - automated start of demo recording in TDM, after match begins.
Quake 2 is a sequel to the iconic FPS game by id Software.
It features a basic scripting language (console commands of different types and console variables) that can be used by players and server admins for writing configuration files.
The Q2PRO source port improves this scripting language by adding triggers, an "IF" command, and more.
How it works?
First extension ("tokenizer")
- The extension has lists of words that need to be colorized, and each list has its own scope name (see Scopes naming explanation).
- All these lists are called "grammar" (based on TextMate rules) and you can find them in the file
- The grammar is attached to a "language", in our case with the name "q2config".
- After opening a text file that is marked as "q2config", VS Code will try to find words from the lists line-by-line using regular expressions (regexps) - this process is called "tokenization".
- For every word found, VS Code assigns its scope name.
Second extension ("colorizer")
- After the tokenization process, VS Code has some words with assigned scope names.
- Matches between scope names and colors are in
- So, it's time to colorize words!
You could check any regexp from
syntaxes/q2config.tmLanguage.json online, for example, here. But be careful - need to change doubled symbols "\\" to single one "\" (Ex.: "\\b" --> "\b"). Because in JSON there must be double escaping.
TODO: add explanations and examples
Numbers are arguments for cvars and some commands.
What numbers should be catched:
Should not be catched:
set sensitivity 2,
alias myCommand "set sensitivity 2; say Hi!".
Regexp (JSON variant with double
This regexp explanation:
(?<=(\s|\")) - what should be BEFORE catching number (and not be included into result!) -
\s - means any white symbol(s) OR
\" - means double qoute.
-? could be or not be minus sign; ???
(?=(\s|\")) - what should be AFTER catching number (and not be included into result!)
How to make your own colors and/or font attributes
Let's make all OpenTDM cvars green and bold for example, and all OpenFFA cvars blue and italic bold.
.vscode/settings.json (create directory ".vscode" at root of your project's directory and create empty file "settings.json" in it) next section:
"fontStyle": "italic bold"
These settings would override your current theme settings.
You could change only 2 things: color of text and font attributes (italic, bold, underline, strikethrough and any combination of these 4 attributes).
Use scope name that you want to modify, from the file
Scopes naming explanation
Ex.1: let's explode scope name
variable.q2config.cvars.game.opentdm from left to right order.
q2config.cvars.game.opentdm - left part "variable" is special TextMate name, right part is created by me.
- "variable" - base scope name (one of TextMate's base scopes) - all theme authors should orient to this and any theme default styling depends only at it;
- "q2config" - language name (created by me);
- "cvars" - type of text tokens (created by me);
- "game" - sub-category: "game" or "engine" (created by me);
- "opentdm" - name of game modification (created by me).
Ex.2: let's explode scope name
support.function.q2config.functions.q2pro from left to right order.
q2config.functions.q2pro - left part "support.function" is special TextMate name, right part is created by me.
- "support.function" - base scope name;
- "q2config" - language name (created by me);
- "functions" - type of commands (according to JakFrost's classification there are 3 types of commands: action, operation, function) (created by me);
- "q2pro" - name of engine/mod (created by me).
later scopes override earlier scopes ?????
All scopes with description
Note: Order is important for priority while tokenization process! Order in which objects are placed in array "patterns". First object has higher priority.
TODO: add explanation for every scope
TODO: create good visualization for scopes
Meaning of "game" here - "game modification".
Modern Q2 source ports (game engines)
- Q2PRO - is a modern multiplayer-oriented client/server for Windows/Linux.
- Yamagi Quake II - is a modern single-player and coop oriented client/server for Windows/Linux/macOS.
Modern Q2 game modifications (also calling "mods")
- Cvars would be white in Nord theme as any other text - hard to read.
quake2-config-syntax - main project - Q2 grammar
quake2-config-theme - optional dependency for main project - theme for better colorizing (instead using non-special for Q2 grammar any other VS Code theme)
quake2-config-vscode-portable - sub-project for auto-build portable version of VS Code with pre-installed both extensions and some pre-defined settings (simplifying things for usual users)
example-grammar - learning project for testing TextMate's default token scopes with popular VS Code themes (how all scopes would be colorized)
Linux-based: paths, EOL and so on.
For better editing, open with VS Code
q2-config-syntax.code-workspace file in root project's directory (Menu: File > Open Workspace from File).
For testing under VS Code:
- run new VS Code debug window by pressing
- there would be opened test files for MANUAL VISUAL control
set is optional, both cases are valid:
set sensitivity "1" and
- Do not use single quotes - engine would take such string "as is" (without expanding) even including quotes themselves (Ex.:
say 'Hi' would produce exact
say "Hi" -->
- Quake 2 vanilla do not support block comments, but Q2PRO does support "/* Multiline block comment */".
- Q2PRO supports new syntax for
wait N, where N - number of waits (like wait*N).
- Assign value to cvar:
- Many white-spaces before value would be removed
set sensitivity 1 -->
sensitivity is "1".
- But nothing would be removed if value was double quoted!
set sensitivity " 1" -->
sensitivity is " 1".