WurstScript Setup and Installation

Complete guide for installing WurstScript and setting up projects.

Prerequisites

WurstScript requires:

• •VSCode (recommended) or any text editor
• •Java Runtime (auto-installed with extension)
• •Warcraft III (for testing)

VSCode Installation (Recommended)

1. Install VSCode

Download from: https://code.visualstudio.com/

2. Install Wurst Extension

1. •Open VSCode
2. •Go to Extensions (Ctrl+Shift+X)
3. •Search "Wurst"
4. •Install "Wurst language support" by peterzeller

3. Extension Auto-Setup

The extension automatically:

• •Downloads and installs the compiler
• •Installs the grill CLI tool
• •Keeps everything updated

4. Activate Extension

Open any .wurst file or run:

• •F1 -> >wurst: Install

Project Creation

Via VSCode

1. •F1 -> >wurst: New Wurst Project
2. •Select folder location
3. •Extension creates project structure

Via CLI

grill generate my-project

Project Structure

my-project/
├── _build/                 # Compiled output (generated)
├── .vscode/
│   └── settings.json       # VSCode workspace settings
├── imports/                # Files to import into map
├── wurst/                  # Wurst source files
│   └── Hello.wurst         # Example package
├── ExampleMap.w3x          # Base map file
├── wurst.build             # Project configuration
├── wurst.dependencies      # Generated dependency list
├── wurst_run.args          # Run configuration
└── .gitignore

wurst.build Configuration

projectName: MyProject
dependencies:
  - https://github.com/wurstscript/WurstStdlib2
buildMapData:
  name: My Map
  author: Your Name
  fileName: MyMap
  scenarioData:
    description: Map description
    suggestedPlayers: 1-8
    loadingScreen:
      model: ""
      title: My Map
      subtitle: ""
      text: Loading...

Configuration Options

projectName: string         # Project name
dependencies: []            # Git URLs of dependencies
buildMapData:
  name: string              # Map name shown in-game
  author: string            # Author name
  fileName: string          # Output file name (no extension)
  scenarioData:
    description: string
    suggestedPlayers: string
    loadingScreen:
      model: string         # Loading screen model path
      title: string
      subtitle: string
      text: string

Managing Dependencies

Add Dependency

grill install https://github.com/some/library

This updates wurst.build and downloads the library.

Update Dependencies

grill install

Common Dependencies

dependencies:
  # Standard Library (required)
  - https://github.com/wurstscript/WurstStdlib2
  
  # Popular Community Libraries
  - https://github.com/Frotty/Frentity
  - https://github.com/theQuazz/wurst-lodash
  - https://github.com/Frotty/wurst-item-shop

Running and Building

Run Map (Development)

• •F1 -> >wurst: Run map
• •Or use hotkey if configured

This:

1. •Compiles your code
2. •Creates WurstRunMap.w3x in WC3 maps folder
3. •Launches Warcraft III with the map

Build Map (Release)

• •F1 -> >wurst: Build map

Creates compiled map in _build/ folder for distribution.

wurst_run.args

Configure run behavior:

-runmapaliases ["wc3path:C:\Games\Warcraft III\_retail_\x86_64\Warcraft III.exe"]
-preloadFiles []

CLI Reference (grill)

# Create new project
grill generate <project-name>

# Install/update dependencies
grill install

# Add specific dependency
grill install <git-url>

# Update compiler
grill install wurstscript

# Build map
grill build <mapfile.w3x>

# Run map
grill run <mapfile.w3x>

Adding to PATH

Add ~/.wurst to your PATH for global grill access:

Windows

1. •Open Environment Variables
2. •Edit PATH in user variables
3. •Add %USERPROFILE%\.wurst

macOS/Linux

Add to ~/.bashrc or ~/.zshrc:

export PATH="$PATH:$HOME/.wurst"

Working with Maps

Base Map

ExampleMap.w3x (or your map) is the "terrain" map:

• •Edit terrain, doodads, destructibles in World Editor
• •Wurst reads this and adds compiled code
• •Wurst never modifies this file

Imports Folder

Files in imports/ are automatically imported:

imports/
├── Models/
│   └── MyModel.mdx
├── Icons/
│   └── MyIcon.blp
└── war3map.j              # Not recommended

Folder structure is preserved in the map.

Updating Base Map

After adding imports via wurst:

1. •Build the map
2. •Copy from _build/ to project root
3. •Open in World Editor
4. •Save (clears wurst code but keeps imports)
5. •Now use as new base map

Troubleshooting

Extension Not Loading

1. •Open a .wurst file
2. •Check Output panel -> Wurst
3. •Run F1 -> >wurst: Install

Compile Errors

• •Check Problems panel (Ctrl+Shift+M)
• •Hover over red underlines for details
• •Check import statements

Map Won't Run

• •Verify WC3 path in wurst_run.args
• •Check if WC3 is already running
• •Try running WC3 manually first

Dependency Issues

# Clean and reinstall
rm -rf _build/dependencies
grill install

Java Issues

The extension manages Java automatically. If issues occur:

• •Check Output panel for errors
• •Reinstall extension
• •Manually install Java 11+

VSCode Tips

Useful Shortcuts

• •F1 - Command palette
• •Ctrl+. - Quick actions
• •Ctrl+Space - Autocomplete
• •Ctrl+Click - Go to definition
• •Shift+F12 - Find references

Recommended Settings

.vscode/settings.json:

{
  "editor.formatOnSave": true,
  "wurst.wc3InstallationPath": "C:\\Games\\Warcraft III"
}

Resources

• •Documentation: https://wurstlang.org/start.html
• •VSCode Extension: https://marketplace.visualstudio.com/items?itemName=peterzeller.wurst
• •Discord Support: https://discord.gg/mSHZpWcadz