### Example Commands

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/BackgroundAgentPrompt.txt

Illustrative examples of using the `add_background` function for different scenarios.

```APIDOC
## Example Commands

Fixed tiled sky:
```
add_background bS="forest" no="0" type="back" x=0 y=-100 rx=0 ry=0 cx=1024 z=0
```

Distant parallax mountains:
```
add_background bS="forest" no="3" type="back" x=0 y=100 rx=25 ry=20 z=10
```

Animated foreground effect:
```
add_background bS="forest" no="2" type="ani" x=100 y=100 rx=90 ry=80 front=true
```
```

--------------------------------

### Example Tile Structure Scenarios

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/TileAgentPrompt.txt

Illustrative examples of how to use the `tile_structure` command for various map designs.

```APIDOC
## Example Scenarios

### Basic Ground Floor (Town Style)
```
// Wide ground floor - 1080px wide (12 tiles), 3 rows deep (180px)
tile_structure tileset="grassySoil" structure_type="tall" start_x=-540 end_x=540 y=450 height=3
```

### Floating Platform
```
// Small floating platform - 270px wide (3 tiles), single row
tile_structure tileset="grassySoil" structure_type="flat" start_x=-135 end_x=135 y=270
```

### Cave with Multiple Levels
```
// Ground floor - 720px wide, 4 rows deep (240px)
tile_structure tileset="deepMine" structure_type="tall" start_x=-360 end_x=360 y=420 height=4

// Mid-level platforms at Y=300 (120px gap - normal jump)
tile_structure tileset="deepMine" structure_type="flat" start_x=-270 end_x=-90 y=300
tile_structure tileset="deepMine" structure_type="flat" start_x=90 end_x=270 y=300

// Upper platform at Y=180 (120px gap)
tile_structure tileset="deepMine" structure_type="flat" start_x=-135 end_x=135 y=180
```

### Staircase Tower
```
// 6-step staircase, each step 60px high (360px total climb)
tile_structure tileset="ludibrium" structure_type="staircase_right" start_x=-270 y=420 height=6
```

### Sloped Hill
```
// Left slope going up, flat top, right slope going down
tile_structure tileset="grassySoil" structure_type="slope_up_right" start_x=-270 end_x=0 y=360
tile_structure tileset="grassySoil" structure_type="flat" start_x=0 end_x=180 y=240
tile_structure tileset="grassySoil" structure_type="slope_up_left" start_x=180 end_x=450 y=360
```
```

--------------------------------

### Example Debug Output

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/hacreator-harepacker-architecture/IMG_FILESYSTEM_MIGRATION_PLAN.md

Sample console output generated during the 64-bit packing process.

```text
[PackCategory] Map: Found 1250 IMG files, total size: 450MB
[PackCategory] Map: Split into 3 WZ file(s)
[PackCategory] Map: Creating Map_000.wz with 420 files
[PackCategory] Map: Saving Map_000.wz
[PackCategory] Map: Created Map_000.wz (148MB)
[PackCategory] Map: Creating Map_001.wz with 415 files
[PackCategory] Map: Saving Map_001.wz
[PackCategory] Map: Created Map_001.wz (147MB)
[PackCategory] Map: Creating Map_002.wz with 415 files
[PackCategory] Map: Saving Map_002.wz
[PackCategory] Map: Created Map_002.wz (155MB)
```

--------------------------------

### Example: Add Warning Zone Tooltip

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/SettingsAgentPrompt.txt

Example of adding a tooltip to warn players about a dangerous area, including title and description.

```plaintext
ADD TOOLTIP at (0, 300) size=(300, 100) title="Danger!" desc="High level monsters ahead. Prepare yourself!"
```

--------------------------------

### Directory Structure Examples

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/wz-format/canvas-outlink-system.md

Comparison of traditional 32-bit and modern 64-bit WZ file directory layouts.

```text
MapleStory/
├── Map.wz
├── Mob.wz
├── Npc.wz
├── Character.wz
└── ...
```

```text
MapleStory/
├── Data/
│   ├── Base/
│   │   ├── Base_000.wz
│   │   └── Base_001.wz
│   ├── Map/
│   │   ├── Map_000.wz
│   │   ├── Map_001.wz
│   │   └── _Canvas/
│   │       ├── _Canvas_000.wz
│   │       ├── _Canvas_001.wz
│   │       └── ...
│   ├── Mob/
│   │   ├── Mob_000.wz
│   │   └── _Canvas/
│   │       └── _Canvas_000.wz
│   └── ...
```

--------------------------------

### Setup Project Dependencies

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/AGENTS.md

Run these commands to initialize Git submodules and restore NuGet and .NET project dependencies.

```powershell
git submodule update --init --recursive
nuget restore MapleHaSuite.sln
dotnet restore MapleHaSuite.sln
```

--------------------------------

### Tiling Examples

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/MapEditorSystemPrompt.txt

Illustrates different tiling intervals (cx, cy) for background images. cx=0 or cy=0 disables tiling in that direction.

```text
cx=0   cy=0   -> No tiling (single image)
cx=520 cy=0   -> Horizontal tiling every 520px (for wide panoramas, skies)
cx=0   cy=300 -> Vertical tiling every 300px (for tall backgrounds)
cx=400 cy=400 -> Tiles in both directions (for patterns, textures)
```

--------------------------------

### Example: Add Quest Hint Tooltip

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/SettingsAgentPrompt.txt

Example of adding a tooltip to provide a hint for a quest, detailing the location of a secret passage.

