Feature flags (#17)

* include `Syringe.h`

* init feature flags

* use double quotes for consistency

* friendship ended with `__declspec(selectany)`, `inline` is my new best friend
iow it didn't compile

* add docs

Author: Metadorius

README.md

@@ -78,3 +78,46 @@ syringe.exe game.exe --nowait
 
 These options can be combined to precisely control debugger lifetime and process synchronization behavior.
 
+# Feature Flags API
+
+SyringeEx uses a feature flags system to signal capability support to injected DLLs. This allows DLLs to verify that the running Syringe version supports the features they depend on, enabling version-aware behavior and graceful fallbacks for older installations.
+
+Current closed-source version of Syringe is considered a baseline (SyringeEx has the features reimplemented, namely: multithreaded hook support, skipping handshakes that refuse Ares (Yuri's Revenge engine extension DLL) to load on Steam version of Yuri's Revenge). Everything beyond that must be declared as a feature flag, and DLLs that want to utilize the new features must check for the presence of required features before using them, and either refuse to load or provide fallback behavior if the features are not supported.
+
+## How It Works
+
+When a DLL is loaded, Syringe resolves exported boolean symbols from the `SyringeFeatures` namespace and sets them to `true` if the feature is supported. DLLs default these flags to `false`, so older Syringe versions that don't know about the flags will leave them unchanged.
+
+## Using Feature Flags in Your DLL
+
+```cpp
+#include <Syringe.h>
+
+void YourDLL::SomeLoadCode()
+{
+    if (SyringeFeatures::ZFPreservation)
+    {
+        // This Syringe version preserves the Zero Flag, so we can safely hook conditional instructions
+    }
+    else
+    {
+        // Fallback for older versions or bail out if this feature is critical
+    }
+}
+```
+
+## Current Feature Flags
+
+- `ESPModification` - Adds an ability for DLLs to modify the stack pointer (ESP) across hooks to be able to exit on addresses with a different stack depth than the hook entry point
+- `ZFPreservation` - Indicates that the Zero Flag (ZF) is preserved after hook execution, allowing to hook on conditional instructions
+
+## Adding New API Features
+
+All API enhancements beyond original Syringe must be declared as feature flags.
+
+To add a new feature:
+
+1. Add a new boolean to [`SyringeFeatures` namespace](include/Syringe.h)
+2. Add the symbol name to `FeatureFlagNames[]` in [`SyringeDebugger.h`](SyringeDebugger.h)
+3. Document the feature and its behavior in this README
+

SyringeDebugger.cpp

@@ -11,6 +11,7 @@
 #include <fstream>
 #include <memory>
 #include <numeric>
+#include <set>
 
 #include <DbgHelp.h>
 
@@ -145,6 +146,73 @@ DWORD SyringeDebugger::HandleException(DEBUG_EVENT const& dbgEvent)
                 Log::WriteLine(__FUNCTION__ ": Finished retrieving proc addresses.");
                 bDLLsLoaded = true;
 
+                if (!v_FeatureFlags.empty())
+                {
+                    Log::WriteLine(__FUNCTION__ ": Starting feature flags resolution...");
+                    loop_FeatureFlags = v_FeatureFlags.begin();
+                    auto const& entry = *loop_FeatureFlags;
+                    PatchMem(&GetData()->LibName, entry.lib, MaxNameLength);
+                    PatchMem(&GetData()->ProcName, entry.symbol, MaxNameLength);
+
+                    context.Eip = reinterpret_cast<DWORD>(&GetData()->LoadLibraryFunc);
+                }
+                else
+                {
+                    bFeaturesSet = true;
+                    context.Eip = reinterpret_cast<DWORD>(pcEntryPoint);
+                }
+            }
+
+            // single step mode
+            context.EFlags |= 0x100;
+            context.ContextFlags = CONTEXT_CONTROL;
+            SetThreadContext(currentThread, &context);
+
+            threadInfo.lastBP = exceptAddr;
+
+            return DBG_CONTINUE;
+        }
+
+        // set feature flags in loaded DLLs
+        if (!bFeaturesSet)
+        {
+            // restore
+            PatchMem(exceptAddr, &Breakpoints[exceptAddr].original_opcode, 1);
+
+            // read the resolved address of the feature flag in the target process
+            void* flagAddr = nullptr;
+            ReadMem(&GetData()->ProcAddress, &flagAddr, 4);
+
+            if (flagAddr)
+            {
+                BYTE const trueVal = 1;
+                PatchMem(flagAddr, &trueVal, 1);
+                Log::WriteLine(
+                    __FUNCTION__ ": Set feature flag \"%s\" in \"%s\" at 0x%08X",
+                    loop_FeatureFlags->symbol, loop_FeatureFlags->lib, flagAddr);
+            }
+            else
+            {
+                Log::WriteLine(
+                    __FUNCTION__ ": Feature flag \"%s\" not exported by \"%s\", skipping.",
+                    loop_FeatureFlags->symbol, loop_FeatureFlags->lib);
+            }
+
+            ++loop_FeatureFlags;
+
+            if (loop_FeatureFlags != v_FeatureFlags.end())
+            {
+                auto const& entry = *loop_FeatureFlags;
+                PatchMem(&GetData()->LibName, entry.lib, MaxNameLength);
+                PatchMem(&GetData()->ProcName, entry.symbol, MaxNameLength);
+
+                context.Eip = reinterpret_cast<DWORD>(&GetData()->LoadLibraryFunc);
+            }
+            else
+            {
+                Log::WriteLine(__FUNCTION__ ": Finished setting feature flags.");
+                bFeaturesSet = true;
+
                 context.Eip = reinterpret_cast<DWORD>(pcEntryPoint);
             }
 
@@ -505,6 +573,7 @@ void SyringeDebugger::Run(std::string_view const arguments)
     // breakpoints for DLL loading and proc address retrieving
     bDLLsLoaded = false;
     bHooksCreated = false;
+    bFeaturesSet = false;
     loop_LoadLibrary = v_AllHooks.end();
 
     // set breakpoint
@@ -779,6 +848,29 @@ void SyringeDebugger::FindDLLs()
     }
 
     Log::WriteLine(__FUNCTION__ ": Done (%d hooks added).", v_AllHooks.size());
