Skip to content

Commit fffef53

Browse files
FrottyFrotty
committed
update whywurst and news
1 parent e5c6190 commit fffef53

20 files changed

Lines changed: 361 additions & 94 deletions

‎_doc/features.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Features
3+
excerpt: WurstScript as an integrated Warcraft III development platform.
4+
date: 2026-04-10
5+
icon:
6+
type: fa
7+
name: fa-cube
8+
color: blue
9+
layout: tutorials
10+
heading: Features
11+
navigation:
12+
- /features/vscode
13+
- /features/backends
14+
- /features/map-formats
15+
- /features/agents
16+
---
17+
18+
WurstScript is more than a programming language. It is a complete, integrated development environment for Warcraft III map making, from writing code to viewing assets to running your map, all from VS Code.

‎_doc/features/agents.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: AI Agent Support
3+
excerpt: Built-in AGENT.md files so AI coding agents understand and verify your Wurst project.
4+
date: 2026-04-10
5+
icon:
6+
type: fa
7+
name: fa-magic
8+
color: purple
9+
author: Frotty
10+
layout: doc
11+
---
12+
13+
WurstScript projects include built-in support for AI coding agents. When you create or install a project with `grill`, an `AGENT.md` file is added to the project root that gives AI assistants (Claude, Copilot, Cursor, and others) the information they need to work effectively with WurstScript code.
14+
15+
## How It Works
16+
17+
`grill` writes `AGENT.md` to new and updated projects automatically. This file describes:
18+
19+
- The WurstScript language and its relationship to Jass and Lua
20+
- Project structure conventions (`wurst/`, `wurst.build`, dependencies)
21+
- The standard library and how packages are imported
22+
- The two compiler backends and when each is used
23+
- Common patterns used in Wurst maps
24+
- Verification commands agents should run before finishing changes
25+
26+
AI agents reading this file can answer questions, suggest code, and make changes that fit the conventions of a Wurst project without needing to be trained on WurstScript specifically.
27+
28+
## Verification Commands
29+
30+
The generated agent instructions point agents at the same small verification commands humans use:
31+
32+
```bash
33+
grill typecheck
34+
grill test NAME
35+
```
36+
37+
Use `grill typecheck` to check the whole project quickly. Use `grill test NAME` to run a specific unit test after changing a focused part of the codebase.
38+
39+
## No Setup Required
40+
41+
`AGENT.md` is created automatically. If you are starting a new project:
42+
43+
```bash
44+
grill generate my-map
45+
```
46+
47+
If you are adding Wurst to an existing project:
48+
49+
```bash
50+
grill install
51+
```
52+
53+
In both cases `AGENT.md` is written alongside the rest of the project scaffolding.
54+
55+
## Keeping It Up to Date
56+
57+
`AGENT.md` is managed by `grill`. Running `grill install` on an existing project will update it to the current version. You can commit it to version control so the whole team benefits.

