NativeAddonManager.h

Go to the documentation of this file.

#pragma once
 
#if EDITOR
 
#include "ProjectSelect/TemplateData.h"
#include "Plugins/PolyphaseEngineAPI.h"
#include "Plugins/PolyphasePluginAPI.h"
 
#include <string>
#include <unordered_map>
#include <unordered_set>
#include <vector>
#include <thread>
#include <atomic>
#include <mutex>
#include <memory>
 
struct NativeAddonCreateInfo
{
    std::string mName;               // Display name (e.g., "My Addon")
    std::string mId;                 // Internal ID (e.g., "my-addon", auto-generated from name if empty)
    std::string mAuthor;
    std::string mDescription;
    std::string mVersion = "1.0.0";
    NativeAddonTarget mTarget = NativeAddonTarget::EngineAndEditor;
    std::string mBinaryName;         // Auto-generated from ID if empty
};
 
struct NativeAddonPackageOptions
{
    std::string mAddonId;
    bool mIncludeSource = true;
    bool mIncludeAssets = true;
    bool mIncludeScripts = true;
    bool mIncludeThumbnail = true;
    std::string mOutputPath;         // Full path to output zip file
};
 
struct NativeAddonState
{
    std::string mAddonId;
    std::string mSourcePath;      // Path to addon source (local Packages/ or cache)
    std::string mLoadedPath;      // Path to loaded DLL/SO
    void* mModuleHandle = nullptr;
    // Cached module image range, computed once after a successful module load.
    // Used by FindAddonIdForFactory to reverse-map a Factory* (which lives at a
    // global static address inside the addon's image) back to its owning addon
    // so the editor can plant addon-registered nodes under "Addons / <addonId>".
    // mModuleEnd is only meaningful on Windows (image-extent known from
    // GetModuleInformation); on Linux only mModuleBase is populated, and the
    // forward lookup uses dladdr().dli_fbase == mModuleBase.
    uintptr_t mModuleBase = 0;
    uintptr_t mModuleEnd  = 0;
    std::string mFingerprint;     // Hash for rebuild detection
    // Shadow-copy directory created at load time so the engine never holds an
    // OS-level LoadLibrary lock on the build-output tree (Intermediate/Plugins).
    // Cleared on successful UnloadNativeAddon; if delete fails (mspdbsrv lag),
    // the path is pushed to NativeAddonManager::mPendingShadowDeletes and
    // retried later / swept on next editor launch.
    std::string mShadowDir;
 
    // Build state
    bool mBuildInProgress = false;
    bool mBuildSucceeded = false;
    std::string mBuildLog;
    std::string mBuildError;
    // "How to fix" text paired with mBuildError. Filled by the build preflight
    // or ClassifyBuildFailure and rendered by the native addon problem modal.
    std::string mFixHint;
    // Optional download page the fix points at (Vulkan SDK, Visual Studio).
    std::string mFixUrl;
    // Dependency addon ids declared in package.json that have no
    // <project>/Packages/<id>/package.json on disk. Non-empty blocks build and
    // load of this addon until the user installs them.
    std::vector<std::string> mMissingDependencies;
 
    // Plugin descriptor (after load)
    PolyphasePluginDesc mDesc = {};
    bool mDescValid = false;
 
    // Native metadata from package.json
    NativeModuleMetadata mNativeMetadata;
 
    // Shared metadata from package.json (name/version/dependencies/onInstall/etc.)
    ContentMetadata mContentMetadata;
 
    // Runtime resolve/load status
    NativeAddonResolveMode mActiveResolveMode = NativeAddonResolveMode::Source;
    bool mLoadedFromBinary = false;
    std::string mBinaryStatus;
 
    // UUIDs of assets that PurgeAssetsFromModule unloaded during the most
    // recent UnloadNativeAddon. LoadNativeAddon drains this on its next
    // successful load, calling LoadAsset on each so an addon-typed asset
    // that was loaded before reload comes back loaded after — without this,
    // the post-reload stub has mAsset=null and SaveAsset becomes a no-op.
    std::vector<uint64_t> mPurgedAssetUuids;
 
    // True once the user has dismissed the build-failure modal entry for the
    // most recent failure. Reset to false whenever a fresh build attempt starts
    // so a re-failure surfaces again.
    bool mBuildFailureAcknowledged = false;
};
 
