Building clockwork¶
Prerequisites¶
- Visual Studio 2022 with the Desktop development with C++ workload.
- CMake 3.21 or newer (the one bundled with VS is fine).
- Git, with submodule support.
Clone¶
git clone --recurse-submodules https://github.com/towbes/clockwork.git
cd clockwork
If you already cloned without --recurse-submodules:
git submodule update --init --recursive
Fresh worktrees
A git worktree created from an existing clone does not get the
submodules initialised, and the build will fail on missing third-party
headers. Run git submodule update --init --recursive in the new worktree
before building.
Build¶
powershell -ExecutionPolicy Bypass -File scripts\build.ps1 -Config Release
Output lands in build\x64-release\bin\.
-Config Debug is accepted but not recommended — live clients run the Release
build, so a clean Debug link does not prove the DLL works.
If build.ps1 can't find your toolchain (it locates VS via vswhere), open a
x64 Native Tools Command Prompt for VS 2022 and build through CMake presets
directly:
cmake --preset x64-release
cmake --build --preset x64-release
A locked DLL is a successful compile¶
LINK : fatal error LNK1168: cannot open bin\eq2core.dll for writing
means the compile passed and a running client currently has the DLL mapped. Unload from that client (or close it) and link again.
Project layout¶
| Path | What |
|---|---|
src/loader/ |
eq2loader.exe — process discovery and injection. |
src/core/ |
eq2core.dll — everything that runs inside the client. |
src/core/lua/ |
The Lua host and every eq2.* / mq.TLO.* binding. |
src/core/overlay/ |
DX11 present hook, ImGui, console, inspector. |
src/core/peer/ |
Peer mesh networking and broadcast commands. |
src/core/ui/ |
Native UI automation (broker, loot, upsell). |
src/core/eq2lib/ |
Game-struct abstractions (group, raid, actor fields). |
src/common/ |
Signature scanning, logging, settings. |
src/login/ |
Login database and crypto, shared between loader and core. |
lua/ |
Bundled scripts and helper libraries shipped with clockwork. |
tests/ |
C++ and Lua test suites. |
re/ |
Reverse-engineering workspace (Frida scripts, sigscan, captures). |
docs/ |
In-repo design and reverse-engineering notes (not this site). |
Contributing¶
clockwork is GPL-3.0. Ground rules that PRs are held to:
- Signatures, never absolute addresses. Resolve at runtime.
- Respect the game thread. Anything touching game state runs from the render-hook callback or the work queue.
- Fail soft. A signature that won't resolve disables its feature and logs. It never crashes the client.
- Stay hot-unloadable. Every hook and allocation has a teardown path.
- Minimal
DllMain. No real work under the loader lock.