@gripforgeai/mcp 0.1.10 → 0.1.11

package/dist/joystick-kit/unreal.js

@@ -0,0 +1,231 @@
+export function unrealJoystickFiles(c) {
+    const p = 'Plugins/GripForgeJoystick/';
+    const src = p + 'Source/GripForgeJoystick/';
+    return [{ path: p + 'GripForgeJoystick.uplugin', content: JSON.stringify({ FileVersion: 3, Version: 1, VersionName: '1.0.0', FriendlyName: 'GripForge Joystick', Description: 'Independent touch/mouse movement and look sticks for an existing Pawn.', Category: 'Input', CreatedBy: 'GripForge', CanContainContent: false, Modules: [{ Name: 'GripForgeJoystick', Type: 'Runtime', LoadingPhase: 'Default' }] }, null, 2) },
+        { path: src + 'GripForgeJoystick.Build.cs', content: `using UnrealBuildTool;
+public class GripForgeJoystick : ModuleRules {
+    public GripForgeJoystick(ReadOnlyTargetRules Target) : base(Target) {
+        PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
+        PublicDependencyModuleNames.AddRange(new string[]{"Core","CoreUObject","Engine","UMG"});
+        PrivateDependencyModuleNames.AddRange(new string[]{"Slate","SlateCore","InputCore","ApplicationCore"});
+    }
+}
+` }, { path: src + 'Private/GripForgeJoystickModule.cpp', content: `#include "Modules/ModuleManager.h"
+IMPLEMENT_MODULE(FDefaultModuleImpl, GripForgeJoystick)
+` }, { path: src + 'Public/GripForgeJoystickWidget.h', content: `#pragma once
+#include "CoreMinimal.h"
+#include "Blueprint/UserWidget.h"
+#include "GripForgeJoystickWidget.generated.h"
+class SGripForgeStick;
+
+UCLASS()
+class GRIPFORGEJOYSTICK_API UGripForgeJoystickWidget : public UUserWidget {
+    GENERATED_BODY()
+public:
+    bool bDual = ${c.layout === 'dual' ? 'true' : 'false'};
+    float Radius = ${c.radius.toFixed(4)}f;
+    float Deadzone = ${c.deadzone.toFixed(4)}f;
+    FLinearColor Accent = FLinearColor(FColor::FromHex(TEXT("${c.accent.slice(1)}")));
+    FVector2D GetMove() const;
+    FVector2D GetLook() const;
+    void ResetSticks();
+    virtual void ReleaseSlateResources(bool bReleaseChildren) override;
+protected:
+    virtual TSharedRef<SWidget> RebuildWidget() override;
+private:
+    TSharedPtr<SGripForgeStick> MoveStick, LookStick;
+};
+` }, { path: src + 'Private/GripForgeJoystickWidget.cpp', content: `#include "GripForgeJoystickWidget.h"
+#include "Widgets/SLeafWidget.h"
+#include "Widgets/SOverlay.h"
+#include "Widgets/Layout/SSafeZone.h"
+#include "Widgets/Layout/SBox.h"
+#include "Brushes/SlateRoundedBoxBrush.h"
+#include "Rendering/DrawElements.h"
+#include "Input/Reply.h"
+#include "InputCoreTypes.h"
+
+class SGripForgeStick : public SLeafWidget {
+public:
+    SLATE_BEGIN_ARGS(SGripForgeStick) : _Radius(72), _Deadzone(.15f), _Accent(FLinearColor::White) {}
+        SLATE_ARGUMENT(float, Radius)
+        SLATE_ARGUMENT(float, Deadzone)
+        SLATE_ARGUMENT(FLinearColor, Accent)
+    SLATE_END_ARGS()
+    void Construct(const FArguments& Args) {
+        Radius=Args._Radius; Deadzone=Args._Deadzone; Accent=Args._Accent;
+        SetCanTick(false);
+    }
+    FVector2D Axis = FVector2D::ZeroVector;
+    void Reset() { Owner=INDEX_NONE; OwnerUser=INDEX_NONE; Axis=Visual=FVector2D::ZeroVector; Invalidate(EInvalidateWidgetReason::Paint); }
+    static FVector2D Radial(FVector2D Value, float Zone) {
+        const double M=Value.Size();
+        return M<=Zone || !FMath::IsFinite(M) ? FVector2D::ZeroVector : Value/M*FMath::Min(1.0,(M-Zone)/(1.0-Zone));
+    }
+    virtual FVector2D ComputeDesiredSize(float) const override { return FVector2D(Radius*2); }
+    virtual int32 OnPaint(const FPaintArgs&, const FGeometry& G, const FSlateRect&, FSlateWindowElementList& Out, int32 Layer, const FWidgetStyle&, bool) const override {
+        const float R=FMath::Min(G.GetLocalSize().X,G.GetLocalSize().Y)*.5f;
+        const FVector2D C=G.GetLocalSize()*.5;
+        FSlateDrawElement::MakeBox(Out,Layer,G.ToPaintGeometry(FVector2D(R*2),FSlateLayoutTransform(C-FVector2D(R))),&Circle,ESlateDrawEffect::None,FLinearColor(.06f,.08f,.11f,.72f));
+        const float TR=R*.28f;
+        FSlateDrawElement::MakeBox(Out,Layer+1,G.ToPaintGeometry(FVector2D(TR*2),FSlateLayoutTransform(C+Visual*R*.65f-FVector2D(TR))),&Circle,ESlateDrawEffect::None,Accent);
+        return Layer+1;
+    }
+    virtual FReply OnMouseButtonDown(const FGeometry& G,const FPointerEvent& E) override { return E.GetEffectingButton()==EKeys::LeftMouseButton ? Begin(G,E) : FReply::Unhandled(); }
+    virtual FReply OnMouseMove(const FGeometry& G,const FPointerEvent& E) override { return Move(G,E); }
+    virtual FReply OnMouseButtonUp(const FGeometry&,const FPointerEvent& E) override { return E.GetEffectingButton()==EKeys::LeftMouseButton ? End(E) : FReply::Unhandled(); }
+    virtual FReply OnTouchStarted(const FGeometry& G,const FPointerEvent& E) override { return Begin(G,E); }
+    virtual FReply OnTouchMoved(const FGeometry& G,const FPointerEvent& E) override { return Move(G,E); }
+    virtual FReply OnTouchEnded(const FGeometry&,const FPointerEvent& E) override { return End(E); }
+    virtual void OnMouseCaptureLost(const FCaptureLostEvent&) override { Reset(); }
+private:
+    int32 Owner=INDEX_NONE, OwnerUser=INDEX_NONE;
+    float Radius=72, Deadzone=.15f;
+    FVector2D Visual=FVector2D::ZeroVector;
+    FLinearColor Accent;
+    const FSlateRoundedBoxBrush Circle{FLinearColor::White,1000.f};
+    bool Owns(const FPointerEvent& E) const { return Owner==(int32)E.GetPointerIndex() && OwnerUser==(int32)E.GetUserIndex(); }
+    void Update(const FGeometry& G,const FPointerEvent& E) {
+        const double Travel=FMath::Min(G.GetLocalSize().X,G.GetLocalSize().Y)*.325;
+        if(Travel<=0){Reset();return;}
+        const FVector2D Raw=(G.AbsoluteToLocal(E.GetScreenSpacePosition())-G.GetLocalSize()*.5)/Travel;
+        Visual=Raw/FMath::Max(1.0,Raw.Size());
+        Axis=Radial(FVector2D(Raw.X,-Raw.Y),Deadzone);
+        Invalidate(EInvalidateWidgetReason::Paint);
+    }
+    FReply Begin(const FGeometry& G,const FPointerEvent& E) {
+        if(Owner!=INDEX_NONE)return FReply::Handled();
+        Owner=E.GetPointerIndex(); OwnerUser=E.GetUserIndex(); Update(G,E);
+        return FReply::Handled().CaptureMouse(SharedThis(this));
+    }
+    FReply Move(const FGeometry& G,const FPointerEvent& E) { if(!Owns(E))return FReply::Unhandled(); Update(G,E); return FReply::Handled(); }
+    FReply End(const FPointerEvent& E) { if(!Owns(E))return FReply::Unhandled(); Reset(); return FReply::Handled().ReleaseMouseCapture(); }
+};
+
+TSharedRef<SWidget> UGripForgeJoystickWidget::RebuildWidget() {
+    auto Overlay=SNew(SOverlay).Visibility(EVisibility::SelfHitTestInvisible);
+    Overlay->AddSlot().HAlign(HAlign_Left).VAlign(VAlign_Bottom).Padding(24)[
+        SAssignNew(MoveStick,SGripForgeStick).Radius(Radius).Deadzone(Deadzone).Accent(Accent)];
+    if(bDual) Overlay->AddSlot().HAlign(HAlign_Right).VAlign(VAlign_Bottom).Padding(24)[
+        SAssignNew(LookStick,SGripForgeStick).Radius(Radius).Deadzone(Deadzone).Accent(Accent)];
+    return SNew(SSafeZone).Visibility(EVisibility::SelfHitTestInvisible)[Overlay];
+}
+FVector2D UGripForgeJoystickWidget::GetMove() const { return MoveStick.IsValid()?MoveStick->Axis:FVector2D::ZeroVector; }
+FVector2D UGripForgeJoystickWidget::GetLook() const { return LookStick.IsValid()?LookStick->Axis:FVector2D::ZeroVector; }
+void UGripForgeJoystickWidget::ResetSticks(){if(MoveStick)MoveStick->Reset();if(LookStick)LookStick->Reset();}
+void UGripForgeJoystickWidget::ReleaseSlateResources(bool bReleaseChildren){ResetSticks();Super::ReleaseSlateResources(bReleaseChildren);MoveStick.Reset();LookStick.Reset();}
+` }, { path: src + 'Public/GripForgeJoystickComponent.h', content: `#pragma once
+#include "CoreMinimal.h"
+#include "Components/ActorComponent.h"
+#include "GripForgeJoystickComponent.generated.h"
+class UGripForgeJoystickWidget;
+class APlayerController;
+
+UCLASS(ClassGroup=(Input), meta=(BlueprintSpawnableComponent))
+class GRIPFORGEJOYSTICK_API UGripForgeJoystickComponent : public UActorComponent {
+    GENERATED_BODY()
+public:
+    UGripForgeJoystickComponent();
+    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Joystick") bool bDual = ${c.layout === 'dual' ? 'true' : 'false'};
+    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Joystick",meta=(ClampMin="32",ClampMax="160")) float Radius = ${c.radius.toFixed(4)}f;
+    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Joystick",meta=(ClampMin="0",ClampMax="0.5")) float Deadzone = ${c.deadzone.toFixed(4)}f;
+    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Joystick") FLinearColor Accent = FLinearColor(FColor::FromHex(TEXT("${c.accent.slice(1)}")));
+    // Turn these off if your existing motor reads GetMove/GetLook itself.
+    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Joystick") bool bDriveMovement = true;
+    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Joystick") bool bDriveLook = true;
+    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Joystick") float LookDegreesPerSecond = 120.f;
+    UFUNCTION(BlueprintPure, Category="Joystick") FVector2D GetMove() const;
+    UFUNCTION(BlueprintPure, Category="Joystick") FVector2D GetLook() const;
+    UFUNCTION(BlueprintCallable, Category="Joystick") void ResetInput();
+    virtual void Deactivate() override;
+    virtual void TickComponent(float Delta, ELevelTick TickType, FActorComponentTickFunction* ThisTick) override;
+protected:
+    virtual void BeginPlay() override;
+    virtual void EndPlay(const EEndPlayReason::Type Reason) override;
+private:
+    UPROPERTY(Transient) TObjectPtr<UGripForgeJoystickWidget> Widget;
+    TWeakObjectPtr<APlayerController> Controller;
+    FDelegateHandle FocusHandle, BackgroundHandle;
+    void RemoveWidget();
+};
+` }, { path: src + 'Private/GripForgeJoystickComponent.cpp', content: `#include "GripForgeJoystickComponent.h"
+#include "GripForgeJoystickWidget.h"
+#include "GameFramework/Pawn.h"
+#include "GameFramework/PlayerController.h"
+#include "GameFramework/PawnMovementComponent.h"
+#include "Misc/CoreDelegates.h"
+#include "Math/RotationMatrix.h"
+
+UGripForgeJoystickComponent::UGripForgeJoystickComponent(){bAutoActivate=true;PrimaryComponentTick.bCanEverTick=true;PrimaryComponentTick.TickGroup=TG_PrePhysics;}
+void UGripForgeJoystickComponent::BeginPlay(){
+    Super::BeginPlay();
+    FocusHandle=FCoreDelegates::ApplicationWillDeactivateDelegate.AddUObject(this,&UGripForgeJoystickComponent::ResetInput);
+    BackgroundHandle=FCoreDelegates::ApplicationWillEnterBackgroundDelegate.AddUObject(this,&UGripForgeJoystickComponent::ResetInput);
+    if(auto* Pawn=Cast<APawn>(GetOwner()))if(auto* Motor=Pawn->GetMovementComponent())Motor->AddTickPrerequisiteComponent(this);
+}
+void UGripForgeJoystickComponent::TickComponent(float Delta,ELevelTick TickType,FActorComponentTickFunction* ThisTick){
+    Super::TickComponent(Delta,TickType,ThisTick);
+    auto* Pawn=Cast<APawn>(GetOwner());
+    auto* PC=Pawn?Cast<APlayerController>(Pawn->GetController()):nullptr;
+    if(!PC || !Pawn->IsLocallyControlled() || !PC->IsLocalController()){RemoveWidget();return;}
+    // Possession may occur AFTER BeginPlay. Recreate on local controller changes.
+    if(Controller.Get()!=PC){RemoveWidget();Controller=PC;}
+    if(!Widget){
+        Widget=CreateWidget<UGripForgeJoystickWidget>(PC);
+        if(!Widget)return;
+        Widget->bDual=bDual;Widget->Radius=FMath::Clamp(Radius,32.f,160.f);Widget->Deadzone=FMath::Clamp(Deadzone,0.f,.5f);Widget->Accent=Accent;
+        Widget->SetVisibility(ESlateVisibility::SelfHitTestInvisible);
+        Widget->AddToPlayerScreen(20);
+    }
+    if(PC->IsPaused()){ResetInput();return;}
+    const FVector2D Move=GetMove(),Look=GetLook();
+    if(bDriveMovement && !PC->IsMoveInputIgnored()){
+        const FRotationMatrix Basis(FRotator(0,PC->GetControlRotation().Yaw,0));
+        Pawn->AddMovementInput(Basis.GetUnitAxis(EAxis::X),Move.Y);
+        Pawn->AddMovementInput(Basis.GetUnitAxis(EAxis::Y),Move.X);
+    }
+    if(bDriveLook && !PC->IsLookInputIgnored()){
+        // InputYaw/PitchScale belong to the game's controller, just as for other axes.
+        Pawn->AddControllerYawInput(Look.X*LookDegreesPerSecond*Delta);
+        Pawn->AddControllerPitchInput(-Look.Y*LookDegreesPerSecond*Delta);
+    }
+}
+FVector2D UGripForgeJoystickComponent::GetMove() const {return IsActive()&&Widget?Widget->GetMove():FVector2D::ZeroVector;}
+FVector2D UGripForgeJoystickComponent::GetLook() const {return IsActive()&&Widget?Widget->GetLook():FVector2D::ZeroVector;}
+void UGripForgeJoystickComponent::ResetInput(){if(Widget)Widget->ResetSticks();}
+void UGripForgeJoystickComponent::Deactivate(){RemoveWidget();Super::Deactivate();}
+void UGripForgeJoystickComponent::RemoveWidget(){if(Widget){Widget->ResetSticks();Widget->RemoveFromParent();Widget=nullptr;}Controller.Reset();}
+void UGripForgeJoystickComponent::EndPlay(const EEndPlayReason::Type Reason){
+    RemoveWidget();FCoreDelegates::ApplicationWillDeactivateDelegate.Remove(FocusHandle);FCoreDelegates::ApplicationWillEnterBackgroundDelegate.Remove(BackgroundHandle);
+    if(auto* Pawn=Cast<APawn>(GetOwner()))if(auto* Motor=Pawn->GetMovementComponent())Motor->RemoveTickPrerequisiteComponent(this);
+    Super::EndPlay(Reason);
+}
+` }, { path: 'README.md', content: `# GripForge joystick · Unreal Engine 5
+
+1. Copy Plugins/GripForgeJoystick into the project (not Engine). Compile the
+   runtime plugin with your UE version/toolchain, then reopen the editor. A
+   Blueprint-only project can add a C++ class first to enable project builds.
+2. Enable GripForge Joystick in Plugins if needed. On the actual possessed Pawn
+   Blueprint, Add Component → GripForge Joystick. It waits for local possession.
+3. Press Play. Left stick feeds your Pawn's existing AddMovementInput; right
+   stick feeds controller yaw/pitch. CharacterMovement still owns collision,
+   gravity, acceleration and network prediction. No GameMode replacement.
+
+Mouse and touch work directly through Slate; Use Mouse for Touch is not required.
+For a desktop mouse test, use Game and UI input mode and show the cursor in your
+PlayerController. Keep the game viewport focused. The plugin deliberately does
+not change your game's input mode/cursor. Native touch works in Game Only mode.
+Remove/disable the previous virtual joystick to avoid overlapping controls.
+
+For a custom motor disable Drive Movement/Drive Look and read Get Move/Get Look
+from the component every tick. Axes: X right, Y forward/up; magnitude <= 1. Apply
+look deltaTime once. Existing gamepad/keyboard actions are not overwritten.
+Deadzone, radius, color and dual-stick layout are set before the UI is created.
+The overlay respects Slate DPI/safe zones. Release, capture loss, application
+focus loss, losing possession and EndPlay reset the axes. Use Reset Input when
+opening your own modal menus. One component per locally controlled pawn.
+
+This is a source plugin, not a precompiled binary for every UE release. Compile
+for the target UE/platform and test in your real project before packaging.
+` }];
+}