‎_doc/features/backends.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: Jass and Lua Backends
3+
excerpt: Write once, compile to Jass or Lua with identical runtime behavior.
4+
date: 2026-04-10
5+
icon:
6+
type: fa
7+
name: fa-exchange
8+
color: orange
9+
author: Frotty
10+
layout: doc
11+
redirect_from:
12+
- /tutorials/lua-jass-shim.html
13+
---
14+
15+
WurstScript compiles to either **Jass** or **Lua**. The goal is to write code once and have it behave identically on both backends — no conditional code paths, no per-backend workarounds in user space.
16+
17+
## Choosing a Backend
18+
19+
Set `compilationTarget` in your `wurst.build` file:
20+
21+
```yaml
22+
compilationTarget: lua
23+
```
24+
25+
Jass is the default and requires no configuration. Lua targets Reforged and is required if you want to run on Battle.net with modern clients.
26+
27+
## Why They Differ
28+
29+
Jass and Lua have different runtime semantics in several areas. The most common differences that affect real maps:
30+
31+
**Null handles.** In Jass, calling a native with a `null` argument is valid — the function returns a type-appropriate zero value. In plain Lua, the same call raises a nil error and crashes.
32+
33+
**Handle IDs.** `GetHandleId` in Jass returns stable integers across a session, commonly used as table keys or for comparisons. In Lua, the equivalent is not stable across sessions and is a known cause of desyncs.
34+
35+
**Uninitialized variables.** Jass initializes all variables to zero values (`0`, `0.0`, `false`, `""`, `null`). Lua leaves uninitialized variables as `nil`, causing type errors when first used.
36+
37+
## The Jass Shim Pass
38+
39+
To close these gaps, the compiler applies a dedicated **Jass shim pass** to all generated Lua code. This pass inserts targeted emulation so that Lua behaves like Jass for the cases above — without any changes needed in user code.
40+
41+
### Null-safe natives
42+
43+
Null handle arguments return the same defaults as Jass instead of erroring:
44+
45+
| Expression | Jass | Plain Lua | Shimmed Lua |
46+
|---|---|---|---|
47+
| `GetUnitX(null)` | `0.0` | nil error | `0.0` |
48+
| `GetUnitState(null, UNIT_STATE_LIFE)` | `0.0` | nil error | `0.0` |
49+
| `IsUnitEnemy(null, null)` | `false` | nil error | `false` |
50+
| `GetUnitName(null)` | `""` | nil error | `""` |
51+
| `GetHandleId(null)` | `0` | nil error | `0` |
52+
53+
This applies across the native surface — integer, real, boolean, and string return types all fall back to their Jass defaults when called with null handles.
54+
55+
### Handle ID replacement
56+
57+
All `GetHandleId` usage is replaced by the compiler with a safe alternative that produces consistent, desync-free identifiers. This is transparent — the replacement behaves the same way as the Jass `GetHandleId` for the purposes code actually relies on.
58+
59+
### Uninitialized variable defaults
60+
61+
Wurst's static type system enforces initialization for most cases at compile time. The shim pass handles any remaining gaps at the generated code level so zero-value semantics are consistent between backends.
62+
63+
## Switching an Existing Map
64+
65+
Maps that run correctly on the Jass backend should run correctly on Lua after the shim pass. The typical process:
66+
67+
1. Set `compilationTarget: lua` in `wurst.build`.
68+
2. Build and test.
69+
3. Report any case where Jass and Lua behavior still diverges on the [WurstScript issue tracker](https://github.com/wurstscript/WurstScript/issues).
70+
71+
No changes to user Wurst code should be required for the cases described above.

‎_doc/features/map-formats.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: Map Formats
3+
excerpt: Work with MPQ archives and unpacked map folders transparently.
4+
date: 2026-04-10
5+
icon:
6+
type: fa
7+
name: fa-folder-open
8+
color: green
9+
author: Frotty
10+
layout: doc
11+
---
12+
13+
WurstScript supports both of Warcraft III's map storage formats: the classic MPQ archive and the unpacked folder format introduced with Reforged.
14+
15+
## MPQ Archives
16+
17+
`.w3x` and `.w3m` files are MPQ archives — binary containers that pack all map assets and data into a single file. This is the traditional format and remains the default output of the World Editor.
18+
19+
Wurst reads MPQ archives natively for building and running. No unpacking step is needed.
20+
21+
## Map Folders
22+
23+
The Reforged World Editor can also load and save maps as plain folders, as long as the folder name ends in `.w3x` or `.w3m`. All the files that would normally be packed into the MPQ archive are stored directly on disk instead.
24+
25+
Wurst supports map folders as a first-class input. A map stored as a folder behaves identically to a packed archive from Wurst's perspective — open, build, and run work the same way.
26+
27+
**Why use folders:**
28+
29+
- Full version control over map data — every file is a plain file, so diffs and history work naturally
30+
- No binary merge conflicts
31+
- Works well with the Export to Folder workflow described below
32+
33+
## Export to Folder
34+
35+
The VS Code extension can convert an existing MPQ map to folder format directly:
36+
37+
1. Open a `.w3x` or `.w3m` map in VS Code using the MPQ inspector.
38+
2. Use **Export to Folder** from the context menu or command palette.
39+
3. The extension unpacks the entire archive into a new folder with the same `.w3x`/`.w3m` name.
40+
41+
From that point, the folder can be opened in the World Editor and used with Wurst exactly like the original archive — but now all files are accessible individually for editing, scripting, and version control.
42+
43+
## Which Format to Use
44+
45+
For new projects, starting with the folder format and keeping it in version control from the beginning is the cleanest approach.
46+
47+
For existing maps, use Export to Folder once and commit the result. The history before the export will be the original binary archive; everything after will be readable diffs.

‎_doc/features/vscode.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: VS Code Integration
3+
excerpt: Rich editor support for the full Wurst development workflow.
4+
date: 2026-04-10
5+
icon:
6+
type: fa
7+
name: fa-code
8+
color: blue
9+
author: Frotty
10+
layout: doc
11+
---
12+
13+
The [Wurst VS Code extension](https://marketplace.visualstudio.com/items?itemName=peterzeller.wurst) turns VS Code into a full Warcraft III development environment. Installing it is all that is needed to get started — the extension manages the compiler and CLI automatically.
14+
15+
## Language Support
16+
17+
The extension provides first-class editing support for `.wurst` files:
18+
19+
- **Syntax highlighting** and semantic tokens
20+
- **Hover documentation** for functions, types, and variables — including native documentation pulled from [JassDoc](https://github.com/lep/jassdoc) where available
21+
- **Inlay hints** for type information and code flow
22+
- **Go-to-definition** and **find references** across the full project
23+
- **Inline diagnostics** from the compiler — errors and warnings appear in the editor as you type
24+
- **Code completion** for identifiers, packages, and native functions
25+
26+
## Build and Run
27+
28+
The play button in VS Code runs your map directly:
29+
30+
1. Open any `.wurst` file or a `.w3x`/`.w3m` map file.
31+
2. Click the run button (or use `F1` → `Wurst: Run`).
32+
33+
The extension builds the project, patches the map, and launches Warcraft III. No terminal needed for the common path.
34+
35+
## Asset Preview
36+
37+
The extension can render common Warcraft III asset formats directly in the editor without needing the World Editor or external tools:
38+
39+
| Format | Description |
40+
|---|---|
41+
| `.blp` | Blizzard texture format |
42+
| `.dds` | DirectDraw Surface texture |
43+
| `.mdx` | Warcraft III model format |
44+
45+
Open any of these files from the VS Code explorer and they are displayed inline.
46+
47+
## MPQ Inspector
48+
49+
`.w3x` and `.w3m` map archives can be browsed directly in VS Code:
50+
51+
- **Browse** the archive file tree without unpacking
52+
- **Extract** individual files from the archive
53+
- **Export to Folder** — unpacks the entire archive into a `.w3x` or `.w3m` folder for use with version control or the map folder workflow (see [Map Formats](/features/map-formats.html))
54+
55+
## Command Palette
56+
57+
Common Wurst actions are available via `F1`:
58+
59+
- `Wurst: Run` — build and launch the map
60+
- `Wurst: Build` — compile without running
61+
- `Wurst: Install` — install/update the toolchain
62+
- `Wurst: New Wurst Project` — project scaffolding

‎_layouts/home.html‎

Lines changed: 24 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
<div class="greeting">
2323
<div>
2424
<h1 class="name">WurstScript</h1>
25-
<div class="tagline">Efficient. Innovative. Delicious.</div>
25+
<div class="tagline">A Warcraft III-first language and toolchain for serious map projects.</div>
2626
<a class="btn btn-primary" href="/start">Get Started</a>
2727
</div>
2828
<div class="img-container">
@@ -50,46 +50,44 @@ <h3>{{ post.title }}</h3>
5050
</div>
5151

5252
<div class="why-wurst">
53-
<h2 class="title">Why Wurst?</h2>
53+
<h2 class="title">Why choose WurstScript?</h2>
5454

55-
<p>WurstScript is a programming language and modding toolkit used to create Warcraft III maps with ease.
56-
It supports Warcraft III reforged and older versions by producing either Jass or Lua code.</p>
57-
58-
<p class="why-special">
59-
Built for serious Warcraft III projects: expressive language design, compiletime generation, and performance-first compilation.
60-
</p>
55+
<p class="why-intro">WurstScript is a WC3-first workflow built around maps, object data, assets, builds, and Jass or Lua output.</p>
6156

6257
<div class="why-feature-stack">
6358
<article class="why-feature">
64-
<div class="why-feature-icon"><i class="fa fa-code"></i></div>
6559
<div class="why-feature-text">
66-
<p class="why-feature-key">Type System</p>
67-
<h3>Write map logic that stays maintainable.</h3>
68-
<p>Strong typing + clean syntax + extension methods.</p>
69-
<pre class="language-wurst why-inline-code"><code class="language-wurst">u..addMana(100)
70-
..addHP(100)</code></pre>
60+
<p class="why-feature-key">WC3-first</p>
61+
<h3>Made for map projects</h3>
62+
<p>Map formats, object data, assets, builds, tests, and editor actions are part of the free open source toolchain.</p>
63+
<img class="why-feature-shot" src="/assets/images/blog/bestof6/vscodeicons.png" alt="Wurst project structure in VS Code">
64+
</div>
65+
</article>
66+
67+
<article class="why-feature">
68+
<div class="why-feature-text">
69+
<p class="why-feature-key">Language</p>
70+
<h3>Modern code, WC3 output</h3>
71+
<p>Use types, packages, classes, closures, and extension methods while compiling to Jass or Lua.</p>
72+
<img class="why-feature-shot" src="/assets/images/blog/bestof4/runTestVS.png" alt="Wurst code and commands in VS Code">
7173
</div>
7274
</article>
7375

7476
<article class="why-feature">
75-
<div class="why-feature-icon"><i class="fa fa-cube"></i></div>
7677
<div class="why-feature-text">
77-
<p class="why-feature-key">Compiletime</p>
78-
<h3>Generate map objects before runtime.</h3>
79-
<p>Create units, abilities, and items from code with consistent IDs and less manual editor work.</p>
80-
<pre class="language-wurst why-inline-code"><code class="language-wurst">@compiletime
81-
new ZombieDefinition(UNIT_ID, UnitIds.dalaranmutant)</code></pre>
78+
<p class="why-feature-key">Object data</p>
79+
<h3>Generate editor work</h3>
80+
<p>Create abilities, units, items, upgrades, and other object edits from source-controlled code.</p>
81+
<img class="why-feature-shot" src="/assets/images/whywurst/wurst-objgen.png" alt="Warcraft III spell created with Wurst">
8282
</div>
8383
</article>
8484

8585
<article class="why-feature">
86-
<div class="why-feature-icon"><i class="fa fa-tachometer"></i></div>
8786
<div class="why-feature-text">
88-
<p class="why-feature-key">Optimization Pipeline</p>
89-
<h3>Ship lean Jass or Lua output.</h3>
90-
<p>Built-in propagation, inlining, and merge passes reduce overhead without hand-tuning every script.</p>
91-
<pre class="language-wurst why-inline-code"><code class="language-wurst">// fewer calls after inlining
92-
fastDamage(target, amount)</code></pre>
87+
<p class="why-feature-key">Tooling</p>
88+
<h3>VS Code knows WC3</h3>
89+
<p>Get diagnostics, completion, native docs, model and texture previews, MPQ browsing, build, and run on Windows, Linux, or macOS.</p>
90+
<img class="why-feature-shot" src="/assets/images/news/model_viewer.png" alt="Wurst VS Code model preview">
9391
</div>
9492
</article>
9593
</div>

‎_news/better-ai-support.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
title: Better AI & CI Support
3+
excerpt: Optional AGENTS.md context, targeted verification commands, macOS support, generated GitHub workflows, and refreshed Docker-backed CI for Wurst projects.
4+
date: 2026-05-14
5+
image: /assets/images/news/wurst-ai.png
6+
layout: newsarticle
7+
author: Frotty
8+
---
9+
10+
Wurst projects are getting better AI and CI support: they are easier to work on with coding agents, cleaner to verify locally, and simpler to run across development machines and continuous integration.
11+
12+
## Agent-Ready Projects
13+
14+
New and existing Wurst repositories can now add an `AGENTS.md` file for AI coding tools. It is not forced into every project by default: `grill` can ask whether to add it during project setup or updates, and the VSCode extension can surface a prompt when a project does not have one yet.
15+
16+
The file gives coding agents the project context they need: where Wurst source lives, how the build file is structured, which commands are expected, and how to verify changes before handing them back.
17+
18+
The important verification commands are intentionally small and predictable:
19+
20+
```bash
21+
grill typecheck
22+
grill test NAME
23+
```
24+
25+
`grill typecheck` checks the project without running the full test suite. `grill test NAME` runs a specific unit test, which gives agents a fast way to validate the exact area they changed.
26+
27+
## macOS Support
28+
29+
Wurst now fully supports macOS alongside Windows and Linux. That means the local toolchain and the usual `grill` workflow can be used across the three major desktop platforms.
30+
31+
## Better Project Generation and CI Scaffolding
32+
33+
`grill generate` was also improved. It now asks a few setup questions during project creation, including the patch target and whether the project should use Lua or Jass mode.
34+
35+
The generator can also provide premade GitHub workflows, giving new projects a ready starting point for continuous integration.
36+
37+
## Docker for CI
38+
39+
For CI environments, the existing Wurst Docker image was updated so builds can run with a consistent, current toolchain. This pairs well with the generated GitHub workflows and keeps verification close to the same commands developers and agents run locally.

0 commit comments

Comments
 (0)