class NativeAddonManager
{
public:
    static void Create();
    static void Destroy();
    static NativeAddonManager* Get();
 
    // ===== Discovery =====
 
    void DiscoverNativeAddons();
 
    std::vector<std::string> GetDiscoveredAddonIds() const;
 
    // ===== Build Operations =====
 
    bool BuildNativeAddon(const std::string& addonId, std::string& outError);
 
    std::string ComputeFingerprint(const std::string& addonId);
 
    bool NeedsBuild(const std::string& addonId);
 
private:
    void WriteAddonBuildMeta(const std::string& outputPath,
                             const std::string& fingerprint);
 
    NativeAddonResolveMode ResolveModeForAddon(const std::string& addonId) const;
 
    bool ResolveBinaryModulePath(const std::string& addonId, std::string& outModulePath, std::string& outStatus, std::string& outError);
 
    bool IsBinaryDescriptorCompatible(const NativeBinaryDescriptor& descriptor, const NativeAddonState& state) const;
 
    bool MetaIndicatesRebuildNeeded(const std::string& outputPath) const;
public:
 
    // ===== Load/Unload Operations =====
 
    bool LoadNativeAddon(const std::string& addonId, std::string& outError);
 
    bool UnloadNativeAddon(const std::string& addonId);
 
    bool ReloadNativeAddon(const std::string& addonId, std::string& outError);
 
    void ReloadAllNativeAddons();
 
    void UnloadAllNativeAddons();
 
    bool RecoverFromStuckAddons(const char* reason);
 
    // Force Rebuild was removed in favour of the per-addon Reload button +
    // the per-project chokepoint. To force a fresh compile of all addons,
    // call ReloadNativeAddonsWithProjectRestart({}, /*forceRebuild*/true, ...).
 
    // ===== Async build state (drives the progress modal) =====
 
    void TickAsyncBuilds();
 
    bool IsBuildingAsync() const;
 
    int  GetAsyncBuildTotal() const;
 
    int  GetAsyncBuildIndex() const;
 
    std::string GetAsyncBuildAddonId() const;
 
    std::string GetAsyncBuildOutput() const;
 
    // ===== Build-blocked state (locked intermediate files) =====
    //
    // Before a build runs, BuildNativeAddon / StartNextQueuedBuild sweep the
    // addon's intermediate fingerprint dir and try to delete every file. If
    // any file is locked (most commonly the .pdb held open by mspdbsrv.exe
    // across DLL unload, producing LNK1201 at link time), the sweep records
    // the offending paths and the build is paused. The editor surfaces a
    // modal listing the locked files with Retry / Cancel — Retry re-sweeps
    // and resumes if clean, Cancel abandons the operation.
    struct BuildBlocked
    {
        bool                     mActive = false;
        std::string              mAddonId;
        std::vector<std::string> mLockedFiles;
        // Absolute path to <project>/Intermediate/Plugins/<addonId>/ — the
        // simplest manual fix is to delete this entire directory. The modal
        // surfaces this as a copy-paste shell command.
        std::string              mIntermediateDir;
        // Number of times the user has clicked Retry on this block. Reset
        // when a fresh block is raised by a different addon or after the
        // build succeeds. The modal uses this to escalate the recovery UX
        // (Tier 1 → Tier 2 → Tier 3) once auto-kill-and-retry plainly isn't
        // unsticking the lock.
        int                      mRetryCount = 0;
    };
    bool                IsBuildBlocked() const   { return mBlocked.mActive; }
    const BuildBlocked& GetBuildBlocked() const  { return mBlocked; }
    void RetryBlockedBuild();
    void CancelBlockedBuild();
 
