@gripforgeai/mcp 0.1.10 → 0.1.11

package/dist/unreal-export-package.js

@@ -0,0 +1,212 @@
+import { createHash } from 'node:crypto';
+import { readFile, writeFile, rename, stat, realpath } from 'node:fs/promises';
+import { resolve, sep } from 'node:path';
+import { inflateSync, deflateSync } from 'node:zlib';
+export const sha256 = (b) => createHash('sha256').update(b).digest('hex');
+export async function atomicJson(file, value) { const tmp = file + '.' + process.pid + '.tmp'; await writeFile(tmp, JSON.stringify(value)); await rename(tmp, file); }
+export async function readJson(file) { if ((await stat(file)).size > 64 * 1024 * 1024)
+    throw Error('Manifest exceeds 64 MB.'); return JSON.parse(await readFile(file, 'utf8')); }
+export async function exportFile(dir, file) {
+    const root = await realpath(dir), path = await realpath(resolve(root, file));
+    if (!path.startsWith(root + sep))
+        throw Error('Export file escapes its job directory.');
+    return path;
+}
+const signature = Buffer.from('89504e470d0a1a0a', 'hex');
+function crc32(data) { let crc = 0xffffffff; for (const byte of data) {
+    crc ^= byte;
+    for (let i = 0; i < 8; i++)
+        crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+} return (crc ^ 0xffffffff) >>> 0; }
+/** Native RGBA8 data, without gamma conversion (height is packed in RG). */
+export function decodeExportPng(bytes) {
+    if (!bytes.subarray(0, 8).equals(signature))
+        throw Error('Invalid PNG signature.');
+    let width = 0, height = 0, channels = 0, ended = false;
+    const parts = [];
+    for (let at = 8; at + 12 <= bytes.length;) {
+        const length = bytes.readUInt32BE(at), end = at + length + 12;
+        if (end > bytes.length)
+            throw Error('Truncated PNG.');
+        const type = bytes.toString('ascii', at + 4, at + 8), data = bytes.subarray(at + 8, end - 4);
+        if (crc32(bytes.subarray(at + 4, end - 4)) !== bytes.readUInt32BE(end - 4))
+            throw Error('PNG checksum mismatch.');
+        if (type === 'IHDR') {
+            if (width || length !== 13 || data[8] !== 8 || ![2, 6].includes(data[9]) || data[10] || data[11] || data[12])
+                throw Error('Expected non-interlaced RGB/RGBA8 PNG.');
+            width = data.readUInt32BE(0);
+            height = data.readUInt32BE(4);
+            channels = data[9] === 6 ? 4 : 3;
+            if (!width || !height || width > 8192 || height > 8192)
+                throw Error('PNG dimensions exceed export budget.');
+        }
+        else if (type === 'IDAT')
+            parts.push(data);
+        else if (type === 'IEND') {
+            ended = true;
+            break;
+        }
+        at = end;
+    }
+    if (!width || !ended)
+        throw Error('Incomplete PNG.');
+    const stride = width * channels, expected = (stride + 1) * height, raw = inflateSync(Buffer.concat(parts), { maxOutputLength: expected });
+    if (raw.length !== expected)
+        throw Error('Invalid PNG data length.');
+    const pixels = Buffer.alloc(stride * height);
+    for (let y = 0; y < height; y++) {
+        const filter = raw[y * (stride + 1)];
+        if (filter > 4)
+            throw Error('Invalid PNG filter.');
+        for (let x = 0; x < stride; x++) {
+            const at = y * stride + x, a = x >= channels ? pixels[at - channels] : 0, b = y ? pixels[at - stride] : 0, c = y && x >= channels ? pixels[at - stride - channels] : 0;
+            const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+            pixels[at] = raw[y * (stride + 1) + x + 1] + (filter === 0 ? 0 : filter === 1 ? a : filter === 2 ? b : filter === 3 ? Math.floor((a + b) / 2) : pa <= pb && pa <= pc ? a : pb <= pc ? b : c);
+        }
+    }
+    return { width, height, channels, pixels };
+}
+export function encodeExportPng(width, height, pixels, channels = 4) {
+    const chunk = (name, data) => { const out = Buffer.alloc(data.length + 12); out.writeUInt32BE(data.length); out.write(name, 4); data.copy(out, 8); out.writeUInt32BE(crc32(out.subarray(4, out.length - 4)), out.length - 4); return out; };
+    const header = Buffer.alloc(13);
+    header.writeUInt32BE(width);
+    header.writeUInt32BE(height, 4);
+    header[8] = 8;
+    header[9] = channels === 4 ? 6 : 2;
+    const stride = width * channels, scan = Buffer.alloc(height * (stride + 1));
+    for (let y = 0; y < height; y++)
+        pixels.copy(scan, y * (stride + 1) + 1, y * stride, (y + 1) * stride);
+    return Buffer.concat([signature, chunk('IHDR', header), chunk('IDAT', deflateSync(scan)), chunk('IEND', Buffer.alloc(0))]);
+}
+const vec = (x = 0, y = 0, z = 0) => ({ x, y, z });
+const identity = () => ({ translation: vec(), rotation: { ...vec(), w: 1 }, scale: vec(1, 1, 1) });
+const base = (id, name = id) => ({ id, name, parentId: null, transform: identity(), visible: true, locked: false });
+const round = (n) => Math.round(n * 1e6) / 1e6;
+const refFor = (file) => ({ assetId: 'ue_' + file.sha256.slice(0, 24), revisionId: 'rev_' + file.sha256.slice(0, 24) });
+export function decodeUnrealTerrain(t, bytes, resolution, visibility) {
+    const png = decodeExportPng(bytes), mask = visibility ? decodeExportPng(visibility) : undefined;
+    if (png.width !== t.width || png.height !== t.height || mask && (mask.width !== t.width || mask.height !== t.height))
+        throw Error('Landscape grid does not match its PNG.');
+    const spanX = t.width - 1, spanZ = t.height - 1, longest = Math.max(spanX, spanZ), sx = Math.max(1, Math.round((resolution - 1) * spanX / longest)), sz = Math.max(1, Math.round((resolution - 1) * spanZ / longest));
+    const q = t.component_quads, occupied = new Set(t.components.map(([x, y]) => x + ':' + y));
+    const present = (x, z) => occupied.has((Math.floor((t.base[0] + Math.min(spanX - .00001, Math.max(0, x))) / q) * q) + ':' + (Math.floor((t.base[1] + Math.min(spanZ - .00001, Math.max(0, z))) / q) * q));
+    const hidden = (x, z) => mask ? mask.pixels[(Math.round(z) * mask.width + Math.round(x)) * mask.channels] >= 128 : false;
+    const sample = (x, z) => { const at = (Math.min(t.height - 1, Math.max(0, z)) * t.width + Math.min(t.width - 1, Math.max(0, x))) * png.channels; return (png.pixels[at] * 256 + png.pixels[at + 1] - 32768) / 128 * t.scale[2] * .01; };
+    const heights = [], holes = [];
+    for (let z = 0; z <= sz; z++)
+        for (let x = 0; x <= sx; x++) {
+            const px = x / sx * spanX, pz = z / sz * spanZ, ix = Math.floor(px), iz = Math.floor(pz), u = px - ix, v = pz - iz;
+            const a = sample(ix, iz) * (1 - u) + sample(ix + 1, iz) * u, b = sample(ix, iz + 1) * (1 - u) + sample(ix + 1, iz + 1) * u;
+            heights.push(present(px, pz) ? Math.round((a * (1 - v) + b * v) * 1000) / 1000 : 0);
+        }
+    for (let z = 0; z < sz; z++)
+        for (let x = 0; x < sx; x++) {
+            let hole = false;
+            // Every source sample overlapped by this quad is checked, so small painted holes survive downsampling.
+            for (let j = Math.floor(z / sz * spanZ); j <= Math.ceil((z + 1) / sz * spanZ) && !hole; j++)
+                for (let i = Math.floor(x / sx * spanX); i <= Math.ceil((x + 1) / sx * spanX); i++)
+                    if (!present(i, j) || hidden(i, j)) {
+                        hole = true;
+                        break;
+                    }
+            holes.push(hole ? 1 : 0);
+        }
+    return { size: [spanX * t.scale[0] * .01, spanZ * t.scale[1] * .01], segments: [sx, sz], heights, holes,
+        center: vec((t.origin[0] + (t.base[0] + spanX / 2) * t.scale[0]) * .01, t.origin[2] * .01, (t.origin[1] + (t.base[1] + spanZ / 2) * t.scale[1]) * .01) };
+}
+export async function buildUnrealStudioPackage(directory) {
+    const dir = await realpath(directory), manifest = await readJson(resolve(dir, 'native.json')), request = await readJson(resolve(dir, 'request.json'));
+    if (manifest.schema !== 'gripforge.unreal-export.v1' || manifest.status !== 'exported-awaiting-gripforge-review' || sha256(await readFile(resolve(dir, 'request.json'))) !== manifest.request_hash)
+        throw Error('Native export must finish successfully before assembly.');
+    const assets = [], nodes = [], assetRefs = new Map();
+    async function addFile(file, name, kind, mime) {
+        const path = await exportFile(dir, file.file), bytes = await readFile(path);
+        if (bytes.length > 128 * 1024 * 1024 || bytes.length !== file.bytes || sha256(bytes) !== file.sha256)
+            throw Error('Changed or oversized export: ' + file.file);
+        const ref = refFor(file);
+        if (!assets.some(a => a.sha256 === file.sha256))
+            assets.push({ ...file, ...ref, name, kind, mime });
+        return ref;
+    }
+    for (const [key, file] of Object.entries(manifest.assets))
+        assetRefs.set(key, await addFile(file, file.name, 'prop', 'model/gltf-binary'));
+    nodes.push({ ...base('props', 'Props & buildings'), type: 'group' }, { ...base('vegetation', 'Vegetation'), type: 'group' }, { ...base('terrain', 'Terrain'), type: 'group' });
+    const batches = new Map();
+    let zeroScaleInstances = 0;
+    for (const instance of manifest.instances) {
+        const asset = assetRefs.get(instance.asset);
+        if (!asset)
+            throw Error('Missing exported mesh: ' + instance.asset);
+        const t = instance.transform, p = t.translation, q = t.rotation, s = t.scale;
+        // Unreal foliage retains removed placements as zero-scale tombstones. They have no visible geometry.
+        if ([s.x, s.y, s.z].every(n => n === 0)) {
+            zeroScaleInstances++;
+            continue;
+        }
+        const row = [p.x, p.y, p.z, q.x, q.y, q.z, q.w, s.x, s.y, s.z].map(round);
+        if (!row.every(Number.isFinite) || Math.abs(Math.hypot(q.x, q.y, q.z, q.w) - 1) > .001 || [s.x, s.y, s.z].some(n => Math.abs(n) < .00001))
+            throw Error('Invalid native transform: ' + instance.id);
+        if (instance.batch && [s.x, s.y, s.z].every(n => n > 0)) {
+            const cx = Math.floor(p.x / 64), cz = Math.floor(p.z / 64), prefix = instance.asset + ':' + cx + ':' + cz;
+            let part = 0, key = prefix;
+            while ((batches.get(key)?.instanceBatch.ids.length ?? 0) >= 4096)
+                key = prefix + ':' + (++part);
+            if (!batches.has(key)) {
+                const b = { ...base('batch_' + sha256(key).slice(0, 24), instance.name.slice(0, 110) + ` [${cx},${cz}]`), type: 'asset', parentId: 'vegetation', asset, role: 'vegetation', materials: {}, parameters: { source: 'unreal-instancing' }, instanceBatch: { ids: [], transforms: [] } };
+                batches.set(key, b);
+                nodes.push(b);
+            }
+            const b = batches.get(key);
+            b.instanceBatch.ids.push(instance.id);
+            b.instanceBatch.transforms.push(row);
+        }
+        else
+            nodes.push({ ...base(instance.id, instance.name), type: 'asset', parentId: instance.batch ? 'vegetation' : 'props', asset, role: 'prop', transform: t, materials: {}, parameters: { unrealSource: instance.source } });
+    }
+    let overview;
+    for (const t of manifest.terrains) {
+        await addFile(t.heightmap, t.id + ' source height', 'texture', 'image/png');
+        if (t.visibility)
+            await addFile(t.visibility, t.id + ' source holes', 'texture', 'image/png');
+        const terrain = decodeUnrealTerrain(t, await readFile(await exportFile(dir, t.heightmap.file)), request.terrain_resolution ?? 513, t.visibility ? await readFile(await exportFile(dir, t.visibility.file)) : undefined);
+        let albedo = t.albedo;
+        if (Math.abs(terrain.size[0] - terrain.size[1]) > .001) {
+            const source = decodeExportPng(await readFile(await exportFile(dir, albedo.file)));
+            const w = Math.max(1, Math.round(source.width * terrain.size[0] / (t.albedo_span_cm * .01))), h = Math.max(1, Math.round(source.height * terrain.size[1] / (t.albedo_span_cm * .01))), data = Buffer.alloc(w * h * source.channels);
+            if (w > source.width || h > source.height)
+                throw Error('Invalid Landscape albedo extent.');
+            const ox = Math.floor((source.width - w) / 2), oy = Math.floor((source.height - h) / 2);
+            for (let y = 0; y < h; y++)
+                source.pixels.copy(data, y * w * source.channels, ((y + oy) * source.width + ox) * source.channels, ((y + oy) * source.width + ox + w) * source.channels);
+            const bytes = encodeExportPng(w, h, data, source.channels), file = t.id + '-albedo-cropped.png';
+            await writeFile(resolve(dir, file), bytes);
+            albedo = { file, bytes: bytes.length, sha256: sha256(bytes) };
+        }
+        const map = await addFile(albedo, t.id + ' albedo', 'texture', 'image/png');
+        nodes.push({ ...base('terrain_' + sha256(t.id).slice(0, 24), t.id), type: 'terrain', parentId: 'terrain', transform: { ...identity(), translation: terrain.center }, size: terrain.size, segments: terrain.segments, heights: terrain.heights, holes: terrain.holes, layers: [], material: { color: '#ffffff', roughness: 1, metalness: 0, map } });
+        overview ??= terrain;
+    }
+    const placements = manifest.instances;
+    if (!overview && placements.length) {
+        const axes = ['x', 'y', 'z'], min = axes.map(k => Math.min(...placements.map(p => p.transform.translation[k]))), max = axes.map(k => Math.max(...placements.map(p => p.transform.translation[k])));
+        overview = { center: vec(...min.map((v, i) => (v + max[i]) / 2)), size: [Math.max(10, max[0] - min[0]), Math.max(10, max[2] - min[2])] };
+    }
+    if (!overview)
+        throw Error('Nothing portable was found in the selected map.');
+    const center = overview.center, span = Math.max(...overview.size), sun = manifest.environment.sun ?? [1, 2, 1];
+    nodes.push({ ...base('environment', 'Environment (portable approximation)'), type: 'environment', preset: 'outdoor', background: '#9dc4e1', intensity: .8, exposure: 1, rotation: 0, fog: null, sky: { mode: 'physical', sun: vec(...sun), turbidity: 3, rayleigh: 1.5, intensity: .8 } });
+    nodes.push({ ...base('camera_overview', 'Overview'), type: 'camera', projection: 'perspective', transform: { ...identity(), translation: vec(center.x + span * .55, center.y + span * .7, center.z + span * .65) }, target: center, fov: 55, near: .1, far: Math.max(3000, span * 6), zoom: 1 });
+    for (const [i, c] of manifest.cameras.entries())
+        nodes.push({ ...base('camera_native_' + i, c.name.slice(0, 160)), type: 'camera', projection: 'perspective', transform: { ...identity(), translation: vec(...c.position) }, target: vec(...c.target), fov: Math.min(175, Math.max(1, c.fov)), near: .1, far: Math.max(3000, span * 6), zoom: 1 });
+    const warnings = [...manifest.warnings, 'Repeated foliage is editable by spatial patch. Member IDs and transforms are retained; per-blade gizmos are not implemented.', 'Portable environment lighting is an approximation; compare against Unreal before validation.'];
+    if (zeroScaleInstances)
+        warnings.push(`${zeroScaleInstances} zero-scale native placements have no visible geometry and were omitted; their original transforms remain in native.json.`);
+    const document = { schemaVersion: 1, id: 'unreal_' + manifest.request_hash.slice(0, 24), workspaceId: 'local-preview', name: manifest.project + ' — ' + manifest.source_level.split('/').pop(), purpose: 'map', revision: 0, nodes, activeCameraId: 'camera_overview', metadata: { unrealSource: { level: manifest.source_level, sha256: manifest.source_sha256, omitted: manifest.omitted }, lifecycle: 'work', warnings } };
+    const input = { schema: 'gripforge.unreal-studio-import.v1', source: { engine: 'unreal', level: manifest.source_level, sha256: manifest.source_sha256, warnings }, document };
+    if (nodes.length > 20000 || Buffer.byteLength(JSON.stringify(input)) > 16 * 1024 * 1024)
+        throw Error('Portable scene exceeds the Studio budget; export smaller regions.');
+    await atomicJson(resolve(dir, 'scene.json'), document);
+    const portable = { schema: 'gripforge.scene-package.v1', scene: 'scene.json', sceneHash: sha256(JSON.stringify(document)), assets, cameras: ['camera_overview', ...nodes.filter(n => n.id.startsWith('camera_native_')).map(n => n.id)], source: input.source, instanceCount: manifest.instances.length - zeroScaleInstances, zeroScaleInstances, nodeCount: nodes.length, lifecycle: 'work' };
+    await atomicJson(resolve(dir, 'manifest.json'), portable);
+    return { directory: dir, input, manifest: portable };
+}