```plaintext
ADD TOOLTIP at (100, 200) size=(250, 150) title="Hidden Path" desc="Look for a secret passage behind the waterfall."
```

--------------------------------

### Add Event Map with Town Return Portal

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/PortalAgentPrompt.txt

Sets up portals for an event map, including a starting point, a town return portal, a script-triggered event start, and a changeable event exit portal.

```script
add_portal portal_type="StartPoint" name="sp" x=0 y=300 target_map=999999999
add_portal portal_type="TownPortal_Point" name="tp" x=50 y=300 target_map=999999999
add_portal portal_type="Script" name="start_event" x=-200 y=300 target_map=999999999 script="eventStart"
add_portal portal_type="Changeable" name="event_exit" x=300 y=300 target_map=100000000 target_portal="sp"
```

--------------------------------

### WZ Property and File Structure

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/wz-format/canvas-outlink-system.md

Examples of the _outlink property in main WZ files and the internal structure of _Canvas WZ files.

```text
Main WZ (Mob_000.wz):
  8800141.img/
    attack1/
      0 (Canvas)
        _outlink = "Mob/_Canvas/8800141.img/attack1/0"
```

```text
_Canvas_000.wz:
  8800141.img/
    Anims/
      0/
        stand/
          LayerSlots/
            Slot0/
              Segment0/
                AnimReference/
                  0 (Canvas) <- Actual bitmap data
                  1 (Canvas)
                  2 (Canvas)
```

--------------------------------

### Key Detection Methods

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/wz-format/wz-format-history.md

Provides C# code examples for detecting different WZ file formats based on directory structure and file presence.

```APIDOC
## Key Detection Methods

```csharp
// Detect 64-bit .exe format (Data/ directory with 40+ WZ files)
bool is64Bit = WzFileManager.Detect64BitDirectoryWzFileFormat(path);

// Detect pre-Big Bang format (List.wz exists or single Data.wz)
bool isPreBB = WzFileManager.DetectIsPreBBDataWZFileFormat(path);

// Check for Big Bang update via UIWindow2.img marker
bool isBigBang = WzFileManager.IsBigBangUpdate(uiWindow2Image);

// Check for Big Bang 2 / Chaos update
bool isBigBang2 = WzFileManager.IsBigBang2Update(uiWindow2Image);
```
```

--------------------------------

### Mob and NPC Placement Examples

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/LifeAgentPrompt.txt

Common patterns for placing mobs and NPCs in various map scenarios.

```text
add_mob mob_id=100100 x=-300 y=300 rx0=-400 rx1=-200
add_mob mob_id=100100 x=-100 y=300 rx0=-200 rx1=0
add_mob mob_id=100100 x=100 y=300 rx0=0 rx1=200
add_mob mob_id=100100 x=300 y=300 rx0=200 rx1=400
```

```text
add_mob mob_id=2230101 x=0 y=300 rx0=-100 rx1=100
```

```text
add_npc npc_id=9000000 x=-200 y=300
add_npc npc_id=1052001 x=200 y=300 flip=true
```

```text
add_mob mob_id=100110 x=-150 y=400 rx0=-250 rx1=-50
add_mob mob_id=100110 x=150 y=400 rx0=50 rx1=250
add_mob mob_id=100120 x=0 y=250 rx0=-100 rx1=100
add_mob mob_id=100120 x=-200 y=100 rx0=-300 rx1=-100
add_mob mob_id=100120 x=200 y=100 rx0=100 rx1=300
```

--------------------------------

### Common MapleStory Directories

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/wz-format/WzFileManager.md

Array of default file paths used to locate MapleStory installations.

```csharp
public static readonly string[] COMMON_MAPLESTORY_DIRECTORY = new string[] {
    @"C:\Nexon\MapleStory",
    @"D:\Nexon\Maple",
    @"C:\Program Files\WIZET\MapleStory",
    @"C:\MapleStory",
    @"C:\NEXPACE\MapleStoryN",
    @"C:\Program Files (x86)\Wizet\MapleStorySEA"
};
```

--------------------------------

### Layout Patterns

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/PlatformAgentPrompt.txt

Examples of common map layout patterns with dimensions and element suggestions.

```APIDOC
## Layout Patterns

Use 60-pixel vertical intervals to align with MapleStory's standard grid.

### Simple Training Ground
**Dimensions:** ~800x400 pixels (single screen width)
- Main floor: X=-400 to X=400, Y=360 (800px wide)
- Floating platform 1: X=-200 to X=0, Y=240 (200px wide)
- Floating platform 2: X=100 to X=300, Y=180 (200px wide)
- Walls at X=-400 and X=400, Y=0 to Y=400
- Suitable for: Tutorial areas, beginner zones

### Multi-level Town Map
**Dimensions:** ~2000x600 pixels (scrolling horizontally)
- Ground level: X=-1000 to X=1000, Y=450 (2000px wide)
- Mid platform left: X=-800 to X=-400, Y=330 (400px wide)
- Mid platform right: X=400 to X=800, Y=270 (400px wide)
- Upper platforms: X=-300 to X=300, Y=150 (600px wide)
- Ladders at X=-600 (Y=270 to Y=450) and X=600 (Y=150 to Y=330)
- Suitable for: Towns like Henesys, Ellinia

### Combat Arena
**Dimensions:** ~1200x300 pixels (wide, shallow)
- Central platform: X=-500 to X=500, Y=300 (1000px wide)
- Left platform: X=-550 to X=-350, Y=240 (200px wide)
- Right platform: X=350 to X=550, Y=240 (200px wide)
- Walls at X=-600 and X=600, Y=100 to Y=350
- Suitable for: Boss rooms, PvP areas

### Tower/Vertical Map
**Dimensions:** ~400x800 pixels (narrow, tall)
- Platform at each level: 300-400px wide, spaced 60-120px vertically
- Example levels: Y=600, Y=480, Y=360, Y=240, Y=120
- Walls at X=-200 and X=200, spanning full height
- Ladders at X=0, connecting each pair of platforms
- Suitable for: Eos Tower, Orbis Tower style
```

