Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/twhl-community/halflife-unified-sdk/llms.txt

Use this file to discover all available pages before exploring further.

The Half-Life Unified SDK uses dotnet-script to run scripts written in C#. These scripts form part of the SDK toolchain and handle tasks such as asset processing and content pipeline automation. This page covers how to install the .NET SDK and dotnet-script, how to run scripts from the command line, and how to configure Visual Studio Code for a full editing and debugging experience — including the PowerShell scripts also used by the SDK.

​
Install the .NET SDK

Before installing dotnet-script you need the .NET SDK. .NET 6.0 or newer is required to run dotnet-script and the packages used by the SDK’s existing scripts. Follow the official installation instructions for your platform from the .NET download page. For SDK-specific guidance see the Setting up the .NET SDK page in this documentation.
Open a new terminal or command prompt after installation completes. The dotnet executable is added to your PATH during installation, but any terminal that was already open will not have the updated PATH and will report dotnet as not found.

​
Install dotnet-script

With the .NET SDK in place, install dotnet-script as a global tool. The full installation instructions are available in the dotnet-script repository. The essential command is: 
dotnet tool install -g dotnet-script
On Windows, Visual Studio 2022 is the first 64-bit version of Visual Studio and it modifies the PATH environment variable to point to the 64-bit version of .NET. If you have both 32-bit (C:\Program Files (x86)\dotnet\) and 64-bit (C:\Program Files\dotnet\) .NET installations on your PATH, the tool installation may fail.To fix this, either move the 32-bit entry to a position after the 64-bit entry in PATH, or remove the 32-bit entry entirely. See this issue on the Visual Studio Developer Community for more details.

​
Running scripts from the command line

To run a C# script with dotnet-script, open a terminal and use the following command: 
dotnet script <script filename>

​
Passing command-line parameters

Append parameters directly after the script filename: 
dotnet script <script filename> --my-parameter my-value
If a parameter name conflicts with one used by dotnet-script itself, use -- to separate the script’s arguments from dotnet-script’s arguments: 
dotnet script <script filename> -- --my-parameter my-value

​
Command-line scripts in the SDK

Command-line scripts in the SDK work like standard .NET tools. See the .NET Tools page for more information on how they are structured and invoked.
Scripts may take some time on their first run while packages are restored and the script is compiled. Subsequent executions are much faster as long as the script’s contents have not changed. If you run dotnet for the first time after installing or updating the SDK, you may see a welcome message — wait a moment and the script will execute automatically.

​
Setting up Visual Studio Code

Visual Studio Code can be used to edit, run, and debug both the C# scripts used by dotnet-script and the PowerShell scripts included in the SDK. The sections below cover each setup.

​
C# scripts with dotnet-script

1

Install the C# extension

Install the C# extension for VS Code from the Extensions marketplace.
2

Configure the extension to use the latest .NET version

To ensure the extension correctly understands the syntax used in SDK scripts, configure OmniSharp to use the latest .NET build. Instructions for this setting are available in the omnisharp-vscode repository.
3

Generate a launch.json file

When editing scripts in VS Code it is recommended to use a launch.json file. dotnet-script can scaffold one for you with the init command — see the dotnet-script scaffolding documentation for details.
On Windows, the generated launch.json currently references an absolute path to the dotnet-script DLL, for example:
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": ".NET Script Debug",
            "type": "coreclr",
            "request": "launch",
            "program": "dotnet",
            "args": [
                "exec",
                "path/to/dotnet-script.dll",
                "${file}"
            ],
            "cwd": "${workspaceRoot}",
            "stopAtEntry": false
        }
    ]
}
This path will break on other machines or after updating dotnet-script. Replace the hardcoded path with the global tool location using environment variables. Use the globaltool.launch.json.template from the dotnet-script repository as a starting point.
4

Customise args for scripts that require parameters

For scripts that accept command-line parameters, modify the args array in launch.json accordingly. The default configuration is sufficient for scripts that take no parameters.

​
PowerShell scripts with VS Code

The SDK also includes PowerShell scripts. Follow these steps to configure VS Code for editing and debugging them.
1

Install Visual Studio Code

If you have not done so already, download and install Visual Studio Code from https://code.visualstudio.com/.
2

Install the PowerShell extension

Install the PowerShell extension for VS Code. This adds syntax highlighting, IntelliSense, and debugging support for .ps1 files.
3

Configure the PowerShell extension settings

Open VS Code and navigate to File → Preferences → Settings. In the Settings panel, go to Extensions → PowerShell Configuration and apply the following two settings:
  • Debugging: Create Temporary Integrated Console — Enable this setting. It makes VS Code create a fresh PowerShell instance every time you run a script, which prevents state from previous executions from affecting the current run.
  • Cwd — Set this to ${fileDirname}. This sets the working directory for each script to the folder that contains the script file itself. The SDK’s PowerShell scripts rely on their location relative to the mod directory, so this setting is essential for them to work correctly.
4

Open the scripts directory

In VS Code, go to File → Open Folder… and open the scripts directory inside your mod directory. All of the SDK’s PowerShell scripts will be available in the Explorer panel for editing.
5

Create a launch configuration

Open the Run and Debug tab from the left-hand activity bar. Click create a launch.json file and select Launch Current File from the drop-down. VS Code will create a launch.json file that looks like this:
{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "PowerShell: Launch Current File",
            "type": "PowerShell",
            "request": "launch",
            "script": "${file}",
            "cwd": "${file}"
        }
    ]
}
Add an args key to pass -Verbose to every script run, which enables additional output useful for debugging:
{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "PowerShell: Launch Current File",
            "type": "PowerShell",
            "request": "launch",
            "script": "${file}",
            "cwd": "${file}",
            "args": [
                "-Verbose"
            ]
        }
    ]
}
6

Run scripts

With a PowerShell script open, switch to the Run and Debug tab and click the green triangle next to PowerShell: Launch Current File, or press F5. The script will execute in a new integrated terminal with verbose output enabled.For more information on running and debugging PowerShell scripts in VS Code, consult the official VS Code documentation and Microsoft’s PowerShell documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us