+
+    // build feature flag entries for each unique DLL
+    v_FeatureFlags.clear();
+    {
+        std::set<std::string> uniqueLibs;
+        for (auto const& hook : v_AllHooks)
+        {
+            if (uniqueLibs.insert(hook->lib).second)
+            {
+                for (auto const& flagName : FeatureFlagNames)
+                {
+                    FeatureFlagEntry entry{};
+                    strncpy_s(entry.lib, hook->lib, MaxNameLength - 1);
+                    flagName.copy(entry.symbol, MaxNameLength - 1);
+                    v_FeatureFlags.push_back(entry);
+                }
+            }
+        }
+    }
+
+    Log::WriteLine(
+        __FUNCTION__ ": %d feature flag entries prepared.",
+        v_FeatureFlags.size());
     Log::WriteLine();
 }
 

SyringeDebugger.h

@@ -143,6 +143,22 @@ class SyringeDebugger
     std::vector<Hook*> v_AllHooks;
     std::vector<Hook*>::iterator loop_LoadLibrary;
 
+    // feature flags
+    static constexpr std::string_view FeatureFlagNames[] = {
+        "ESPModification",
+        "ZFPreservation",
+    };
+
+    struct FeatureFlagEntry
+    {
+        char lib[MaxNameLength];
+        char symbol[MaxNameLength];
+    };
+
+    std::vector<FeatureFlagEntry> v_FeatureFlags;
+    std::vector<FeatureFlagEntry>::iterator loop_FeatureFlags;
+    bool bFeaturesSet{ false };
+
     // syringe
     std::string exe;
     std::vector<std::string> dlls{};