--------------------------------

### Rope Placement

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/PlatformAgentPrompt.txt

Guidelines and examples for adding ropes to connect platform levels.

```APIDOC
## Rope Placement Guidelines

Position ropes to connect platform levels. The top should be at or slightly above the upper platform's Y coordinate, and the bottom at the lower platform's Y.

| Climb Type | Length (pixels) | Typical Use |
|------------|-----------------|-------------|
| Short      | 100-150 px      | Single level, quick access |
| Medium     | 150-250 px      | 2-3 level spans, common |
| Long       | 250-400 px      | Multi-level towers, vertical maps |

### Add Rope

Adds a rope element to the map.

#### Parameters
- **x** (integer) - Required - The X coordinate for the rope.
- **top_y** (integer) - Required - The Y coordinate for the top of the rope.
- **bottom_y** (integer) - Required - The Y coordinate for the bottom of the rope.
- **uf** (boolean) - Optional - If true, the rope can be exited at the top. Defaults to true.
- **layer** (integer) - Optional - The layer the rope belongs to.

### Request Example
```
add_rope x=0 top_y=150 bottom_y=300
```

### Rope Ending at Ceiling Example
```
add_rope x=100 top_y=50 bottom_y=200 uf=false
```
```

--------------------------------

### Layered Scene Example

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/ObjectAgentPrompt.txt

Demonstrates layering objects using z-order to create depth. Lower z values are for background objects, while higher values are for foreground elements.

```javascript
add_object oS="acc1" l0="nature" l1="tree" l2="2" x=-200 y=300 z=5
add_object oS="acc1" l0="nature" l1="tree" l2="0" x=-100 y=300 z=15
add_object oS="acc1" l0="nature" l1="bush" l2="0" x=-50 y=300 z=25
```

--------------------------------

### NPC Listing Commands

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/LifeAgentPrompt.txt

Examples of how to filter and retrieve NPC lists using the get_npc_list function.

```text
get_npc_list(search="shop")
get_npc_list(search="storage")
get_npc_list(search="instructor")
get_npc_list()
```

--------------------------------

### Define Documentation Directory Structure

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/hacreator-harepacker-architecture/IMG_FILESYSTEM_MIGRATION_PLAN.md

A recommended file system layout for organizing user guides, developer documentation, tutorials, and sample files.

```markdown
# Suggested Documentation Structure
docs/
├── user-guide/
│   ├── getting-started.md
│   ├── extracting-wz-files.md
│   ├── version-management.md
│   ├── troubleshooting.md
│   └── faq.md
├── developer-guide/
│   ├── architecture.md
│   ├── api-reference.md
│   ├── contributing.md
│   ├── building.md
│   └── testing.md
├── tutorials/
│   ├── video-links.md
│   ├── creating-custom-maps.md
│   └── sharing-versions.md
└── samples/
    ├── sample-config.json
    └── sample-manifest.json
```

--------------------------------

### Add Portal with Activation Delay

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/PortalAgentPrompt.txt

Adds a visible portal with a specified activation delay in milliseconds. This example demonstrates a 2-second delay for a boss door.

```script
add_portal portal_type="Visible" name="boss_door" x=0 y=300 target_map=100010000 target_portal="sp" delay=2000
```

--------------------------------

### C++ Physics Calculation Example

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/plan.md

Illustrates the calculation of vMax based on character walk speed, game client walk speed, and foothold drag. This formula is derived from official client physics.

```cpp
v16 = TSecType<double>::GetData(&v15->walkSpeed);  // CAttrShoe::walkSpeed
pAttrFootholda = v16 * (v14->dWalkSpeed * drag);   // vMax calculation
```

--------------------------------

### Incorrect Mob Addition (No Query)

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/MapEditorSystemPrompt.txt

This example shows an incorrect way to add a mob, as it bypasses the mandatory query step. This will result in a failure.

```python
add_mob mob_id=100100 x=100 y=300    // BAD! No query first!
```

--------------------------------

### Forest Decoration Scenario

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/ObjectAgentPrompt.txt

An example scenario for decorating a forest area, including trees, rocks, and bushes. It shows variations in object types, flip parameters, and positioning.

```javascript
add_object oS="acc1" l0="nature" l1="tree" l2="0" x=-300 y=300
add_object oS="acc1" l0="nature" l1="tree" l2="1" x=-100 y=300 flip=true
add_object oS="acc1" l0="nature" l1="tree" l2="0" x=200 y=300
add_object oS="acc1" l0="nature" l1="rock" l2="0" x=0 y=300
add_object oS="acc1" l0="nature" l1="bush" l2="0" x=-200 y=300
add_object oS="acc1" l0="nature" l1="bush" l2="0" x=100 y=300
```

--------------------------------

### Canvas Index File Format

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/hacreator-harepacker-architecture/IMG_FILESYSTEM_MIGRATION_PLAN.md

Example INI file format for tracking canvas WZ files within a _Canvas directory. Includes a count of the files.

