reverseport 1.6.0 → 1.8.0

package/port/src/trace.mjs

@@ -0,0 +1,302 @@
+// Behaviour parity beyond names: timing (frame vs physics tick, delta use, fixed step), randomness (seeding, RNG
+// calls) and execution order, compared between a source unit and its port; plus trace harnesses that log the
+// same properties per physics tick in both engines and a comparer that finds the first divergence.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { RPError, requireFile } from './util.mjs';
+import { functionBodies } from './dormant.mjs';
+
+const FRAME = ['_process', 'Update', 'LateUpdate', 'Tick', 'update', '_Process', 'onUpdate', 'draw'];
+const PHYSICS = ['_physics_process', 'FixedUpdate', '_PhysicsProcess', 'fixedUpdate', 'physicsUpdate', '_integrate_forces', '_IntegrateForces', 'TickPhysics', 'step'];
+const DELTA_RE = /\b(delta|deltaTime|DeltaTime|fixedDeltaTime|DeltaSeconds|dt|elapsed|get_process_delta_time\(\)|get_physics_process_delta_time\(\))\b/;
+const MOTION_RE = /\b(position|global_position|velocity|linear_velocity|angular_velocity|transform\.position|transform\.Translate|Translate|Rotate|rotation|rotate|move_and_slide|move_and_collide|MovePosition|AddForce|apply_force|apply_impulse|apply_central_impulse|AddTorque|SetActorLocation|AddActorLocalOffset|AddMovementInput|LaunchCharacter|\.x\s*[+-]=|\.y\s*[+-]=|\.z\s*[+-]=)\b/;
+const RNG_CALL_RE = /\b(randf|randi|randf_range|randi_range|randfn|rand_range|randomize|RandomNumberGenerator|GD\.Randf|GD\.Randi|GD\.RandRange|Random\.(Range|value|insideUnitCircle|insideUnitSphere|onUnitSphere|rotation|InitState)|UnityEngine\.Random|System\.Random|new Random|Math\.random|FMath::(Rand\w*|FRand\w*|SRand|RandRange|VRand)|FRandomStream|rand\(\)|random\(\)|randint|uniform|choice|shuffle|RandomRange|RandomFloat|GetRandom\w*)\b/g;
+const SEED_RE = /\b(seed\s*\(|randomize\s*\(|\.seed\s*=|set_seed|Random\.InitState|new Random\s*\(\s*\d|new System\.Random\s*\(\s*\w|FMath::SRandInit|FMath::RandInit|FRandomStream\s*\(|srand\s*\(|random\.seed|seedrandom|Mulberry|xorshift|RandomNumberGenerator\s*\.new\s*\(\s*\)\s*[\s\S]{0,80}?\.seed)/;
+const ORDER_RE = /\b(DefaultExecutionOrder|process_priority|process_physics_priority|ExecutionOrder|TickGroup|PrimaryActorTick\.TickGroup|AddTickPrerequisiteActor|call_deferred|CallDeferred|Invoke\s*\(|InvokeRepeating|StartCoroutine|coroutine|yield return|await\s+ToSignal|await\s+\w+\.\w+|\.timeout\b|SetTimer|setTimeout|requestAnimationFrame)\b/g;
+const TIMESCALE_RE = /\b(?:(?:Time\.timeScale|Engine\.time_scale|Engine\.TimeScale|CustomTimeDilation|Application\.targetFrameRate|Engine\.max_fps|Engine\.MaxFps|QualitySettings\.vSyncCount|Time\.fixedDeltaTime|Engine\.physics_ticks_per_second|Engine\.PhysicsTicksPerSecond|Time\.maximumDeltaTime|Engine\.max_physics_steps_per_frame)(?=\s*=[^=])|SetGlobalTimeDilation|t\.MaxFPS|ProjectSettings\.set_setting\("physics\/common\/physics_ticks_per_second")/g;
+
+function bodiesByName(text, lang) {
+  const out = new Map();
+  for (const b of functionBodies(text, lang).functions) out.set(b.name, (out.get(b.name) ?? '') + '\n' + b.body);
+  return out;
+}
+const cat = name => (FRAME.includes(name) ? 'frame' : PHYSICS.includes(name) ? 'physics' : null);
+
+/** Timing/randomness/order findings for one unit. Returns [{kind, detail, fix}]. */
+export function parityFindings({ sourceText, sourceLang, targetText, targetLang }) {
+  const out = [];
+  if (!sourceText || !targetText) return out;
+  const src = bodiesByName(sourceText, sourceLang), dst = bodiesByName(targetText, targetLang);
+  const srcCat = { frame: '', physics: '' }, dstCat = { frame: '', physics: '' };
+  for (const [n, b] of src) { const c = cat(n); if (c) srcCat[c] += b; }
+  for (const [n, b] of dst) { const c = cat(n); if (c) dstCat[c] += b; }
+  // 1. Motion moved between frame and physics callbacks.
+  const srcMotion = { frame: MOTION_RE.test(srcCat.frame), physics: MOTION_RE.test(srcCat.physics) };
+  const dstMotion = { frame: MOTION_RE.test(dstCat.frame), physics: MOTION_RE.test(dstCat.physics) };
+  if (srcMotion.physics && !dstMotion.physics && dstMotion.frame) out.push({ kind: 'tick-moved', detail: 'movement/physics code ran in the physics tick in the source but in the frame callback in the port', fix: 'move it to the physics callback (FixedUpdate / _physics_process / fixed-step accumulator) or results depend on frame rate' });
+  if (srcMotion.frame && !dstMotion.frame && dstMotion.physics && !srcMotion.physics) out.push({ kind: 'tick-moved', detail: 'movement ran per frame in the source but per physics tick in the port', fix: 'fine for physics bodies; for visual-only motion keep it per frame or interpolate' });
+  // 2. Delta usage changed where motion happens.
+  const sAnyDelta = DELTA_RE.test(srcCat.frame + srcCat.physics) && MOTION_RE.test(srcCat.frame + srcCat.physics);
+  const dAnyDelta = DELTA_RE.test(dstCat.frame + dstCat.physics), dAnyMotion = MOTION_RE.test(dstCat.frame + dstCat.physics);
+  if (sAnyDelta && dAnyMotion && !dAnyDelta) out.push({ kind: 'delta-dropped', detail: 'the source scaled its motion by delta; the port moves by fixed amounts per callback', fix: 'multiply speeds by delta (or by the fixed step) in the port' });
+  for (const c of ['frame', 'physics']) {
+    if (sAnyDelta && !dAnyDelta) break;
+    const sHas = DELTA_RE.test(srcCat[c]), dHas = DELTA_RE.test(dstCat[c]);
+    if (MOTION_RE.test(srcCat[c]) && sHas && !dHas && (dstCat[c].trim() || c === 'frame')) out.push({ kind: 'delta-dropped', detail: `the source scaled ${c}-callback motion by delta; the port does not`, fix: 'multiply speeds by delta (or by the fixed step) in the port' });
+    if (MOTION_RE.test(dstCat[c]) && !sHas && dHas && srcCat[c].trim()) out.push({ kind: 'delta-added', detail: `the port scales ${c}-callback motion by delta; the source used fixed per-tick amounts`, fix: 'either keep per-tick amounts at the same tick rate, or convert amounts to per-second values (amount × tick rate) when multiplying by delta' });
+  }
+  // 3. Randomness.
+  const sRng = (sourceText.match(RNG_CALL_RE) ?? []).length, dRng = (targetText.match(RNG_CALL_RE) ?? []).length;
+  if (sRng && !dRng) out.push({ kind: 'rng-missing', detail: `source uses randomness (${sRng} call(s)); the port has none`, fix: 'port the random choices; replays and difficulty depend on them' });
+  if (sRng && dRng) {
+    const sSeed = SEED_RE.test(sourceText), dSeed = SEED_RE.test(targetText);
+    if (sSeed && !dSeed) out.push({ kind: 'seed-missing', detail: 'the source seeds its RNG (deterministic runs); the port does not', fix: 'seed the same way (seed(n) / Random.InitState(n) / FMath::SRandInit(n) / a seeded PRNG in JS) and draw in the same order' });
+    if (!sSeed && dSeed) out.push({ kind: 'seed-added', detail: 'the port seeds its RNG; the source did not (runs varied)', fix: 'drop the fixed seed unless replays are wanted' });
+    if (Math.abs(sRng - dRng) > Math.max(2, sRng * 0.5)) out.push({ kind: 'rng-count', detail: `random calls: ${sRng} in the source, ${dRng} in the port`, fix: 'same number of draws in the same order keeps seeded runs identical' });
+  }
+  // 4. Ordering and deferred execution.
+  const sOrder = new Set((sourceText.match(ORDER_RE) ?? []).map(x => x.trim())), dOrder = new Set((targetText.match(ORDER_RE) ?? []).map(x => x.trim()));
+  if (sOrder.size && !dOrder.size) out.push({ kind: 'order-dropped', detail: `the source controls execution order/deferral (${[...sOrder].slice(0, 5).join(', ')}); the port has nothing equivalent`, fix: 'map to process_priority / [DefaultExecutionOrder] / TickGroup, and deferred calls to call_deferred / coroutines / timers' });
+  // 5. Time scale and frame-rate settings.
+  const sTime = new Set((sourceText.match(TIMESCALE_RE) ?? [])), dTime = new Set((targetText.match(TIMESCALE_RE) ?? []));
+  if (sTime.size && !dTime.size) out.push({ kind: 'timescale-dropped', detail: `the source sets time scale / frame rate / fixed step (${[...sTime].join(', ')}); the port does not`, fix: 'set the equivalent (Engine.time_scale, Time.timeScale, CustomTimeDilation; Engine.max_fps, Application.targetFrameRate; physics_ticks_per_second, Time.fixedDeltaTime)' });
+  return out;
+}
+
+const TICK_RATE = { godot: 60, 'godot-csharp': 60, unity: 50, unreal: 60, threejs: 60 };
+
+/** A logger that records properties of one node per physics tick to JSON, in the engine's own language. */
+export function traceHarness({ engine, node = '.', properties = ['position'], ticks = 300, file = 'reverseport-trace.json', label = engine } = {}) {
+  const e = String(engine).toLowerCase();
+  const props = properties.map(p => String(p));
+  const common = { ticks, properties: props, format: '{ "engine", "tickRate", "ticks": [{ "t": tick, "<property>": number | [numbers] }] } — compare two with port_trace action:"compare"' };
+  if (e === 'godot' || e === 'godot-csharp') {
+    const text = `extends Node
+## ReversePort trace harness: add this node to the scene, set target to the node to watch, run ${ticks} physics ticks.
+## Writes user://${file}. Compare with the original engine's trace: port_trace {action:"compare", a, b}.
+@export var target_path: NodePath = ^"${node}"
+@export var ticks: int = ${ticks}
+var _rows: Array = []
+var _tick := 0
+
+func _ready() -> void:
+\tseed(12345) # same seed in both engines
+\tEngine.physics_ticks_per_second = ${TICK_RATE[e]}
+
+func _physics_process(_delta: float) -> void:
+\tvar target := get_node_or_null(target_path)
+\tif target == null:
+\t\treturn
+\tvar row := {"t": _tick}
+${props.map(p => `\trow["${p}"] = _num(target.get("${p}"))`).join('\n')}
+\t_rows.append(row)
+\t_tick += 1
+\tif _tick >= ticks:
+\t\t_flush()
+\t\tset_physics_process(false)
+
+func _num(v):
+\tif v is Vector2: return [v.x, v.y]
+\tif v is Vector3: return [v.x, v.y, v.z]
+\tif v is Quaternion: return [v.x, v.y, v.z, v.w]
+\tif v is bool: return 1.0 if v else 0.0
+\treturn v
+
+func _flush() -> void:
+\tvar f := FileAccess.open("user://${file}", FileAccess.WRITE)
+\tf.store_string(JSON.stringify({"engine": "${label}", "tickRate": ${TICK_RATE[e]}, "ticks": _rows}))
+\tf.close()
+\tprint("ReversePort trace written: ", ProjectSettings.globalize_path("user://${file}"))
+`;
+    return { engine: e, fileName: 'ReversePortTrace.gd', text, where: 'user:// folder (printed at the end)', ...common };
+  }
+  if (e === 'unity') {
+    const text = `using System.Collections.Generic;
+using System.IO;
+using System.Text;
+using UnityEngine;
+
+// ReversePort trace harness: add to any GameObject, assign target, play ${ticks} fixed updates.
+// Writes ${file} next to persistentDataPath. Compare with the port's trace: port_trace {action:"compare", a, b}.
+public class ReversePortTrace : MonoBehaviour
+{
+    public Transform target;
+    public int ticks = ${ticks};
+    readonly List<string> rows = new List<string>();
+    int tick;
+
+    void Awake() { Random.InitState(12345); Time.fixedDeltaTime = 1f / ${TICK_RATE[e]}f; }
+
+    void FixedUpdate()
+    {
+        if (target == null || tick >= ticks) return;
+        var sb = new StringBuilder();
+        sb.Append("{\\"t\\":").Append(tick);
+${props.map(p => `        sb.Append(",\\"${p}\\":").Append(Num(Get("${p}")));`).join('\n')}
+        sb.Append("}");
+        rows.Add(sb.ToString());
+        if (++tick >= ticks) Flush();
+    }
+
+    object Get(string prop)
+    {
+        var rb = target.GetComponent<Rigidbody>();
+        var rb2 = target.GetComponent<Rigidbody2D>();
+        switch (prop)
+        {
+            case "position": case "global_position": return target.position;
+            case "rotation": return target.rotation;
+            case "rotation_degrees": return target.eulerAngles;
+            case "scale": return target.localScale;
+            case "velocity": case "linear_velocity": return rb != null ? (object)rb.linearVelocity : rb2 != null ? (object)rb2.linearVelocity : null;
+            case "angular_velocity": return rb != null ? (object)rb.angularVelocity : rb2 != null ? (object)rb2.angularVelocity : null;
+        }
+        foreach (var c in target.GetComponents<MonoBehaviour>())
+        {
+            var f = c.GetType().GetField(prop); if (f != null) return f.GetValue(c);
+            var pr = c.GetType().GetProperty(prop); if (pr != null) return pr.GetValue(c);
+        }
+        return null;
+    }
+
+    static string Num(object v)
+    {
+        var ci = System.Globalization.CultureInfo.InvariantCulture;
+        switch (v)
+        {
+            case null: return "null";
+            case Vector2 a: return "[" + a.x.ToString("R", ci) + "," + a.y.ToString("R", ci) + "]";
+            case Vector3 a: return "[" + a.x.ToString("R", ci) + "," + a.y.ToString("R", ci) + "," + a.z.ToString("R", ci) + "]";
+            case Quaternion q: return "[" + q.x.ToString("R", ci) + "," + q.y.ToString("R", ci) + "," + q.z.ToString("R", ci) + "," + q.w.ToString("R", ci) + "]";
+            case bool b: return b ? "1" : "0";
+            case float f: return f.ToString("R", ci);
+            case double d: return d.ToString("R", ci);
+            case int i: return i.ToString(ci);
+        }
+        return "\\"" + v + "\\"";
+    }
+
+    void Flush()
+    {
+        var p = Path.Combine(Application.persistentDataPath, "${file}");
+        File.WriteAllText(p, "{\\"engine\\":\\"${label}\\",\\"tickRate\\":${TICK_RATE[e]},\\"ticks\\":[" + string.Join(",", rows) + "]}");
+        Debug.Log("ReversePort trace written: " + p);
+    }
+}
+`;
+    return { engine: e, fileName: 'ReversePortTrace.cs', text, where: 'Application.persistentDataPath (logged)', ...common };
+  }
+  if (e === 'threejs') {
+    const text = `// ReversePort trace harness (three.js + your physics step). Call trace.tick(object) once per fixed step
+// and trace.download() (browser) or trace.toJSON() after ${ticks} ticks. Compare: port_trace {action:"compare", a, b}.
+export function createTrace({ ticks = ${ticks}, properties = ${JSON.stringify(props)}, label = ${JSON.stringify(label)} } = {}) {
+  const rows = [];
+  let tick = 0;
+  const num = v => (v == null ? null : typeof v === 'number' ? v : typeof v === 'boolean' ? (v ? 1 : 0) : 'w' in v ? [v.x, v.y, v.z, v.w] : 'z' in v ? [v.x, v.y, v.z] : [v.x, v.y]);
+  const get = (obj, p) => { const map = { position: obj.position, global_position: obj.getWorldPosition?.(new obj.position.constructor()) ?? obj.position, rotation: obj.quaternion, rotation_degrees: obj.rotation, scale: obj.scale, velocity: obj.userData?.velocity ?? obj.body?.linvel?.(), linear_velocity: obj.userData?.velocity ?? obj.body?.linvel?.(), angular_velocity: obj.body?.angvel?.() }; return p in map ? map[p] : obj.userData?.[p] ?? obj[p]; };
+  return {
+    tick(obj) { if (tick >= ticks) return; const row = { t: tick }; for (const p of properties) row[p] = num(get(obj, p)); rows.push(row); tick++; },
+    done() { return tick >= ticks; },
+    toJSON() { return { engine: label, tickRate: ${TICK_RATE[e]}, ticks: rows }; },
+    download(name = ${JSON.stringify(file)}) { const blob = new Blob([JSON.stringify(this.toJSON())], { type: 'application/json' }); const a = document.createElement('a'); a.href = URL.createObjectURL(blob); a.download = name; a.click(); },
+  };
+}
+// Seed your PRNG the same way in both engines (e.g. a mulberry32(12345)) and use a fixed-step accumulator at 1/${TICK_RATE[e]} s.
+`;
+    return { engine: e, fileName: 'reverseport-trace.js', text, where: 'browser download or your own fs write', ...common };
+  }
+  if (e === 'unreal') {
+    const text = `// ReversePort trace harness (Unreal, C++). Add this component to the actor to watch; it logs ${ticks} physics ticks
+// to Saved/${file} on the TickGroup TG_PostPhysics. Compare: port_trace {action:"compare", a, b}.
+#pragma once
+#include "CoreMinimal.h"
+#include "Components/ActorComponent.h"
+#include "Misc/FileHelper.h"
+#include "ReversePortTrace.generated.h"
+
+UCLASS(ClassGroup=(ReversePort), meta=(BlueprintSpawnableComponent))
+class UReversePortTrace : public UActorComponent
+{
+    GENERATED_BODY()
+public:
+    UPROPERTY(EditAnywhere) int32 Ticks = ${ticks};
+    UReversePortTrace() { PrimaryComponentTick.bCanEverTick = true; PrimaryComponentTick.TickGroup = TG_PostPhysics; }
+    virtual void BeginPlay() override { Super::BeginPlay(); FMath::SRandInit(12345); }
+    virtual void TickComponent(float DeltaTime, ELevelTick TickType, FActorComponentTickFunction* ThisTickFunction) override
+    {
+        Super::TickComponent(DeltaTime, TickType, ThisTickFunction);
+        if (Tick >= Ticks) return;
+        AActor* A = GetOwner();
+        const FVector P = A->GetActorLocation() / 100.0f; // cm → m, Unreal X-forward/Z-up: convert axes with port_convert before comparing
+        const FQuat Q = A->GetActorQuat();
+        const FVector V = A->GetVelocity() / 100.0f;
+        Rows.Add(FString::Printf(TEXT("{\\"t\\":%d,\\"position\\":[%g,%g,%g],\\"rotation\\":[%g,%g,%g,%g],\\"velocity\\":[%g,%g,%g]}"), Tick, P.X, P.Y, P.Z, Q.X, Q.Y, Q.Z, Q.W, V.X, V.Y, V.Z));
+        if (++Tick >= Ticks)
+        {
+            const FString Out = FString::Printf(TEXT("{\\"engine\\":\\"${label}\\",\\"tickRate\\":${TICK_RATE[e]},\\"ticks\\":[%s]}"), *FString::Join(Rows, TEXT(",")));
+            FFileHelper::SaveStringToFile(Out, *(FPaths::ProjectSavedDir() / TEXT("${file}")));
+            UE_LOG(LogTemp, Log, TEXT("ReversePort trace written: %s"), *(FPaths::ProjectSavedDir() / TEXT("${file}")));
+        }
+    }
+private:
+    int32 Tick = 0;
+    TArray<FString> Rows;
+};
+`;
+    return { engine: e, fileName: 'ReversePortTrace.h', text, where: 'Saved/ folder of the project', ...common, note: 'Unreal logs position/rotation/velocity in meters, Unreal axes; convert the other trace with port_convert or compare per axis with mapping.' };
+  }
+  throw new RPError('INVALID_ARGUMENT', `No trace harness for ${engine}; available: godot, unity, threejs, unreal.`);
+}
+
+/** Compare two traces: first divergence per property, max error, drift (error growth per tick). */
+export async function compareTraces({ a, b, tolerance = 0.01, resample = true, axisMap } = {}) {
+  const read = async f => { const { abs } = await requireFile(f); const j = JSON.parse(await fs.readFile(abs, 'utf8')); if (!Array.isArray(j.ticks)) throw new RPError('BAD_FORMAT', `${abs} is not a ReversePort trace (no ticks array).`); return { file: abs, ...j }; };
+  const A = await read(a), B = await read(b);
+  const rateA = A.tickRate ?? 60, rateB = B.tickRate ?? 60;
+  const props = [...new Set([...Object.keys(A.ticks[0] ?? {}), ...Object.keys(B.ticks[0] ?? {})])].filter(k => k !== 't');
+  const mapB = v => (Array.isArray(v) && axisMap && v.length >= 3 ? axisMap.map(i => (typeof i === 'string' ? (i.startsWith('-') ? -v[Number(i.slice(1))] : v[Number(i)]) : v[i])) : v);
+  const at = (trace, rate, tSeconds) => {
+    const idx = tSeconds * rate;
+    const i0 = Math.floor(idx), i1 = Math.min(trace.ticks.length - 1, i0 + 1), f = idx - i0;
+    const r0 = trace.ticks[i0], r1 = trace.ticks[i1];
+    if (!r0) return null;
+    if (!resample || !r1 || f === 0) return r0;
+    const row = { t: idx };
+    for (const k of Object.keys(r0)) { const x = r0[k], y = r1[k]; row[k] = Array.isArray(x) && Array.isArray(y) ? x.map((v, j) => v + (y[j] - v) * f) : typeof x === 'number' && typeof y === 'number' ? x + (y - x) * f : x; }
+    return row;
+  };
+  const seconds = Math.min((A.ticks.length - 1) / rateA, (B.ticks.length - 1) / rateB);
+  const steps = Math.max(1, Math.floor(seconds * Math.min(rateA, rateB)));
+  const result = {};
+  for (const p of props) {
+    let first = null, maxErr = 0, maxAt = 0, sum = 0, n = 0, early = 0, late = 0;
+    for (let s = 0; s <= steps; s++) {
+      const t = s / Math.min(rateA, rateB);
+      const ra = at(A, rateA, t), rb = at(B, rateB, t);
+      if (!ra || !rb || ra[p] == null || rb[p] == null) continue;
+      const va = ra[p], vb = mapB(rb[p]);
+      const err = Array.isArray(va) ? Math.sqrt(va.reduce((acc, v, i) => acc + (v - (vb[i] ?? 0)) ** 2, 0)) : Math.abs(va - vb);
+      if (!Number.isFinite(err)) continue;
+      sum += err; n++;
+      if (s < steps / 2) early += err; else late += err;
+      if (err > maxErr) { maxErr = err; maxAt = t; }
+      if (first === null && err > tolerance) first = { seconds: Math.round(t * 1000) / 1000, a: va, b: vb, error: Math.round(err * 1e6) / 1e6 };
+    }
+    result[p] = { matches: first === null, firstDivergence: first, maxError: Math.round(maxErr * 1e6) / 1e6, maxErrorAt: Math.round(maxAt * 1000) / 1000, meanError: n ? Math.round((sum / n) * 1e6) / 1e6 : null, drift: n ? (late > early * 1.5 ? 'growing' : late < early * 0.67 ? 'shrinking' : 'steady') : null };
+  }
+  const failing = Object.entries(result).filter(([, r]) => !r.matches).map(([p]) => p);
+  const hints = [];
+  if (rateA !== rateB) hints.push(`tick rates differ (${rateA} vs ${rateB} Hz): traces were resampled by time; per-tick amounts without delta scale by ${Math.round((rateB / rateA) * 1000) / 1000}`);
+  for (const p of failing) { const r = result[p]; if (r.drift === 'growing') hints.push(`${p}: error grows over time → integration differs (delta vs per-tick, damping, gravity or friction); check the physics profile (port_convert physics)`); else if (r.firstDivergence && r.firstDivergence.seconds === 0) hints.push(`${p}: differs from the first tick → initial state, units or axes differ (axisMap, unit factor, spawn position)`); else hints.push(`${p}: diverges at ${r.firstDivergence?.seconds}s → an event (input, collision, random draw) happened differently there`); }
+  return { a: { file: A.file, engine: A.engine, tickRate: rateA, ticks: A.ticks.length }, b: { file: B.file, engine: B.engine, tickRate: rateB, ticks: B.ticks.length }, comparedSeconds: Math.round(seconds * 1000) / 1000, tolerance, properties: result, passed: failing.length === 0, failing, hints };
+}
+
+export async function portTraceTool({ action = 'harness', engine, node, properties, ticks, out, a, b, tolerance, axisMap } = {}) {
+  if (action === 'compare') { if (!a || !b) throw new RPError('INVALID_ARGUMENT', 'compare needs a and b: two trace JSON files.'); return compareTraces({ a, b, tolerance, axisMap }); }
+  if (action !== 'harness') throw new RPError('INVALID_ARGUMENT', 'action must be harness or compare.');
+  if (!engine) throw new RPError('INVALID_ARGUMENT', 'harness needs engine: godot, unity, threejs or unreal.');
+  const h = traceHarness({ engine, node, properties, ticks });
+  let file = null;
+  if (out) { file = path.resolve(out); await fs.mkdir(path.dirname(file), { recursive: true }); await fs.writeFile(file, h.text); }
+  return { ...h, ...(file ? { file } : {}), next: `Add ${h.fileName} to both projects (original and port) watching the same node and properties, run each for ${h.ticks} ticks from the same start, then port_trace {action:"compare", a:<original trace>, b:<port trace>, tolerance}.` };
+}

package/port/src/unity-anim.mjs

@@ -0,0 +1,229 @@
+// Unity animation clips (.anim) and animator controllers (.controller) → Godot Animation resources and a
+// state-machine script. Clips become .tres Animation resources with value tracks (position/rotation/scale/
+// float properties/sprite swaps); controllers become an AnimationPlayer-driven GDScript state machine with the
+// same states, parameters and transition conditions, so the behaviour is readable and finishable by hand.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { RPError } from './util.mjs';
+import { findUnityRoot, unityGuidMap } from './scene.mjs';
+
+const f = n => { const v = Number(n); if (!Number.isFinite(v)) return '0'; const s = v.toFixed(6).replace(/\.?0+$/, ''); return s === '-0' ? '0' : s; };
+const ref = v => { const m = String(v ?? '').match(/fileID:\s*(-?\d+)(?:,\s*guid:\s*([0-9a-f]{32}))?/); return m ? { fileID: m[1], guid: m[2] ?? null } : null; };
+export const snake = s => String(s).replace(/([a-z0-9])([A-Z])/g, '$1_$2').replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '').toLowerCase() || 'anim';
+
+/** Split a Unity YAML file into documents keyed by fileID with the raw body (the generic parser in scene.mjs is flat; curves need depth). */
+function docs(text) {
+  const parts = text.split(/^--- !u!(\d+) &(-?\d+)[^\n]*$/m);
+  const out = new Map();
+  for (let i = 1; i + 2 < parts.length; i += 3) {
+    const body = parts[i + 2] ?? '';
+    const type = (body.match(/^(\w+):/m) ?? [])[1] ?? '';
+    out.set(parts[i + 1], { classId: Number(parts[i]), fileID: parts[i + 1], type, body });
+  }
+  return out;
+}
+
+/** Parse the `m_Curve:` key list under a block: returns [{time, value}] where value is number | {x,y,z,w}. */
+function keys(block) {
+  const out = [];
+  for (const m of block.matchAll(/- serializedVersion: \d+\s*\n\s*time: (-?[\d.e+-]+)\s*\n\s*value: ([^\n]*)/g)) {
+    const raw = m[2].trim();
+    const v = raw.startsWith('{') ? Object.fromEntries([...raw.matchAll(/([xyzw]):\s*(-?[\d.e+-]+)/g)].map(x => [x[1], Number(x[2])])) : raw.startsWith('{fileID') ? ref(raw) : Number(raw);
+    out.push({ time: Number(m[1]), value: v });
+  }
+  return out;
+}
+
+/** Top-level list blocks of a clip: `m_PositionCurves:` … up to the next `  m_` key at indent 2. */
+function listBlock(body, key) {
+  const m = body.match(new RegExp(`^  ${key}:\\s*\\n((?:(?! {2}\\w).*\\n?)*)`, 'm'));
+  if (!m) return [];
+  // Each curve starts with "  - " at indent 2.
+  return m[1].split(/^  - /m).slice(1);
+}
+
+export function parseAnimClip(text, { asset = r => (r?.guid ? `guid:${r.guid}` : null) } = {}) {
+  const d = [...docs(text).values()].find(x => x.type === 'AnimationClip');
+  if (!d) throw new RPError('BAD_FORMAT', 'Not a Unity AnimationClip (.anim saved as text).');
+  const b = d.body;
+  const name = b.match(/^  m_Name: (.*)$/m)?.[1]?.trim() ?? 'clip';
+  const sampleRate = Number(b.match(/m_SampleRate: ([\d.]+)/)?.[1] ?? 60);
+  const loop = /m_LoopTime: 1/.test(b);
+  const tracks = [];
+  const curvePath = block => block.match(/^\s*path: (.*)$/m)?.[1]?.trim() ?? '';
+  for (const c of listBlock(b, 'm_PositionCurves')) tracks.push({ kind: 'position', path: curvePath(c), keys: keys(c) });
+  for (const c of listBlock(b, 'm_RotationCurves')) tracks.push({ kind: 'rotation', path: curvePath(c), keys: keys(c) });
+  for (const c of listBlock(b, 'm_EulerCurves')) tracks.push({ kind: 'euler', path: curvePath(c), keys: keys(c) });
+  for (const c of listBlock(b, 'm_ScaleCurves')) tracks.push({ kind: 'scale', path: curvePath(c), keys: keys(c) });
+  for (const c of listBlock(b, 'm_FloatCurves')) {
+    const attr = c.match(/^\s*attribute: (.*)$/m)?.[1]?.trim() ?? '';
+    const type = c.match(/classID: (\d+)/)?.[1];
+    tracks.push({ kind: 'float', path: curvePath(c), attribute: attr, classID: Number(type ?? 0), keys: keys(c) });
+  }
+  for (const c of listBlock(b, 'm_PPtrCurves')) {
+    const attr = c.match(/^\s*attribute: (.*)$/m)?.[1]?.trim() ?? '';
+    const ks = [...c.matchAll(/- time: (-?[\d.e+-]+)\s*\n\s*value: ([^\n]*)/g)].map(m => ({ time: Number(m[1]), value: asset(ref(m[2])) }));
+    tracks.push({ kind: 'object', path: curvePath(c), attribute: attr, keys: ks });
+  }
+  const events = [...b.matchAll(/- time: (-?[\d.e+-]+)\s*\n\s*functionName: (\w+)/g)].map(m => ({ time: Number(m[1]), function: m[2] }));
+  let length = 0;
+  for (const t of tracks) for (const k of t.keys) length = Math.max(length, k.time);
+  const stopTime = Number(b.match(/m_StopTime: ([\d.e+-]+)/)?.[1] ?? length);
+  return { name, sampleRate, loop, length: Math.max(length, stopTime), tracks, events };
+}
+
+const PROPERTY_MAP = {
+  'm_IsActive': 'visible', 'm_Enabled': 'visible', 'm_LocalPosition.x': 'position:x', 'm_LocalPosition.y': 'position:y', 'm_LocalPosition.z': 'position:z',
+  'm_LocalScale.x': 'scale:x', 'm_LocalScale.y': 'scale:y', 'm_LocalScale.z': 'scale:z', 'localEulerAnglesRaw.x': 'rotation_degrees:x', 'localEulerAnglesRaw.y': 'rotation_degrees:y', 'localEulerAnglesRaw.z': 'rotation_degrees:z',
+  'm_Color.r': 'modulate:r', 'm_Color.g': 'modulate:g', 'm_Color.b': 'modulate:b', 'm_Color.a': 'modulate:a', 'm_Sprite': 'texture', 'm_Intensity': 'light_energy', 'm_Volume': 'volume_db', 'm_Pitch': 'pitch_scale', 'm_Size': 'size', 'm_FieldOfView': 'fov',
+  'm_FlipX': 'flip_h', 'm_FlipY': 'flip_v', 'm_AnchoredPosition.x': 'position:x', 'm_AnchoredPosition.y': 'position:y', 'm_SizeDelta.x': 'size:x', 'm_SizeDelta.y': 'size:y',
+};
+
+/** Godot node path for a Unity transform path ("Body/Arm" → "Body/Arm", "" → "."), with the Godot property. */
+function nodePath(p, prop) { return `NodePath("${p ? p.split('/').map(s => s.replace(/[":]/g, '_')).join('/') : '.'}:${prop}")`; }
+
+/**
+ * Write a Godot 4 Animation .tres from a parsed clip.
+ * coords: 'unity-3d' mirrors Z (Unity left-handed → Godot), 'unity-2d' flips Y for sprites, 'none' keeps values.
+ */
+export function clipToTres(clip, { coords = 'unity-3d', resolve = () => null } = {}) {
+  const ext = [], extId = new Map();
+  const addExt = (type, p) => { const k = `${type}:${p}`; if (!extId.has(k)) { const id = `${ext.length + 1}_rp`; extId.set(k, id); ext.push(`[ext_resource type="${type}" path="${p}" id="${id}"]`); } return extId.get(k); };
+  const lines = [];
+  const todo = [];
+  let n = 0;
+  const mirror = v => (coords === 'unity-3d' ? { ...v, z: -(v.z ?? 0) } : coords === 'unity-2d' ? { ...v, y: -(v.y ?? 0) } : v);
+  const track = (pathStr, { times, values, update = 0, interp = 1 }) => {
+    lines.push(`tracks/${n}/type = "value"`, `tracks/${n}/imported = false`, `tracks/${n}/enabled = true`, `tracks/${n}/path = ${pathStr}`, `tracks/${n}/interp = ${interp}`, `tracks/${n}/loop_wrap = true`,
+      `tracks/${n}/keys = {\n"times": PackedFloat32Array(${times.map(f).join(', ')}),\n"transitions": PackedFloat32Array(${times.map(() => '1').join(', ')}),\n"update": ${update},\n"values": [${values.join(', ')}]\n}`);
+    n++;
+  };
+  const floatGroups = new Map(); // path+base → {x,y,z,w} float curves merged into one vector track when they animate the same property.
+  for (const t of clip.tracks) {
+    if (!t.keys.length) continue;
+    if (t.kind === 'position') track(nodePath(t.path, 'position'), { times: t.keys.map(k => k.time), values: t.keys.map(k => { const v = mirror(k.value); return coords === 'unity-2d' ? `Vector2(${f(v.x)}, ${f(v.y)})` : `Vector3(${f(v.x)}, ${f(v.y)}, ${f(v.z)})`; }) });
+    else if (t.kind === 'scale') track(nodePath(t.path, 'scale'), { times: t.keys.map(k => k.time), values: t.keys.map(k => coords === 'unity-2d' ? `Vector2(${f(k.value.x)}, ${f(k.value.y)})` : `Vector3(${f(k.value.x)}, ${f(k.value.y)}, ${f(k.value.z)})`) });
+    else if (t.kind === 'rotation') {
+      // Unity quaternion (x,y,z,w) in a left-handed frame → mirror Z: negate x and y of the quaternion.
+      track(nodePath(t.path, 'quaternion'), { times: t.keys.map(k => k.time), values: t.keys.map(k => { const q = k.value; const m = coords === 'unity-3d' ? { x: -q.x, y: -q.y, z: q.z, w: q.w } : q; return `Quaternion(${f(m.x)}, ${f(m.y)}, ${f(m.z)}, ${f(m.w)})`; }) });
+    } else if (t.kind === 'euler') {
+      track(nodePath(t.path, coords === 'unity-2d' ? 'rotation_degrees' : 'rotation_degrees'), { times: t.keys.map(k => k.time), values: t.keys.map(k => { const e = k.value; return coords === 'unity-2d' ? f(-(e.z ?? 0)) : coords === 'unity-3d' ? `Vector3(${f(-(e.x ?? 0))}, ${f(-(e.y ?? 0))}, ${f(e.z ?? 0)})` : `Vector3(${f(e.x)}, ${f(e.y)}, ${f(e.z)})`; }) });
+    } else if (t.kind === 'float') {
+      const prop = PROPERTY_MAP[t.attribute];
+      if (!prop) { todo.push(`${t.path || '.'}: ${t.attribute} (${t.keys.length} keys) has no Godot property mapping; add a value track by hand`); continue; }
+      const isBool = prop === 'visible' || prop.startsWith('flip_');
+      const vals = t.keys.map(k => isBool ? (k.value >= 0.5 ? 'true' : 'false') : f(coords === 'unity-2d' && /^(position:y|rotation_degrees)$/.test(prop) ? -k.value : coords === 'unity-3d' && prop === 'position:z' ? -k.value : k.value));
+      track(nodePath(t.path, prop), { times: t.keys.map(k => k.time), values: vals, update: isBool ? 1 : 0, interp: isBool ? 0 : 1 });
+      void floatGroups;
+    } else if (t.kind === 'object') {
+      const prop = PROPERTY_MAP[t.attribute] ?? (t.attribute === 'm_Sprite' ? 'texture' : null);
+      if (!prop) { todo.push(`${t.path || '.'}: object curve ${t.attribute} not mapped`); continue; }
+      const vals = t.keys.map(k => { const target = k.value ? resolve(k.value) : null; if (!target) { todo.push(`${t.path || '.'}: sprite ${k.value ?? '?'} at ${k.time}s not resolved; assign the imported texture`); return 'null'; } return `ExtResource("${addExt('Texture2D', target)}")`; });
+      track(nodePath(t.path, prop), { times: t.keys.map(k => k.time), values: vals, update: 1, interp: 0 });
+    }
+  }
+  if (clip.events.length) {
+    track('NodePath(".")', { times: clip.events.map(e => e.time), values: clip.events.map(e => `{\n"args": [],\n"method": &"${e.function}"\n}`), update: 1, interp: 0 });
+    // Godot method tracks have their own type; rewrite the last emitted track header.
+    const i = lines.findIndex((l, k) => k === lines.length - 7);
+    if (i >= 0) lines[i] = `tracks/${n - 1}/type = "method"`;
+  }
+  const head = `[gd_resource type="Animation" load_steps=${ext.length + 1} format=3]`;
+  const body = ['[resource]', `resource_name = "${snake(clip.name)}"`, `length = ${f(clip.length)}`, `loop_mode = ${clip.loop ? 1 : 0}`, `step = ${f(1 / (clip.sampleRate || 60))}`, ...lines];
+  if (todo.length) body.push(`metadata/reverseport_todo = "${todo.join('; ').replace(/"/g, "'")}"`);
+  return { text: [head, ext.join('\n'), body.join('\n')].filter(Boolean).join('\n\n') + '\n', tracks: n, todo };
+}
+
+const PARAM_TYPES = { 1: 'float', 3: 'int', 4: 'bool', 9: 'trigger' };
+const MODES = { 1: '>', 2: '<', 3: '>', 4: '<', 6: '==', 7: '!=' }; // 1 If (bool true), 2 IfNot, 3 Greater, 4 Less, 6 Equals, 7 NotEqual
+
+export function parseAnimatorController(text, { asset = r => (r?.guid ? `guid:${r.guid}` : null) } = {}) {
+  const all = docs(text);
+  const ctrl = [...all.values()].find(d => d.type === 'AnimatorController');
+  if (!ctrl) throw new RPError('BAD_FORMAT', 'Not a Unity AnimatorController (.controller saved as text).');
+  const name = ctrl.body.match(/^  m_Name: (.*)$/m)?.[1]?.trim() ?? 'Animator';
+  const parameters = [...ctrl.body.matchAll(/- m_Name: (.*)\n\s*m_Type: (\d+)\n\s*m_DefaultFloat: ([\d.e+-]+)\n\s*m_DefaultInt: (-?\d+)\n\s*m_DefaultBool: (\d)/g)].map(m => ({ name: m[1].trim(), type: PARAM_TYPES[m[2]] ?? m[2], default: m[2] === '1' ? Number(m[3]) : m[2] === '3' ? Number(m[4]) : m[5] === '1' }));
+  const layers = [...ctrl.body.matchAll(/- serializedVersion: \d+\s*\n\s*m_Name: (.*)\n\s*m_StateMachine: ([^\n]*)/g)].map(m => ({ name: m[1].trim(), stateMachine: ref(m[2])?.fileID }));
+  const stateOf = id => all.get(id);
+  const transitionsOf = ids => ids.map(id => all.get(id)).filter(t => t?.type === 'AnimatorStateTransition').map(t => {
+    const b = t.body;
+    const dst = ref(b.match(/m_DstState: ([^\n]*)/)?.[1]);
+    const conditions = [...b.matchAll(/m_ConditionMode: (\d+)\s*\n\s*m_ConditionEvent: (.*)\n\s*m_EventTreshold: ([\d.e+-]+)/g)].map(c => ({ parameter: c[2].trim(), mode: Number(c[1]), op: MODES[c[1]] ?? '?', threshold: Number(c[3]) }));
+    return { to: dst ? stateOf(dst.fileID)?.body.match(/^  m_Name: (.*)$/m)?.[1]?.trim() ?? null : null, exit: /m_IsExit: 1/.test(b), hasExitTime: /m_HasExitTime: 1/.test(b), exitTime: Number(b.match(/m_ExitTime: ([\d.e+-]+)/)?.[1] ?? 1), duration: Number(b.match(/m_TransitionDuration: ([\d.e+-]+)/)?.[1] ?? 0), conditions };
+  });
+  const machines = layers.map(l => {
+    const sm = all.get(l.stateMachine);
+    if (!sm) return { layer: l.name, states: [], anyState: [], defaultState: null };
+    const stateIds = [...sm.body.matchAll(/- serializedVersion: \d+\s*\n\s*m_State: ([^\n]*)/g)].map(m => ref(m[1])?.fileID).filter(Boolean);
+    const states = stateIds.map(id => stateOf(id)).filter(Boolean).map(s => {
+      const b = s.body;
+      const trIds = [...b.matchAll(/- \{fileID: (-?\d+)\}/g)].map(m => m[1]);
+      return { name: b.match(/^  m_Name: (.*)$/m)?.[1]?.trim() ?? 'State', speed: Number(b.match(/m_Speed: ([\d.e+-]+)/)?.[1] ?? 1), motion: asset(ref(b.match(/m_Motion: ([^\n]*)/)?.[1])), transitions: transitionsOf(trIds), tag: b.match(/m_Tag: (.*)/)?.[1]?.trim() || null };
+    });
+    const anyIds = (sm.body.match(/m_AnyStateTransitions:\s*\n((?:\s*- \{fileID: -?\d+\}\n?)*)/)?.[1] ?? '').match(/-?\d+/g) ?? [];
+    const defaultState = stateOf(ref(sm.body.match(/m_DefaultState: ([^\n]*)/)?.[1])?.fileID)?.body.match(/^  m_Name: (.*)$/m)?.[1]?.trim() ?? states[0]?.name ?? null;
+    return { layer: l.name, states, anyState: transitionsOf(anyIds), defaultState };
+  });
+  return { name, parameters, layers: machines };
+}
+
+/** GDScript state machine driving an AnimationPlayer with the controller's states, parameters and conditions. */
+export function controllerToGd(ctrl, { className, resolveClip = () => null } = {}) {
+  const L = ctrl.layers[0] ?? { states: [], anyState: [], defaultState: null };
+  const cls = className ?? `${ctrl.name.replace(/[^A-Za-z0-9]/g, '')}Animator`;
+  const gdName = s => snake(s);
+  const cond = c => {
+    const p = ctrl.parameters.find(x => x.name === c.parameter);
+    const v = gdName(c.parameter);
+    if (!p) return `false # unknown parameter ${c.parameter}`;
+    if (p.type === 'trigger') return `_triggers.has(&"${c.parameter}")`;
+    if (p.type === 'bool') return c.mode === 1 ? v : `not ${v}`;
+    return `${v} ${c.op} ${f(c.threshold)}`;
+  };
+  const lines = [
+    `class_name ${cls}`, 'extends Node', '## Ported by ReversePort from the Unity AnimatorController "' + ctrl.name + '".', '## Same states, parameters and transition conditions; call update_state() every frame (or on parameter change),',
+    '## set_trigger("Name") for triggers. Blend trees and layers beyond the first are listed in metadata/reverseport_todo.', '',
+    '@export var player: AnimationPlayer', '',
+    ...ctrl.parameters.filter(p => p.type !== 'trigger').map(p => `var ${gdName(p.name)}: ${p.type === 'int' ? 'int' : p.type === 'bool' ? 'bool' : 'float'} = ${p.type === 'bool' ? (p.default ? 'true' : 'false') : f(p.default)}`),
+    '', 'var state: StringName = &"' + (L.defaultState ?? '') + '"', 'var _triggers: Array[StringName] = []', 'var _time_in_state := 0.0', '',
+    'const CLIPS := {', ...L.states.map(s => `\t&"${s.name}": "${resolveClip(s.motion) ?? (s.motion ? `PORT: ${s.motion}` : '')}",`), '}', '',
+    'func _ready() -> void:', '\tif player == null:', '\t\tplayer = get_parent().get_node_or_null("AnimationPlayer")', '\t_enter(state)', '',
+    'func _process(delta: float) -> void:', '\t_time_in_state += delta', '\tupdate_state()', '',
+    'func set_trigger(name: StringName) -> void:', '\tif not _triggers.has(name):', '\t\t_triggers.append(name)', '',
+    'func _enter(next: StringName) -> void:', '\tstate = next', '\t_time_in_state = 0.0', '\tif player and CLIPS.has(next) and player.has_animation(CLIPS[next]):', '\t\tplayer.play(CLIPS[next])', '',
+    'func _exit_time_reached(exit_time: float) -> bool:', '\tif player == null or not player.is_playing():', '\t\treturn true', '\treturn _time_in_state >= exit_time * player.current_animation_length', '',
+    'func update_state() -> void:',
+  ];
+  const trLines = (t, indent) => {
+    const parts = [...t.conditions.map(cond), ...(t.hasExitTime ? [`_exit_time_reached(${f(t.exitTime)})`] : [])];
+    const target = t.exit ? (L.defaultState ?? '') : t.to;
+    if (!target) return [];
+    const out = [`${indent}if ${parts.length ? parts.join(' and ') : 'true'}:`, ...t.conditions.filter(c => ctrl.parameters.find(p => p.name === c.parameter)?.type === 'trigger').map(c => `${indent}\t_triggers.erase(&"${c.parameter}")`), `${indent}\t_enter(&"${target}")`, `${indent}\treturn`];
+    return out;
+  };
+  for (const t of L.anyState) lines.push(...trLines(t, '\t'));
+  lines.push('\tmatch state:');
+  for (const s of L.states) {
+    lines.push(`\t\t&"${s.name}":`);
+    const body = s.transitions.flatMap(t => trLines(t, '\t\t\t'));
+    lines.push(...(body.length ? body : ['\t\t\tpass']));
+  }
+  if (!L.states.length) lines.push('\t\t_:', '\t\t\tpass');
+  const todo = [];
+  if (ctrl.layers.length > 1) todo.push(`${ctrl.layers.length - 1} more layer(s): ${ctrl.layers.slice(1).map(l => l.layer).join(', ')} (Godot: AnimationTree with blend/add nodes, or a second player)`);
+  for (const s of L.states) if (!s.motion) todo.push(`state ${s.name} has no clip (blend tree or empty): build it in an AnimationTree`);
+  if (todo.length) lines.push('', `# PORT: ${todo.join('; ')}`);
+  return { text: lines.join('\n') + '\n', todo, states: L.states.length, transitions: L.states.reduce((n, s) => n + s.transitions.length, L.anyState.length) };
+}
+
+/** Read a .anim or .controller from disk with GUIDs resolved through the Unity project. */
+export async function readUnityAnimation(file) {
+  const text = await fs.readFile(file, 'utf8');
+  const root = await findUnityRoot(file);
+  const guids = await unityGuidMap(root);
+  const asset = r => (r?.guid ? guids.get(r.guid) ?? `guid:${r.guid}` : null);
+  const ext = path.extname(file).toLowerCase();
+  if (ext === '.anim') return { kind: 'unity-animation', clip: parseAnimClip(text, { asset }) };
+  if (ext === '.controller') return { kind: 'unity-animator', controller: parseAnimatorController(text, { asset }) };
+  throw new RPError('UNSUPPORTED_SCENE', 'Expected a .anim or .controller file.');
+}