openDecal/docs/PLAN.md

# Plan: Open-Source Decal Rebuild

## Context
Decal is a plugin framework for Asheron's Call. The game's official servers shut down, but the community runs it via ACEmulator. The modern Decal installer (v2.9.8.3) is closed-source. We have old C++ source code (partial match) and have decompiled all .NET assemblies. Goal: produce a fully open-source Decal that works with the original AC client, buildable from a single Visual Studio 2022 solution.

## Architecture Decision
- **Rewrite native C++ DLLs as C# COM servers** — same GUIDs, same interfaces, different implementation language
- **Keep only 2 components in C++:** `Inject.DLL` (D3D hooking, ~500-800 lines) and `LauncherHook.DLL` (~200 lines)
- **Use Vortice.DirectX** for D3D9 rendering in C# (DecalRender, D3DService)
- **Preserve plugin compatibility** by matching all COM CLSIDs/IIDs exactly

## Project Structure
```
reconstructed/
├── Managed/                          # 25 C# projects
│   ├── Decal.sln                     # Solution file (25 projects, 0 errors)
│   ├── Directory.Build.props         # Shared: net472, x86, LangVersion 12
│   ├── Decal.Interop.*/              # 11 COM interface assemblies (decompiled)
│   ├── Decal.Adapter/                # Plugin adapter (decompiled)
│   ├── Decal.FileService/            # File service (decompiled)
│   ├── DecalUtil/                    # Utility exe (decompiled)
│   ├── Decal.DecalDat/               # DAT file I/O (COM server)
│   ├── Decal.DHS/                    # Hotkey system (COM server)
│   ├── Decal.SpellFilter/            # Spell data (COM server)
│   ├── Decal.DecalInput/             # Input handling (COM server)
│   ├── Decal.DecalNet/               # Network packets (COM server)
│   ├── Decal.DecalFilters/           # Game data/world objects (COM server)
│   ├── Decal.Core/                   # Plugin manager/lifecycle (COM server)
│   ├── Decal.DecalControls/          # UI widgets (COM server)
│   ├── Decal.DecalRender/            # HUD rendering (COM server)
│   ├── Decal.D3DService/             # 3D markers (COM server)
│   └── Decal.DenAgent/               # System tray app (WinForms)
├── Native/
│   ├── InjectModern/                 # Inject.DLL - D3D9 vtable hooking (C++)
│   ├── LauncherHookModern/           # LauncherHook.DLL - process injection (C++)
│   ├── CMakeLists.txt                # Top-level CMake for native builds
│   ├── Inject/                       # Old C++ source (reference only)
│   ├── LobbyHook/                    # Old C++ source (reference only)
│   ├── Decal/                        # Old C++ source (reference only)
│   └── ...                           # Other old native source (reference)
├── Installer/
│   ├── Package.wxs                   # WiX v5 MSI package definition
│   └── Decal.Installer.wixproj      # WiX project file
├── build.cmd                         # Top-level build script
└── docs/
    └── PLAN.md                       # This file
```

---

## Status: Phases 1-5 Complete (Skeleton)

All 5 phases are structurally complete. The solution compiles with 0 errors.
Most COM server methods are **stubs** — they implement the correct interfaces
and preserve GUIDs, but many methods are no-ops that need real logic.

---

## Phase 1: Build Existing .NET Layer ✅ COMPLETE
- 14 decompiled .NET projects building from `Decal.sln`
- `Directory.Build.props` centralizes build settings
- All Interop projects use ProjectReference

## Phase 2: Rewrite Native DLLs as C# COM Servers ✅ COMPLETE (stubs)

| # | Component | CLSID | Status |
|---|-----------|-------|--------|
| 1 | DecalDat | IDatService, IDatReader | Stub |
| 2 | DHS | IHotkeySystem, IHotkey | Stub |
| 3 | SpellFilter | ISpells, ISpell | Stub |
| 4 | DecalInput | IInputService, IKeyboard, IMouse | Stub |
| 5 | DecalNet | INetService, IMessage2, INetworkFilter2 | Stub |
| 6 | DecalFilters | IWorld, IWorldObject, ICharacterStats | Stub |
| 7 | Decal.Core | IDecalCore, IPluginSite2, IACHooks, IDecalEnum | Stub |
| 8 | DecalControls | 16 control types | Stub |
| 9 | DecalRender | IRenderService, IHUDView, IHUDBackground | Stub |
| 10 | D3DService | ID3DService, ID3DObj | Stub |

