Difference between revisions of "HPL3/Scripting/Scripting Guide/Setting up Visual Studio Code"

From Frictional Wiki
Jump to navigation Jump to search
m (Darkfire moved page Hpl3:Community:scripting:visual studio code setup to HPL3/Scripting/Scripting Guide/Setting up Visual Studio Code without leaving a redirect: Moving to the main namespace)
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
= Visual Studio Code Setup =
+
{{Hpl3ScriptingGuideMenuBasic}}
 +
{{shortPageTitle}}
  
−
This is an extended guide on how to setup Visual Studio Code to use Intellisense for HPL3 and SOMA. Visual Studio Code is a lightweight notepad-esque version of Microsoft's full IDE Visual Studio. As Visual Studio Code is still under active development, some steps of this guide may need to be altered, so feel free to do so as the need arises.
+
== Visual Studio Code language support ==
  
−
Note: Even though Visual Studio Code is a cross-platform program, HPL3 is designed to be modded on a Windows machine. As such, the instructions in this guide assume that you are on a Windows OS. (Linux users who have successfully gotten the HPL3 modding tools may use this guide as a base to get Intellisense working on their platform.)
+
[https://marketplace.visualstudio.com/items?itemName=TiManGames.hpl3-language-tools HPL3 Language Tools] is a community-made Visual Studio Code extension that provides language support for HPL3 <code>.hps</code> scripts.
  
−
== Install VS Code ==
+
It supports:
  
−
You will need to download and install VS Code. You can do so from Microsoft's [https://code.visualstudio.com/ VS Code website]. Simply choose your desired platform and download the installer. Follow the instructions given in the installer to install VS Code on your computer.
+
* ''SOMA''
 +
* ''Amnesia: Rebirth''
 +
* ''Amnesia: The Bunker''
  
−
== Open SOMA Folder in VS Code ==
+
The extension treats HPL3 scripts as their own AngelScript-based language instead of C++. This prevents unrelated C++ diagnostics and enables HPL3-specific completion, validation, navigation, mod overlays, and callback checking.
  
−
VS Code has the capability of opening an entire folder into its internal directory tree. Doing this gives you the benefit to be able to quickly and easily navigate to files in that folder and in subsequent folders. It also grants added benefits for inter-file relationships, such as C++ linking capabilities.
+
HPL3 Language Tools is not affiliated with or endorsed by Frictional Games. The game compiler remains the final authority when validating scripts.
  
−
To do this, simply navigate to your SOMA installation folder and right-click on the window background. (i.e. Don't click on any file or folder within the SOMA folder.) Then select the "Open with Code" option from the drop down menu:
+
=== Installation ===
  
−
[[File:01.png]]
+
==== Visual Studio Marketplace ====
  
−
== Associate HPS files with C++ ==
+
# Open Visual Studio Code.
 +
# Open the '''Extensions''' view.
 +
# Search for '''HPL3 Language Tools'''.
 +
# Select the extension published by '''TiManGames'''.
 +
# Click '''Install'''.
  
−
The first thing to do is to associate HPL3 script files with VS Code's C++ syntax highlighting engine. To do so, you need to open VS Code's preferences file:
+
<!-- Replace this comment with the Marketplace link after publication:
 +
[MARKETPLACE_URL Install HPL3 Language Tools from the Visual Studio Marketplace]
 +
-->
  
−
[[File:02.png]]
+
==== Local VSIX ====
  
−
In VS Code, settings are saved in a JSON file. The window on the left is the VS Code default settings, while the window on the right is a JSON file for creating and saving user configurations.
+
The extension can also be installed manually:
  
−
To associate <html>.hps</html> files with C++, simply copy the following text into the user preferences window (on the right):
+
# Download the latest <code>.vsix</code> package from the [https://github.com/TiManGames/hpl3-language-tools/releases GitHub releases page].
 +
# Open the Visual Studio Code Command Palette with <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>.
 +
# Run '''Extensions: Install from VSIX...'''
 +
# Select the downloaded file.
 +
# Reload Visual Studio Code if prompted.
  
−
<syntaxhighlight lang="">
+
=== Opening an HPL3 project ===
 +
 
 +
The simplest setup is to open the game installation folder as the Visual Studio Code workspace:
 +
 
 +
<pre>
 +
C:\Program Files (x86)\Steam\steamapps\common\SOMA
 +
C:\Program Files (x86)\Steam\steamapps\common\Amnesia Rebirth
 +
C:\Program Files (x86)\Steam\steamapps\common\Amnesia The Bunker
 +
</pre>
 +
 
 +
When the game folder is open, the extension normally detects the game automatically by locating:
 +
 
 +
* <code>hps_api.hps</code>
 +
* <code>resources.cfg</code>
 +
* The <code>script</code> directory
 +
 
 +
It is also possible to open an individual mod folder or another folder beneath the game installation.
 +
 
 +
If automatic detection fails:
 +
 
 +
# Open the Command Palette.
 +
# Run '''HPL3: Select Game Root'''.
 +
# Select the root folder of the appropriate HPL3 game.
 +
 
 +
The selected folder should be the main game folder, not its <code>mods</code>, <code>maps</code>, or <code>script</code> subdirectory.
 +
 
 +
=== HPS language association ===
 +
 
 +
Files ending in <code>.hps</code> should use the '''HPL3 HPS''' language mode.
 +
 
 +
The current language mode is displayed in the lower-right corner of Visual Studio Code. If it displays '''C++''', click it and select '''HPL3 HPS'''.
 +
 
 +
Some existing setups explicitly associate HPS files with C++:
 +
 
 +
<syntaxhighlight lang="json">
 
"files.associations": {
 
"files.associations": {
 
     "*.hps": "cpp"
 
     "*.hps": "cpp"
Line 33: Line 80:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
Afterwards, your preferences file should look something like this:
+
Remove that association if it prevents the extension from selecting HPL3 HPS. The extension may display a one-time warning about this configuration, but it will not modify the user's settings automatically.
  
−
[[File:03.png]]
+
=== Selecting an active mod ===
  
−
== Install CPPTools extension ==
+
By default, <code>hpl3.activeMod</code> is set to <code>auto</code>.
  
−
Next, you will need to get the C/C++ extension for VS Studio. To do this, go to the Extensions tab on the left side of the window. In the search bar, search for "C/C++". The extension you want should appear at the top of the list (it's authored by Microsoft). After you find it, click the green "Install" button:
+
In automatic mode, the extension selects the mod containing the currently opened script. To select a mod explicitly:
  
−
[[File:04.png]]
+
# Open the Command Palette.
 +
# Run '''HPL3: Select Active Mod'''.
 +
# Select the desired mod.
  
−
(After you install it, the window will need to be reloaded twice. The first time is after installing the extension, and the second time is after the extension downloads and installs its needed dependencies. Simply click on the "Reload" button as it appears and VS Code will restart itself for you, retaining your open files.)
+
The active mod controls script overlays, include resolution, completion, definitions, and project validation.
  
−
== Configure The HPL3 Profile ==
+
Resolution generally follows this priority:
  
−
Now you need to congifure the extension to use the HPL3 script files for its Intellisense. To do this, open the Command Palette by pressing "Ctrl-Shift-P". From there, find and select the "C/Cpp: Edit Configurations" option:
+
# The directory containing the current file
 +
# The active mod
 +
# Direct mod dependencies
 +
# Deeper transitive dependencies
 +
# The base game
 +
# Additional configured resource roots
  
−
[[File:05.png]]
+
An active-mod file shadows a dependency or base-game file using the same virtual resource path.
  
−
On this page, you will see a lot of existing JSON text. This was automatically generated by the extension, and there's no need to change it. Instead, we are going to add a new profile for the Intellisense to use in our projects.
+
=== Mod dependencies ===
  
−
Scroll to the bottom and put the cursor after the closing bracket of the last profile. (It's the third bracket from the bottom.)
+
The extension reads each mod's <code>entry.hpc</code> file and resolves dependencies through their exact <code>Content.UID</code> values.
  
−
[[File:06.png]]
+
When mod X depends on mod Y, selecting mod X indexes:
  
−
After that bracket, add a comma, add a new line (press Enter), then paste the following text:
+
* Scripts belonging to mod X
 +
* Scripts belonging to mod Y
 +
* Reachable transitive dependencies
 +
* Base-game scripts and API declarations
  
−
<syntaxhighlight lang="">
+
Unrelated mods are excluded.
−
{
+
 
−
    "name": "HPL3",
+
Missing dependencies, duplicate UIDs, malformed manifests, and dependency cycles are reported through the HPL3 status tooltip and output channel. Valid and unambiguous dependencies continue to be indexed when possible.
−
    "includePath": [
+
 
−
        "F:/Program Files (x86)/Steam/steamapps/common/SOMA",
+
=== Language features ===
−
        "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/agents",
+
 
−
        "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/areas",
+
HPL3 Language Tools provides:
−
        "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/base",
+
 
−
        "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/critters",
+
* Engine and project API completion
−
        "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/custom_depth",
+
* Class and inherited-member completion
−
        "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/custom_depth/helper_custom_depth_imgui",
+
* Enum-value completion
−
        "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/effects",
+
* Array and handle type inference
−
        "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/helpers",
+
* Include-path completion
−
        "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/interfaces",
+
* Hover documentation
−
        "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/modules",
+
* Function signature help
−
        "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/player",
+
* Go to definition
−
        "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/props",
+
* Document and workspace symbols
−
        "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/utilities"
+
* Include navigation
−
    ],
+
* Incremental analysis while editing
−
    "intelliSenseMode": "clang-x64",
+
* Automatic reindexing when scripts are changed or saved
−
    "browse":{
+
* Semantic highlighting for HPL3 types, members, enums, and keywords
−
        "path":[
+
 
−
            "F:/Program Files (x86)/Steam/steamapps/common/SOMA",
+
Documentation and engine declarations are primarily loaded from the selected game's <code>hps_api.hps</code> file.
−
            "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/agents",
+
 
−
            "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/areas",
+
=== Diagnostics ===
−
            "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/base",
+
 
−
            "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/critters",
+
The extension reports likely script or engine failures, including:
−
            "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/custom_depth",
+
 
−
            "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/custom_depth/helper_custom_depth_imgui",
+
* Malformed HPL3 or AngelScript syntax
−
            "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/effects",
+
* Unresolved or ambiguous includes
−
            "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/helpers",
+
* Unknown variables, functions, types, or members
−
            "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/interfaces",
+
* Duplicate declarations in the same scope
−
            "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/modules",
+
* Invalid assignments and primitive conversions
−
            "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/player",
+
* Invalid return values
−
            "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/props",
+
* Incorrect constructor arguments
−
            "F:/Program Files (x86)/Steam/steamapps/common/SOMA/script/utilities"
+
* Missing function arguments
−
        ]
+
* Invalid overload calls
−
    }
+
* Callback names that cannot be resolved
−
}
+
* Callback signature mismatches
−
</syntaxhighlight>
+
* Unsupported dialect operations such as <code>array.clear()</code>
 +
 
 +
Callback and mutable-global checks that can be valid in dynamic HPL3 code are generally displayed as warnings.
 +
 
 +
The extension intentionally does not enforce:
  
−
(Change the path in each one to the folder where your installation of SOMA is located, obviously.)
+
* C++ formatting conventions
 +
* Naming conventions
 +
* Include guards
 +
* Pointer style
 +
* Unused-variable rules
 +
* Other C++-specific style diagnostics
  
−
Afterwards, the text should look like this (the new text is highlighted):
+
To validate every indexed script rather than only open or affected files, run '''HPL3: Validate Workspace'''.
  
−
[[File:07.png]]
+
=== Running the current map ===
  
−
(If your text has any red squiggles in it, then you copied the text into the wrong place. Compare your text to the image above to make sure it looks the same.)
+
A '''Run Map''' CodeLens and editor-title play button appear when an HPS map script has a matching <code>.hpm</code> or legacy <code>.map</code> asset.
  
−
Now your profile is ready to go. Save and close the file, then go back to your map script. Open the Command Palette again ("Ctrl-Shift-P") and navigate to "C/Cpp: Select a Configuration":
+
To launch the map:
  
−
[[File:08.png]]
+
# Open the map's <code>.hps</code> script.
 +
# Click '''Run Map''' above the map class, or click the play icon in the editor title.
 +
# The extension saves modified workspace files.
 +
# The selected game starts in developer mode with the resolved map and mod arguments.
  
−
Under the drop-down menu, select "HPL3":
+
The map is resolved through the active-mod, dependency, and base-game overlays. A script-only mod override can therefore launch a map asset supplied by a dependency or the base game.
  
−
[[File:09.png]]
+
Launch details are written to the '''HPL3 Map Launcher''' output channel.
  
−
And that's it! You're done! Go ahead and test it out in your map script:
+
The extension directly launches the game executable. It does not create or modify development batch files.
  
−
[[File:10.png]]
+
=== Commands ===
  
−
== Optional: Launch SOMA from VS Code ==
+
{| class="wikitable"
 +
! Command
 +
! Description
 +
|-
 +
| '''HPL3: Select Game Root'''
 +
| Selects the SOMA, Rebirth, or Bunker installation used for indexing.
 +
|-
 +
| '''HPL3: Select Active Mod'''
 +
| Selects the active mod and its dependency profile.
 +
|-
 +
| '''HPL3: Rebuild Language Index'''
 +
| Discards existing caches and reindexes the API, resources, and scripts.
 +
|-
 +
| '''HPL3: Validate Workspace'''
 +
| Runs diagnostics across the complete indexed project.
 +
|-
 +
| '''HPL3: Run Current Map'''
 +
| Launches the map associated with the current script.
 +
|}
  
−
Another useful thing you can do with Visual Studio Code is to set Custom Debug Configuration. With that in mind, we can make VS Code launch the SomaDev.bat (or any other custom bat) file through the debugger.
+
=== Settings ===
  
−
Go to the Debug Panel by pressing "Ctrl+Shift+D". On the Debug tab, press on the configuration button and select C/C++ (Windows).
+
{| class="wikitable"
 +
! Setting
 +
! Default
 +
! Description
 +
|-
 +
| <code>hpl3.gameRoot</code>
 +
| Automatic
 +
| Absolute path to a supported HPL3 game installation.
 +
|-
 +
| <code>hpl3.activeMod</code>
 +
| <code>auto</code>
 +
| Automatically detected or explicitly selected active mod.
 +
|-
 +
| <code>hpl3.extraResourceRoots</code>
 +
| <code>[]</code>
 +
| Additional read-only resource roots searched after mod and base-game resources.
 +
|-
 +
| <code>hpl3.diagnostics.maxPerFile</code>
 +
| <code>100</code>
 +
| Maximum number of diagnostics displayed in one file.
 +
|-
 +
| <code>hpl3.trace.server</code>
 +
| <code>off</code>
 +
| Controls language-server protocol logging.
 +
|-
 +
| <code>hpl3.launch.executable</code>
 +
| Automatic
 +
| Optional game executable override.
 +
|-
 +
| <code>hpl3.launch.user</code>
 +
| <code>Dev</code>
 +
| Developer user passed to the game.
 +
|-
 +
| <code>hpl3.launch.config</code>
 +
| <code>config/main_init_dev.cfg</code>
 +
| Developer configuration passed to the game.
 +
|-
 +
| <code>hpl3.launch.extraArgs</code>
 +
| <code>[]</code>
 +
| Additional arguments appended to the map-launch command.
 +
|}
  
−
Override the existing code with the following:
+
=== Troubleshooting ===
  
−
<syntaxhighlight lang="">
+
==== Completion is not displayed ====
−
{
 
  
−
// Use IntelliSense to learn about possible attributes.
+
* Confirm that the file language mode is '''HPL3 HPS'''.
 +
* Remove any explicit <code>"*.hps": "cpp"</code> file association.
 +
* Verify that the correct game and mod appear in the HPL3 status tooltip.
 +
* Run '''HPL3: Rebuild Language Index'''.
  
−
// Hover to view descriptions of existing attributes.
+
==== The project is marked as degraded ====
  
−
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+
Open '''View: Toggle Output''' and select the '''HPL3 Language Server''' channel.
  
−
"version": "0.2.0",
+
A degraded project can be caused by:
  
−
"configurations": [
+
* A missing or malformed <code>hps_api.hps</code>
−
{
+
* A malformed <code>entry.hpc</code>
 +
* Missing or duplicate dependency UIDs
 +
* Dependency cycles
 +
* Invalid resource configuration
  
−
      "name": "SOMA",
+
When API indexing is degraded, the extension suppresses unreliable unknown-engine-symbol diagnostics to avoid excessive false errors.
  
−
      "type": "cppvsdbg",
+
==== The wrong helper definition is selected ====
  
−
      "request": "launch",
+
Use '''HPL3: Select Active Mod''' and confirm the intended top-level mod. The active mod shadows dependency and base-game resources using the same virtual path.
  
−
      "program": "${workspaceFolder}/SomaDevCMD.bat",
+
==== Run Map is unavailable ====
  
−
      "args": [],
+
Confirm that:
  
−
      "stopAtEntry": false,
+
* The current file is an HPS map script.
 +
* A matching <code>.hpm</code> or <code>.map</code> asset exists.
 +
* The map is reachable through the selected mod profile.
 +
* The correct game root is selected.
  
−
      "cwd": "${workspaceFolder}",
+
=== Platform support ===
  
−
      "environment": [],
+
Windows is the officially supported platform.
  
−
      "externalConsole": true
+
Language-server features may work on Linux when <code>hpl3.gameRoot</code> points to a Steam/Proton installation. Linux is not currently tested, and '''Run Map''' is Windows-only because it directly detects and launches the Windows game executables.
  
−
    }
+
=== Source code and bug reports ===
  
−
  ]
+
Source code, releases, and issue tracking are available at:
  
−
}
+
* [https://github.com/TiManGames/hpl3-language-tools TiManGames/hpl3-language-tools]
−
</syntaxhighlight>
+
* [https://github.com/TiManGames/hpl3-language-tools/issues Report a bug or request a feature]
  
−
You can add more configurations by pressing on the "Add Configuration" Button at the bottom right and selecting again C/C++ Windows (Launch).
+
{{NavBar|HPL3/Scripting/Scripting_Guide/What is scripting in HPL3?|What is scripting in HPL3?|HPL3/Scripting/HPL3 Scripting Guide|HPL3 Scripting Guide|HPL3/Scripting/Scripting_Guide/Scripting Workflow and Structure|Scripting Workflow and Structure}}
  
−
Now, just select the debugger you want and press on the green arrow to launch it.
+
[[Category:HPL3 Scripting]]
 +
[[Category:English]]

Latest revision as of 00:18, 31 July 2026

  1. The Basics - Introduction
  2. What is scripting in HPL3?
  3. Setting up Visual Studio Code - Scripting Tool
  4. Scripting Workflow and Structure
  5. Hello World
  6. Calling Functions and Function Callbacks
  7. Helper Files
  8. The OnAction method
  9. The Update method
  10. Timers
  11. Sequences
  12. Local and Global Variables
  13. Enums
  14. Conclusion


Visual Studio Code language support

HPL3 Language Tools is a community-made Visual Studio Code extension that provides language support for HPL3 .hps scripts.

It supports:

  • SOMA
  • Amnesia: Rebirth
  • Amnesia: The Bunker

The extension treats HPL3 scripts as their own AngelScript-based language instead of C++. This prevents unrelated C++ diagnostics and enables HPL3-specific completion, validation, navigation, mod overlays, and callback checking.

HPL3 Language Tools is not affiliated with or endorsed by Frictional Games. The game compiler remains the final authority when validating scripts.

Installation

Visual Studio Marketplace

  1. Open Visual Studio Code.
  2. Open the Extensions view.
  3. Search for HPL3 Language Tools.
  4. Select the extension published by TiManGames.
  5. Click Install.


Local VSIX

The extension can also be installed manually:

  1. Download the latest .vsix package from the GitHub releases page.
  2. Open the Visual Studio Code Command Palette with Ctrl+Shift+P.
  3. Run Extensions: Install from VSIX...
  4. Select the downloaded file.
  5. Reload Visual Studio Code if prompted.

Opening an HPL3 project

The simplest setup is to open the game installation folder as the Visual Studio Code workspace: 

C:\Program Files (x86)\Steam\steamapps\common\SOMA
C:\Program Files (x86)\Steam\steamapps\common\Amnesia Rebirth
C:\Program Files (x86)\Steam\steamapps\common\Amnesia The Bunker

When the game folder is open, the extension normally detects the game automatically by locating:

  • hps_api.hps
  • resources.cfg
  • The script directory

It is also possible to open an individual mod folder or another folder beneath the game installation.

If automatic detection fails:

  1. Open the Command Palette.
  2. Run HPL3: Select Game Root.
  3. Select the root folder of the appropriate HPL3 game.

The selected folder should be the main game folder, not its mods, maps, or script subdirectory.

HPS language association

Files ending in .hps should use the HPL3 HPS language mode.

The current language mode is displayed in the lower-right corner of Visual Studio Code. If it displays C++, click it and select HPL3 HPS.

Some existing setups explicitly associate HPS files with C++: 

"files.associations": {
    "*.hps": "cpp"
}

Remove that association if it prevents the extension from selecting HPL3 HPS. The extension may display a one-time warning about this configuration, but it will not modify the user's settings automatically.

Selecting an active mod

By default, hpl3.activeMod is set to auto.

In automatic mode, the extension selects the mod containing the currently opened script. To select a mod explicitly:

  1. Open the Command Palette.
  2. Run HPL3: Select Active Mod.
  3. Select the desired mod.

The active mod controls script overlays, include resolution, completion, definitions, and project validation.

Resolution generally follows this priority:

  1. The directory containing the current file
  2. The active mod
  3. Direct mod dependencies
  4. Deeper transitive dependencies
  5. The base game
  6. Additional configured resource roots

An active-mod file shadows a dependency or base-game file using the same virtual resource path.

Mod dependencies

The extension reads each mod's entry.hpc file and resolves dependencies through their exact Content.UID values.

When mod X depends on mod Y, selecting mod X indexes:

  • Scripts belonging to mod X
  • Scripts belonging to mod Y
  • Reachable transitive dependencies
  • Base-game scripts and API declarations

Unrelated mods are excluded.

Missing dependencies, duplicate UIDs, malformed manifests, and dependency cycles are reported through the HPL3 status tooltip and output channel. Valid and unambiguous dependencies continue to be indexed when possible.

Language features

HPL3 Language Tools provides:

  • Engine and project API completion
  • Class and inherited-member completion
  • Enum-value completion
  • Array and handle type inference
  • Include-path completion
  • Hover documentation
  • Function signature help
  • Go to definition
  • Document and workspace symbols
  • Include navigation
  • Incremental analysis while editing
  • Automatic reindexing when scripts are changed or saved
  • Semantic highlighting for HPL3 types, members, enums, and keywords

Documentation and engine declarations are primarily loaded from the selected game's hps_api.hps file.

Diagnostics

The extension reports likely script or engine failures, including:

  • Malformed HPL3 or AngelScript syntax
  • Unresolved or ambiguous includes
  • Unknown variables, functions, types, or members
  • Duplicate declarations in the same scope
  • Invalid assignments and primitive conversions
  • Invalid return values
  • Incorrect constructor arguments
  • Missing function arguments
  • Invalid overload calls
  • Callback names that cannot be resolved
  • Callback signature mismatches
  • Unsupported dialect operations such as array.clear()

Callback and mutable-global checks that can be valid in dynamic HPL3 code are generally displayed as warnings.

The extension intentionally does not enforce:

  • C++ formatting conventions
  • Naming conventions
  • Include guards
  • Pointer style
  • Unused-variable rules
  • Other C++-specific style diagnostics

To validate every indexed script rather than only open or affected files, run HPL3: Validate Workspace.

Running the current map

A Run Map CodeLens and editor-title play button appear when an HPS map script has a matching .hpm or legacy .map asset.

To launch the map:

  1. Open the map's .hps script.
  2. Click Run Map above the map class, or click the play icon in the editor title.
  3. The extension saves modified workspace files.
  4. The selected game starts in developer mode with the resolved map and mod arguments.

The map is resolved through the active-mod, dependency, and base-game overlays. A script-only mod override can therefore launch a map asset supplied by a dependency or the base game.

Launch details are written to the HPL3 Map Launcher output channel.

The extension directly launches the game executable. It does not create or modify development batch files.

Commands

Command Description
HPL3: Select Game Root Selects the SOMA, Rebirth, or Bunker installation used for indexing.
HPL3: Select Active Mod Selects the active mod and its dependency profile.
HPL3: Rebuild Language Index Discards existing caches and reindexes the API, resources, and scripts.
HPL3: Validate Workspace Runs diagnostics across the complete indexed project.
HPL3: Run Current Map Launches the map associated with the current script.

Settings

Setting Default Description
hpl3.gameRoot Automatic Absolute path to a supported HPL3 game installation.
hpl3.activeMod auto Automatically detected or explicitly selected active mod.
hpl3.extraResourceRoots [] Additional read-only resource roots searched after mod and base-game resources.
hpl3.diagnostics.maxPerFile 100 Maximum number of diagnostics displayed in one file.
hpl3.trace.server off Controls language-server protocol logging.
hpl3.launch.executable Automatic Optional game executable override.
hpl3.launch.user Dev Developer user passed to the game.
hpl3.launch.config config/main_init_dev.cfg Developer configuration passed to the game.
hpl3.launch.extraArgs [] Additional arguments appended to the map-launch command.

Troubleshooting

Completion is not displayed

  • Confirm that the file language mode is HPL3 HPS.
  • Remove any explicit "*.hps": "cpp" file association.
  • Verify that the correct game and mod appear in the HPL3 status tooltip.
  • Run HPL3: Rebuild Language Index.

The project is marked as degraded

Open View: Toggle Output and select the HPL3 Language Server channel.

A degraded project can be caused by:

  • A missing or malformed hps_api.hps
  • A malformed entry.hpc
  • Missing or duplicate dependency UIDs
  • Dependency cycles
  • Invalid resource configuration

When API indexing is degraded, the extension suppresses unreliable unknown-engine-symbol diagnostics to avoid excessive false errors.

The wrong helper definition is selected

Use HPL3: Select Active Mod and confirm the intended top-level mod. The active mod shadows dependency and base-game resources using the same virtual path.

Run Map is unavailable

Confirm that:

  • The current file is an HPS map script.
  • A matching .hpm or .map asset exists.
  • The map is reachable through the selected mod profile.
  • The correct game root is selected.

Platform support

Windows is the officially supported platform.

Language-server features may work on Linux when hpl3.gameRoot points to a Steam/Proton installation. Linux is not currently tested, and Run Map is Windows-only because it directly detects and launches the Windows game executables.

Source code and bug reports

Source code, releases, and issue tracking are available at:

Retrieved from "https://wiki.frictionalgames.com/page?title=HPL3/Scripting/Scripting_Guide/Setting_up_Visual_Studio_Code&oldid=7170"