# How to Contribute to the Wand Enhancer Project: Setup, Workflow, and Code Guidelines

> Ready to contribute to Wand Enhancer? Learn how to fork the repo, set up your dev environment, and submit a pull request following our code guidelines. Start enhancing today!

- Repository: [k1tbyte/Wand-Enhancer](https://github.com/k1tbyte/Wand-Enhancer)
- Tags: how-to-guide
- Published: 2026-07-13

---

**To contribute to the Wand Enhancer project, fork the repository on GitHub, configure the .NET Framework and Node.js development environment, create a feature branch from `master`, and submit a pull request that follows the architectural constraints documented in [`AGENTS.md`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/AGENTS.md) and [`CONTRIBUTING.md`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/CONTRIBUTING.md).**

The Wand Enhancer is an open-source patching tool for the Wand Electron client, built as a .NET Framework WPF application with an integrated TypeScript web panel. Understanding how to contribute to the Wand Enhancer project requires familiarity with its hybrid architecture spanning C# desktop code, ASAR archive manipulation, and modern frontend tooling.

## Setting Up Your Development Environment

Before modifying the codebase, you must configure the specialized toolchain that builds both the native components and the web interface.

### Fork and Clone the Repository

Start by creating your own copy of the repository and cloning it locally:

```bash
git clone https://github.com/<your-username>/Wand-Enhancer.git
cd Wand-Enhancer

```

### Install Required Build Tools

The project requires a specific stack documented in the [README – Build Steps](https://github.com/k1tbyte/Wand-Enhancer/blob/master/README.md#build-steps):

- **CMake** for native compilation
- **Node.js** ≥ 18 and **pnpm** (`npm i -g pnpm`)
- **Visual Studio 2022** (or Build Tools) with the *Desktop development with C++* workload
- **.NET Framework 4.8** development pack

### Build the Solution

Use the provided cross-platform script to restore dependencies and compile:

```bash
./build.cmd   # or build.sh / build.ps1 depending on your shell

```

This script installs web-panel dependencies, compiles the native helper with CMake, restores NuGet packages, and builds the `Wand-Enhancer.sln` solution.

## Understanding the Three-Component Architecture

Wand Enhancer consists of three distinct layers. Isolating your changes to the correct component ensures clean pull requests that are easy to review.

### Desktop Patcher (WPF Application)

The **desktop patcher** is the .NET Framework WPF application that extracts, patches, and repacks the `app.asar` file from the Wand client. Key entry points include:

- **[`WandEnhancer/App.xaml.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/App.xaml.cs)** – Application entry point that launches the patch workflow
- **[`WandEnhancer/Core/Enhancer.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/Core/Enhancer.cs)** – Core logic that determines which patches to apply and coordinates the modification sequence

### ASAR Handling Library (AsarSharp)

The **ASAR handling library** (`AsarSharp`) is a C# library that reads and writes ASAR archives, enabling the patcher to modify the Electron bundle without corrupting the archive structure:

- **[`AsarSharp/AsarExtractor.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/AsarSharp/AsarExtractor.cs)** – Handles reading and extraction of ASAR bundles
- **[`AsarSharp/AsarCreator.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/AsarSharp/AsarCreator.cs)** – Manages repacking the modified archive after patching

Reference the **ASAR Patch Pipeline** section in [`AGENTS.md`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/AGENTS.md) for invariants like avoiding hard failures when extracting unpacked entries.

### Remote Web Panel (TypeScript/React)

The **remote web panel** provides a TypeScript bridge and React-compatible UI that runs inside the patched Electron renderer:

- **[`web-panel/bridge/src/websocket-codec.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/bridge/src/websocket-codec.ts)** – Encodes and decodes WebSocket messages between the Electron bridge and the remote panel
- **[`web-panel/src/trainer/controls/SliderTrack.tsx`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/src/trainer/controls/SliderTrack.tsx)** – Example UI component for the trainer interface

The [`AGENTS.md`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/AGENTS.md) file documents implementation details including the default port `3223`, storage conventions, and bridge-to-renderer IPC protocols.

## The Contribution Workflow: From Branch to Pull Request

Follow this standardized workflow to contribute to the Wand Enhancer project effectively.

### Create a Feature Branch

Always branch from `master` with a descriptive name:

```bash
git checkout -b feature/awesome-feature

```

### Make Isolated Changes

Keep modifications scoped to the relevant component:

- For **UI work**, use the Tailwind-based primitives in `web-panel/src/shared/ui/`
- For **ASAR modifications**, respect the pipeline invariants in [`AGENTS.md`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/AGENTS.md)
- For **patch logic**, modify the core workflow in [`WandEnhancer/Core/Enhancer.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/Core/Enhancer.cs)

### Validate with Build and Tests

Before committing, verify your changes compile correctly:

```bash

# For web-panel changes

cd web-panel
pnpm install
pnpm run build   # Validates TypeScript and bundles the bridge

node --check web-panel/dist/bridge.cjs   # Syntax check

# For C# changes

dotnet build

```

### Submit Your Pull Request

Commit with clear, conventional messages:

```bash
git add .
git commit -m "feat: add XYZ support to remote panel"
git push origin feature/awesome-feature

```

Open a pull request on GitHub explaining **why** the change is needed, **what** was modified, and referencing any relevant issue numbers. Consult [`CONTRIBUTING.md`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/CONTRIBUTING.md) for the exact checklist and coding style requirements.

## Code Examples for Common Contributions

These practical examples demonstrate how to extend specific subsystems when you contribute to the Wand Enhancer project.

### Injecting a Custom Script into the Renderer

Place a `.js` file in the `renderer-scripts/` folder (or add via the patch dialog) to inject code into the Wand renderer:

```javascript
if (!globalThis.__helloInstalled) {
  globalThis.__helloInstalled = true;
  WandEnhancer.log("Hello from my custom script!", WandEnhancer.remoteUrl);
}

```

When the patcher runs, this script bundles into `app.asar` and executes inside the Electron renderer process.

### Adding a New IPC Channel to the Bridge

To extend communication between the bridge and the remote panel, modify [`web-panel/bridge/src/constants.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/bridge/src/constants.ts):

```typescript
export const IPC = {
  REMOTE_COMMAND: "wand-remote-command",
  NEW_FEATURE: "wand-new-feature"
};

export type IpcMessage = 
  | { type: typeof IPC.REMOTE_COMMAND; payload: any }
  | { type: typeof IPC.NEW_FEATURE; payload: any };

```

Reference the new channel in [`web-panel/bridge/src/websocket-codec.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/bridge/src/websocket-codec.ts), then rebuild with `pnpm run build:bridge` to regenerate the injected `bridge.cjs`.

### Modifying ASAR Extraction Rules

When handling edge cases in archive extraction, update [`AsarSharp/AsarExtractor.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/AsarSharp/AsarExtractor.cs):

```csharp
if (entry.IsUnpacked && entry.SourcePath.Equals(entry.DestinationPath, StringComparison.OrdinalIgnoreCase))
{
    // Skip self-copy to avoid locked-file errors (see AGENTS.md)
    continue;
}

```

This follows the guideline to never re-introduce hard failures when extracting unpacked entries.

## Summary

- **Fork and clone** the repository, then install CMake, Node.js ≥18, pnpm, Visual Studio 2022, and .NET Framework 4.8 to build the project using `./build.cmd`.
- **Understand the three layers**: the WPF desktop patcher ([`WandEnhancer/Core/Enhancer.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/Core/Enhancer.cs)), the ASAR library ([`AsarSharp/AsarExtractor.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/AsarSharp/AsarExtractor.cs)), and the TypeScript web panel ([`web-panel/bridge/src/websocket-codec.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/bridge/src/websocket-codec.ts)).
- **Follow the workflow**: Create feature branches, keep changes isolated, validate with `pnpm run build` and `dotnet build`, and submit PRs referencing [`CONTRIBUTING.md`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/CONTRIBUTING.md).
- **Respect architectural constraints** documented in [`AGENTS.md`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/AGENTS.md), particularly regarding ASAR extraction invariants and IPC message structures.

## Frequently Asked Questions

### Do I need a specific IDE to contribute to Wand Enhancer?

While **Visual Studio 2022** is recommended for the C# components, you can use any editor that supports .NET Framework 4.8 and CMake. For the TypeScript web panel, any editor with Node.js support works, provided you can run `pnpm` commands from the terminal.

### What are the most important files to understand before contributing?

Study **[`WandEnhancer/Core/Enhancer.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/Core/Enhancer.cs)** for the main patching logic, **[`AsarSharp/AsarExtractor.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/AsarSharp/AsarExtractor.cs)** for archive handling, and **[`web-panel/bridge/src/websocket-codec.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/bridge/src/websocket-codec.ts)** for the IPC communication layer. Additionally, review **[`AGENTS.md`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/AGENTS.md)** for architectural constraints and **[`CONTRIBUTING.md`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/CONTRIBUTING.md)** for style guidelines.

### How do I test changes to the remote web panel?

After modifying files in `web-panel/`, run `pnpm install` followed by `pnpm run build` to validate TypeScript compilation and bundle the bridge. Use `node --check web-panel/dist/bridge.cjs` to verify the output syntax before testing the patcher against a Wand client installation.

### Where should I place custom scripts for the patcher?

Place custom `.js` files in the **`renderer-scripts/`** directory adjacent to the patcher executable, or add them via the patch dialog. These scripts automatically bundle into the ASAR archive and execute within the Electron renderer context when the patched client launches.