package/dist/joystick-tools.js

@@ -0,0 +1,26 @@
+/** Identical deterministic delivery in the hosted MCP and npm client. */
+import { z } from 'zod/v4';
+import { createJoystickKit } from './joystick-kit/index.js';
+export const JOYSTICK_TOOL_NAMES = ['gripforge_joystick_kit'];
+export function registerJoystickTools(register, schema = z) {
+    const shape = {
+        target: schema.enum(['threejs', 'godot', 'unity', 'unreal', 'all']).describe('Engine delivery. all returns each of the four source kits.'),
+        layout: schema.enum(['move', 'dual']).default('dual').describe('One movement stick, or independent movement + camera sticks.'),
+        deadzone: schema.number().min(0).max(.5).default(.15).describe('Radial deadzone, continuously rescaled to a unit disc.'),
+        radius: schema.number().min(32).max(160).default(72).describe('Stick radius in CSS/UI logical pixels, before engine DPI scaling.'),
+        accent: schema.string().regex(/^#[\da-f]{6}$/i).default('#ff681f').describe('Thumb color, six-digit hexadecimal RGB.'),
+    };
+    register('gripforge_joystick_kit', {
+        title: 'Ready-to-use joystick · Unreal / Godot / Unity / Three.js',
+        description: 'Generate input.joystick source files and installation instructions: touch + mouse, independent dual sticks, radial deadzone, continuous holding and release/focus reset. Unreal runtime Pawn component, Godot CanvasLayer scene, Unity UI component, Three.js DOM controls + GripForge input.actions bridge. Feeds the existing movement controller rather than replacing physics, collision or networking. Returns files with relative path/content; the agent writes them into the target project and compiles/tests there. Does not install automatically, modify project settings or claim runtime validation. 0 credits.',
+        inputSchema: shape,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (args) => {
+        const parsed = schema.object(shape).safeParse(args);
+        if (!parsed.success)
+            return { isError: true, content: [{ type: 'text', text: parsed.error.message }] };
+        const { target, ...config } = parsed.data;
+        const result = createJoystickKit(target, config);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
+    });
+}

package/dist/map-unreal-export-local.js

@@ -0,0 +1,285 @@
+import { z } from 'zod/v4';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFile, writeFile, mkdir, copyFile, realpath, open, unlink } from 'node:fs/promises';
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { unrealLaunchCommand } from './map-unreal-import-local.js';
+import { atomicJson, readJson, sha256, buildUnrealStudioPackage, exportFile } from './unreal-export-package.js';
+const absolute = z.string().min(1).max(4096).refine(isAbsolute, 'Absolute local path required.').refine(s => !/[\r\n\0"]/.test(s), 'Invalid path.');
+const level = z.string().regex(/^\/Game(?:\/[\w-]+)+$/);
+const qualities = { texture_size: z.union([z.literal(512), z.literal(1024), z.literal(2048)]).default(1024), terrain_texture_size: z.union([z.literal(1024), z.literal(2048), z.literal(4096)]).default(4096), terrain_resolution: z.union([z.literal(129), z.literal(257), z.literal(513), z.literal(1025)]).default(513) };
+const requestSchema = z.object({ schema: z.literal('gripforge.unreal-export-request.v1'), project_file: absolute, source_level: level, source_sha256: z.string().regex(/^[a-f0-9]{64}$/), ...qualities }).strict();
+function alive(pid) { if (typeof pid !== 'number' || pid <= 0)
+    return false; try {
+    process.kill(pid, 0);
+    return true;
+}
+catch (e) {
+    if (e.code === 'EPERM')
+        return true;
+    if (e.code !== 'ESRCH')
+        throw e;
+    return false;
+} }
+async function optionalJson(file) { try {
+    return await readJson(file);
+}
+catch (e) {
+    if (e.code !== 'ENOENT')
+        throw e;
+    return null;
+} }
+async function withLaunchLock(dir, stage, task) {
+    const file = join(dir, stage + '-launch.lock');
+    try {
+        await writeFile(file, JSON.stringify({ pid: process.pid }), { flag: 'wx' });
+    }
+    catch (e) {
+        if (e.code !== 'EEXIST')
+            throw e;
+        if (alive((await readJson(file)).pid))
+            throw Error('Another launch request is in progress.');
+        await unlink(file);
+        return withLaunchLock(dir, stage, task);
+    }
+    try {
+        return await task();
+    }
+    finally {
+        await unlink(file);
+    }
+}
+export async function prepareUnrealExport(input) {
+    absolute.parse(input.job_directory);
+    absolute.parse(input.project_file);
+    level.parse(input.source_level);
+    const project = await realpath(input.project_file);
+    if (!project.endsWith('.uproject'))
+        throw Error('Expected an installed .uproject.');
+    const source = join(dirname(project), 'Content', input.source_level.slice(6) + '.umap');
+    const request = requestSchema.parse({ schema: 'gripforge.unreal-export-request.v1', project_file: project, source_level: input.source_level, source_sha256: sha256(await readFile(source)), texture_size: input.texture_size, terrain_texture_size: input.terrain_texture_size, terrain_resolution: input.terrain_resolution });
+    await mkdir(input.job_directory, { recursive: true });
+    const dir = await realpath(input.job_directory);
+    const previous = await optionalJson(join(dir, 'request.json'));
+    if (previous && JSON.stringify(requestSchema.parse(previous)) !== JSON.stringify(request))
+        throw Error('Job inputs changed. Use a new job directory.');
+    if (!previous)
+        await writeFile(join(dir, 'request.json'), JSON.stringify(request), { flag: 'wx' });
+    const worker = fileURLToPath(new URL('../runtime/unreal-scene-export.py', import.meta.url)), target = join(dir, 'unreal-scene-export.py');
+    try {
+        await copyFile(worker, target, 1);
+    }
+    catch (e) {
+        if (e.code !== 'EEXIST')
+            throw e;
+        if (sha256(await readFile(worker)) !== sha256(await readFile(target)))
+            throw Error('Worker version changed. Prepare a new job directory.');
+    }
+    return { job_directory: dir, request, lifecycle: 'work' };
+}
+export async function unrealExportStatus(directory) {
+    absolute.parse(directory);
+    const dir = await realpath(directory);
+    requestSchema.parse(await readJson(join(dir, 'request.json')));
+    const result = { job_directory: dir, lifecycle: 'work' };
+    for (const stage of ['export', 'upload']) {
+        const file = stage === 'export' ? 'status.json' : 'upload-status.json', launch = await optionalJson(join(dir, stage + '-launch.json'));
+        let state = await optionalJson(join(dir, file));
+        if (launch && (!state || launch.started_at > (state.updated_at ?? 0)))
+            state = { ...launch, status: 'running', stage: 'launching' };
+        if (!state) {
+            result[stage] = { status: 'pending' };
+            continue;
+        }
+        const running = alive(launch?.pid ?? state.pid);
+        if (state.status === 'running' && !running)
+            state = { ...state, status: 'interrupted', error: 'Worker exited. Read its log and resume the saved job; completed steps remain available.' };
+        result[stage] = { ...state, worker_running: running };
+    }
+    if (result.upload.studio_url)
+        result.studio_url = result.upload.studio_url;
+    return result;
+}
+export async function startUnrealExport(directory, editor) {
+    absolute.parse(directory);
+    absolute.parse(editor);
+    const dir = await realpath(directory), executable = await realpath(editor);
+    if (!/^UnrealEditor(?:-Cmd)?(?:\.exe)?$/.test(basename(executable)))
+        throw Error('Expected UnrealEditor or UnrealEditor-Cmd executable.');
+    return withLaunchLock(dir, 'export', async () => {
+        const state = await unrealExportStatus(dir);
+        if (state.export.worker_running || state.export.status === 'succeeded')
+            return state;
+        const request = requestSchema.parse(await readJson(join(dir, 'request.json')));
+        const source = join(dirname(request.project_file), 'Content', request.source_level.slice(6) + '.umap');
+        if (sha256(await readFile(source)) !== request.source_sha256)
+            throw Error('Source level changed. Prepare a new export.');
+        const worker = await exportFile(dir, 'unreal-scene-export.py');
+        const current = fileURLToPath(new URL('../runtime/unreal-scene-export.py', import.meta.url));
+        if (sha256(await readFile(worker)) !== sha256(await readFile(current)))
+            throw Error('Worker changed. Prepare a new job.');
+        await atomicJson(join(dir, 'control.json'), { cancel: false });
+        const arm = process.platform === 'darwin' && (await promisify(execFile)('/usr/sbin/sysctl', ['-n', 'hw.optional.arm64'])).stdout.trim() === '1';
+        const launch = unrealLaunchCommand(executable, [request.project_file, '-run=pythonscript', '-script=' + worker, '-GFExportJob=' + dir, '-AllowCommandletRendering', '-EnablePlugins=PythonScriptPlugin,EditorScriptingUtilities,GLTFExporter', '-unattended', '-nosplash', '-nosound', '-abslog=' + join(dir, 'export.log')], arm);
+        const log = await open(join(dir, 'export-launch.log'), 'a');
+        try {
+            const child = spawn(launch.command, launch.args, { cwd: dirname(executable), detached: true, shell: false, stdio: ['ignore', log.fd, log.fd] });
+            await new Promise((ok, bad) => { child.once('spawn', ok); child.once('error', bad); });
+            child.unref();
+            await atomicJson(join(dir, 'export-launch.json'), { pid: child.pid, started_at: Date.now() / 1000 });
+            return { job_directory: dir, status: 'running', stage: 'launching', pid: child.pid, next: 'Poll gripforge_map_unreal_export_status_local. No source level/assets will be saved.' };
+        }
+        finally {
+            await log.close();
+        }
+    });
+}
+function apiOrigin(value) {
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash || url.pathname !== '/' || url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))
+        throw Error('Use an HTTPS API origin, or HTTP loopback for local development.');
+    return url.origin;
+}
+async function api(url, key, workspace, path, method = 'GET', body, headers = {}) {
+    const response = await fetch(url + path, { method, redirect: 'error', headers: { 'x-api-key': key, 'x-workspace-id': workspace, 'x-gripforge-client': 'mcp', ...headers }, ...(body === undefined ? {} : { body: typeof body === 'string' ? body : new Uint8Array(body) }), signal: AbortSignal.timeout(120000) });
+    const data = await response.json();
+    if (!response.ok)
+        throw Error('GripForge API ' + response.status + ': ' + JSON.stringify(data).slice(0, 1500));
+    return data;
+}
+/** Runs in a detached Node worker. The credential is inherited in memory, never persisted in its checkpoints. */
+export async function uploadUnrealExport(directory, origin, workspace, key) {
+    const dir = await realpath(directory), url = apiOrigin(origin), scope = sha256(url + ':' + workspace), stateFile = join(dir, 'upload-status.json');
+    let state = await optionalJson(stateFile) ?? {};
+    if (state.scope && state.scope !== scope)
+        throw Error('Upload job belongs to another workspace or API origin. Use a separate copy of the export.');
+    state = { ...state, scope, workspace_id: workspace, api_origin: url, status: 'running', pid: process.pid, lifecycle: 'work', updated_at: Date.now() / 1000, uploaded: state.uploaded ?? {} };
+    const progress = async (stage) => { state.stage = stage; state.updated_at = Date.now() / 1000; await atomicJson(stateFile, state); };
+    const checkCancel = async () => {
+        if ((await optionalJson(join(dir, 'upload-control.json')))?.cancel) {
+            if (state.job_id)
+                await api(url, key, workspace, '/api/v1/generation-jobs/' + encodeURIComponent(state.job_id), 'POST', JSON.stringify({ action: 'cancel' }), { 'content-type': 'application/json' });
+            throw Error('Upload cancelled; completed assets retained.');
+        }
+    };
+    try {
+        await progress('assembling');
+        await checkCancel();
+        const portable = await buildUnrealStudioPackage(dir), hash = portable.manifest.sceneHash;
+        if (state.scene_hash && state.scene_hash !== hash)
+            throw Error('Portable scene changed during upload. Use a new job.');
+        state.scene_hash = hash;
+        state.total = portable.manifest.assets.length;
+        for (const file of portable.manifest.assets) {
+            await checkCancel();
+            if (state.uploaded[file.sha256])
+                continue;
+            state.file = file.name;
+            state.completed = Object.keys(state.uploaded).length;
+            await progress('uploading_assets');
+            const bytes = await readFile(await exportFile(dir, file.file));
+            if (sha256(bytes) !== file.sha256)
+                throw Error('Export changed: ' + file.file);
+            const response = await api(url, key, workspace, '/api/v1/maps/import/unreal/assets', 'POST', bytes, { 'content-type': file.mime, 'x-asset-filename': basename(file.file), 'x-content-sha256': file.sha256 });
+            if (response.sha256 !== file.sha256 || !response.asset?.assetId || !response.asset?.revisionId)
+                throw Error('Unexpected asset upload response.');
+            state.uploaded[file.sha256] = response.asset;
+            await progress('uploading_assets');
+        }
+        await checkCancel();
+        const refs = new Map(portable.manifest.assets.map(a => [a.assetId + ':' + a.revisionId, state.uploaded[a.sha256]]));
+        const replaceRefs = (v) => {
+            if (!v || typeof v !== 'object')
+                return v;
+            if (typeof v.assetId === 'string' && typeof v.revisionId === 'string') {
+                const ref = refs.get(v.assetId + ':' + v.revisionId);
+                if (!ref)
+                    throw Error('Unresolved asset reference.');
+                return { ...ref, ...(v.fileRole ? { fileRole: v.fileRole } : {}) };
+            }
+            return Array.isArray(v) ? v.map(replaceRefs) : Object.fromEntries(Object.entries(v).map(([k, x]) => [k, replaceRefs(x)]));
+        };
+        const input = replaceRefs(portable.input);
+        input.document.workspaceId = workspace;
+        input.idempotency_key = 'ue-import-' + hash;
+        await progress('queueing_import');
+        if (!state.job_id) {
+            const response = await api(url, key, workspace, '/api/v1/maps/import/unreal', 'POST', JSON.stringify(input), { 'content-type': 'application/json' });
+            if (typeof response.job_id !== 'string')
+                throw Error('Missing persistent import job.');
+            state.job_id = response.job_id;
+            await progress('saving_scene');
+        }
+        let first = true;
+        for (;;) {
+            await checkCancel();
+            const response = await api(url, key, workspace, '/api/v1/generation-jobs/' + encodeURIComponent(state.job_id)), job = response.job ?? response;
+            if (job.status === 'failed' || job.status === 'cancelled') {
+                if (!first)
+                    throw Error('Import job ' + job.status + ': ' + String(job.error ?? 'Read generation_read for details.'));
+                await api(url, key, workspace, '/api/v1/generation-jobs/' + encodeURIComponent(state.job_id), 'POST', JSON.stringify({ action: 'retry' }), { 'content-type': 'application/json' });
+            }
+            else if (job.status === 'succeeded') {
+                if (!job.result?.studio_url)
+                    throw Error('Import completed without a Studio link.');
+                Object.assign(state, { status: 'succeeded', result: job.result, studio_url: new URL(job.result.studio_url, url).href, completed: state.total });
+                await progress('awaiting_visual_review');
+                return state;
+            }
+            first = false;
+            state.remote_status = job.status;
+            await progress('saving_scene');
+            await new Promise(ok => setTimeout(ok, 3000));
+        }
+    }
+    catch (e) {
+        state.status = (await optionalJson(join(dir, 'upload-control.json')))?.cancel ? 'cancelled' : 'failed';
+        state.error = e instanceof Error ? e.message : String(e);
+        await progress(state.stage);
+        throw e;
+    }
+}
+export async function startUnrealUpload(directory, origin, workspace, key) {
+    if (!key)
+        throw Error('Connect a GripForge API key before uploading.');
+    absolute.parse(directory);
+    z.string().regex(/^[\w-]{1,100}$/).parse(workspace);
+    const url = apiOrigin(origin), dir = await realpath(directory);
+    return withLaunchLock(dir, 'upload', async () => {
+        const status = await unrealExportStatus(dir);
+        if (status.export.status !== 'succeeded')
+            throw Error('Wait for a successful native export.');
+        if (status.upload.scope && status.upload.scope !== sha256(url + ':' + workspace))
+            throw Error('Job already belongs to another workspace/API.');
+        if (status.upload.worker_running || status.upload.status === 'succeeded')
+            return status;
+        await atomicJson(join(dir, 'upload-control.json'), { cancel: false });
+        const log = await open(join(dir, 'upload.log'), 'a');
+        try {
+            const child = spawn(process.execPath, [fileURLToPath(new URL('../runtime/unreal-scene-upload.mjs', import.meta.url)), dir, url, workspace], { detached: true, shell: false, stdio: ['ignore', log.fd, log.fd], env: { ...process.env, GRIPFORGE_API_KEY: key } });
+            await new Promise((ok, bad) => { child.once('spawn', ok); child.once('error', bad); });
+            child.unref();
+            await atomicJson(join(dir, 'upload-launch.json'), { pid: child.pid, started_at: Date.now() / 1000 });
+            return { job_directory: dir, status: 'running', stage: 'uploading', next: 'Poll gripforge_map_unreal_export_status_local for progress and studio_url.' };
+        }
+        finally {
+            await log.close();
+        }
+    });
+}
+export function registerMapUnrealExportLocalTools(register, options) {
+    const job = { job_directory: absolute.describe('Persistent local export directory; retain it to resume completed stages.') };
+    const wrap = (f) => async (a) => { try {
+        const data = await f(a);
+        return { structuredContent: data, content: [{ type: 'text', text: JSON.stringify(data) }] };
+    }
+    catch (e) {
+        return { isError: true, content: [{ type: 'text', text: e instanceof Error ? e.message : String(e) }] };
+    } };
+    const annotations = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+    register('gripforge_map_unreal_export_local', { title: 'Export an Unreal map to GripForge', description: 'Generic local UE 5.7 exporter. Pins the selected saved map and runs a separate Unreal Python commandlet without saving source assets. Exports PBR GLBs, all supported static placements, compact foliage patches, Landscape height/holes and baked albedo. Durable per-file checkpoints survive closed MCP calls. Native shader graphs, animated water/sky, Niagara and gameplay Blueprints are reported, not silently recreated. Work version requires visual review in GripForge. Local MCP only; Unreal/Python/GLTFExporter must be installed.', inputSchema: { project_file: absolute, source_level: level, editor_executable: absolute, ...job, ...qualities }, annotations }, wrap(async (a) => { const prepared = await prepareUnrealExport(a); return startUnrealExport(prepared.job_directory, String(a.editor_executable)); }));
+    register('gripforge_map_unreal_export_status_local', { title: 'Read Unreal export/upload progress', description: 'Read durable stages, failures, completed assets and final GripForge Studio link. Does not equate technical export success with visual validation.', inputSchema: job, annotations: { ...annotations, readOnlyHint: true } }, wrap(a => unrealExportStatus(String(a.job_directory))));
+    register('gripforge_map_unreal_export_cancel_local', { title: 'Cancel an Unreal export or upload', description: 'Request cancellation at the next safe asset checkpoint. Keeps completed files and uploaded private assets; resume with export_local or upload_local using the same directory. Never kills an unrelated Unreal editor.', inputSchema: { ...job, stage: z.enum(['export', 'upload']) }, annotations }, wrap(async (a) => { const state = await unrealExportStatus(String(a.job_directory)); await atomicJson(join(state.job_directory, a.stage === 'export' ? 'control.json' : 'upload-control.json'), { cancel: true }); return { cancel_requested: true, stage: a.stage, job_directory: state.job_directory }; }));
+    register('gripforge_map_unreal_upload_local', { title: 'Import exported Unreal map into your workspace', description: 'Assemble a completed native export as a common SceneDocument, upload immutable assets to the authenticated workspace and queue a persistent API import. Detached upload resumes per-file checkpoints. Poll export_status_local for studio_url. Private work only, never auto-promotes or publishes. 0 generation credits; workspace storage quota applies.', inputSchema: { ...job, workspace_id: z.string().regex(/^[\w-]{1,100}$/) }, annotations }, wrap(a => startUnrealUpload(String(a.job_directory), options.apiUrl, String(a.workspace_id), options.getApiKey() ?? '')));
+}