reverseport 1.6.0 → 1.7.0

package/port/src/il2cpp.mjs

@@ -0,0 +1,148 @@
+// re_il2cpp: names out of a Unity IL2CPP global-metadata.dat — assemblies, namespaces, types, methods and string
+// literals — so a Unity game without its C# source still yields a class map to port or rebuild from.
+// The header is a list of (offset, size) section pairs whose order differs between metadata versions (24–31+),
+// so sections are recognised by validating their records against the identifier string table instead of trusting
+// fixed indices. Only names are read; no code is decompiled (the code lives in GameAssembly/libil2cpp/.wasm as
+// native code: re_binary). Encrypted or obfuscated metadata (wrong magic, unreadable string table) is reported.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { RPError, requireFile, limit } from './util.mjs';
+import { workspaceDir } from './workspace.mjs';
+
+const MAGIC = 0xfab11baf;
+
+export function parseMetadata(buf) {
+  if (buf.length < 64) throw new RPError('BAD_FORMAT', 'File too small for IL2CPP metadata.');
+  const magic = buf.readUInt32LE(0);
+  if (magic !== MAGIC) throw new RPError('BAD_FORMAT', `Not IL2CPP metadata (magic 0x${magic.toString(16)}); the game may encrypt or obfuscate it. Reported, not decrypted.`);
+  const version = buf.readInt32LE(4);
+  // Header: pairs of (int32 offset, int32 size) until the first section starts.
+  const pairs = [];
+  let firstData = buf.length;
+  for (let p = 8; p + 8 <= Math.min(buf.length, firstData); p += 8) {
+    const off = buf.readInt32LE(p), size = buf.readInt32LE(p + 4);
+    if (off < 0 || size < 0 || off + size > buf.length) break;
+    pairs.push({ index: pairs.length, offset: off, size });
+    if (off > 0 && off < firstData) firstData = off;
+  }
+  // String table: the section of NUL-terminated identifiers. It is pair 2 in every known version; verify.
+  const isIdentTable = s => { if (!s || s.size < 4) return false; const b = buf.subarray(s.offset, s.offset + Math.min(s.size, 4096)); let printable = 0, nul = 0; for (const c of b) { if (c === 0) nul++; else if (c >= 0x20 && c < 0x7f) printable++; } return nul > 4 && printable + nul > b.length * 0.97; };
+  const strSec = isIdentTable(pairs[2]) ? pairs[2] : pairs.find(isIdentTable);
+  if (!strSec) throw new RPError('BAD_FORMAT', 'No readable identifier table: metadata is probably encrypted or obfuscated. Reported, not decrypted.');
+  const str = idx => { if (idx < 0 || idx >= strSec.size) return null; const s = strSec.offset + idx; const e = buf.indexOf(0, s); return e < 0 || e - s > 1024 ? null : buf.toString('utf8', s, e); };
+  const validName = idx => { const s = str(idx); return s != null && /^[\w<>`.$|=@-]*$/.test(s); };
+
+  // Images (40 bytes in v24.1+): nameIndex, assemblyIndex, typeStart, typeCount, … ; names end in .dll.
+  let images = null;
+  for (const s of pairs) {
+    if (s === strSec || s.size === 0 || s.size % 40) continue;
+    const n = s.size / 40;
+    const out = [];
+    let ok = true, expect = 0;
+    for (let i = 0; i < n && ok; i++) {
+      const r = s.offset + i * 40;
+      const name = str(buf.readInt32LE(r)), typeStart = buf.readInt32LE(r + 8), typeCount = buf.readUInt32LE(r + 12);
+      if (!name || !/\.dll$/i.test(name) || typeStart !== expect) ok = false; else { out.push({ name, typeStart, typeCount }); expect += typeCount; }
+    }
+    if (ok && out.length) { images = { section: s.index, list: out, typeTotal: expect }; break; }
+  }
+  if (!images) throw new RPError('BAD_FORMAT', 'Could not find the image (assembly) table; this metadata version or layout is not recognised.');
+
+  // Methods: records with nameIndex at 0 and declaringType at 4 (a type index); record size 24–40 depending on version.
+  let methods = null;
+  for (const s of pairs) {
+    if (s === strSec || s.index === images.section || s.size < 24) continue;
+    for (const rec of [32, 36, 28, 24, 40]) {
+      if (s.size % rec) continue;
+      const n = s.size / rec, sample = Math.min(n, 80);
+      let good = 0, lastDecl = -1, monotone = true;
+      for (let i = 0; i < sample; i++) { const r = s.offset + i * rec; const nm = buf.readInt32LE(r), decl = buf.readInt32LE(r + 4); if (validName(nm) && str(nm) && decl >= 0 && decl < images.typeTotal) good++; if (decl < lastDecl) monotone = false; lastDecl = decl; }
+      if (good >= sample * 0.95 && monotone) { methods = { section: s.index, rec, count: n }; break; }
+    }
+    if (methods) break;
+  }
+  // Type definitions: the section whose size divides by the type total and whose records start with name/namespace indices.
+  let types = null;
+  for (const s of pairs) {
+    if (s === strSec || s.index === methods?.section || s.index === images.section || !images.typeTotal || s.size % images.typeTotal) continue;
+    const rec = s.size / images.typeTotal;
+    if (rec < 48 || rec > 160) continue;
+    const sample = Math.min(images.typeTotal, 64);
+    let good = 0;
+    for (let i = 0; i < sample; i++) { const r = s.offset + i * rec; if (validName(buf.readInt32LE(r)) && validName(buf.readInt32LE(r + 4)) && str(buf.readInt32LE(r))) good++; }
+    if (good >= sample * 0.95) { types = { section: s.index, rec }; break; }
+  }
+  if (!types) throw new RPError('BAD_FORMAT', 'Could not find the type definition table for this metadata version.');
+  const typeList = [];
+  for (let i = 0; i < images.typeTotal; i++) {
+    const r = pairs[types.section].offset + i * types.rec;
+    typeList.push({ index: i, name: str(buf.readInt32LE(r)), namespace: str(buf.readInt32LE(r + 4)) || '', methods: [] });
+  }
+  for (const img of images.list) for (let i = img.typeStart; i < img.typeStart + img.typeCount; i++) typeList[i].assembly = img.name;
+
+  let methodCount = 0;
+  if (methods) for (let i = 0; i < methods.count; i++) { const r = pairs[methods.section].offset + i * methods.rec; const name = str(buf.readInt32LE(r)); const decl = buf.readInt32LE(r + 4); if (name && typeList[decl]) { typeList[decl].methods.push(name); methodCount++; } }
+
+  // String literals: (length, dataIndex) pairs into the literal data blob (pair 0/1 in v24–v29).
+  const literals = [];
+  const litSec = pairs[0], litData = pairs[1];
+  if (litSec && litData && litSec.size % 8 === 0 && litSec.size) {
+    for (let i = 0; i < Math.min(litSec.size / 8, 200000); i++) { const len = buf.readUInt32LE(litSec.offset + i * 8), di = buf.readInt32LE(litSec.offset + i * 8 + 4); if (di < 0 || di + len > litData.size) { literals.length = 0; break; } literals.push(buf.toString('utf8', litData.offset + di, litData.offset + di + len)); }
+  }
+  return { version, sections: pairs.length, images: images.list, types: typeList, methodCount, literals, layout: { strings: strSec.index, images: images.section, types: types.section, typeRecord: types.rec, methods: methods?.section ?? null, methodRecord: methods?.rec ?? null } };
+}
+
+const SYSTEM_ASM = /^(mscorlib|System|Mono\.|Unity\.|UnityEngine|netstandard|Microsoft\.|DOTween|TextMeshPro|Newtonsoft)/;
+
+/** C# skeleton per assembly: namespaces, classes and method names, for port_plan/re_blueprint to work from. */
+export function skeleton(meta, { includeSystem = false } = {}) {
+  const byAsm = new Map();
+  for (const t of meta.types) {
+    if (!t.name || t.name === '<Module>' || t.name.startsWith('<')) continue;
+    if (!includeSystem && SYSTEM_ASM.test(t.assembly ?? '')) continue;
+    if (!byAsm.has(t.assembly)) byAsm.set(t.assembly, []);
+    byAsm.get(t.assembly).push(t);
+  }
+  const files = [];
+  for (const [asm, list] of byAsm) {
+    const lines = [`// ${asm}: names recovered by ReversePort re_il2cpp from global-metadata.dat. Bodies are not in the metadata.`, ''];
+    const byNs = new Map();
+    for (const t of list) { if (!byNs.has(t.namespace)) byNs.set(t.namespace, []); byNs.get(t.namespace).push(t); }
+    for (const [ns, ts] of [...byNs].sort((a, b) => a[0].localeCompare(b[0]))) {
+      const ind = ns ? '    ' : '';
+      if (ns) lines.push(`namespace ${ns}`, '{');
+      for (const t of ts) {
+        const cls = t.name.replace(/`\d+$/, '');
+        lines.push(`${ind}public class ${cls}`, `${ind}{`);
+        for (const m of [...new Set(t.methods)]) if (!m.startsWith('<')) lines.push(`${ind}    // ${m}()`);
+        lines.push(`${ind}}`, '');
+      }
+      if (ns) lines.push('}', '');
+    }
+    files.push({ name: `${asm.replace(/\.dll$/i, '')}.cs`, text: lines.join('\n'), types: list.length });
+  }
+  return files;
+}
+
+export async function il2cppTool({ file, out, match, includeSystem = false, limit: max = 400 } = {}) {
+  if (!file) throw new RPError('INVALID_ARGUMENT', 'file is required: global-metadata.dat (in <Game>_Data/il2cpp_data/Metadata/ or Il2CppData/Metadata in WebGL).');
+  const { abs } = await requireFile(file);
+  const meta = parseMetadata(await fs.readFile(abs));
+  const q = match ? String(match).toLowerCase() : null;
+  const gameTypes = meta.types.filter(t => t.name && !t.name.startsWith('<') && (includeSystem || !SYSTEM_ASM.test(t.assembly ?? '')));
+  const shown = gameTypes.filter(t => !q || `${t.namespace}.${t.name} ${t.methods.join(' ')}`.toLowerCase().includes(q));
+  const unityCallbacks = ['Awake', 'Start', 'Update', 'FixedUpdate', 'LateUpdate', 'OnEnable', 'OnDisable', 'OnDestroy', 'OnTriggerEnter', 'OnCollisionEnter', 'OnTriggerEnter2D', 'OnCollisionEnter2D'];
+  const behaviours = gameTypes.filter(t => t.methods.some(m => unityCallbacks.includes(m))).map(t => `${t.namespace ? t.namespace + '.' : ''}${t.name}`);
+  const files = skeleton(meta, { includeSystem });
+  const dir = out ? path.resolve(out) : path.join(await workspaceDir('il2cpp'), path.basename(path.dirname(path.dirname(abs))) || 'game');
+  await fs.mkdir(dir, { recursive: true });
+  const written = [];
+  for (const f of files) { const p = path.join(dir, f.name); await fs.writeFile(p, f.text); written.push(p); }
+  const lit = meta.literals.filter(s => s.length > 1 && s.length < 200);
+  return {
+    file: abs, metadataVersion: meta.version, assemblies: meta.images.map(i => ({ name: i.name, types: i.typeCount })), types: meta.types.length, gameTypes: gameTypes.length, methods: meta.methodCount,
+    behaviours: limit(behaviours, 300), typesMatching: limit(shown.map(t => ({ name: `${t.namespace ? t.namespace + '.' : ''}${t.name}`, assembly: t.assembly, methods: [...new Set(t.methods)].slice(0, 40) })), max),
+    stringLiterals: { count: meta.literals.length, sample: lit.slice(0, 80) }, written, layout: meta.layout,
+    next: 'The skeleton lists every game class and method name; behaviours are MonoBehaviours (Unity callbacks). Port or rebuild from it with re_blueprint/port_plan; for method bodies, read the native code (GameAssembly.dll / libil2cpp.so / .wasm) with re_binary and the deep-analysis engine, matching names from here.',
+  };
+}

package/port/src/jsworkspace.mjs

@@ -80,7 +80,7 @@ export function packageCandidates({ dir, pkg }, sub) {
       const pre = k.slice(0, star), post = k.slice(star + 1);
       if (key.startsWith(pre) && key.endsWith(post) && key.length >= pre.length + post.length) {
         const t = exportTarget(v);
-        if (t) out.push(t.replace('*', key.slice(pre.length, key.length - post.length)));
+        if (t) out.push(t.replaceAll('*', () => key.slice(pre.length, key.length - post.length))); // Node replaces every * in the target; the function keeps $&, $1… in the match literal
       }
     }
   } else if (!sub && (typeof ex === 'string' || Array.isArray(ex))) { const t = exportTarget(ex); if (t) out.push(t); }
@@ -144,7 +144,7 @@ export async function tsconfigAliases(files, byRel) {
             if (!spec.startsWith(pre) || !spec.endsWith(post) || spec.length < pre.length + post.length) continue;
             wild = spec.slice(pre.length, spec.length - post.length);
           }
-          for (const t of [targets].flat()) if (typeof t === 'string') out.push(path.posix.normalize(path.posix.join(cfg.baseDir || '.', t.replace('*', wild))));
+          for (const t of [targets].flat()) if (typeof t === 'string') out.push(path.posix.normalize(path.posix.join(cfg.baseDir || '.', t.replaceAll('*', () => wild))));
         }
         return out;
       }

