@adiholick/nvstudio-mcp 2.3.0 → 2.4.0

package/studio-plugin/nv_joint_math.lua

@@ -0,0 +1,138 @@
+--!strict
+-- ══════════════════════════════════════════════════════════════════════
+-- NVStudio Subsystem: nv_joint_math
+-- Deskripsi: Modul Matematika Kinematika Sambungan (Joints) & Transformasi
+-- Menyediakan kalkulasi C0/C1 presisi, pemindahan poros tanpa dislokasi,
+-- rotasi poros, penyelarasan koordinat, dan pencerminan simetri bilateral.
+-- ══════════════════════════════════════════════════════════════════════
+
+local JointMath = {}
+
+local EPSILON = 1e-6
+
+-- ── 1. Hitung Offset Awal C0 & C1 ─────────────────────────────────────────────
+-- Menghubungkan Part0 dan Part1 tanpa mengubah posisi relatif fisik saat ini
+function JointMath.computeInitialOffsets(part0: BasePart, part1: BasePart): (CFrame, CFrame)
+	local c0 = part0.CFrame:ToObjectSpace(part1.CFrame)
+	local c1 = CFrame.identity
+	return c0, c1
+end
+
+-- ── 2. Geser Poros Sendi di Koordinat Dunia (World Delta) ─────────────────────
+-- Menggeser titik pivot tanpa mendislokasi posisi part anak di dunia 3D
+function JointMath.offsetPivot(joint: JointInstance, deltaWorld: Vector3): boolean
+	local part0 = joint.Part0
+	local part1 = joint.Part1
+	if not part0 or not part1 then return false end
+
+	local origJointWorld = part0.CFrame * joint.C0
+	local desiredWorld = origJointWorld + deltaWorld
+
+	local newC0 = part0.CFrame:ToObjectSpace(desiredWorld)
+	local diff = joint.C0:ToObjectSpace(newC0)
+	local newC1 = joint.C1 * diff
+
+	joint.C0 = newC0
+	joint.C1 = newC1
+	return true
+end
+
+-- ── 3. Tetapkan Posisi Poros ke Titik Dunia Absolut (Set World Position) ──────
+-- Memindahkan titik tumpu sendi tepat ke koordinat 3D yang diinginkan
+function JointMath.setPivotWorld(joint: JointInstance, targetWorldPos: Vector3): boolean
+	local part0 = joint.Part0
+	local part1 = joint.Part1
+	if not part0 or not part1 then return false end
+
+	local origJointWorld = part0.CFrame * joint.C0
+	local targetWorldCF = CFrame.new(targetWorldPos) * origJointWorld.Rotation
+
+	local newC0 = part0.CFrame:ToObjectSpace(targetWorldCF)
+	local diff = joint.C0:ToObjectSpace(newC0)
+	local newC1 = joint.C1 * diff
+
+	joint.C0 = newC0
+	joint.C1 = newC1
+	return true
+end
+
+-- ── 4. Rotasi Poros Sendi Tanpa Merusak Rig ───────────────────────────────────
+-- Memutar orientasi poros sendi sebesar sudut Euler radian
+function JointMath.rotatePivot(joint: JointInstance, rotEulerRad: Vector3): boolean
+	local part0 = joint.Part0
+	local part1 = joint.Part1
+	if not part0 or not part1 then return false end
+
+	local rotCF = CFrame.Angles(rotEulerRad.X, rotEulerRad.Y, rotEulerRad.Z)
+	joint.C0 = joint.C0 * rotCF
+	joint.C1 = joint.C1 * rotCF
+	return true
+end
+
+-- ── 5. Reset Poros Sendi ke Pusat Part Anak ───────────────────────────────────
+-- Mengembalikan poros sendi ke origin geometris Part1
+function JointMath.resetPivot(joint: JointInstance): boolean
+	local part0 = joint.Part0
+	local part1 = joint.Part1
+	if not part0 or not part1 then return false end
+
+	joint.C0 = part0.CFrame:ToObjectSpace(part1.CFrame)
+	joint.C1 = CFrame.identity
+	return true
+end
+
+-- ── 6. Selaraskan Orientasi Poros ke Part0 atau Part1 ─────────────────────────
+-- Menjaga posisi poros di dunia tetap sama, tetapi rotasinya mengikuti part referensi
+function JointMath.alignJoint(joint: JointInstance, alignTo: "Part0" | "Part1"): boolean
+	local part0 = joint.Part0
+	local part1 = joint.Part1
+	if not part0 or not part1 then return false end
+
+	local pivotWorldPos = (part0.CFrame * joint.C0).Position
+	local refCF = alignTo == "Part0" and part0.CFrame or part1.CFrame
+	local targetWorldCF = CFrame.new(pivotWorldPos) * refCF.Rotation
+
+	local newC0 = part0.CFrame:ToObjectSpace(targetWorldCF)
+	local diff = joint.C0:ToObjectSpace(newC0)
+	local newC1 = joint.C1 * diff
+
+	joint.C0 = newC0
+	joint.C1 = newC1
+	return true
+end
+
+-- ── 7. Refleksi CFrame Sumbu X Simetris (Bilateral Mirroring) ──────────────────
+-- Mencerminkan CFrame melewati bidang sagittal (sumbu X)
+function JointMath.mirrorCFrame(cf: CFrame): CFrame
+	local x, y, z,
+		r00, r01, r02,
+		r10, r11, r12,
+		r20, r21, r22 = cf:GetComponents()
+
+	-- Refleksi koordinat posisi dan rotasi M_x * R * M_x
+	return CFrame.new(
+		-x, y, z,
+		r00, -r01, -r02,
+		-r10, r11, r12,
+		-r20, r21, r22
+	)
+end
+
+-- ── 8. Cerminkan Sendi Bilateral Kiri <-> Kanan ────────────────────────────────
+-- Menerapkan C0 dan C1 yang telah dicerminkan dari sumber ke sendi target
+function JointMath.mirrorJoint(sourceJoint: JointInstance, targetJoint: JointInstance): boolean
+	if not sourceJoint or not targetJoint then return false end
+	targetJoint.C0 = JointMath.mirrorCFrame(sourceJoint.C0)
+	targetJoint.C1 = JointMath.mirrorCFrame(sourceJoint.C1)
+	return true
+end
+
+-- ── 9. Dapatkan Posisi Poros di Dunia ─────────────────────────────────────────
+function JointMath.getJointWorldPosition(joint: JointInstance): Vector3?
+	local part0 = joint.Part0
+	if not part0 then return nil end
+	return (part0.CFrame * joint.C0).Position
+end
+
+return JointMath
+