```ini
; Canvas_directory.ini
[Canvas]
Count=3
; Canvas_000.wz, Canvas_001.wz, Canvas_002.wz

```

--------------------------------

### Initialize and Run Map Simulator

Source: https://context7.com/lastbattle/harepacker-resurrected/llms.txt

Shows how to instantiate the MapSimulator, configure map loading callbacks, and access game subsystems.

```csharp
// Create and run a map simulator
Board mapBoard = LoadMap(mapId);
string title = $"{mapName}:{mapId}";

MapSimulator simulator = new MapSimulator(mapBoard, title, spawnPortalName);

// Set callback for portal teleportation
simulator.SetLoadMapCallback((targetMapId) => {
    Board newBoard = LoadMap(targetMapId.ToString());
    string newTitle = GetMapTitle(targetMapId);
    return new Tuple<Board, string>(newBoard, newTitle);
});

// Run the simulator (blocking call)
simulator.Run();

// Access game subsystems
PlayerManager player = simulator.PlayerManager;
MobPool mobs = simulator.MobPool;
DropPool drops = simulator.DropPool;
PortalPool portals = simulator.PortalPool;
ReactorPool reactors = simulator.ReactorPool;
```

--------------------------------

### INI File Format for WZ File Count

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/wz-format/wz-format-history.md

An example of an INI file format used in MapleStory's Data directory. The 'LastWzIndex' value indicates the total number of WZ files for a given category, starting from _000.wz.

```ini
LastWzIndex|3
```

--------------------------------

### Clone and Initialize Repository

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/README.md

Use these commands to download the repository and initialize all required submodules.

```bash
git clone https://github.com/lastbattle/Harepacker-resurrected.git
git submodule update --init --recursive
```

--------------------------------

### Example: Add Area Description Tooltip

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/SettingsAgentPrompt.txt

Example of adding a tooltip to describe a map area, specifying coordinates, size, title, and description.

```plaintext
ADD TOOLTIP at (-200, 100) size=(400, 200) title="Forest Entrance" desc="A peaceful clearing at the edge of the forest."
```

--------------------------------

### Refactor Initialization: Old vs. New Approach (C#)

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/hacreator-harepacker-architecture/IMG_FILESYSTEM_MIGRATION_PLAN.md

Compares the old WZ file initialization method with the new IMG file system initialization. Use the new approach for IMG file system compatibility.

```csharp
private async Task InitializeFromWzFiles(string mapleStoryPath)
{
    Program.WzManager = new WzFileManager(mapleStoryPath);
    // Load WZ files...
}

// New approach
private async Task InitializeFromImgFileSystem(string versionPath)
{
    Program.ImgManager = new ImgFileSystemManager(versionPath);
    // Load IMG files with same extraction logic...
}
```

--------------------------------

### Configure portals and background music

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/OrchestratorPrompt.txt

Demonstrates parallel execution of portal placement and background music settings.

```json
{
  "agents": [
    {"agent": "portal", "task": "Add a visible portal to Henesys (map 100000000)", "priority": 1},
    {"agent": "settings", "task": "Query get_bgm_list and set BGM to a peaceful track", "priority": 1}
  ],
  "reasoning": "Two independent tasks can run in parallel"
}
```

--------------------------------

### GET /get_bgm_list

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/MapEditorSystemPrompt.txt

Query available background music tracks.

```APIDOC
## GET /get_bgm_list

### Description
Query available background music tracks.

### Method
GET

### Endpoint
/get_bgm_list

### Response
- Returns a list of available BGM paths grouped by folder
```

--------------------------------

### GET /get_object_info

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/ObjectAgentPrompt.txt

Retrieves information about a specific object set.

```APIDOC
## GET /get_object_info

### Description
Retrieves metadata and configuration for a specific object set.

### Method
GET

### Parameters
#### Query Parameters
- **oS** (string) - Required - The unique identifier of the object set (e.g., "acc3", "acc5", "orbis")

### Request Example
get_object_info(oS="acc3")
```

--------------------------------

### GET /get_background_info

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/MapEditorSystemPrompt.txt

Queries available items and dimensions for a background set.

```APIDOC
## GET /get_background_info

### Description
Retrieves available background items, types (back, ani, spine), and dimensions for a specific background set.

### Method
GET

### Parameters
#### Query Parameters
- **bS** (string) - Required - The name of the background set to query

### Response
#### Success Response (200)
- **data** (array) - List of items by type with dimensions
```

--------------------------------

### Understanding Tiling

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/MapEditorSystemPrompt.txt

Explains the concept of tiling for background images, including parameters cx and cy.

```APIDOC
## Understanding Tiling (cx, cy)

### Description
Tiling controls how backgrounds repeat to fill the screen.

- **cx** = horizontal tiling interval in pixels (0 = no horizontal tiling)
- **cy** = vertical tiling interval in pixels (0 = no vertical tiling)

### How tiling works:
- `0` = No tiling (single image, uses image's natural width/height for any auto-tiling)
- `>0` = Image tiles at this pixel interval

### Tiling examples:
```
cx=0   cy=0   -> No tiling (single image)
cx=520 cy=0   -> Horizontal tiling every 520px (for wide panoramas, skies)
cx=0   cy=300 -> Vertical tiling every 300px (for tall backgrounds)
cx=400 cy=400 -> Tiles in both directions (for patterns, textures)
```

### Common tiling patterns:
- **Full-width sky:** cx=(image width), cy=0, ry=0 (fixed horizontally tiled sky)
- **Seamless ground texture:** cx=(image width), cy=0 (repeating ground pattern)
- **Wallpaper effect:** cx=(image width), cy=(image height) (fills entire view)
```