package/port/src/knowledge.mjs

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { RPError } from './util.mjs';
 import { closest } from './agent.mjs';
+import { physicsProfile } from './physics.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'knowledge');
 export const ENGINES = JSON.parse(fs.readFileSync(path.join(ROOT, 'engines.json'), 'utf8'));
@@ -45,7 +46,8 @@ export function portMapTool({ from, to, query, topic } = {}) {
   }
   const q = query ? String(query).toLowerCase() : null;
   const entries = map.entries.filter(e => (!topic || e.topic === topic) && (!q || `${e.id} ${e.topic} ${e.from} ${e.to} ${e.notes ?? ''}`.toLowerCase().includes(q))).map(({ re, leftoverRe, pattern, leftover, ...e }) => e);
-  return { title: map.title, from: a, to: b, fromEngine: ENGINES[a] ?? null, toEngine: ENGINES[b] ?? null, conventions: map.conventions, topics: [...new Set(map.entries.map(e => e.topic))], entries, ...(!q && !topic ? { hint: 'This is the whole map; query or topic narrows it (e.g. {query:"signal"}). port_unit already lists the entries a file uses.' } : {}) };
+  let physics = null; try { const p = physicsProfile({ from: a, to: b }); physics = { differences: p.differences, from: p.profiles.from, to: p.profiles.to, hint: 'port_convert {from, to, physics:{gravity, fixedStep, linearDamp, friction, bounce, jumpVelocity, layers}} converts the actual numbers.' }; } catch { /* no profile for this pair */ }
+  return { title: map.title, from: a, to: b, fromEngine: ENGINES[a] ?? null, toEngine: ENGINES[b] ?? null, conventions: map.conventions, topics: [...new Set(map.entries.map(e => e.topic))], entries, ...(physics && !q && !topic ? { physics } : {}), ...(!q && !topic ? { hint: 'This is the whole map; query or topic narrows it (e.g. {query:"signal"}). port_unit already lists the entries a file uses.' } : {}) };
 }
 
 /** Which mapped APIs does this source text use? */