package/studio-plugin/nv_kinematics.lua

@@ -0,0 +1,248 @@
+--!strict
+-- ══════════════════════════════════════════════════════════════════════
+-- NVStudio Subsystem: nv_kinematics
+-- Deskripsi: Mesin Kinematika Analitis 2-Link LimbIK & Abstraksi R6/R15
+-- Menyelesaikan posisi siku/lutut menggunakan Hukum Cosinus O(1) tertutup,
+-- ekstensi SoftIK anti-hentakan kaku, dan stabilisasi rotasi leher/kaki.
+-- ══════════════════════════════════════════════════════════════════════
+
+local Kinematics = {}
+local EPSILON = 1e-6
+
+-- ── 1. SoftIK Algorithm ───────────────────────────────────────────────────────
+local function softDistance(dist: number, reach: number, softPercent: number?): number
+	if dist <= 0 or reach <= 0 then return 0 end
+	local pct = math.clamp(softPercent or 90, 0, 100) / 100
+	local onset = reach * pct
+	if dist <= onset then
+		return dist
+	end
+	local zone = reach - onset
+	if zone <= 0 then
+		return math.min(dist, reach)
+	end
+	local x = (dist - onset) / zone
+	local eased = x < 1e-4 and (x * (1 - x * 0.5)) or (1 - math.exp(-x))
+	return math.min(dist, reach, onset + zone * eased)
+end
+
+-- ── 2. Rotation Between Two Vectors ───────────────────────────────────────────
+function Kinematics.rotationBetween(from: Vector3, to: Vector3): CFrame
+	if from.Magnitude < EPSILON or to.Magnitude < EPSILON then
+		return CFrame.identity
+	end
+	from = from.Unit
+	to = to.Unit
+	local dot = math.clamp(from:Dot(to), -1, 1)
+	local cross = from:Cross(to)
+	if cross.Magnitude < EPSILON then
+		if dot > 0 then
+			return CFrame.identity
+		end
+		local basis = math.abs(from.X) < 0.8 and Vector3.xAxis or Vector3.yAxis
+		return CFrame.fromAxisAngle(from:Cross(basis).Unit, math.pi)
+	end
+	return CFrame.fromAxisAngle(cross.Unit, math.atan2(cross.Magnitude, dot))
+end
+
+-- ── 3. Analytical 2-Bone Limb Solver (Law of Cosines) ─────────────────────────
+function Kinematics.solveTwoLink(
+	root: Vector3,
+	middle: Vector3,
+	tip: Vector3,
+	goal: Vector3,
+	pole: Vector3?,
+	softPercent: number?
+): (Vector3, Vector3)
+	local upperLen = (middle - root).Magnitude
+	local lowerLen = (tip - middle).Magnitude
+	if upperLen < EPSILON or lowerLen < EPSILON then
+		return middle, tip
+	end
+
+	local delta = goal - root
+	local rawDist = delta.Magnitude
+	local dir = rawDist > EPSILON and delta.Unit or (tip - root).Unit
+	local reach = upperLen + lowerLen
+
+	-- Soften distance
+	local softened = softDistance(rawDist, reach, softPercent or 90)
+	local dist = math.clamp(softened, math.max(math.abs(upperLen - lowerLen), EPSILON), reach - 1e-4)
+
+	-- Bend direction towards pole
+	local polePos = pole or (middle + Vector3.new(0, 0, -1))
+	local bend = polePos - root
+	bend = bend - dir * bend:Dot(dir)
+	if bend.Magnitude < EPSILON then
+		local basis = math.abs(dir.X) < 0.8 and Vector3.xAxis or Vector3.yAxis
+		bend = basis - dir * basis:Dot(dir)
+	end
+	bend = bend.Unit
+
+	-- Law of Cosines: Upper arm projection along direction vector
+	local along = (upperLen * upperLen - lowerLen * lowerLen + dist * dist) / (2 * dist)
+	local heightSq = upperLen * upperLen - along * along
+	local height = math.sqrt(math.max(0, heightSq))
+
+	local solvedMiddle = root + dir * along + bend * height
+	local solvedTip = root + dir * dist
+	return solvedMiddle, solvedTip
+end
+
+-- ── 4. Rig Discovery & Abstraction (R6 & R15) ──────────────────────────────────
+export type RigInfo = {
+	model: Model,
+	isR15: boolean,
+	rootPart: BasePart,
+	motors: { [string]: Motor6D },
+	parts: { [string]: BasePart }
+}
+
+function Kinematics.inspectRig(model: Model): RigInfo?
+	if not model or not model:IsA("Model") then return nil end
+	local rootPart = model:FindFirstChild("HumanoidRootPart") :: BasePart?
+	if not rootPart then
+		rootPart = model.PrimaryPart or model:FindFirstChildWhichIsA("BasePart")
+	end
+	if not rootPart then return nil end
+
+	local humanoid = model:FindFirstChildOfClass("Humanoid")
+	local isR15 = humanoid and (humanoid.RigType == Enum.HumanoidRigType.R15) or false
+	if not humanoid then
+		isR15 = model:FindFirstChild("UpperTorso") ~= nil
+	end
+
+	local motors: { [string]: Motor6D } = {}
+	local parts: { [string]: BasePart } = {}
+
+	for _, desc in ipairs(model:GetDescendants()) do
+		if desc:IsA("Motor6D") then
+			motors[desc.Name] = desc
+		elseif desc:IsA("BasePart") then
+			parts[desc.Name] = desc
+		end
+	end
+
+	return {
+		model = model,
+		isR15 = isR15,
+		rootPart = rootPart,
+		motors = motors,
+		parts = parts
+	}
+end
+
+-- ── 5. Solve Limb IK on R15 / R6 Rig ──────────────────────────────────────────
+function Kinematics.solveLimb(
+	rigInfo: RigInfo,
+	limbName: string, -- "LeftArm" | "RightArm" | "LeftLeg" | "RightLeg"
+	targetWorldPos: Vector3,
+	poleWorldPos: Vector3?,
+	applyToRig: boolean?
+): { [string]: CFrame }?
+	local m = rigInfo.motors
+	local p = rigInfo.parts
+
+	if rigInfo.isR15 then
+		local upperMotorName, lowerMotorName, endMotorName
+		local upperPartName, lowerPartName, endPartName
+		local defaultPoleOffset = Vector3.new(0, 0, -2)
+
+		if limbName == "LeftArm" then
+			upperMotorName, lowerMotorName, endMotorName = "LeftShoulder", "LeftElbow", "LeftWrist"
+			upperPartName, lowerPartName, endPartName = "LeftUpperArm", "LeftLowerArm", "LeftHand"
+			defaultPoleOffset = Vector3.new(-1, 0, -2)
+		elseif limbName == "RightArm" then
+			upperMotorName, lowerMotorName, endMotorName = "RightShoulder", "RightElbow", "RightWrist"
+			upperPartName, lowerPartName, endPartName = "RightUpperArm", "RightLowerArm", "RightHand"
+			defaultPoleOffset = Vector3.new(1, 0, -2)
+		elseif limbName == "LeftLeg" then
+			upperMotorName, lowerMotorName, endMotorName = "LeftHip", "LeftKnee", "LeftAnkle"
+			upperPartName, lowerPartName, endPartName = "LeftUpperLeg", "LeftLowerLeg", "LeftFoot"
+			defaultPoleOffset = Vector3.new(0, 0, 2)
+		elseif limbName == "RightLeg" then
+			upperMotorName, lowerMotorName, endMotorName = "RightHip", "RightKnee", "RightAnkle"
+			upperPartName, lowerPartName, endPartName = "RightUpperLeg", "RightLowerLeg", "RightFoot"
+			defaultPoleOffset = Vector3.new(0, 0, 2)
+		else
+			return nil
+		end
+
+		local upperMotor = m[upperMotorName]
+		local lowerMotor = m[lowerMotorName]
+		local upperPart = p[upperPartName]
+		local lowerPart = p[lowerPartName]
+		local endPart = p[endPartName]
+
+		if not upperMotor or not lowerMotor or not upperPart or not lowerPart or not endPart then
+			return nil
+		end
+
+		local rootPos = upperPart.Position
+		local midPos = lowerPart.Position
+		local tipPos = endPart.Position
+		local pole = poleWorldPos or (midPos + defaultPoleOffset)
+
+		local solvedMid, solvedTip = Kinematics.solveTwoLink(rootPos, midPos, tipPos, targetWorldPos, pole, 90)
+
+		-- Hitung C0 baru untuk upper dan lower
+		local upperParentCF = upperMotor.Part0.CFrame
+		local upperGoalWorldCF = CFrame.lookAt(rootPos, solvedMid, pole - rootPos)
+		local upperC0 = upperParentCF:Inverse() * upperGoalWorldCF * upperMotor.C1
+
+		local lowerParentCF = solvedMid ~= rootPos and CFrame.lookAt(rootPos, solvedMid) or upperPart.CFrame
+		local lowerGoalWorldCF = CFrame.lookAt(solvedMid, solvedTip, pole - solvedMid)
+		local lowerC0 = lowerParentCF:Inverse() * lowerGoalWorldCF * lowerMotor.C1
+
+		if applyToRig then
+			upperMotor.C0 = upperC0
+			lowerMotor.C0 = lowerC0
+		end
+
+		return {
+			[upperMotorName] = upperC0,
+			[lowerMotorName] = lowerC0
+		}
+	else
+		-- Mode R6: 1 bone per limb, arahkan ke targetWorldPos
+		local motorName, partName
+		if limbName == "LeftArm" then motorName, partName = "Left Shoulder", "Left Arm"
+		elseif limbName == "RightArm" then motorName, partName = "Right Shoulder", "Right Arm"
+		elseif limbName == "LeftLeg" then motorName, partName = "Left Hip", "Left Leg"
+		elseif limbName == "RightLeg" then motorName, partName = "Right Hip", "Right Leg"
+		else return nil end
+
+		local motor = m[motorName]
+		local part = p[partName]
+		if not motor or not part or not motor.Part0 then return nil end
+
+		local rootPos = part.Position
+		local goalCF = CFrame.lookAt(rootPos, targetWorldPos)
+		local c0 = motor.Part0.CFrame:Inverse() * goalCF * motor.C1
+
+		if applyToRig then
+			motor.C0 = c0
+		end
+		return { [motorName] = c0 }
+	end
+end
+
+-- ── 6. Head Look-At Stabilizer ────────────────────────────────────────────────
+function Kinematics.solveLookAt(rigInfo: RigInfo, targetWorldPos: Vector3, applyToRig: boolean?): CFrame?
+	local neckMotor = rigInfo.motors["Neck"]
+	local headPart = rigInfo.parts["Head"]
+	if not neckMotor or not headPart or not neckMotor.Part0 then return nil end
+
+	local headPos = headPart.Position
+	local lookDir = (targetWorldPos - headPos).Unit
+	local targetWorldCF = CFrame.lookAt(headPos, headPos + lookDir)
+	local neckC0 = neckMotor.Part0.CFrame:Inverse() * targetWorldCF * neckMotor.C1
+
+	if applyToRig then
+		neckMotor.C0 = neckC0
+	end
+	return neckC0
+end
+
+return Kinematics
+