--------------------------------

### Log Extraction Events

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/hacreator-harepacker-architecture/IMG_FILESYSTEM_MIGRATION_PLAN.md

Example of event-based logging for concurrent extraction processes.

```text
Starting: String
Starting: Map
Starting: Mob
Starting: Npc
Starting: Sound
Starting: Skill
Starting: Character
  Completed: String - 8 images (125 KB)
  Completed: Npc - 890 images (45 MB)
Starting: Item
...
  Completed: Map - 1250 images (350 MB)
```

--------------------------------

### GET /get_object_info

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/MapEditorSystemPrompt.txt

Queries available paths and dimensions for a specific object set.

```APIDOC
## GET /get_object_info

### Description
Retrieves the available l0/l1/l2 paths and dimensions for a given object set name. This should be called before adding objects to the map.

### Method
GET

### Parameters
#### Query Parameters
- **oS** (string) - Required - The name of the object set to query

### Response
#### Success Response (200)
- **data** (array) - List of all l0/l1/l2 paths with dimensions (width x height)
```

--------------------------------

### Implement Batch Conversion Tool

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/hacreator-harepacker-architecture/IMG_FILESYSTEM_MIGRATION_PLAN.md

Provides an asynchronous interface for converting multiple WZ source configurations into the new format.

```csharp
public class BatchConverter
{
    public async Task ConvertMultipleVersions(
        IEnumerable<WzSourceConfig> sources,
        string outputRoot,
        IProgress<BatchProgress> progress);
}
```

--------------------------------

### Build Project in Release Mode

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/AGENTS.md

Compile the entire solution in Release configuration using the .NET CLI.

```powershell
dotnet build MapleHaSuite.sln -c Release
```

--------------------------------

### VirtualWzDirectory Mapping

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/hacreator-harepacker-architecture/README.md

Demonstrates how a physical filesystem structure is mapped into the HaRepacker TreeView using VirtualWzDirectory.

```csharp
// Filesystem structure
Map/
├── Map0/
│   ├── 100000000.img/
│   │   ├── info/
│   │   └── ...
│   └── 100000100.img/
└── Tile/
    └── grassySoil.img/

// Appears in HaRepacker TreeView as:
[Map] (VirtualWzDirectory)
├── [Map0] (VirtualWzDirectory)
│   ├── [100000000.img] (WzImage)
│   └── [100000100.img] (WzImage)
└── [Tile] (VirtualWzDirectory)
    └── [grassySoil.img] (WzImage)
```

--------------------------------

### Connect Portals Between Maps

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/PortalAgentPrompt.txt

Example of linking two maps using paired portals.

```text
# In Map A (id=100000100)
add_portal portal_type="Visible" name="out00" x=500 y=300 target_map=100000200 target_portal="in00"

# In Map B (id=100000200) - you would add this when editing Map B
add_portal portal_type="Visible" name="in00" x=-400 y=300 target_map=100000100 target_portal="out00"
```

--------------------------------

### GET /get_npc_list

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/LifeAgentPrompt.txt

Retrieves a list of available NPCs, optionally filtered by search terms.

```APIDOC
## GET /get_npc_list

### Description
Retrieves a list of available NPCs. Can be filtered by name or function.

### Method
GET

### Endpoint
/get_npc_list

### Parameters
#### Query Parameters
- **search** (string) - Optional - Search term to filter by name or function (e.g., "shop", "storage").
- **limit** (integer) - Optional - Maximum results to return (default 50).
```

--------------------------------

### Add a platform with tiles

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/MapEditorSystemPrompt.txt

Create a platform by defining collision points first, followed by visual tile structures.

```text
- add_platform with points=[{x: -270, y: 300}, {x: 270, y: 300}]  // 540px wide
   - tile_structure with tileset="deepMine", structure_type="flat", start_x=-270, end_x=270, y=300
```

```text
- add_platform with points=[{x: 90, y: 300}, {x: 540, y: 300}]  // 450px, aligned to 90px grid
   - tile_structure with tileset="snowyRord", structure_type="flat", start_x=90, end_x=540, y=300
```

--------------------------------

### Implement Dual-Mode Data Source Support

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/hacreator-harepacker-architecture/IMG_FILESYSTEM_MIGRATION_PLAN.md

Defines the data source modes and a factory pattern to switch between filesystem, legacy WZ, or hybrid loading strategies.

```csharp
public enum DataSourceMode
{
    ImgFileSystem,  // New default
    WzFiles,        // Legacy support
    Hybrid          // IMG with WZ fallback
}

public class DataSourceFactory
{
    public static IDataSource Create(DataSourceMode mode, string path)
    {
        return mode switch
        {
            DataSourceMode.ImgFileSystem => new ImgFileSystemDataSource(path),
            DataSourceMode.WzFiles => new WzFileDataSource(path),
            DataSourceMode.Hybrid => new HybridDataSource(path),
            _ => throw new ArgumentException()
        };
    }
}
```

--------------------------------

### Build Project with MSBuild for Native/C++

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/AGENTS.md

Use MSBuild to build the solution, specifying Release configuration and x64 platform for native/C++ components, skipping package restore.

```powershell
msbuild MapleHaSuite.sln /p:Configuration=Release /p:Platform="x64" /p:RestorePackages=false
```

--------------------------------

### Create simple flat platform

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/TileAgentPrompt.txt