    // ===== Build-failure surface =====
    //
    // Aggregates per-addon compile/link failures across both the sync
    // BuildNativeAddon path and the async TickAsyncBuilds path. Drives the
    // build-failure modal so users don't have to scan the log to know which
    // addon broke. An entry stays "active" while:
    //   state.mBuildSucceeded == false &&
    //   !state.mBuildError.empty() &&
    //   !state.mBuildInProgress &&
    //   !state.mBuildFailureAcknowledged
    // and is implicitly cleared the next time the addon starts a build.
    struct BuildFailureEntry
    {
        std::string mAddonId;
        std::string mError;    // High-level message (exit code, "Build failed" etc.)
        std::string mLog;      // Captured stdout/stderr from the compiler/linker
        std::string mFixHint;  // How to fix, from the preflight or ClassifyBuildFailure
        std::string mFixUrl;   // Download page for the fix; empty when none applies
        std::vector<std::string> mMissingDependencies; // Deps installable from the modal
    };
    std::vector<BuildFailureEntry> GetActiveBuildFailures() const;
    bool                           HasUnacknowledgedBuildFailures() const;
    void                           DismissBuildFailure(const std::string& addonId);
    void                           DismissAllBuildFailures();
    void                           RetryFailedBuild(const std::string& addonId);
 
    // ===== Build environment =====
 
    static std::string ResolveVulkanIncludeDir();
 
    struct BuildFailureHint
    {
        std::string mText;          // What to do; empty when the failure is not recognised
        std::string mUrl;           // Download page, may be empty
        std::string mDependencyId;  // Addon id to install, may be empty
    };
    static BuildFailureHint ClassifyBuildFailure(const std::string& log);
 
    bool DiscoverAddonPackage(const std::string& addonId);
 
    std::vector<std::string> RefreshMissingDependencies();
 
    // ===== Project-restart reload chokepoint =====
    //
    // Native addon reload is unsafe when scenes are open — live nodes hold
    // vtable pointers into the addon's mapped DLL pages and any unload
    // invalidates them, plus Node factories get stripped from the global
    // registry so a later scene reopen falls back to Node3D and silently
    // corrupts the in-memory tree on save. The fix is to close the project
    // entirely (saving dirty scenes first per user choice), unload every
    // addon, rebuild, then reopen the project from disk so factories,
    // assets, and scenes all rehydrate cleanly.
    //
    // The flow is staged across frames because the rebuild runs async on a
    // worker thread. Phase advances:
    //   None
    //     -> AwaitingConfirm  (one-shot confirm modal)
    //     -> AwaitingDirty    (per-scene Save/Discard/Cancel — one popup at
    //                          a time, advancing through mDirtyScenes)
    //     -> Building         (project closed, builds in flight; advanced by
    //                          TickAsyncBuilds when the queue drains)
    //     -> Reopening        (synchronous OpenProject + scene restore; only
    //                          held briefly for telemetry, then cleared)
    //     -> None
    enum class ProjectRestartPhase
    {
        None,
        AwaitingConfirm,
        AwaitingDirty,
        Building,
        Reopening,
    };
 
    struct ProjectRestart
    {
        ProjectRestartPhase mPhase = ProjectRestartPhase::None;
 
        // Addons being rebuilt. Empty = all installed enabled native addons
        // (unless this is a removal, where nothing is rebuilt).
        std::vector<std::string> mTargetAddons;
        // forceRebuild=true wipes each target's fingerprint dir before
        // building so NeedsBuild() returns true even for an unchanged source.
        bool                     mForceRebuild = false;
        std::string              mReason;       // user-facing modal copy
        // Removal flow: addons to unload + uninstall inside the close window,
        // dependents first. No builds are queued; the project reopens with
        // the packages gone. mIsRemoval switches the modal copy.
        std::vector<std::string> mRemoveAddons;
        bool                     mIsRemoval = false;
 
        // Snapshot — captured at restart entry, restored after OpenProject.
        std::string              mProjectPath;
        std::vector<std::string> mOpenSceneNames;   // names of edit scenes to reopen
        std::string              mActiveSceneName;  // active edit scene at snapshot
 
        // Per-scene dirty queue. Walked one-at-a-time during AwaitingDirty.
        std::vector<std::string> mDirtyScenes;
        int32_t                  mDirtyCursor = 0;
    };
 
    bool                  IsProjectRestartActive() const { return mRestart.mPhase != ProjectRestartPhase::None; }
    const ProjectRestart& GetProjectRestart() const      { return mRestart; }
 
    void ReloadNativeAddonsWithProjectRestart(const std::vector<std::string>& addonIds,
                                              bool forceRebuild,
                                              const char* reason);
 