package/studio-plugin/nv_motion_generator.lua

@@ -0,0 +1,279 @@
+--!strict
+-- ══════════════════════════════════════════════════════════════════════
+-- NVStudio Subsystem: nv_motion_generator
+-- Deskripsi: Generator Gerakan Karakter Alami (Human-like Motion Synthesis)
+-- Menghasilkan pose kunci realistis (Anticipation, Follow-through, Easing)
+-- untuk berjalan, berlari, tebasan pedang, tinju, idle, dan lompat.
+-- ══════════════════════════════════════════════════════════════════════
+
+local curvesMod = script.Parent:WaitForChild("nv_curves")
+local Curves = require(curvesMod)
+local kinematicsMod = script.Parent:WaitForChild("nv_kinematics")
+local Kinematics = require(kinematicsMod)
+
+local MotionGenerator = {}
+
+export type KeyframeData = {
+	time: number, -- 0.0 to duration
+	poses: { [string]: CFrame } -- motorName -> C0 CFrame
+}
+
+-- ── Helper Angles ─────────────────────────────────────────────────────────────
+local function anglesDeg(x: number, y: number, z: number): CFrame
+	return CFrame.Angles(math.rad(x), math.rad(y), math.rad(z))
+end
+
+-- ── 1. Generator: Walk Cycle ──────────────────────────────────────────────────
+function MotionGenerator.generateWalkCycle(rigInfo: Kinematics.RigInfo, options: { [string]: any }?): { KeyframeData }
+	local opts = options or {}
+	local duration = tonumber(opts.duration) or 1.0
+	local intensity = tonumber(opts.intensity) or 1.0
+	local isR15 = rigInfo.isR15
+
+	-- Base offsets per motor
+	local m = rigInfo.motors
+	local defaultC0 = {}
+	for name, motor in pairs(m) do
+		defaultC0[name] = motor.C0
+	end
+
+	local legAngle = 26 * intensity
+	local armAngle = 22 * intensity
+	local torsoBob = 0.12 * intensity
+	local torsoTwist = 6 * intensity
+
+	local kfTimes = { 0.0, 0.25, 0.50, 0.75, 1.0 }
+	local keyframes: { KeyframeData } = {}
+
+	for _, tFrac in ipairs(kfTimes) do
+		local tSec = tFrac * duration
+		local poses: { [string]: CFrame } = {}
+
+		if isR15 then
+			local legPhase = math.sin(tFrac * math.pi * 2)
+			local armPhase = -legPhase
+
+			-- Torso movement (vertical bounce on each step)
+			local bobY = math.abs(math.cos(tFrac * math.pi * 2)) * torsoBob
+			local rootC0 = defaultC0["Root"] or CFrame.identity
+			poses["Root"] = rootC0 * CFrame.new(0, -bobY, 0) * anglesDeg(4, legPhase * torsoTwist, 0)
+
+			-- Left Leg & Right Leg
+			local lHip = defaultC0["LeftHip"] or CFrame.identity
+			local rHip = defaultC0["RightHip"] or CFrame.identity
+			local lKnee = defaultC0["LeftKnee"] or CFrame.identity
+			local rKnee = defaultC0["RightKnee"] or CFrame.identity
+
+			poses["LeftHip"] = lHip * anglesDeg(legPhase * legAngle, 0, 0)
+			poses["RightHip"] = rHip * anglesDeg(-legPhase * legAngle, 0, 0)
+
+			-- Knee bends when leg swings back
+			local lKneeBend = math.clamp(-legPhase * legAngle * 1.5, 0, 45)
+			local rKneeBend = math.clamp(legPhase * legAngle * 1.5, 0, 45)
+			poses["LeftKnee"] = lKnee * anglesDeg(lKneeBend, 0, 0)
+			poses["RightKnee"] = rKnee * anglesDeg(rKneeBend, 0, 0)
+
+			-- Left Arm & Right Arm (opposite to legs)
+			local lShoulder = defaultC0["LeftShoulder"] or CFrame.identity
+			local rShoulder = defaultC0["RightShoulder"] or CFrame.identity
+			poses["LeftShoulder"] = lShoulder * anglesDeg(armPhase * armAngle, 0, -4)
+			poses["RightShoulder"] = rShoulder * anglesDeg(-armPhase * armAngle, 0, 4)
+		else
+			-- R6 Rig
+			local legPhase = math.sin(tFrac * math.pi * 2)
+			local armPhase = -legPhase
+
+			local lShoulder = defaultC0["Left Shoulder"] or CFrame.identity
+			local rShoulder = defaultC0["Right Shoulder"] or CFrame.identity
+			local lHip = defaultC0["Left Hip"] or CFrame.identity
+			local rHip = defaultC0["Right Hip"] or CFrame.identity
+
+			poses["Left Shoulder"] = lShoulder * anglesDeg(armPhase * armAngle, 0, 0)
+			poses["Right Shoulder"] = rShoulder * anglesDeg(-armPhase * armAngle, 0, 0)
+			poses["Left Hip"] = lHip * anglesDeg(legPhase * legAngle, 0, 0)
+			poses["Right Hip"] = rHip * anglesDeg(-legPhase * legAngle, 0, 0)
+		end
+
+		table.insert(keyframes, { time = tSec, poses = poses })
+	end
+
+	return keyframes
+end
+
+-- ── 2. Generator: Melee Slash (Combat Attack) ─────────────────────────────────
+function MotionGenerator.generateMeleeSlash(rigInfo: Kinematics.RigInfo, options: { [string]: any }?): { KeyframeData }
+	local opts = options or {}
+	local duration = tonumber(opts.duration) or 0.8
+	local isR15 = rigInfo.isR15
+
+	local defaultC0 = {}
+	for name, motor in pairs(rigInfo.motors) do
+		defaultC0[name] = motor.C0
+	end
+
+	-- Keyframes: 0 (Ready), 0.25 (Wind-up Anticipation), 0.50 (Slash Snap), 0.75 (Follow-Through), 1.0 (Recover)
+	local points = {
+		{
+			t = 0.0,
+			armRot = anglesDeg(10, 0, 5),
+			torsoRot = anglesDeg(0, 0, 0),
+			lArmRot = anglesDeg(5, 0, -5)
+		},
+		{
+			t = 0.25, -- Wind-up
+			armRot = anglesDeg(-110, -35, 40),
+			torsoRot = anglesDeg(-5, -25, 0),
+			lArmRot = anglesDeg(20, 15, -15)
+		},
+		{
+			t = 0.50, -- Slash Strike
+			armRot = anglesDeg(65, 30, -25),
+			torsoRot = anglesDeg(10, 35, 0),
+			lArmRot = anglesDeg(-25, -10, -20)
+		},
+		{
+			t = 0.75, -- Follow-through overshoot
+			armRot = anglesDeg(75, 40, -30),
+			torsoRot = anglesDeg(8, 40, 0),
+			lArmRot = anglesDeg(-15, -5, -15)
+		},
+		{
+			t = 1.0, -- Return
+			armRot = anglesDeg(10, 0, 5),
+			torsoRot = anglesDeg(0, 0, 0),
+			lArmRot = anglesDeg(5, 0, -5)
+		}
+	}
+
+	local keyframes: { KeyframeData } = {}
+	for _, pt in ipairs(points) do
+		local poses: { [string]: CFrame } = {}
+		if isR15 then
+			poses["RightShoulder"] = (defaultC0["RightShoulder"] or CFrame.identity) * pt.armRot
+			poses["LeftShoulder"] = (defaultC0["LeftShoulder"] or CFrame.identity) * pt.lArmRot
+			poses["Waist"] = (defaultC0["Waist"] or CFrame.identity) * pt.torsoRot
+		else
+			poses["Right Shoulder"] = (defaultC0["Right Shoulder"] or CFrame.identity) * pt.armRot
+			poses["Left Shoulder"] = (defaultC0["Left Shoulder"] or CFrame.identity) * pt.lArmRot
+			poses["RootJoint"] = (defaultC0["RootJoint"] or CFrame.identity) * pt.torsoRot
+		end
+		table.insert(keyframes, { time = pt.t * duration, poses = poses })
+	end
+
+	return keyframes
+end
+
+-- ── 3. Generator: Punch Combo ─────────────────────────────────────────────────
+function MotionGenerator.generatePunch(rigInfo: Kinematics.RigInfo, options: { [string]: any }?): { KeyframeData }
+	local opts = options or {}
+	local duration = tonumber(opts.duration) or 0.6
+	local isR15 = rigInfo.isR15
+
+	local defaultC0 = {}
+	for name, motor in pairs(rigInfo.motors) do
+		defaultC0[name] = motor.C0
+	end
+
+	local points = {
+		{ t = 0.0, rArm = anglesDeg(0, 0, 0), torso = anglesDeg(0, 0, 0) },
+		{ t = 0.2, rArm = anglesDeg(-20, -10, 15), torso = anglesDeg(0, -15, 0) }, -- Coil back
+		{ t = 0.45, rArm = anglesDeg(90, 10, -5), torso = anglesDeg(8, 25, 0) },   -- Thrust forward
+		{ t = 0.7, rArm = anglesDeg(70, 5, -2), torso = anglesDeg(4, 15, 0) },     -- Recoil
+		{ t = 1.0, rArm = anglesDeg(0, 0, 0), torso = anglesDeg(0, 0, 0) }
+	}
+
+	local keyframes: { KeyframeData } = {}
+	for _, pt in ipairs(points) do
+		local poses: { [string]: CFrame } = {}
+		if isR15 then
+			poses["RightShoulder"] = (defaultC0["RightShoulder"] or CFrame.identity) * pt.rArm
+			poses["Waist"] = (defaultC0["Waist"] or CFrame.identity) * pt.torso
+		else
+			poses["Right Shoulder"] = (defaultC0["Right Shoulder"] or CFrame.identity) * pt.rArm
+			poses["RootJoint"] = (defaultC0["RootJoint"] or CFrame.identity) * pt.torso
+		end
+		table.insert(keyframes, { time = pt.t * duration, poses = poses })
+	end
+
+	return keyframes
+end
+
+-- ── 4. Generator: Idle Breathing ──────────────────────────────────────────────
+function MotionGenerator.generateIdle(rigInfo: Kinematics.RigInfo, options: { [string]: any }?): { KeyframeData }
+	local opts = options or {}
+	local duration = tonumber(opts.duration) or 2.5
+	local isR15 = rigInfo.isR15
+
+	local defaultC0 = {}
+	for name, motor in pairs(rigInfo.motors) do
+		defaultC0[name] = motor.C0
+	end
+
+	local keyframes: { KeyframeData } = {}
+	local steps = 8
+	for i = 0, steps do
+		local frac = i / steps
+		local timeSec = frac * duration
+		local breathCycle = math.sin(frac * math.pi * 2)
+
+		local poses: { [string]: CFrame } = {}
+		if isR15 then
+			poses["Root"] = (defaultC0["Root"] or CFrame.identity) * CFrame.new(0, breathCycle * 0.04, 0)
+			poses["Waist"] = (defaultC0["Waist"] or CFrame.identity) * anglesDeg(breathCycle * 1.5, 0, 0)
+			poses["Neck"] = (defaultC0["Neck"] or CFrame.identity) * anglesDeg(-breathCycle * 1.0, 0, 0)
+		else
+			poses["RootJoint"] = (defaultC0["RootJoint"] or CFrame.identity) * CFrame.new(0, 0, breathCycle * 0.04)
+			poses["Neck"] = (defaultC0["Neck"] or CFrame.identity) * anglesDeg(-breathCycle * 1.2, 0, 0)
+		end
+
+		table.insert(keyframes, { time = timeSec, poses = poses })
+	end
+
+	return keyframes
+end
+
+-- ── 5. Dense Sampler: Interpolasi Keyframes Menggunakan SLERP & Easing ────────
+function MotionGenerator.sampleSequence(
+	keyframes: { KeyframeData },
+	fps: number,
+	easing: string?
+): { [number]: { [string]: CFrame } }
+	if #keyframes == 0 then return {} end
+	table.sort(keyframes, function(a, b) return a.time < b.time end)
+
+	local totalDuration = keyframes[#keyframes].time
+	local totalFrames = math.max(1, math.floor(totalDuration * fps))
+	local sampled: { [number]: { [string]: CFrame } } = {}
+
+	for f = 0, totalFrames do
+		local curTime = (f / totalFrames) * totalDuration
+
+		-- Cari segment keyframe [prev, next]
+		local kA = keyframes[1]
+		local kB = keyframes[#keyframes]
+		for i = 1, #keyframes - 1 do
+			if curTime >= keyframes[i].time and curTime <= keyframes[i + 1].time then
+				kA = keyframes[i]
+				kB = keyframes[i + 1]
+				break
+			end
+		end
+
+		local segDuration = kB.time - kA.time
+		local rawAlpha = segDuration > 1e-5 and ((curTime - kA.time) / segDuration) or 0
+		local curvedAlpha = Curves.evaluate(easing or "QuadInOut", rawAlpha)
+
+		local framePoses: { [string]: CFrame } = {}
+		for motorName, cfA in pairs(kA.poses) do
+			local cfB = kB.poses[motorName] or cfA
+			framePoses[motorName] = Curves.slerp(cfA, cfB, curvedAlpha)
+		end
+
+		sampled[f] = framePoses
+	end
+
+	return sampled
+end
+
+return MotionGenerator
+