All preserve original CLSIDs/GUIDs for plugin compatibility.

## Phase 3: C++ Shims ✅ COMPLETE
- `Native/InjectModern/` — Inject.DLL (~530 lines) — D3D9 vtable hooking, lifecycle
- `Native/LauncherHookModern/` — LauncherHook.DLL (~330 lines) — CreateProcess IAT hook
- CMake build: `cmake -G "Visual Studio 17 2022" -A Win32`

## Phase 4: DenAgent ✅ COMPLETE
- `Managed/Decal.DenAgent/` — System tray, plugin management, options dialog

## Phase 5: Build System & Installer ✅ COMPLETE
- `Installer/Package.wxs` — WiX v5 MSI
- `build.cmd` — Top-level build script

---

## Phase 6: Verification & Implementation (IN PROGRESS)

Goal: **Pixel-perfect drop-in replacement** for the closed-source Decal v2.9.8.3.

Strategy: **Bottom-up, one DLL at a time.** Replace one original DLL with our C#
version while keeping all other original DLLs in place. Test. Move to the next.

### Step 1: Build on Windows ✅ COMPLETE
```
dotnet build Managed\Decal.sln -c Release   # 25 projects, 0 errors
```

### Step 2: COM Registration Test ✅ COMPLETE
Automated script: `tools/Test-ComRegistration.ps1 -Build`
- 10/10 DLLs register successfully with regasm /codebase
- 50/50 CLSIDs verified in registry (WOW6432Node for 32-bit on 64-bit Windows)
- 0 GUID mismatches vs original Decal .rgs files
- 35 CLSIDs match original .rgs files exactly
- 15 additional CLSIDs from decompiled interops (no .rgs source available)
- 23 original CLSIDs not in scope (Inject module C++, internal action classes)

### Step 2b: DecalDat Functional Test ✅ COMPLETE
`Managed/Decal.DecalDat.Tests/` — 13/13 tests pass against real AC DAT files:
- Opens portal.dat (884 MB, sector size 1024) and cell.dat (332 MB, sector size 256)
- Reads 6 known file IDs from portal.dat (SpellTable, ComponentTable, etc.)
- DatStream: Read, Restart, ReadBinary with Tell tracking

### Step 3: Smoke Test — DenAgent
Run `Decal.DenAgent.exe` and verify:
- Tray icon appears
- Configure dialog opens
- Plugin list populates from registry

### Step 4: Integration Test (one DLL at a time)
Install original Decal v2.9.8.3, then swap one DLL at a time:
1. Replace `DecalDat.DLL` → test DAT file reading
2. Replace `DHS.dll` → test hotkeys
3. Replace `SpellFilter.dll` → test spell data
4. Continue through all 10...
Each swap that fails tells us exactly which stubs need real implementations.

### Step 5: Plugin Compatibility Test
Load community Decal plugins and verify they work:
- VTank
- Mag-Tools
- Other popular plugins

---

## Known Pitfalls
- `record` types need IsExternalInit, unavailable in net472 → use class instead
- `CollectionsMarshal.AsSpan` unavailable in net472
- LongValueKey enum: correct names are `keyStackCount`, `keyContainer`
- tagPOINT defined in Interop.Inject, needed by Interop.Render → add ProjectReference
- ICommandEvents delegates ambiguous between Interop.Controls and Interop.Inject → use `using` aliases

## Build Requirements
- .NET SDK 8.0+ (targets net472 via NuGet reference assemblies)
- Visual Studio 2022 with C++ Desktop workload (for native DLLs)
- Windows SDK (for d3d9.h, Win32 APIs)
- WiX Toolset v5 (optional, for MSI installer)