    bool RemoveNativeAddonsWithProjectRestart(const std::vector<std::string>& removeIds,
                                              const char* reason);
 
    void ForgetAddon(const std::string& addonId);
 
    // Modal callbacks. Called from the EditorImgui modal renderers when the
    // user clicks the corresponding button. Public because the modal lives
    // outside this class.
    void ProjectRestartConfirm();        // [Continue] on confirm modal
    void ProjectRestartCancel();         // [Cancel] on confirm modal — abort whole flow
    void ProjectRestartDirtySave();      // [Save] for the current dirty scene
    void ProjectRestartDirtyDiscard();   // [Discard] for the current dirty scene
    void ProjectRestartDirtyCancel();    // [Cancel] in dirty prompt — abort whole flow
 
    void TickAllPlugins(float deltaTime);
 
    void TickEditorAllPlugins(float deltaTime);
 
    void CallOnEditorPreInit();
 
    void CallOnEditorReady();
 
    // ===== State Queries =====
 
    const NativeAddonState* GetState(const std::string& addonId) const;
 
    bool IsLoaded(const std::string& addonId) const;
 
    std::string GetAddonSourcePath(const std::string& addonId) const;
 
    std::string FindAddonRootForBuildTarget(const std::string& buildTargetId) const;
 
    std::vector<NativeAddonState> GetEngineAddons() const;
 
    PolyphaseEngineAPI* GetEngineAPI() { return &mEngineAPI; }
 
    const char* FindAddonIdForFactory(const void* factoryPtr) const;
 
    // ===== Creation and Packaging =====
 
    bool CreateNativeAddon(const NativeAddonCreateInfo& info, std::string& outError, std::string* outPath = nullptr);
 
    bool CreateNativeAddonAtPath(const NativeAddonCreateInfo& info, const std::string& targetDir,
                                  std::string& outError, std::string* outPath = nullptr);
 
    bool PackageNativeAddon(const NativeAddonPackageOptions& options, std::string& outError);
 
    bool GenerateIDEConfig(const std::string& addonPath);
 
    std::vector<std::string> GetLocalPackageIds() const;
 
    static bool GenerateAddonIncludesManifest();
 
    static bool LoadAddonIncludesManifest(std::vector<std::string>& outIncludePaths,
                                           std::vector<std::string>& outDefines);
 
private:
    static NativeAddonManager* sInstance;
    NativeAddonManager();
    ~NativeAddonManager();
 
    // Discovery helpers
    void ScanLocalPackages();
    void ScanInstalledAddons();
    bool ParsePackageJson(const std::string& path, NativeModuleMetadata& outMetadata, ContentMetadata* outContent = nullptr);
 
    std::vector<std::string> GetLoadOrder() const;
 
    // Cached topo order produced by the most recent ResolveAll() during discovery.
    std::vector<std::string> mCachedLoadOrder;
 
    // Build helpers
    std::string GetIntermediateDir(const std::string& addonId);
    std::string GetOutputPath(const std::string& addonId, const std::string& fingerprint);
    bool RunBuildPreflight(const std::string& addonId, std::string& outError,
                           BuildFailureHint& outHint);
 
    bool GenerateBuildScript(const std::string& addonId, const std::string& outputDir,
                             const std::string& outputPath, std::string& outScriptPath);
    std::vector<std::string> GatherSourceFiles(const std::string& sourceDir);
 
    std::vector<std::string> TryClearAddonIntermediates(const std::string& addonId);
 
    // Engine API setup
    void InitializeEngineAPI();
 
    // Creation helpers
    std::string GenerateIdFromName(const std::string& name);
    bool WriteTemplateSourceFile(const std::string& path, const std::string& addonName,
                                  const std::string& binaryName);
    bool WritePackageJson(const std::string& path, const NativeAddonCreateInfo& info);
    bool WriteVSCodeConfig(const std::string& addonPath);
    bool WriteCMakeLists(const std::string& addonPath, const std::string& binaryName);
    bool WriteVSProject(const std::string& addonPath, const std::string& addonName,
                        const std::string& binaryName);
 
    std::unordered_map<std::string, NativeAddonState> mStates;
    PolyphaseEngineAPI mEngineAPI;
 