package/port/src/physics.mjs

@@ -0,0 +1,135 @@
+// Physics profiles: what each engine does differently (gravity, fixed step, damping, friction/bounce combination,
+// layers, character controllers, units) and how to carry one project's physics numbers to another engine.
+// Numbers come from the engines' documented defaults and source (Godot: PhysicsMaterial.xml, godot_body_pair_3d.cpp;
+// Unity: Physics/Rigidbody/PhysicMaterial manual; Unreal: UPhysicalMaterial/CharacterMovementComponent docs).
+import { RPError } from './util.mjs';
+
+export const PHYSICS = {
+  godot: {
+    label: 'Godot 4', units: 'm (3D) / px (2D, 100 px ≈ 1 m by default)', gravity3d: 9.8, gravity2d: 980, fixedStep: 1 / 60, fixedStepSetting: 'physics/common/physics_ticks_per_second (60)',
+    engineSetting: 'physics/3d/physics_engine: "Jolt Physics" (default since 4.4) or "GodotPhysics3D"',
+    gravitySetting: 'physics/3d/default_gravity (9.8) + physics/3d/default_gravity_vector; 2D: physics/2d/default_gravity (980)',
+    linearDamp: 0.1, angularDamp: 0.1, dampSetting: 'physics/3d/default_linear_damp (0.1) and default_angular_damp (0.1); per body linear_damp with linear_damp_mode Combine (adds to default) or Replace',
+    dampFormula: 'v *= 1 - min(damp * dt, 1) per physics tick (same shape as Unity drag and Unreal damping)',
+    friction: 1.0, bounce: 0.0, frictionCombine: 'min of both (GodotPhysics; rough=true wins), Jolt: geometric mean sqrt(f1*f2)', bounceCombine: 'sum clamped to 1 (GodotPhysics; absorbent subtracts), Jolt: max',
+    material: 'PhysicsMaterial { friction (one value, no static/dynamic split), bounce, rough, absorbent } on the body or shape owner',
+    layers: '32 layers; each body has collision_layer (what it is) and collision_mask (what it scans). A collides with B when A.mask includes B.layer — one-directional per body, no global matrix',
+    character: 'CharacterBody3D: no gravity, you integrate velocity and call move_and_slide(); floor_max_angle 45°, floor_snap_length 0.1, wall_min_slide_angle 15°',
+    ccd: 'RigidBody3D.continuous_cd (Jolt supports it; GodotPhysics uses it for shape casts)', mass: 'RigidBody3D.mass (kg, default 1); center_of_mass_mode Auto',
+    interpolation: 'physics/common/physics_interpolation (4.3+) or manual lerp in _process',
+  },
+  'godot-csharp': { alias: 'godot' },
+  unity: {
+    label: 'Unity', units: 'm (3D) / units with Pixels Per Unit (2D sprites, default 100 px per unit)', gravity3d: 9.81, gravity2d: 9.81, fixedStep: 0.02, fixedStepSetting: 'Time.fixedDeltaTime / Project Settings ▸ Time ▸ Fixed Timestep (0.02 s = 50 Hz)',
+    engineSetting: 'PhysX (3D) / Box2D (2D); Unity 6: Physics ▸ Simulation Mode',
+    gravitySetting: 'Physics.gravity (0, -9.81, 0); Physics2D.gravity (0, -9.81)',
+    linearDamp: 0, angularDamp: 0.05, dampSetting: 'Rigidbody.drag / linearDamping (0) and angularDrag / angularDamping (0.05) per body; no project default',
+    dampFormula: 'v *= clamp01(1 - drag * fixedDeltaTime) per fixed step',
+    friction: 0.6, bounce: 0.0, frictionCombine: 'Average by default (Minimum, Maximum, Multiply per PhysicMaterial)', bounceCombine: 'Average by default',
+    material: 'PhysicMaterial { dynamicFriction (0.6), staticFriction (0.6), bounciness (0), frictionCombine, bounceCombine } on the Collider',
+    layers: '32 layers with a global Layer Collision Matrix (ProjectSettings/DynamicsManager.asset m_LayerCollisionMatrix); a pair collides when the matrix allows it, symmetric',
+    character: 'CharacterController: no gravity, you add it and call Move(); slopeLimit 45°, stepOffset 0.3, skinWidth 0.08, minMoveDistance 0.001',
+    ccd: 'Rigidbody.collisionDetectionMode (Discrete, Continuous, ContinuousDynamic, ContinuousSpeculative)', mass: 'Rigidbody.mass (kg, default 1); automatic center of mass',
+    interpolation: 'Rigidbody.interpolation (None, Interpolate, Extrapolate)',
+  },
+  unreal: {
+    label: 'Unreal Engine 5', units: 'cm', gravity3d: 980, gravity2d: 980, fixedStep: null, fixedStepSetting: 'variable (frame rate) by default; Project Settings ▸ Physics ▸ Substepping or Tick Physics Async for a fixed step',
+    engineSetting: 'Chaos',
+    gravitySetting: 'Project Settings ▸ Physics ▸ Default Gravity Z (-980 cm/s²); WorldSettings GlobalGravityZ; per actor GravityScale',
+    linearDamp: 0.01, angularDamp: 0, dampSetting: 'BodyInstance LinearDamping (0.01) and AngularDamping (0) per primitive component',
+    dampFormula: 'v *= max(0, 1 - damping * dt) per substep (PhysX/Chaos convention)',
+    friction: 0.7, bounce: 0.3, frictionCombine: 'Average by default (Min, Multiply, Max; bOverrideFrictionCombineMode on the physical material)', bounceCombine: 'Average by default',
+    material: 'UPhysicalMaterial { Friction (0.7), StaticFriction (0, uses Friction unless overridden), Restitution (0.3), Density (1 g/cm³) } assigned to the mesh or collision',
+    layers: 'Object channels (WorldStatic, Pawn, PhysicsBody, custom…) with per-component responses Block/Overlap/Ignore, usually via Collision Presets; asymmetric responses possible (both must Block to collide)',
+    character: 'CharacterMovementComponent: gravity applied by the component (GravityScale 1), JumpZVelocity 420 cm/s, MaxWalkSpeed 600 cm/s, GroundFriction 8, BrakingDecelerationWalking 2048, MaxStepHeight 45 cm, WalkableFloorAngle 44.765°',
+    ccd: 'BodyInstance bUseCCD', mass: 'computed from volume × material density unless MassInKg override is set (default: a 1 m cube ≈ 1000 kg)',
+    interpolation: 'smooth by default with substepping; Chaos async tick interpolates',
+  },
+  threejs: {
+    label: 'three.js + Rapier (or cannon-es)', units: 'm', gravity3d: 9.81, gravity2d: 9.81, fixedStep: 1 / 60, fixedStepSetting: 'world.timestep (Rapier default 1/60) driven by your own accumulator',
+    engineSetting: 'no physics in three.js itself; Rapier (recommended), cannon-es, ammo.js',
+    gravitySetting: 'new RAPIER.World({ x: 0, y: -9.81, z: 0 })',
+    linearDamp: 0, angularDamp: 0, dampSetting: 'RigidBodyDesc.setLinearDamping / setAngularDamping per body',
+    dampFormula: 'v *= 1 / (1 + damping * dt) per step (Rapier)',
+    friction: 0.5, bounce: 0.0, frictionCombine: 'Average by default (ColliderDesc.setFrictionCombineRule: Average, Min, Multiply, Max)', bounceCombine: 'Average by default (setRestitutionCombineRule)',
+    material: 'ColliderDesc.setFriction / setRestitution per collider',
+    layers: 'collision groups: 16 membership bits + 16 filter bits packed in one u32 (ColliderDesc.setCollisionGroups); pair collides when each side\'s filter includes the other\'s membership',
+    character: 'KinematicCharacterController: you apply gravity to the desired translation; setMaxSlopeClimbAngle, enableAutostep, enableSnapToGround',
+    ccd: 'RigidBodyDesc.setCcdEnabled(true)', mass: 'from collider density (ColliderDesc.setDensity, default 1) or setMass; three.js has none',
+    interpolation: 'copy body translation/rotation into the mesh after each step; interpolate with the accumulator alpha',
+  },
+};
+const profile = e => { const k = String(e ?? '').toLowerCase().replace(/[^a-z-]/g, ''); const p = PHYSICS[k]; if (!p) throw new RPError('INVALID_ARGUMENT', `Unknown engine ${e}; physics profiles: ${Object.keys(PHYSICS).join(', ')}.`); return p.alias ? { ...PHYSICS[p.alias], label: `${PHYSICS[p.alias].label} (C#)` } : p; };
+const r4 = x => Math.round(x * 1e4) / 1e4;
+
+/**
+ * Carry physics numbers from one engine to another.
+ * values: { gravity, fixedStep, linearDamp, angularDamp, friction, bounce, mass, speed, jumpVelocity, jumpHeight, force, impulse, layers: [{name, index, collidesWith:[...]}], dimension: '2d'|'3d' }
+ */
+export function physicsProfile({ from, to, values = {} } = {}) {
+  const a = profile(from), b = profile(to);
+  const srcKey = String(from).toLowerCase().replace(/[^a-z-]/g, ''), dstKey = String(to).toLowerCase().replace(/[^a-z-]/g, '');
+  const dim = values.dimension === '2d' ? '2d' : '3d';
+  const unitFactor = (dstKey === 'unreal' ? 100 : 1) / (srcKey === 'unreal' ? 100 : 1) * (dim === '2d' ? ((dstKey.startsWith('godot') ? 100 : 1) / (srcKey.startsWith('godot') ? 100 : 1)) : 1);
+  const converted = {};
+  const settings = [];
+  const notes = [];
+  const g = v => v == null ? null : r4(Math.abs(v) * unitFactor);
+  const gravity = values.gravity != null ? g(values.gravity) : null;
+  const defaultG = dim === '2d' ? b.gravity2d : b.gravity3d;
+  if (gravity != null) {
+    converted.gravity = gravity;
+    settings.push(`${b.gravitySetting} → ${gravity}${dstKey === 'unreal' ? ' (Default Gravity Z = -' + gravity + ')' : ''}`);
+    if (Math.abs(gravity - defaultG) > 1e-6) notes.push(`Gravity ${gravity} differs from the ${b.label} default ${defaultG}: set it in the project, not per body, or jumps and falls change.`);
+  } else settings.push(`gravity: ${a.label} default ${dim === '2d' ? a.gravity2d : a.gravity3d} → ${b.label} default ${defaultG} (${b.gravitySetting})`);
+  const step = values.fixedStep ?? a.fixedStep;
+  if (step != null) {
+    converted.fixedStep = b.fixedStep ?? step;
+    if (b.fixedStep == null) { settings.push(`${b.fixedStepSetting}: enable substepping or async physics tick and set 1/${Math.round(1 / step)} s to keep a fixed ${Math.round(1 / step)} Hz step`); notes.push('Unreal physics runs at frame rate by default; per-frame forces and friction-based movement then depend on FPS unless substepping is on.'); }
+    else if (Math.abs(step - b.fixedStep) > 1e-9) { settings.push(`${b.fixedStepSetting} → ${Math.round(1 / step)} Hz to match the source (or keep ${Math.round(1 / b.fixedStep)} Hz and retune)`); notes.push(`Fixed step changes from ${Math.round(1 / step)} Hz to ${Math.round(1 / b.fixedStep)} Hz by default: anything added per physics tick (forces in FixedUpdate/_physics_process, per-tick velocity += …) scales by ${r4(step / b.fixedStep)} unless you multiply by delta.`); }
+  }
+  for (const k of ['linearDamp', 'angularDamp']) {
+    if (values[k] == null) continue;
+    converted[k] = values[k];
+    const def = b[k];
+    settings.push(`${b.dampSetting.split(';')[0]}: ${values[k]}${dstKey.startsWith('godot') && values[k] !== def ? ` with ${k === 'linearDamp' ? 'linear_damp_mode' : 'angular_damp_mode'} = Replace (Combine adds the project default ${def})` : ''}`);
+  }
+  if ((values.linearDamp == null || values.angularDamp == null) && (a.linearDamp !== b.linearDamp || a.angularDamp !== b.angularDamp)) notes.push(`Default damping differs: ${a.label} ${a.linearDamp}/${a.angularDamp} vs ${b.label} ${b.linearDamp}/${b.angularDamp} (linear/angular). Bodies that relied on defaults coast differently; set them explicitly.`);
+  if (values.friction != null || values.bounce != null) {
+    if (values.friction != null) converted.friction = values.friction;
+    if (values.bounce != null) converted.bounce = values.bounce;
+    settings.push(`${b.material}: friction ${values.friction ?? '(default ' + b.friction + ')'}, bounce ${values.bounce ?? '(default ' + b.bounce + ')'}`);
+    if (a.frictionCombine !== b.frictionCombine) notes.push(`Friction combination differs: ${a.label} = ${a.frictionCombine}; ${b.label} = ${b.frictionCombine}. Two surfaces of friction ${values.friction ?? a.friction} and ${b.friction} land at different values; put the same friction on both bodies or set the combine mode where the engine allows.`);
+    if (a.bounceCombine !== b.bounceCombine) notes.push(`Bounce combination differs: ${a.label} = ${a.bounceCombine}; ${b.label} = ${b.bounceCombine}.`);
+  } else notes.push(`Default material differs: friction ${a.friction} → ${b.friction}, bounce ${a.bounce} → ${b.bounce}; objects slide and bounce differently unless materials are set on both sides.`);
+  if (values.mass != null) { converted.mass = values.mass; settings.push(`${b.mass}: ${values.mass}`); if (dstKey === 'unreal') notes.push('Unreal derives mass from volume and density: set MassInKg (Override Mass) on each body or weights are off by orders of magnitude.'); }
+  for (const k of ['speed', 'force', 'impulse']) if (values[k] != null) converted[k] = g(values[k]);
+  if (values.jumpHeight != null) { converted.jumpHeight = g(values.jumpHeight); converted.jumpVelocity = r4(Math.sqrt(2 * (gravity ?? defaultG) * converted.jumpHeight)); settings.push(`jump velocity for ${converted.jumpHeight} ${dstKey === 'unreal' ? 'cm' : 'units'} under gravity ${gravity ?? defaultG}: ${converted.jumpVelocity}`); }
+  else if (values.jumpVelocity != null) { const srcG = values.gravity != null ? Math.abs(values.gravity) : (dim === '2d' ? a.gravity2d : a.gravity3d); const h = (values.jumpVelocity ** 2) / (2 * srcG); converted.jumpHeight = g(h); converted.jumpVelocity = r4(Math.sqrt(2 * (gravity ?? defaultG) * converted.jumpHeight)); settings.push(`jump velocity ${values.jumpVelocity} (height ${r4(h)}) → ${converted.jumpVelocity} so the height stays ${converted.jumpHeight} under gravity ${gravity ?? defaultG}`); }
+  if (values.layers?.length) {
+    converted.layers = values.layers.map((l, i) => {
+      const idx = l.index ?? i;
+      const peers = l.collidesWith ?? [];
+      const bit = n => 1 << n;
+      const indexOf = name => { const pos = values.layers.findIndex(x => x.name === name); return pos < 0 ? -1 : (values.layers[pos].index ?? pos); };
+      const mask = peers.map(p => (typeof p === 'number' ? p : indexOf(p))).filter(n => n >= 0).reduce((m, n) => m | bit(n), 0);
+      if (dstKey.startsWith('godot')) return { name: l.name, collision_layer: bit(idx), collision_mask: mask, godot: `collision_layer = ${bit(idx)}, collision_mask = ${mask} (layer ${idx + 1})` };
+      if (dstKey === 'threejs') return { name: l.name, membership: bit(idx) & 0xffff, filter: mask & 0xffff, rapier: `setCollisionGroups(${((bit(idx) & 0xffff) << 16 | (mask & 0xffff)) >>> 0})` };
+      if (dstKey === 'unreal') return { name: l.name, channel: `ECC_GameTraceChannel${idx + 1} ("${l.name}")`, responses: Object.fromEntries(values.layers.map(x => [x.name, peers.includes(x.name) || peers.includes(x.index) ? 'Block' : 'Ignore'])) };
+      return { name: l.name, layer: idx, matrixRow: Object.fromEntries(values.layers.map(x => [x.name, peers.includes(x.name) || peers.includes(x.index)])) };
+    });
+    if (srcKey === 'unity' && dstKey.startsWith('godot')) notes.push('Unity\'s layer matrix is symmetric; Godot masks are per body. For every pair the matrix allows, both bodies need the other in their mask (or only the one that must react).');
+    if (dstKey === 'unreal') notes.push('Define the channels in Project Settings ▸ Collision and build a Collision Preset per layer; Unreal needs Block on both sides to collide.');
+  }
+  if (srcKey === 'unity' && dstKey.startsWith('godot')) notes.push('Unity CharacterController → CharacterBody3D: keep your own gravity integration; Unity stepOffset has no direct equivalent (use a raycast or floor_snap_length), skinWidth has none.');
+  if (dstKey === 'unreal' && (srcKey.startsWith('godot') || srcKey === 'unity')) notes.push('Unreal CharacterMovementComponent applies gravity, friction and braking itself (GroundFriction 8, BrakingDecelerationWalking 2048): remove manual gravity/friction code or set those to 0 and keep your own.');
+  if (srcKey.startsWith('godot') && dstKey === 'unity') notes.push('Godot default linear/angular damp 0.1 is added to every body (Combine mode); Unity bodies default to drag 0: set drag 0.1 on ported rigidbodies that relied on the default.');
+  if (dim === '2d') notes.push(`2D units: ${a.units} → ${b.units}; speeds and gravity were scaled ×${unitFactor}.`);
+  return {
+    from: a.label, to: b.label, dimension: dim, unitFactor,
+    profiles: { from: pick(a), to: pick(b) },
+    converted, settings, differences: notes,
+    next: 'Apply the settings, then check in play: fall time from a fixed height, a jump\'s peak, a sliding box\'s stop distance and a dropped ball\'s bounce count should match the original within tolerance (re_blueprint parity.json style).',
+  };
+}
+const pick = p => ({ units: p.units, gravity3d: p.gravity3d, gravity2d: p.gravity2d, fixedStep: p.fixedStep, fixedStepSetting: p.fixedStepSetting, engine: p.engineSetting, damping: `${p.linearDamp}/${p.angularDamp} — ${p.dampFormula}`, friction: p.friction, bounce: p.bounce, frictionCombine: p.frictionCombine, bounceCombine: p.bounceCombine, material: p.material, layers: p.layers, character: p.character, ccd: p.ccd, mass: p.mass, interpolation: p.interpolation });