package/dist/weapon-motion-tools.js

@@ -0,0 +1,34 @@
+import { z } from 'zod/v4';
+export const WEAPON_MOTION_TOOL_NAMES = ['gripforge_weapon_profile', 'gripforge_weapon_motion', 'gripforge_weapon_motion_review'];
+export function registerWeaponMotionTools(register, options, s = z) {
+    const v = s.tuple([s.number(), s.number(), s.number()]);
+    const common = { source_id: s.string().regex(/^lib_[A-Za-z0-9_-]{8,64}$/), workspace_id: s.string().max(100).optional() };
+    const profile = { ...common, family: s.enum(['axe', 'sword', 'hammer', 'staff']).optional().describe('Required on the first call. Never infer axe vs sword from geometry alone.'), hand: s.enum(['left', 'right']).optional(), hands: s.union([s.literal(1), s.literal(2)]).optional(), weaponNode: s.string().max(150).optional(), primaryAnchor: v.optional(), secondaryAnchor: v.optional().describe('Required for two hands; weapon-node local coordinates.'), handleAxis: v.optional(), edgeAxis: v.optional() };
+    const generate = { ...profile, slots: s.array(s.enum(['idle', 'walk', 'run', 'attack1', 'attack2', 'attack3', 'hit', 'death', 'dodge', 'block', 'jump_start', 'jump_loop', 'jump_land'])).min(1).max(13).optional(), name: s.string().max(150).optional(), idempotency_key: s.string().regex(/^[a-zA-Z0-9_.:-]{8,160}$/).optional() };
+    const definitions = [
+        { name: WEAPON_MOTION_TOOL_NAMES[0], action: 'profile', shape: profile, description: 'Measure an owned armed GLB instance and return its editable weapon/motion profile: explicit family, holding hand, dimensions, grip anchors, handle and cutting-edge axes. Use gripforge_attach first. Default axes are +Y handle and +Z edge; inspect/correct them. Does not mutate the Library source or certify the initial seating.' },
+        { name: WEAPON_MOTION_TOOL_NAMES[1], action: 'generate', shape: generate, description: 'Queue a persistent weapon-aware motion draft from an owned armed GLB. Axe/hammer get distinct procedural cleave, backhand and overhead attacks; sword uses the explicit UAL sword pack. Staff attacks fail with compatible_motion_missing; no silent sword fallback. Holds Grip finger poses, supports a second-hand anchor with IK. Poll gripforge_generation_read, cancel/retry with generation tools. Returns a NEW work asset and Character Studio URL; never replaces the game/source or visually validates a result. 0 generation credits.' },
+        { name: WEAPON_MOTION_TOOL_NAMES[2], action: 'review', shape: common, description: 'Independently sample the saved weapon-motion GLB at 60 Hz: grip drift, finger pose, wrist rotation, joint discontinuities, second-hand reach and torso overlaps. Reports technicalPassed separately from visualStatus=not_reviewed. Inspect idle, wind-up, impact, recovery and locomotion in GripForge before using the draft. No promotion or mutation.' },
+    ];
+    for (const d of definitions)
+        register(d.name, { title: d.name, description: d.description, inputSchema: d.shape, annotations: { readOnlyHint: d.action !== 'generate', destructiveHint: false, idempotentHint: d.action !== 'generate', openWorldHint: false } }, async (args, extra) => {
+            const key = options.getApiKey();
+            if (!key)
+                return { isError: true, content: [{ type: 'text', text: 'GripForge API key required.' }] };
+            const parsed = s.object(d.shape).strict().safeParse(args);
+            if (!parsed.success)
+                return { isError: true, content: [{ type: 'text', text: parsed.error.message }] };
+            const { workspace_id, ...body } = parsed.data;
+            try {
+                const response = await fetch(options.apiUrl.replace(/\/$/, '') + '/api/v1/weapon-motion', { method: 'POST', headers: { 'content-type': 'application/json', 'x-api-key': key, ...(workspace_id ? { 'x-workspace-id': workspace_id } : {}) }, body: JSON.stringify({ action: d.action, ...body }), signal: AbortSignal.any([AbortSignal.timeout(150000), ...(extra?.signal ? [extra.signal] : [])]) });
+                const data = await response.json();
+                for (const k of ['studio_url', 'status_url'])
+                    if (typeof data[k] === 'string' && data[k].startsWith('/'))
+                        data[k] = new URL(data[k], options.apiUrl).href;
+                return { ...(!response.ok ? { isError: true } : {}), structuredContent: data, content: [{ type: 'text', text: JSON.stringify(data) }] };
+            }
+            catch (error) {
+                return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : 'Weapon motion request failed.' }] };
+            }
+        });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gripforgeai/mcp",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "The tools your AI needs to make your games. Turn prompts into production-ready game assets — animated characters with their weapons attached, seamless textures, terrain, VFX, HUDs — and playable game kits Unity, Godot, Unreal or Three.js can load.",
   "license": "MIT",
   "type": "module",