Adds a basic horizontal tiled surface.

```text
tile_platform tileset="grassySoil" start_x=-300 width=600 y=350
```

--------------------------------

### Validating Mob Placement

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/LifeAgentPrompt.txt

Examples demonstrating incorrect and correct mob placement relative to platform coordinates.

```text
add_mob mob_id=100100 x=0 y=150  // BAD! No platform at y=150!
```

```text
// If map context shows: Platform: y=300, x: -400 to 400
add_mob mob_id=100100 x=0 y=300 rx0=-200 rx1=200  // GOOD! On the platform!
```

--------------------------------

### Build WZ File List

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/wz-format/WzFileManager.md

Scans the MapleStory directory to build internal lookup dictionaries for WZ files.

```csharp
public void BuildWzFileList()
```

```text
LastWzIndex|5
```

--------------------------------

### Manage WZ Files with WzFileManager

Source: https://context7.com/lastbattle/harepacker-resurrected/llms.txt

Initialize the file manager, build file lists, and load specific WZ categories with encryption versions.

```csharp
// Initialize WzFileManager with MapleStory directory
WzFileManager wzManager = new WzFileManager("C:\\MapleStory", false);

// Build the list of available WZ files
wzManager.BuildWzFileList();

// Check if using 64-bit format (modern MapleStory versions)
bool is64Bit = wzManager.Is64Bit;

// Load a specific WZ file with encryption version
WzMapleVersion encryptionVersion = WzMapleVersion.BMS;
wzManager.LoadWzFile("map", encryptionVersion);

// Get WZ directories for a category
List<WzDirectory> mobDirectories = wzManager.GetWzDirectoriesFromBase("mob");

// Find a specific WZ image by path
WzImage mapHelperImage = (WzImage)wzManager.FindWzImageByName("map", "MapHelper.img");

// Access loaded WZ files by category
WzDirectory mobDir = wzManager["mob"];
```

--------------------------------

### GET /get_npc_list

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/MapEditorSystemPrompt.txt

Query available NPCs from the loaded game data. Must be called before using add_npc.

```APIDOC
## GET /get_npc_list

### Description
Query available NPCs from the loaded game data. This must be called before using add_npc.

### Method
GET

### Endpoint
/get_npc_list

### Parameters
#### Query Parameters
- **search** (string) - Optional - Search term to filter by name or function (e.g., "shop", "storage")
- **limit** (integer) - Optional - Maximum results to return (default 50)

### Response
- Returns a list of NPC IDs, names, and functions
```

--------------------------------

### GET /get_mob_list

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/MapEditorSystemPrompt.txt

Query available mobs from the loaded game data. Must be called before using add_mob.

```APIDOC
## GET /get_mob_list

### Description
Query available mobs from the loaded game data. This must be called before using add_mob.

### Method
GET

### Endpoint
/get_mob_list

### Parameters
#### Query Parameters
- **search** (string) - Optional - Search term to filter by name (e.g., "snail", "mushroom", "slime")
- **limit** (integer) - Optional - Maximum results to return (default 50)

### Response
- Returns a list of mob IDs and names
```

--------------------------------

### UI System Implementation

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/plan.md

Details the implementation of various UI components, including inventory, equipment, skills, and quest logs, along with foundational UI classes and management systems.

```APIDOC
## UI System Implementation

### UI Components

- **Inventory Display** (`InventoryUI.cs`)
  - Tab system (Equip/Use/Setup/Etc/Cash).
  - Item slot grid with scrolling.
  - Meso display and item quantity indicators.
  - Loaded from `UI.wz/UIWindow.img/Item`.

- **Equipment Window** (`EquipUI.cs`)
  - Equipment slot grid.
  - Slot positions for all equipment types.
  - Character preview area.
  - Tab system for Normal/Cash/Pet equipment.
  - Loaded from `UI.wz/UIWindow.img/Equip`.

- **Skill Window** (`SkillUI.cs`)
  - View-only skill display.
  - Job advancement tabs (Beginner through 4th job).
  - Skill icon grid with level indicators.
  - Skill point display per tab.
  - Selected skill description area.
  - Loaded from `UI.wz/UIWindow.img/Skill`.

- **Quest Log Display** (`QuestUI.cs`)
  - Quest state tabs (In Progress/Completed/Available).
  - Quest list with selection and scrolling.
  - Progress bar for in-progress quests.
  - Quest detail panel with description.
  - Quest state icons from `UI.wz/UIWindow.img/QuestIcon`.

### Base Classes & Managers

- **UIWindowBase**
  - Draggable windows with title bar.
  - Close button support.
  - Visibility toggle with cooldown.
  - Mouse event handling.

- **UIWindowManager**
  - Manages window focus and z-order.
  - Routes mouse events to the topmost window.
  - Handles keyboard shortcuts: I=Inventory, E=Equipment, S=Skills, Q=Quest.

- **UIWindowLoader**
  - Loads window backgrounds from `UI.wz/UIWindow.img`.
  - Creates placeholder windows when WZ assets are unavailable.
  - Initializes all UI windows on map load.
```

--------------------------------

### BuildWzFileList

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/wz-format/WzFileManager.md

Scans the MapleStory directory and builds internal lookup dictionaries for WZ files based on client architecture.

```APIDOC
## BuildWzFileList

### Description
Scans the MapleStory directory to build internal lookup dictionaries for WZ files. It handles 64-bit clients by reading .ini files for file counts and 32-bit clients by scanning for .wz files.

### Method
void

### Endpoint
BuildWzFileList()
```