package/port/src/plan.mjs

@@ -15,6 +15,9 @@ import { ENGINES, normEngine, mapFor, apiHits, leftovers, LIFECYCLE_EQUIV, portM
 import { readScene, parseGodotScene, parseUnityYaml } from './scene.mjs';
 import { convertTree } from './convert.mjs';
 import { writeTscn, unitySpec, threeModule, unrealSpec, scaffold, sceneFunctionName } from './porters.mjs';
+import { dormantFindings, resumePack } from './dormant.mjs';
+import { parityFindings } from './trace.mjs';
+import { readUnityAnimation, clipToTres, controllerToGd, snake as animSnake } from './unity-anim.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const TARGETS = ['godot', 'godot-csharp', 'unity', 'unreal', 'threejs'];
@@ -24,7 +27,7 @@ const MAX_UNIT_SOURCE = 200 * 1024;
 const plansDir = () => workspaceDir('ports');
 const planFile = async id => path.join(await plansDir(), id, 'plan.json');
 
-async function loadPlan(id) {
+export async function loadPlan(id) {
   if (!id || !/^[a-z0-9-]{3,80}$/.test(id)) throw new RPError('INVALID_ARGUMENT', 'Give a planId (port_status lists them).');
   const plan = await readJson(await planFile(id), null);
   if (!plan) throw new RPError('UNKNOWN_PLAN', `No port plan "${id}". port_status without planId lists the plans.`);
@@ -45,7 +48,7 @@ const callText = c => `${c.tool} ${JSON.stringify(c.arguments)}`;
 function nextCallObj(plan) {
   const u = nextUnit(plan);
   if (!u) return call('port_verify', { planId: plan.id });
-  if (u.kind === 'scene') return call('port_scene', { planId: plan.id, unit: u.id });
+  if (u.kind === 'scene' || (u.kind === 'animation' && u.action === 'convert-scene')) return call('port_scene', { planId: plan.id, unit: u.id });
   if (u.kind === 'asset') return call('port_copy_assets', { planId: plan.id });
   return call('port_unit', { planId: plan.id });
 }
@@ -97,6 +100,11 @@ function targetPath(rel, kind, ctx) {
     const tExt = LANGUAGE_TARGETS[to] ?? ext;
     return j(dir, `${base}${tExt}`);
   }
+  if (kind === 'animation') {
+    const isCtrl = ext === '.controller';
+    if (to === 'godot' || to === 'godot-csharp') return j('animations', dir.replace(/^(Animations?|Anim)(\/|$)/, ''), isCtrl ? `${snakeCase(base)}_animator.gd` : `${snakeCase(base)}.tres`);
+    return j('ReversePort', 'Notes', `${p}.md`);
+  }
   if (kind === 'scene') {
     if (to === 'godot') return j('scenes', dir.replace(/^(Scenes|Prefabs)(\/|$)/, ''), `${snakeCase(base)}.tscn`);
     if (to === 'godot-csharp') return rel;
@@ -121,6 +129,7 @@ function kindOf(f) {
   if (/\.(import|meta|uid)$/i.test(f.rel)) return null;
   if (lang === 'godot-scene' || lang === 'unity-scene' || lang === 'unity-prefab') return 'scene';
   if (lang === 'godot-resource') return 'resource';
+  if (/\.(anim|controller)$/i.test(f.rel) && /(^|\/)Assets\//.test(f.rel)) return 'animation';
   if (lang === 'shader') return 'shader';
   if (cat === 'code') return 'script';
   if (['image', 'audio', 'model', 'font', 'video'].includes(cat)) return 'asset';
@@ -163,7 +172,7 @@ export async function planPort({ source, to, output, name, include, exclude, unr
     const kind = kindOf(f);
     if (!kind) continue;
     const node = graph.nodes.get(f.rel);
-    let action = kind === 'asset' ? 'copy' : kind === 'scene' ? (['godot', 'unity', 'threejs', 'unreal', 'godot-csharp'].includes(target) ? 'convert-scene' : 'rebuild') : kind === 'config' ? 'rebuild' : 'translate';
+    let action = kind === 'asset' ? 'copy' : kind === 'scene' ? (['godot', 'unity', 'threejs', 'unreal', 'godot-csharp'].includes(target) ? 'convert-scene' : 'rebuild') : kind === 'animation' ? (target === 'godot' ? 'convert-scene' : 'rebuild') : kind === 'config' ? 'rebuild' : 'translate';
     if (target === 'godot-csharp' && ctx.from === 'godot' && (kind === 'resource' || (kind === 'config' && /project\.godot$/.test(f.rel)))) action = 'convert-scene';
     const unit = { source: f.rel, kind, language: languageOf(f.rel), size: f.size, lines: node?.lines ?? null, target: targetPath(f.rel, kind, ctx), action, status: 'pending' };
     if (target === 'unreal' && kind === 'script') unit.extraTargets = [unit.target.replace(/\.h$/, '.cpp')];
@@ -265,7 +274,7 @@ const CHECKLIST = {
   ],
   scene: ['Run port_scene {planId, unit}: it writes the converted scene/spec and marks the unit. Then review its reverseport TODO notes.'],
   resource: ['Port the data with the field names of its ported script/class. Keep values; convert units if they are distances.'],
-  shader: ['Port the shader to the target shading system; uniforms keep their names. Mark untranslatable parts with PORT: comments.'],
+  shader: ['Start from port_shader {file, to}: it maps uniforms, intrinsics and built-ins and marks the rest with PORT: comments. Resolve every leftover it lists; uniforms keep their names.'],
   asset: ['Copy as-is: port_write {planId, unit, copy:true}. The target engine imports it itself.'],
   config: ['Recreate these project settings in the target (input actions, tags/groups, autoloads/singletons, main scene). Write what you did into the notes file.'],
 };
@@ -280,6 +289,10 @@ export async function portUnit({ planId, unit, full = false } = {}) {
   if (u.status === 'pending') { u.status = 'in_progress'; u.started = new Date().toISOString(); await savePlan(plan); }
   result.checklist = repeat ? 'Same checklist as the earlier units (port_unit {planId, unit, full:true} repeats it).' : CHECKLIST[u.kind] ?? CHECKLIST.script;
   if (u.kind === 'asset') { const c = call('port_write', { planId, unit: u.id, copy: true }); return { ...result, next: callText(c), nextCall: c }; }
+  if (u.kind === 'animation' && u.action === 'convert-scene') {
+    const c = call('port_scene', { planId, unit: u.id });
+    return { ...result, next: callText(c), nextCall: c };
+  }
   if (u.kind === 'scene') {
     const scene = await readScene(abs).catch(e => ({ error: e.message }));
     const c = call('port_scene', { planId, unit: u.id });
@@ -433,19 +446,19 @@ export async function portStatus({ planId } = {}) {
   }
   const plan = await loadPlan(planId);
   await savePlan(plan);
-  return { ...summary(plan), progress: progress(plan), recent: plan.log.slice(-10), partial: plan.units.filter(u => u.status === 'partial').map(u => ({ unit: u.id, source: u.source, notes: u.notes })).slice(0, 30), planFile: path.join(plan.output, 'PORT-PLAN.md') };
+  return { ...summary(plan), progress: progress(plan), recent: plan.log.slice(-10), partial: plan.units.filter(u => u.status === 'partial').map(u => ({ unit: u.id, source: u.source, notes: u.notes })).slice(0, 30), planFile: path.join(plan.output, 'PORT-PLAN.md'), resume: resumePack(plan, { verify: plan.lastVerify ?? null }) };
 }
 
 export async function portVerify({ planId } = {}) {
   const plan = await loadPlan(planId);
   const errors = [], warnings = [], notPorted = [];
-  let markers = 0, left = 0, missingTotal = 0;
+  let markers = 0, left = 0, missingTotal = 0, dormantTotal = 0, behaviourTotal = 0;
   for (const u of plan.units) {
     if (u.status === 'skipped') continue;
     if (['pending', 'in_progress'].includes(u.status)) { notPorted.push(u.id); continue; }
     const files = u.written ?? [];
     for (const rel of files) if (!(await statOrNull(safeJoin(plan.output, rel)))) errors.push({ unit: u.id, issue: `written file is missing: ${rel}` });
-    if (u.kind === 'asset' || u.kind === 'scene' || u.kind === 'config') continue;
+    if (u.kind === 'asset' || u.kind === 'scene' || u.kind === 'config' || u.kind === 'animation') continue;
     const texts = [];
     for (const rel of files) { const b = await fs.readFile(safeJoin(plan.output, rel)).catch(() => null); if (b && isText(b)) texts.push(b.toString('utf8')); }
     if (!texts.length) continue;
@@ -457,18 +470,27 @@ export async function portVerify({ planId } = {}) {
       const parity = parityFor(check.sym, src, texts.join('\n'));
       if (parity.missing.length) { missingTotal += parity.missing.length; warnings.push({ unit: u.id, source: u.source, issue: 'functions/signals not found in the port', missing: parity.missing.slice(0, 40) }); }
       if (parity.lifecycle.length) warnings.push({ unit: u.id, source: u.source, issue: 'lifecycle callbacks without a counterpart (fine if their work moved elsewhere)', lifecycle: parity.lifecycle });
+      // Dormant logic: names exist but do nothing, or nothing calls them, or errors were silenced.
+      const srcLang = languageOf(u.source);
+      const srcText = srcLang && CODE_LANGUAGES.has(srcLang) ? await fs.readFile(path.join(plan.source, u.source), 'utf8').catch(() => null) : null;
+      const findings = dormantFindings({ sourceText: srcText, sourceLang: srcLang, targetText: texts.join('\n'), targetLang: languageOf(u.target), lifecycleGroups: LIFECYCLE_EQUIV });
+      if (findings.length) { dormantTotal += findings.length; warnings.push({ unit: u.id, source: u.source, issue: 'dormant logic: empty or thin bodies, functions the source called but the port never does, added suppressions', findings: findings.slice(0, 40) }); }
+      // Behaviour parity: tick placement, delta use, randomness and seeding, execution order, time scale.
+      const behaviour = parityFindings({ sourceText: srcText, sourceLang: srcLang, targetText: texts.join('\n'), targetLang: languageOf(u.target) });
+      if (behaviour.length) { behaviourTotal += behaviour.length; warnings.push({ unit: u.id, source: u.source, issue: 'behaviour parity: timing, randomness or order differs from the source', findings: behaviour }); }
     }
     if (u.status === 'partial') warnings.push({ unit: u.id, source: u.source, issue: 'marked partial', notes: u.notes });
   }
   const p = progress(plan);
-  const passed = !errors.length && p.pending === 0 && p.partial === 0 && left === 0 && missingTotal === 0;
+  const passed = !errors.length && p.pending === 0 && p.partial === 0 && left === 0 && missingTotal === 0 && dormantTotal === 0 && behaviourTotal === 0;
   if (notPorted.length) warnings.unshift({ issue: 'not ported yet', count: notPorted.length, units: notPorted.slice(0, 10) });
   const onlyPending = !errors.length && warnings.length === (notPorted.length ? 1 : 0);
-  const report = { planId, passed, progress: p, errors, warnings: warnings.slice(0, 200), portMarkers: markers, leftovers: left, missingSymbols: missingTotal, output: plan.output,
-    next: passed ? 'Open the output in the target engine, build, run, and compare behaviour with the original.' : onlyPending ? `Nothing is wrong so far; ${notPorted.length} unit(s) are not ported yet. Continue: ${nextCall(plan)}` : 'Fix the errors and the warnings above (leftovers, missing functions, partial units), then run port_verify again.',
+  const report = { planId, passed, progress: p, errors, warnings: warnings.slice(0, 200), portMarkers: markers, leftovers: left, missingSymbols: missingTotal, dormant: dormantTotal, behaviour: behaviourTotal, output: plan.output,
+    next: passed ? 'Open the output in the target engine, build, run, and compare behaviour with the original.' : onlyPending ? `Nothing is wrong so far; ${notPorted.length} unit(s) are not ported yet. Continue: ${nextCall(plan)}` : 'Fix the errors and the warnings above (leftovers, missing functions, dormant logic, behaviour parity, partial units), then run port_verify again. To prove behaviour, log both with port_trace harnesses and compare.',
     ...(passed ? {} : { nextCall: onlyPending ? nextCallObj(plan) : call('port_verify', { planId }) }) };
   plan.lastVerify = { at: new Date().toISOString(), passed, errors: errors.length, warnings: warnings.length };
   await savePlan(plan);
+  report.resume = resumePack(plan, { verify: report });
   return report;
 }
 
@@ -495,11 +517,71 @@ async function sceneTree(abs) {
   throw new RPError('UNSUPPORTED_SCENE', 'Scene conversion needs a Godot .tscn or a Unity .unity/.prefab saved as text.');
 }
 
+/** For every Animator controller used in a Unity tree: its ported script and the clips already ported (by plan). */
+async function animatorInfos(plan, root, resolveFromPlan) {
+  const out = new Map();
+  const visit = async n => {
+    const a = (n.components ?? []).find(c => c.type === 'Animator');
+    if (a && !out.has(a.controller ?? null)) {
+      const info = { clips: [], missing: [], script: null };
+      if (a.controller && plan && !a.controller.startsWith('guid:')) {
+        const t = resolveFromPlan(a.controller);
+        info.script = t ? `res://${t}` : null;
+        try {
+          const { controller } = await readUnityAnimation(path.join(plan.source, plan.sourceRoot ? `${plan.sourceRoot}/${a.controller}` : a.controller));
+          for (const st of controller.layers[0]?.states ?? []) {
+            if (!st.motion) continue;
+            const res = resolveFromPlan(st.motion);
+            const name = animSnake(path.basename(st.motion).replace(/\.anim$/i, ''));
+            if (res && !info.clips.some(c => c.name === name)) info.clips.push({ name, res: `res://${res}` }); else if (!res) info.missing.push(st.motion);
+          }
+        } catch { /* controller unreadable: the node gets a todo */ }
+      }
+      out.set(a.controller ?? null, info);
+    }
+    for (const c of n.children ?? []) await visit(c);
+  };
+  await visit(root);
+  return out;
+}
+
+async function portUnityAnimation({ plan, u, abs, target, out }) {
+  if (target !== 'godot') throw new RPError('INVALID_ARGUMENT', 'Unity .anim/.controller conversion targets Godot; other targets get a rebuild note from port_unit.');
+  const parsed = await readUnityAnimation(abs);
+  const resolveFromPlan = ref => { if (!plan || !ref) return null; const rel = plan.sourceRoot ? `${plan.sourceRoot}/${ref}` : ref; return plan.units.find(x => x.source === rel || x.source.toLowerCase() === rel.toLowerCase())?.target ?? null; };
+  let content, notes = [], summary;
+  if (parsed.kind === 'unity-animation') {
+    const r = clipToTres(parsed.clip, { coords: 'unity-3d', resolve: ref => { const t = resolveFromPlan(ref); return t ? `res://${t}` : null; } });
+    content = r.text; summary = { tracks: r.tracks, length: parsed.clip.length, loop: parsed.clip.loop, todo: r.todo };
+    notes.push(`${r.tracks} track(s); positions mirrored on Z. Add this Animation to the AnimationPlayer library of the node that had the Animator (port_scene does that for prefabs ported after this clip).`);
+    if (r.todo.length) notes.push(...r.todo);
+  } else {
+    const ctrl = parsed.controller;
+    const r = controllerToGd(ctrl, { className: `${pascalCase(path.basename(abs, '.controller'))}Animator`, resolveClip: ref => (ref && resolveFromPlan(ref) ? animSnake(path.basename(ref).replace(/\.anim$/i, '')) : null) });
+    content = r.text; summary = { states: r.states, transitions: r.transitions, parameters: ctrl.parameters.length, todo: r.todo };
+    notes.push('A GDScript state machine with the same states, parameters and conditions, driving an AnimationPlayer; port_scene puts it on an "Animator" child of every node that used this controller. Blend trees and extra layers need an AnimationTree by hand.');
+    if (r.todo.length) notes.push(...r.todo);
+  }
+  if (plan) {
+    const written = await writeFiles(plan, u, [{ path: u.target, content }]);
+    u.status = 'done'; u.written = written; u.finished = new Date().toISOString(); u.notes = notes.join(' ');
+    plan.log.push({ at: u.finished, event: 'scene', unit: u.id, files: written });
+    await savePlan(plan);
+    return withNext(plan, { planId: plan.id, unit: u.id, written: written.map(r => path.join(plan.output, r)), ...summary, notes, progress: progress(plan) });
+  }
+  const name = path.basename(abs).replace(/\.[^.]+$/, '');
+  const dest = out ? path.resolve(out) : path.join(await workspaceDir('scenes'), parsed.kind === 'unity-animation' ? `${snakeCase(name)}.tres` : `${snakeCase(name)}_animator.gd`);
+  await fs.mkdir(path.dirname(dest), { recursive: true });
+  await fs.writeFile(dest, content);
+  return { file: dest, target, ...summary, notes, preview: content.slice(0, 4000) };
+}
+
 export async function portScene({ planId, unit, file, to, out } = {}) {
   let plan = null, u = null, abs, target;
   if (planId) { plan = await loadPlan(planId); u = unit ? findUnit(plan, unit) : plan.units.find(x => x.action === 'convert-scene' && x.status !== 'done'); if (!u) return { planId, message: 'No scene units left.' }; if (u.action !== 'convert-scene') throw new RPError('INVALID_ARGUMENT', `Unit ${u.id} (${u.kind}) is not a scene conversion; use port_unit/port_write.`); abs = path.join(plan.source, u.source); target = plan.to; }
   else { if (!file || !to) throw new RPError('INVALID_ARGUMENT', 'Give {planId, unit} or {file, to}.'); abs = path.resolve(file); target = normEngine(to); }
   if (target === 'godot-csharp') return swapToCsharp(plan, u, abs, resolveRef => resolveRef);
+  if (/\.(anim|controller)$/i.test(abs)) return portUnityAnimation({ plan, u, abs, target, out });
   const { engine, parsed } = await sceneTree(abs);
   const resolveFromPlan = (srcRef, kindWanted) => {
     if (!plan || !srcRef) return null;
@@ -516,7 +598,8 @@ export async function portScene({ planId, unit, file, to, out } = {}) {
   if (target === 'godot') {
     if (engine !== 'unity') throw new RPError('INVALID_ARGUMENT', 'Scene → Godot conversion reads Unity scenes/prefabs.');
     const tree = convertTree(parsed.root, 'unity', 'godot');
-    content = writeTscn(tree, { engine: 'unity', name, resolve: ref => { const t = resolveFromPlan(ref); return t ? `res://${t}` : null; } });
+    const animators = await animatorInfos(plan, parsed.root, resolveFromPlan);
+    content = writeTscn(tree, { engine: 'unity', name, resolve: ref => { const t = resolveFromPlan(ref); return t ? `res://${t}` : null; }, animator: ref => animators.get(ref ?? null) ?? null });
     notes.push('Meshes from model files are placeholders (metadata/reverseport_todo); import the models in Godot and assign them.');
   } else if (target === 'unity') {
     if (engine !== 'godot') throw new RPError('INVALID_ARGUMENT', 'Scene → Unity conversion reads Godot .tscn scenes.');