Skip to content

Commit

Permalink
Update jhcr.md
Browse files Browse the repository at this point in the history
  • Loading branch information
Frotty committed Jan 6, 2025
1 parent 8947327 commit af3c2a7
Showing 1 changed file with 85 additions and 25 deletions.
110 changes: 85 additions & 25 deletions _tutorials/jhcr.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Hot Code Reload Guide
excerpt: Learn how to update code in a running map with JHCR
date: 2022-11-03
date: 2025-01-06
icon:
type: fa
name: fa-share-square
Expand All @@ -12,45 +12,105 @@ layout: doc

# Jass Hot Code Reload

Wurst has integrated support for JHCR to reload code while the map is running.
This allows you to iterate quickly, because it is not necessary to test the map from the beginning after every code change.
**Jass Hot Code Reload (JHCR)** is an integrated feature in Wurst that allows you to reload your Warcraft III map's code while the game is still running. This drastically speeds up iteration because you do not need to restart the map (and replay from the beginning) whenever you change your code.

## Why Use Hot Code Reload?

- **Faster Iterations**: Quickly test and validate changes without fully restarting Warcraft III.
- **Smooth Development**: Keep your in-game session active, preventing the overhead of reloading your entire map.
- **Testing Flexibility**: Tweak specific features or values on the fly to see how they behave in real time.

## Installation

If you have not installed Wurst and Visual Studio Code yet, you should first check out the [Setup Guide](/start).
> **Prerequisite**: If you have not installed Wurst and Visual Studio Code yet, start with the [Wurst Setup Guide](/start) to get your environment ready.
Then to setup JHCR:
Once you have Wurst and Visual Studio Code, follow these steps to set up JHCR:

1. [Download JHCR](https://www.hiveworkshop.com/threads/jass-hot-code-reload.313811/) and extract it to a folder on your machine.
2. Open the Visual Studio Code Settings and change the entry for `wurst.jhcrExe` to the jhcr executable you extracted in step 1. For example `C:\apps\jhcr.exe`.
3. Configure the Visual Studio Code Setting `wurst.customMapDataPath` to point to the path where Warcraft stores custom map data.
1. **Download JHCR**
[Download the latest version here](https://www.hiveworkshop.com/threads/jass-hot-code-reload.313811/) and extract it to a folder on your machine.

This is usually something like
2. **Configure the JHCR Executable Path**
- Open the Visual Studio Code settings.
- Locate the setting `wurst.jhcrExe`.
- Point it to the JHCR executable you extracted in step 1 (e.g., `C:\apps\jhcr.exe`).

`C:\\Users\\YourName\\Documents\\Warcraft III\\CustomMapData`
3. **Set the Custom Map Data Path**
- In Visual Studio Code, find the `wurst.customMapDataPath` setting.
- Set it to the folder where Warcraft III stores custom map data. Typically, this is one of the following:
```
C:\Users\YourName\Documents\Warcraft III\CustomMapData
```
or
```
C:\Users\YourName\OneDrive\Documents\Warcraft III\CustomMapData
```
- This path is passed to JHCR’s `--preload-path` option.
- If you do not specify this path, Wurst will attempt to detect the correct folder automatically.
or
## Usage
`C:\\Users\\YourName\\OneDrive\\Dokumente\\Warcraft III\\CustomMapData`
Once everything is set up, you can run your map with JHCR directly from Visual Studio Code. This is called **Hot Code Reload**.
This path will be passed to the `--preload-path` option of Jass Hot Code Reload (JHCR).
If you do not specify this path, Wurst will try to detect the correct folder.
### 1. Start Your Map with JHCR
## Usage
1. Press `F1` in Visual Studio Code.
2. Search for the command: `wurst: Hot Run a Wurst map with Jass Hot Code Reload (JHCR)`
3. Press `Enter` to select it.
4. Choose the map you want to run and press `Enter` again.
Warcraft III will now start and load your map with JHCR support.
To use Hot Code Reload, simply run your map using your map with the `wurst.hotstartmap` command:
### 2. Reload Your Code On-the-Fly
- Press `F1`
- Search for `wurst: Hot Run a Wurst map with Jass Hot Code Reload (JHCR)` and hit `Enter`
- Select the map to run and press `Enter`
Once your map is running in Warcraft III:
After Warcraft has started you can edit your code and when you want to load your changes into the running WC3 instance you simply run the the `wurst.hotreload` command:
1. Make changes to your Wurst code in Visual Studio Code.
2. Press `F1`.
3. Search for the command: `wurst: Hot reload code for a Wurst map started with Jass Hot Code Reload (JHCR)`
4. Press `Enter`.
5. Wait for the compilation to finish in the VS Code console.
6. Switch back to the Warcraft III window and press `ESC` to trigger the actual reload.
- Press `F1`
- Search for `wurst: Hot reload code for a Wurst map started with Jass Hot Code Reload (JHCR)` and hit `Enter`
- Wait until the compilation has finished
- Switch back to the Game and hit `ESC` to trigger the reload.
You should see a message like: `Code reloaded, status: 1`
This indicates a successful reload. Other status codes include:
- **Status 2**: No reload was necessary (no changes detected).
- **Status 3**: Reload failed (often due to too many changes or incompatible edits).
## Advanced Usage
If you want to use these commands often, you can assign keyboard shortcuts for them in Visual Studio Code.
If you find yourself reloading and restarting your map frequently, you can speed up your workflow even more by assigning keyboard shortcuts in Visual Studio Code for the following commands:
- `wurst: Hot Run a Wurst map with Jass Hot Code Reload (JHCR)`
- `wurst: Hot reload code for a Wurst map started with Jass Hot Code Reload (JHCR)`
To do this, open **Keyboard Shortcuts** in VS Code (usually under **File > Preferences > Keyboard Shortcuts** or by pressing `Ctrl+K, Ctrl+S` on Windows) and set bindings for the commands above.
## Limitations
- **Existing Data**: Only function calls made after the reload will use the updated code. Data created beforehand (such as existing class instances) will not be retroactively changed.
- **Package Initializers**: These are not re-run after a reload. For example, a print statement in a package initializer will not be called again.
- **Stateful Objects**: If you have objects that rely on initialization logic, they won’t automatically re-initialize on reload.
### Example 1: Static Print
```wurst
init
print("Hello")
```

After reloading, you will not see this message re-printed, because initializers aren’t re-run.

### Example 2: Periodic Print

```
init
doPeriodically(1.) cb ->
print("Hello") // If you change this to "There" and reload, the new text will show.
```

Here, the text printed every second will change after a successful reload.

Despite these constraints, JHCR is still extremely useful for experimenting with small features, fine-tuning values, and rapidly iterating on game logic.

Enjoy faster development and real-time testing with Jass Hot Code Reload!

0 comments on commit af3c2a7

Please sign in to comment.