--------------------------------

### Define Checksum Validation in Manifest

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/hacreator-harepacker-architecture/IMG_FILESYSTEM_MIGRATION_PLAN.md

Example structure for storing file metadata and SHA256 hashes for integrity verification.

```json
// Example: Checksum validation in manifest.json
{
  "files": {
    "Map/Map0/100000000.img": {
      "size": 45230,
      "sha256": "a1b2c3d4...",
      "lastModified": "2025-01-15T10:30:00Z"
    }
  }
}
```

--------------------------------

### Visualize Current Data Flow

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/hacreator-harepacker-architecture/IMG_FILESYSTEM_MIGRATION_PLAN.md

Represents the existing data loading pipeline from MapleStory installations to the HaCreator UI.

```text
MapleStory Installation → WZ Files → WzFileManager → WzInformationManager → HaCreator UI
     (Encrypted)           (.wz)      (Parse/Cache)    (Extract Data)        (Display)
```

--------------------------------

### tile_platform: Create Simple Flat Platforms

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/TileAgentPrompt.txt

Creates a simple flat tiled platform. Good for basic horizontal surfaces.

```APIDOC
## tile_platform

### Description
Creates a simple flat tiled platform. Good for basic horizontal surfaces.

### Parameters
- **tileset** (string) - Required - Tileset name
- **start_x** (integer) - Required - Left edge X coordinate
- **end_x** (integer) OR **width** (integer) - Required - Right edge X, or width in pixels
- **y** (integer) - Required - Platform Y coordinate
- **layer** (integer) - Optional - Layer 0-7 (default 0)

### Request Example
```
tile_platform tileset="grassySoil" start_x=-300 width=600 y=350
```
```

--------------------------------

### Create VersionManager Class

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/hacreator-harepacker-architecture/IMG_FILESYSTEM_MIGRATION_PLAN.md

Handles scanning for game versions, loading and creating version manifest files, and validating the integrity of version data.

```csharp
public class VersionManager
{
    public List<VersionInfo> ScanVersions(string rootDir);
    public VersionInfo LoadVersionManifest(string versionPath);
    public void CreateVersionManifest(string versionPath, VersionInfo info);
    public bool ValidateVersionIntegrity(string versionPath);
}
```

--------------------------------

### Add Sloped Platform

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/PlatformAgentPrompt.txt

Creates a platform with a gradual incline or decline by specifying different Y-coordinates for the start and end points.

```javascript
add_platform points=[{x: 0, y: 300}, {x: 200, y: 250}]
```

--------------------------------

### Add Map Elements Programmatically

Source: https://context7.com/lastbattle/harepacker-resurrected/llms.txt

Demonstrates how to instantiate and add mobs, NPCs, portals, and footholds to a map board.

```csharp
// Add a mob to the map
int mobId = 100100; // Snail
int x = 100, y = 300;
int rx0 = 0, rx1 = 200; // Patrol range
Layer layer = mapBoard.Layers[0];

MobInfo mobInfo = MobInfo.Get(mobId.ToString());
MobInstance mob = (MobInstance)mobInfo.CreateInstance(
    layer, mapBoard, x, y, rx0, rx1,
    null,  // name
    null,  // tags
    false, // flip
    false  // hide
);
mapBoard.BoardItems.Mobs.Add(mob);

// Add an NPC
string npcId = "9010000"; // Maple Admin
NpcInfo npcInfo = NpcInfo.Get(npcId);
NpcInstance npc = (NpcInstance)npcInfo.CreateInstance(
    layer, mapBoard, x, y, rx0, rx1,
    null, null, false, false
);
mapBoard.BoardItems.NPCs.Add(npc);

// Add a portal
PortalType portalType = PortalType.Visible;
int targetMap = 100000000;
string targetPortal = "out00";
string portalName = "portal1";

PortalInstance portal = new PortalInstance(
    mapBoard, portalType, portalName, targetMap, targetPortal,
    null, // script
    x, y, null, null
);
mapBoard.BoardItems.Portals.Add(portal);

// Add a platform (foothold)
var points = new List<Microsoft.Xna.Framework.Point> {
    new Microsoft.Xna.Framework.Point(-270, 300),
    new Microsoft.Xna.Framework.Point(270, 300)
};
FootholdLine fh = new FootholdLine(mapBoard, points[0], points[1]);
mapBoard.BoardItems.FootholdLines.Add(fh);
```

--------------------------------

### Detect WZ File Formats

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/wz-format/wz-format-history.md

Use these methods to identify the specific WZ file structure of a MapleStory installation directory.

```csharp
// Detect 64-bit .exe format (Data/ directory with 40+ WZ files)
bool is64Bit = WzFileManager.Detect64BitDirectoryWzFileFormat(path);

// Detect pre-Big Bang format (List.wz exists or single Data.wz)
bool isPreBB = WzFileManager.DetectIsPreBBDataWZFileFormat(path);

// Check for Big Bang update via UIWindow2.img marker
bool isBigBang = WzFileManager.IsBigBangUpdate(uiWindow2Image);

// Check for Big Bang 2 / Chaos update
bool isBigBang2 = WzFileManager.IsBigBang2Update(uiWindow2Image);
```

--------------------------------

### Version Detection from MapleStory.exe

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/wz-format/wz-format-history.md

Explains how to extract version and region information from MapleStory executables using `WzFile.GetMapleStoryVerFromExe()`.

