HPL3 Language Tools

Native Visual Studio Code language support for Frictional Games' HPL3 Engine .hps scripts used by:

• SOMA
• Amnesia: Rebirth
• Amnesia: The Bunker

HPL3 Language Tools understands the engine's AngelScript-based dialect instead of treating scripts as C++. It provides useful feedback while a script is still being written, without applying unrelated C++ style rules.

Preview

HPL3-aware IntelliSense

Engine APIs, project declarations, inherited members, enum values, arrays, and include-visible symbols are suggested as you type.

Callback validation

Literal callback names are checked against reachable script functions and known callback signatures.

Conservative diagnostics

Diagnostics focus on likely HPL3 failures and use warnings where the engine permits dynamic behavior.

Mod dependency and overlay resolution

Selecting an active mod indexes its reachable UID-based dependencies and resolves their scripts through the same overlay used by includes, completion, diagnostics, and definitions.

Run maps from Visual Studio Code

Confirmed map scripts can launch their matching map through the CodeLens or editor-title play button.

Main features

• Live completion for engine APIs, project functions, classes, inherited members, enums, arrays, handles, and include paths.
• Hover documentation and signature help sourced from the selected game's hps_api.hps.
• Go to definition, document symbols, workspace symbols, and include navigation.
• HPL3-aware diagnostics for syntax, includes, declarations, primitive types, assignments, constructors, overloads, members, callbacks, and unsupported dialect features.
• Semantic highlighting for classes, interfaces, enum values, members, and HPL3 keywords.
• Active-mod overlays and transitive UID-based mod dependency indexing.
• Context-aware resolution where an active mod shadows dependencies and the base game without leaking mod-only symbols into base-game scripts.
• A Run Map CodeLens and editor play button for scripts with a matching .hpm or legacy .map asset.
• Incremental, error-tolerant analysis that automatically refreshes as files are edited or saved.

Why use it instead of a C++ configuration?

• .hps is registered as its own language, so C++-only errors and style warnings are not applied.
• Completions and diagnostics understand HPL3 APIs, callbacks, resource overlays, mod dependencies, handles, and AngelScript-specific syntax.
• The extension resolves symbols using the game and mod that own the current file, rather than presenting every script as one flat codebase.
• Language features run locally and offline. No compiler, Rust installation, running game, or network connection is required for editing.

The game compiler remains the final authority for runtime behavior.

Requirements

• Windows for officially supported use and the Run Map feature.
• Visual Studio Code 1.95 or newer.
• A local installation of at least one supported HPL3 game.
• Access to the selected game's hps_api.hps, resources.cfg, and script directory.

Linux compatibility

Linux is not officially supported or tested yet. The language server, diagnostics, and IntelliSense may work when hpl3.gameRoot points to the game's Steam/Proton installation, but Run Map currently detects and launches Windows game executables directly and is therefore Windows-only.

Installation

From the Visual Studio Marketplace

1. Open the Extensions view in Visual Studio Code.
2. Search for HPL3 Language Tools.
3. Select the extension published by TiManGames and choose Install.

From a local VSIX

1. Open the Command Palette.
2. Run Extensions: Install from VSIX...
3. Select the downloaded .vsix file.

Quick start

1. Open a supported game's root folder, a mod folder, or a folder containing your HPL3 project.
2. Open any .hps file. Its language mode should be HPL3 HPS.
3. If the game root cannot be found automatically, run HPL3: Select Game Root and choose the game installation folder.
4. Leave hpl3.activeMod set to auto, or run HPL3: Select Active Mod when you want to pin a specific mod profile.
5. Wait for the HPL3 status item to report that indexing is ready.

When the opened workspace is the game folder, the extension normally discovers the game root automatically. Common Steam locations include:

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

If VS Code already associates *.hps with C++, the extension shows a one-time remediation prompt. It never rewrites your file-association settings automatically.

Run the current map

A Run Map CodeLens and play icon appear only when the current .hps script resolves to a matching .hpm or .map asset through the active overlay.

Launching a map:

1. Saves all dirty workspace files.
2. Resolves the current game, selected top-level mod, and physical map asset.
3. Starts the detected game executable with developer configuration and map arguments.
4. Writes the complete launch target and arguments to the HPL3 Map Launcher output channel.

The extension does not generate or modify .bat files. Launching occurs only when you explicitly use the command or play button.

Commands

Settings

Diagnostic philosophy

The default checks focus on likely engine or script failures: malformed syntax, unresolved includes, unknown symbols or members, incompatible primitive types, invalid calls, bad overloads, and callback mismatches. Callback and mutable global checks that can be valid in dynamic HPL3 usage are reported as warnings where appropriate.

The extension intentionally does not enforce C++ naming, formatting, pointer-style, include-guard, unused-variable, or conversion-style rules. Generated hps_api.hps declarations are indexed as API input rather than validated as ordinary game scripts.

Troubleshooting

Completion does not appear

• Confirm the status bar language mode is HPL3 HPS, not C++.
• Remove any explicit "*.hps": "cpp" file association if VS Code keeps selecting C++.
• Confirm the HPL3 status item shows the expected game and active mod.
• Run HPL3: Rebuild Language Index after changing game or resource files.

The project is marked degraded

Open View: Toggle Output, select the HPL3 Language Server channel, and review the reported API, manifest, dependency, or resource issue. The server suppresses unreliable unknown-engine-symbol errors when API indexing is degraded.

The wrong helper or definition is selected

Run HPL3: Select Active Mod and verify the selected top-level mod. Active mod files shadow dependencies and the base game; equal-priority dependency collisions are reported as ambiguous.

Run Map is not available

Confirm that the script has a matching .hpm or .map asset in the selected overlay and that the current active-mod profile can reach it.

Privacy and runtime behavior

Analysis is local and offline. The extension reads scripts and configuration from the selected game, mod dependencies, and configured resource roots. It does not launch a game unless Run Current Map is explicitly invoked.

Source and support

• Source code
• Report an issue

HPL3, SOMA, and Amnesia are trademarks of Frictional Games. This community extension is not affiliated with or endorsed by Frictional Games.