    // ----- Shadow-copy load cache -----
    //
    // The editor LoadLibrary's an addon DLL from a per-launch cache dir rather
    // than from Intermediate/Plugins/<addon>/<fp>/ directly. That keeps the
    // build-output tree free of OS file locks so the user can wipe / rebuild
    // intermediates while the editor is running. See NativeAddonManager.cpp
    // GetShadowCopyPath / SweepStaleShadowCopies for the layout.
    std::string              mShadowSessionId;       // PID-derived, set in ctor
    std::vector<std::string> mPendingShadowDeletes;  // shadow dirs to retry on Tick
    // Retry pacing for mPendingShadowDeletes: one rmdir sweep every few
    // seconds, a bounded number of times, then leave the leftovers to the
    // next launch's SweepStaleShadowCopies. Without this a .pdb pinned by a
    // debugger spams an rmdir per frame for the rest of the session.
    float                    mShadowDeleteRetryTimer = 0.0f;
    int                      mShadowDeleteRetryCount = 0;
    void                     RetryPendingShadowDeletes(float deltaTime);
 
    std::string GetShadowCopyDir(const std::string& addonId,
                                 const std::string& fingerprint);
    bool        StageShadowCopy(const std::string& sourceModulePath,
                                const std::string& shadowDir,
                                std::string& outShadowModulePath,
                                std::string& outError);
    void        TryDeleteShadowDir(const std::string& dir);
    void        SweepStaleShadowCopies();
 
    // ----- Async build queue -----
    //
    // One worker thread shells out to build.bat / build.sh per addon. The
    // main thread polls completion in TickAsyncBuilds(), runs the post-
    // build steps (write meta, MOD_Load, register types), and starts the
    // next queued item. This keeps the editor interactive while addons
    // compile, especially during multi-addon Force Rebuild.
    struct AsyncAddonBuild
    {
        std::string addonId;
        std::string scriptPath;
        std::string outputPath;
        std::string fingerprint;
 
        std::thread thread;
        std::atomic<bool> complete{false};
        std::atomic<int>  exitCode{0};
 
        mutable std::mutex outputMutex;
        std::string output;  // guarded by outputMutex
    };
 
    std::unique_ptr<AsyncAddonBuild> mActiveBuild;
    std::vector<std::string>         mBuildQueue;
    int                              mBuildQueueTotal = 0;
    int                              mBuildQueueIndex = 0;  // 1-based, advanced when a build starts
 
    // Set when a pre-build sweep finds locked files in the intermediate dir.
    BuildBlocked                     mBlocked;
 
    // Carries the retry counter from one RetryBlockedBuild into the next
    // BuildBlocked the (synchronous or async) build path raises. Reset to 0
    // after the value lands in mBlocked.mRetryCount. Without this, the
    // counter would reset every time we transiently clear mBlocked at the
    // top of RetryBlockedBuild — the modal would never see "this is the
    // user's third try" and never escalate to Tier 2.
    int                              mPendingRetryCount = 0;
 
    // Project-restart state machine. See ProjectRestartPhase for the flow.
    ProjectRestart                   mRestart;
 
    // One-shot per-addon override: addon IDs in this set get their next
    // LoadNativeAddon() invocation treated as resolveMode=source even when
    // package.json says "binary". Set when the user clicks Reload Native
    // Addons on a binary-mode addon — Reload means "recompile my local
    // source", not "redownload the published binary". Consumed (erased)
    // on first read so the override doesn't persist beyond a single load.
    std::unordered_set<std::string>  mForceSourceForNextLoad;
 
    // Internal helpers
    void StartNextQueuedBuild();
    void FinalizeAsyncBuild(AsyncAddonBuild& job, bool success);
    bool LoadNativeAddonAfterBuild(const std::string& addonId, std::string& outError);
 
    // Project-restart helpers
    bool ProjectRestartStage(const std::vector<std::string>& addonIds,
                             bool forceRebuild, const char* reason); // guards + snapshot + dirty queue → AwaitingConfirm
    void ProjectRestartBeginClose();   // dirty queue exhausted → close project + enqueue rebuilds
    void ProjectRestartOnBuildsDone(); // called from TickAsyncBuilds when in Building phase
    void ProjectRestartReset();        // clear state back to Phase::None
};
 
#endif // EDITOR