```APIDOC
## Version Detection from MapleStory.exe

The `WzFile.GetMapleStoryVerFromExe()` method extracts version information directly from the MapleStory executable using Windows `FileVersionInfo`.

### Supported Executables

| Executable | Description |
|------------|-------------|
| `MapleStoryT.exe` | Test server client |
| `MapleStoryA.exe` | Admin client |
| `MapleStory.exe` | Standard client |

### Version Info Structure

The executable's file version follows the format: `Major.Minor.Build.Revision`

| Component | Meaning | Example |
|-----------|---------|---------|
| `FileMajorPart` | Region/Locale code | 8 (GMS) |
| `FileMinorPart` | MapleStory patch version | 83 |
| `FileBuildPart` | Minor patch version | 1 |

### Region/Locale Codes

| Code | Region | Enum Value |
|------|--------|------------|
| 1 | Korea (KMS) | `MapleStoryKorea` |
| 2 | Korea Tespia | `MapleStoryKoreaTespia` |
| 5 | Tespia | `MapleStoryTespia` |
| 7 | South East Asia (MSEA) | `MapleStorySEA` |
| 8 | Global (GMS) | `MapleStoryGlobal` |
| 9 | Europe (EMS) | `MapleStoryEurope` |

### Usage Example

```csharp
// In WzFile.cs - automatically called during WZ parsing
short version = GetMapleStoryVerFromExe(wzFilePath, out MapleStoryLocalisation locale);

// Example: GMS v83
// FileVersion: 8.83.1.0
// locale = MapleStoryGlobal (8)
// version = 83
// minorPatch = 1
```

### Detection Flow

```
1. Start from WZ file directory
2. Search up to 4 parent directories for:
   - MapleStoryT.exe (prioritized)
   - MapleStoryA.exe
   - MapleStory.exe
3. Read FileVersionInfo from found executable
4. Skip if version is 1.0.0.x or 0.0.0.x (invalid/old format)
5. Extract locale from Major, version from Minor, patch from Build
```

**Note:** Older clients (pre-v30) may use version 1.0.0.1 which cannot be parsed this way.

**Location:** `MapleLib/WzLib/WzFile.cs` - `GetMapleStoryVerFromExe()` method
```

--------------------------------

### Publish WzImg-MCP-Server

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/README.md

Builds the MCP server project for Windows x64 deployment.

```bash
dotnet publish .\\WzImg-MCP-Server\\WzImgMCP\\WzImgMCP.csproj -c Release -r win-x64 --self-contained false
```

--------------------------------

### Initialize WzFileManager

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/wz-format/WzFileManager.md

Constructors for HaRepacker and HaCreator, with the latter supporting directory-based loading and format auto-detection.

```csharp
public WzFileManager()
```

```csharp
public WzFileManager(string directory, bool bIsStandAloneWzFile)
```

--------------------------------

### Add Animated Foreground Effect

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/BackgroundAgentPrompt.txt

Example of adding an animated foreground element. Uses front=true to render above all other layers and rx/ry for parallax.

```javascript
add_background bS="forest" no="2" type="ani" x=100 y=100 rx=90 ry=80 front=true
```

--------------------------------

### Create Complete Backdrop with Depth

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/HaCreator/MapEditor/AI/Prompts/MapEditorSystemPrompt.txt

Demonstrates layering multiple background elements to create depth, from fixed sky to near foliage. Each element requires a call to get_background_info and specific z-order for proper layering.

```text
add_background bS="forest" no="0" type="back" x=0 y=-100 rx=0 ry=0 cx=1024 z=0
add_background bS="forest" no="3" type="back" x=0 y=100 rx=25 ry=20 cx=800 z=10
add_background bS="forest" no="5" type="back" x=0 y=200 rx=50 ry=40 z=20
add_background bS="forest" no="7" type="back" x=0 y=250 rx=75 ry=60 z=30
```

--------------------------------

### 64-bit Format Detection

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/wz-format/WzFileManager.md

The `Detect64BitDirectoryWzFileFormat` method identifies 64-bit MapleStory installations by checking for a 'Data/' subdirectory and counting WZ files within it.

```APIDOC
## Format Detection

### 64-bit Detection

The `Detect64BitDirectoryWzFileFormat()` method identifies 64-bit MapleStory installations:

```csharp
public static bool Detect64BitDirectoryWzFileFormat(string baseDirectoryPath)
```

**Detection Logic:**
1. Check for `Data/` subdirectory
2. Count `.wz` files in Data/ directory
3. If > 40 WZ files found, it's 64-bit format

**Example 64-bit structure:**
```
MapleStory/
├── Data/
│   ├── Base/
│   │   ├── Base_000.wz
│   │   └── Base.ini
│   ├── Map/
│   │   ├── Map_000.wz
│   │   ├── Map_001.wz
│   │   └── _Canvas/
│   │       └── _Canvas_000.wz
```
```

--------------------------------

### Detect 64-bit WZ Format

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/wz-format/WzFileManager.md

Identifies 64-bit MapleStory installations by checking for the Data/ directory and counting the number of WZ files.

```csharp
public static bool Detect64BitDirectoryWzFileFormat(string baseDirectoryPath)
```

--------------------------------

### Load WZ Files

Source: https://github.com/lastbattle/harepacker-resurrected/blob/master/docs/wz-format/WzFileManager.md

Methods for loading and registering WZ files by name, version, or existing object instances.

```csharp
public WzFile LoadWzFile(string baseName, WzMapleVersion encVersion)
```

```csharp
public WzFile LoadWzFile(string baseName, WzFile wzf)
```