Add project plan and next steps documentation
Covers all 5 completed phases, project structure, Phase 6 verification strategy (bottom-up one-DLL-at-a-time testing), and known pitfalls. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
erik
parent
d1442e3747
commit
a415c6d6ac
1 changed files with 155 additions and 0 deletions
155
docs/PLAN.md
Normal file
155
docs/PLAN.md
Normal file
|
|
@ -0,0 +1,155 @@
|
||||||
|
# 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 (NEXT)
|
||||||
|
|
||||||
|
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
|
||||||
|
```
|
||||||
|
# C++ native projects (requires VS 2022 + Windows SDK)
|
||||||
|
cd Native
|
||||||
|
cmake -G "Visual Studio 17 2022" -A Win32 -B build
|
||||||
|
cmake --build build --config Release
|
||||||
|
|
||||||
|
# Managed solution
|
||||||
|
dotnet build Managed\Decal.sln -c Release
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: COM Registration Test
|
||||||
|
Register all C# COM servers and verify GUIDs match originals:
|
||||||
|
```
|
||||||
|
regasm /codebase Managed\bin\Release\Decal.Core.dll
|
||||||
|
regasm /codebase Managed\bin\Release\Decal.DecalDat.dll
|
||||||
|
... (all 10 COM server DLLs)
|
||||||
|
```
|
||||||
|
Then verify in registry: `HKCR\CLSID\{GUID}\InprocServer32` points to our DLLs.
|
||||||
|
|
||||||
|
### 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)
|
||||||
Loading…
Add table
Add a link
Reference in a new issue