@@ -9,6 +9,11 @@
   },
   "files": [
     "dist",
+    "runtime/unreal-scene-import.py",
+    "runtime/unreal-scene-export.py",
+    "runtime/unreal-scene-upload.mjs",
+    "runtime/unreal_scene_math.py",
+    "runtime/unreal_spawn_review.py",
     "README.md"
   ],
   "scripts": {

package/runtime/unreal-scene-export.py

@@ -0,0 +1,341 @@
+"""GripForge read-only UE -> portable scene worker (Python commandlet).
+
+Run in a separate editor process with rendering enabled and -GFExportJob=<dir>.
+No source asset/map is saved. Atomic checkpoints survive the MCP request.
+"""
+import hashlib
+import json
+import math
+import os
+import re
+import time
+import traceback
+from pathlib import Path
+import unreal
+
+match = re.search(r'-GFExportJob=(?:"([^"]+)"|(\S+))', unreal.SystemLibrary.get_command_line())
+if not match:
+    raise RuntimeError('Missing -GFExportJob')
+folder = Path(match.group(1) or match.group(2)).resolve()
+request = json.loads((folder / 'request.json').read_text())
+fingerprint = hashlib.sha256((folder / 'request.json').read_bytes()).hexdigest()
+manifest_path = folder / 'native.json'
+state_path = folder / 'status.json'
+
+
+def atomic(path, value):
+    tmp = path.with_suffix(path.suffix + '.tmp')
+    tmp.write_text(json.dumps(value, separators=(',', ':')))
+    tmp.replace(path)
+
+
+def sha(path):
+    h = hashlib.sha256()
+    with path.open('rb') as f:
+        for b in iter(lambda: f.read(1024 * 1024), b''):
+            h.update(b)
+    return h.hexdigest()
+
+
+def cancelled():
+    p = folder / 'control.json'
+    if p.exists() and json.loads(p.read_text()).get('cancel'):
+        raise InterruptedError('Export cancelled; completed assets retained')
+
+
+def progress(stage, **kw):
+    cancelled()
+    atomic(state_path, dict(schema='gripforge.unreal-export-job.v1', request_hash=fingerprint,
+                            status='running', stage=stage, pid=os.getpid(), updated_at=time.time(), **kw))
+
+
+def xyz(v):
+    return [float(v.x), float(v.y), float(v.z)]
+
+
+def transform(t):
+    q = t.rotation
+    p, s = t.translation, t.scale3d
+    return dict(translation=dict(x=p.x*.01, y=p.z*.01, z=p.y*.01),
+                rotation=dict(x=-q.x, y=-q.z, z=-q.y, w=q.w),
+                scale=dict(x=s.x, y=s.z, z=s.y))
+
+
+def native_prop(obj, names, default=None):
+    for name in names:
+        try:
+            return obj.get_editor_property(name)
+        except Exception:
+            pass
+    return default
+
+
+def file_record(file):
+    p = folder / file
+    return dict(file=file, sha256=sha(p), bytes=p.stat().st_size)
+
+
+def done(record):
+    p = folder / record['file']
+    return p.is_file() and sha(p) == record['sha256']
+
+
+def package_file(path):
+    package = path.split('.')[0]
+    if package.startswith('/Game/'):
+        return Path(unreal.Paths.project_content_dir()) / (package[6:] + '.uasset')
+    if package.startswith('/Engine/'):
+        return Path(unreal.Paths.engine_content_dir()) / (package[8:] + '.uasset')
+    return None
+
+
+def png(rt, name):
+    unreal.RenderingLibrary.export_render_target(world, rt, str(folder), name)
+    path = folder / name
+    if not path.is_file() or path.stat().st_size < 64:
+        raise RuntimeError('Render target export failed: ' + name)
+    return file_record(name)
+
+
+try:
+    assert request['schema'] == 'gripforge.unreal-export-request.v1'
+    assert Path(unreal.Paths.get_project_file_path()).resolve() == Path(request['project_file']).resolve()
+    source_file = Path(request['project_file']).parent / 'Content' / (request['source_level'][6:] + '.umap')
+    assert sha(source_file) == request['source_sha256'], 'Source level changed; prepare a new job'
+    progress('loading_source')
+    world = unreal.EditorLoadingAndSavingUtils.load_map(request['source_level'])
+    assert world and world.get_path_name().split('.')[0] == request['source_level']
+    actors = unreal.GameplayStatics.get_all_actors_of_class(world, unreal.Actor)
+    previous = json.loads(manifest_path.read_text()) if manifest_path.exists() else {}
+    if previous:
+        assert previous['request_hash'] == fingerprint, 'Job inputs changed'
+    manifest = dict(schema='gripforge.unreal-export.v1', request_hash=fingerprint,
+                    source_level=request['source_level'], source_sha256=request['source_sha256'],
+                    project=Path(request['project_file']).stem, units='metres', up='Y',
+                    assets=previous.get('assets', {}), instances=[], terrains=previous.get('terrains', []),
+                    environment={}, lights=[], cameras=[], omitted={}, warnings=[])
+    definitions, landscapes, dependencies = {}, [], {}
+
+    def omit(kind):
+        manifest['omitted'][kind] = manifest['omitted'].get(kind, 0) + 1
+
+    def pin(path):
+        p = package_file(path)
+        if p and p.is_file():
+            info = p.stat()
+            dependencies[str(p)] = [info.st_size, info.st_mtime_ns]
+
+    pinned_materials = set()
+    def pin_material(material):
+        if not material or material.get_path_name() in pinned_materials:
+            return
+        pinned_materials.add(material.get_path_name())
+        pin(material.get_path_name())
+        if isinstance(material, unreal.Material):
+            for tex in unreal.MaterialEditingLibrary.get_used_textures(material):
+                pin(tex.get_path_name())
+        else:
+            for value in native_prop(material, ['texture_parameter_values'], []):
+                tex = value.get_editor_property('parameter_value')
+                if tex:
+                    pin(tex.get_path_name())
+            pin_material(native_prop(material, ['parent']))
+
+    for actor in actors:
+        cancelled()
+        cls = actor.get_class().get_path_name()
+        if isinstance(actor, unreal.LandscapeProxy):
+            landscapes.append(actor)
+            continue
+        if isinstance(actor, unreal.DirectionalLight):
+            comp = actor.get_component_by_class(unreal.DirectionalLightComponent)
+            direction = actor.get_actor_forward_vector()
+            color = comp.get_light_color()
+            manifest['environment'] = dict(sun=[-direction.x, -direction.z, -direction.y],
+                                            color=[color.r, color.g, color.b], intensity=comp.get_editor_property('intensity'))
+            continue
+        if isinstance(actor, unreal.CameraActor):
+            c = actor.get_camera_component()
+            p, d = actor.get_actor_location(), actor.get_actor_forward_vector()
+            manifest['cameras'].append(dict(name=actor.get_actor_label(), position=[p.x*.01,p.z*.01,p.y*.01],
+                                             target=[(p.x+d.x*1000)*.01,(p.z+d.z*1000)*.01,(p.y+d.y*1000)*.01], fov=c.field_of_view))
+        # Procedural UE skies and water are reported, not exported as opaque domes/planes.
+        if re.search(r'(?:GoodSky|UltraDynamicSky|SkySphere|SkyAtmosphere|CartoonWater)', cls, re.I):
+            omit(cls)
+            continue
+        components = actor.get_components_by_class(unreal.StaticMeshComponent)
+        supported = 0
+        for component in components:
+            mesh = component.static_mesh
+            if not mesh or not component.is_visible():
+                continue
+            if isinstance(component, unreal.SplineMeshComponent):
+                omit('SplineMeshComponent (deformed mesh requires a dedicated bake)')
+                continue
+            materials = [component.get_material(i) for i in range(component.get_num_materials())]
+            paths = [m.get_path_name() if m else None for m in materials]
+            source = dict(mesh=mesh.get_path_name(), materials=paths)
+            key = hashlib.sha256(json.dumps(source, sort_keys=True).encode()).hexdigest()[:24]
+            definitions[key] = (mesh, materials, source)
+            pin(mesh.get_path_name())
+            for material in materials:
+                pin_material(material)
+            transforms = []
+            if isinstance(component, unreal.InstancedStaticMeshComponent):
+                transforms = [component.get_instance_transform(i, world_space=True) for i in range(component.get_instance_count())]
+            else:
+                transforms = [component.get_world_transform()]
+            for i, t in enumerate(transforms):
+                identifier = component.get_path_name() + ':' + str(i)
+                manifest['instances'].append(dict(id='ue_'+hashlib.sha256(identifier.encode()).hexdigest()[:24],
+                    name=actor.get_actor_label()[:145], source=identifier, asset=key, transform=transform(t),
+                    batch=isinstance(component, unreal.InstancedStaticMeshComponent)))
+            supported += len(transforms)
+        if not supported and not components and any(s in cls for s in ['Niagara', 'Decal', 'SpotLight', 'RectLight', 'PointLight']):
+            omit(cls)
+    manifest['source_snapshot'] = dependencies
+    if previous.get('source_snapshot') and previous['source_snapshot'] != dependencies:
+        raise RuntimeError('Source dependencies changed; use a new export job')
+    atomic(manifest_path, manifest)
+    assert len(manifest['instances']) <= 100000, 'Map exceeds 100,000 portable instances; export regions'
+    progress('inventory', instances=len(manifest['instances']), unique_assets=len(definitions), landscapes=len(landscapes))
+
+    # UE finishes compiling before render-target capture/material baking.
+    # Commandlets do not tick the editor to apply asynchronous shader results.
+    # Preload the export shader as well, before the native blocking compile command.
+    unreal.load_asset('/Engine/EditorLandscapeResources/Landscape_Heightmap_To_RenderTarget2D')
+    unreal.load_asset('/Engine/EditorLandscapeResources/Landscape_Weightmap_To_RenderTarget2D')
+    unreal.SystemLibrary.execute_console_command(world, 'Editor.AsyncAssetCompilationFinishAll')
+    for landscape in landscapes:
+        cancelled()
+        key = landscape.get_name()
+        old = next((t for t in manifest['terrains'] if t['id'] == key), None)
+        if old and old.get('bake_version') == 2 and all(done(old[k]) for k in ['heightmap', 'albedo']):
+            continue
+        progress('terrain', terrain=key)
+        rotation = landscape.get_actor_rotation()
+        assert abs(rotation.pitch)+abs(rotation.yaw)+abs(rotation.roll) < .001, 'Rotated Landscape needs a dedicated adapter'
+        components = landscape.get_components_by_class(unreal.LandscapeComponent)
+        bases = [(int(c.get_editor_property('section_base_x')), int(c.get_editor_property('section_base_y'))) for c in components]
+        q = native_prop(components[0], ['ComponentSizeQuads', 'component_size_quads'])
+        if not q:
+            diffs = [abs(b-a) for axis in [0,1] for a,b in zip(sorted(set(p[axis] for p in bases)), sorted(set(p[axis] for p in bases))[1:])]
+            assert diffs, 'Cannot determine single-component Landscape resolution'
+            q = math.gcd(*diffs)
+        minx, miny = min(p[0] for p in bases), min(p[1] for p in bases)
+        maxx, maxy = max(p[0] for p in bases)+q, max(p[1] for p in bases)+q
+        width, height = maxx-minx+1, maxy-miny+1
+        assert max(width,height) <= 8192, 'Landscape exceeds 8192 height samples; export regions'
+        rt = unreal.RenderingLibrary.create_render_target2d(world, width, height, unreal.TextureRenderTargetFormat.RTF_RGBA8)
+        assert landscape.landscape_export_heightmap_to_render_target(rt, True, False)
+        heightmap = png(rt, key+'-height-rg.png')
+        unreal.RenderingLibrary.release_render_target2d(rt)
+        visibility = None
+        layer_names = [str(n) for n in landscape.get_target_layer_names(True)] if hasattr(landscape, 'get_target_layer_names') else []
+        visibility_name = next((n for n in layer_names if 'visibility' in n.lower()), None)
+        if visibility_name:
+            rt = unreal.RenderingLibrary.create_render_target2d(world, width, height, unreal.TextureRenderTargetFormat.RTF_RGBA8)
+            assert landscape.landscape_export_weightmap_to_render_target(rt, visibility_name), 'Visibility mask export failed'
+            visibility = png(rt, key+'-visibility.png')
+            unreal.RenderingLibrary.release_render_target2d(rt)
+        p, s = landscape.get_actor_location(), landscape.get_actor_scale3d()
+        assert s.x > 0 and s.y > 0 and s.z > 0, 'Reflected Landscape requires a dedicated adapter'
+        center = unreal.Vector(p.x+(minx+maxx)*s.x/2, p.y+(miny+maxy)*s.y/2, p.z+200000)
+        capture = unreal.get_editor_subsystem(unreal.EditorActorSubsystem).spawn_actor_from_class(unreal.SceneCapture2D, center, unreal.Rotator(-90,-90,0))
+        comp = capture.get_component_by_class(unreal.SceneCaptureComponent2D)
+        size = request.get('terrain_texture_size', 4096)
+        rt = unreal.RenderingLibrary.create_render_target2d(world, size, size, unreal.TextureRenderTargetFormat.RTF_RGBA8)
+        comp.set_editor_property('texture_target', rt)
+        comp.set_editor_property('projection_type', unreal.CameraProjectionMode.ORTHOGRAPHIC)
+        # Export a square orthographic projection; the manifest retains the crop.
+        span = max((maxx-minx)*s.x, (maxy-miny)*s.y)
+        comp.set_editor_property('ortho_width', span)
+        comp.set_editor_property('capture_source', unreal.SceneCaptureSource.SCS_BASE_COLOR)
+        comp.set_editor_property('primitive_render_mode', unreal.SceneCapturePrimitiveRenderMode.PRM_USE_SHOW_ONLY_LIST)
+        comp.show_only_actor_components(landscape)
+        comp.set_editor_property('capture_every_frame', False)
+        comp.set_editor_property('capture_on_movement', False)
+        comp.capture_scene()
+        albedo = png(rt, key+'-albedo.png')
+        unreal.get_editor_subsystem(unreal.EditorActorSubsystem).destroy_actor(capture)
+        unreal.RenderingLibrary.release_render_target2d(rt)
+        row = dict(id=key, bake_version=2, heightmap=heightmap, albedo=albedo, width=width, height=height,
+                   base=[minx,miny], components=bases, component_quads=q, origin=xyz(p), scale=xyz(s),
+                   albedo_span_cm=span, material=landscape.get_editor_property('landscape_material').get_path_name())
+        if visibility:
+            row['visibility'] = visibility
+        manifest['terrains'] = [t for t in manifest['terrains'] if t['id'] != key]+[row]
+        atomic(manifest_path, manifest)
+
+    options = unreal.GLTFExportOptions()
+    options.set_editor_property('export_uniform_scale', .01)
+    options.set_editor_property('bake_material_inputs', unreal.GLTFMaterialBakeMode.USE_MESH_DATA)
+    options.set_editor_property('default_material_bake_size', unreal.GLTFMaterialBakeSize(request.get('texture_size',1024), request.get('texture_size',1024)))
+    options.set_editor_property('texture_image_format', unreal.GLTFTextureImageFormat.PNG)
+    options.set_editor_property('adjust_normalmaps', True)
+    options.set_editor_property('export_vertex_colors', False)
+    options.set_editor_property('export_lights', False)
+    options.set_editor_property('export_cameras', False)
+    options.set_editor_property('export_level_sequences', False)
+    (folder/'assets').mkdir(exist_ok=True)
+    for index, (key, (mesh, materials, source)) in enumerate(definitions.items()):
+        progress('meshes', completed=index, total=len(definitions), asset=mesh.get_name())
+        old = manifest['assets'].get(key)
+        if old and done(old):
+            continue
+        # Export one neutral instance of each mesh/material combination. No mutation of Library/native assets.
+        temp = unreal.get_editor_subsystem(unreal.EditorActorSubsystem).spawn_actor_from_class(unreal.StaticMeshActor, unreal.Vector(0,0,0))
+        comp = temp.static_mesh_component
+        comp.set_static_mesh(mesh)
+        for slot, material in enumerate(materials):
+            if material:
+                comp.set_material(slot, material)
+        name = 'assets/'+key+'.glb'
+        try:
+            unreal.GLTFExporter.export_to_gltf(world, str(folder/name), options, {temp})
+            assert (folder/name).is_file(), 'GLB export failed: '+source['mesh']
+            manifest['assets'][key] = dict(file_record(name), name=mesh.get_name(), source=source)
+            atomic(manifest_path, manifest)
+        finally:
+            unreal.get_editor_subsystem(unreal.EditorActorSubsystem).destroy_actor(temp)
+    if manifest['terrains']:
+        progress('native_reference')
+        terrain = manifest['terrains'][0]
+        o, s, base = terrain['origin'], terrain['scale'], terrain['base']
+        sx, sy = (terrain['width']-1)*s[0], (terrain['height']-1)*s[1]
+        span = max(sx, sy)
+        target = unreal.Vector(o[0]+(base[0]+(terrain['width']-1)/2)*s[0], o[1]+(base[1]+(terrain['height']-1)/2)*s[1], o[2])
+        position = target + unreal.Vector(span*.55, span*.65, span*.7)
+        capture = unreal.get_editor_subsystem(unreal.EditorActorSubsystem).spawn_actor_from_class(unreal.SceneCapture2D, position, unreal.MathLibrary.find_look_at_rotation(position,target))
+        try:
+            comp = capture.get_component_by_class(unreal.SceneCaptureComponent2D)
+            rt = unreal.RenderingLibrary.create_render_target2d(world, 1600, 900, unreal.TextureRenderTargetFormat.RTF_RGBA8)
+            comp.set_editor_property('texture_target', rt)
+            comp.set_editor_property('fov_angle', math.degrees(2*math.atan(math.tan(math.radians(55)/2)*1600/900)))
+            comp.set_editor_property('capture_source', unreal.SceneCaptureSource.SCS_FINAL_COLOR_LDR)
+            comp.set_editor_property('capture_every_frame', False)
+            comp.set_editor_property('capture_on_movement', False)
+            unreal.SystemLibrary.execute_console_command(world, 'Editor.AsyncAssetCompilationFinishAll')
+            comp.capture_scene()
+            manifest['native_reference'] = png(rt, 'unreal-overview.png')
+            unreal.RenderingLibrary.release_render_target2d(rt)
+        finally:
+            unreal.get_editor_subsystem(unreal.EditorActorSubsystem).destroy_actor(capture)
+    for file, before in dependencies.items():
+        info = Path(file).stat()
+        assert [info.st_size,info.st_mtime_ns] == before, 'Source changed during export: '+file
+    assert sha(source_file) == request['source_sha256'], 'Source level changed during export'
+    manifest['warnings'] = [
+        'Native Blueprint logic, Niagara, decals, animated water and procedural sky are not portable; omitted classes are counted.',
+        'Complex static materials are baked. Time/view/world-dependent shader behavior is not retained.',
+        'Landscape base color is a top-down native bake; material paint layers remain a source provenance, not an editable UE shader graph.',
+    ]
+    manifest['status'] = 'exported-awaiting-gripforge-review'
+    atomic(manifest_path,manifest)
+    atomic(state_path,dict(status='succeeded',stage='exported',request_hash=fingerprint,updated_at=time.time(),
+                          instances=len(manifest['instances']),assets=len(manifest['assets']),terrains=len(manifest['terrains']),lifecycle='work'))
+except Exception as error:
+    atomic(state_path, dict(status='cancelled' if isinstance(error,InterruptedError) else 'failed',
+                           error=str(error), traceback=traceback.format_exc(), request_hash=fingerprint,updated_at=time.time()))
+    unreal.log_error(traceback.format_exc())
+    raise