@adiholick/nvstudio-mcp 2.3.0 → 2.4.0

package/studio-plugin/nv_rig_dispatcher.lua

@@ -0,0 +1,319 @@
+--!strict
+-- ══════════════════════════════════════════════════════════════════════
+-- NVStudio Subsystem: nv_rig_dispatcher
+-- Deskripsi: Headless Modular Command Dispatcher untuk NV-Rig Engine
+-- Mengelola routing perintah rigging dari AI Agent LLM, eksekusi
+-- deterministik, inspeksi topologi rig, dan diagnostik otomatis.
+-- ══════════════════════════════════════════════════════════════════════
+
+local jointMathMod = script.Parent:WaitForChild("nv_joint_math")
+local JointMath = require(jointMathMod)
+local autoRiggerMod = script.Parent:WaitForChild("nv_auto_rigger")
+local AutoRigger = require(autoRiggerMod)
+
+local Dispatcher = {}
+
+-- ── 1. Inspeksi & Diagnostik Rig Mendalam (Deep Topological Inspection) ────────
+function Dispatcher.inspectRig(targetInstance: Instance): { [string]: any }
+	if not targetInstance then
+		return { status = "error", error = "Target instance tidak ditemukan." }
+	end
+
+	local model = targetInstance:IsA("Model") and targetInstance or targetInstance:FindFirstAncestorOfClass("Model")
+	if not model then
+		model = targetInstance:IsA("Folder") and targetInstance or targetInstance:IsA("BasePart") and targetInstance.Parent :: any
+	end
+	if not model then
+		return { status = "error", error = "Target harus berada di dalam Model atau Folder." }
+	end
+
+	local parts: { [string]: { anchored: boolean, size: { number }, mass: number, className: string } } = {}
+	local joints: { any } = {}
+	local parentToChildren: { [string]: { string } } = {}
+	local childToParent: { [string]: string } = {}
+	local rootCandidates: { string } = {}
+	local anchoredCount = 0
+	local totalParts = 0
+
+	for _, desc in ipairs(model:GetDescendants()) do
+		if desc:IsA("BasePart") then
+			totalParts += 1
+			if desc.Anchored then anchoredCount += 1 end
+			parts[desc.Name] = {
+				anchored = desc.Anchored,
+				size = { desc.Size.X, desc.Size.Y, desc.Size.Z },
+				mass = desc:GetMass(),
+				className = desc.ClassName
+			}
+		elseif desc:IsA("Motor6D") or desc:IsA("Weld") then
+			local p0Name = desc.Part0 and desc.Part0.Name or "nil"
+			local p1Name = desc.Part1 and desc.Part1.Name or "nil"
+			local pivotWorld = JointMath.getJointWorldPosition(desc)
+
+			table.insert(joints, {
+				name = desc.Name,
+				type = desc.ClassName,
+				part0 = p0Name,
+				part1 = p1Name,
+				parent = desc.Parent and desc.Parent.Name or "nil",
+				pivotWorld = pivotWorld and { pivotWorld.X, pivotWorld.Y, pivotWorld.Z } or nil,
+				c0 = { desc.C0:GetComponents() },
+				c1 = { desc.C1:GetComponents() }
+			})
+
+			if p0Name ~= "nil" and p1Name ~= "nil" then
+				if not parentToChildren[p0Name] then parentToChildren[p0Name] = {} end
+				table.insert(parentToChildren[p0Name], p1Name)
+				childToParent[p1Name] = p0Name
+			end
+		end
+	end
+
+	-- Deteksi Root Part (Part yang tidak memiliki Part0 di atasnya)
+	for partName, _ in pairs(parts) do
+		if not childToParent[partName] then
+			table.insert(rootCandidates, partName)
+		end
+	end
+
+	-- Deteksi Loop / Circular Dependency dalam hierarki
+	local hasCycle = false
+	local cyclePath = ""
+	local visited: { [string]: boolean } = {}
+	local recStack: { [string]: boolean } = {}
+
+	local function checkCycle(node: string, path: string): boolean
+		visited[node] = true
+		recStack[node] = true
+		local children = parentToChildren[node] or {}
+		for _, child in ipairs(children) do
+			if not visited[child] then
+				if checkCycle(child, path .. " -> " .. child) then return true end
+			elseif recStack[child] then
+				cyclePath = path .. " -> " .. child
+				return true
+			end
+		end
+		recStack[node] = false
+		return false
+	end
+
+	for _, root in ipairs(rootCandidates) do
+		if checkCycle(root, root) then
+			hasCycle = true
+			break
+		end
+	end
+
+	local humanoid = model:FindFirstChildOfClass("Humanoid")
+	local rigType = humanoid and (humanoid.RigType == Enum.HumanoidRigType.R15 and "R15" or "R6") or "Custom"
+
+	local warnings: { string } = {}
+	if hasCycle then
+		table.insert(warnings, "Ditemukan siklus tertutup (Circular Dependency): " .. cyclePath)
+	end
+	if anchoredCount > 1 then
+		table.insert(warnings, string.format("Ada %d part yang masih 'Anchored = true'. Karakter mungkin tidak dapat bergerak/beranimasi.", anchoredCount))
+	end
+	if #rootCandidates > 1 then
+		table.insert(warnings, "Ditemukan lebih dari 1 calon root part: " .. table.concat(rootCandidates, ", "))
+	end
+
+	return {
+		status = "success",
+		modelName = model.Name,
+		rigType = rigType,
+		totalParts = totalParts,
+		totalJoints = #joints,
+		rootParts = rootCandidates,
+		hasCycle = hasCycle,
+		warnings = warnings,
+		joints = joints,
+		parts = parts
+	}
+end
+
+-- ── 2. Buat Sambungan Sendi Baru (Create Joint / Weld) ─────────────────────────
+function Dispatcher.createJoint(targetModel: Instance, params: { [string]: any }): { [string]: any }
+	local part0Name = params.part0
+	local part1Name = params.part1
+	local jointType = params.joint_type or "Motor6D"
+	local jointName = params.name
+
+	if not part0Name or not part1Name then
+		return { status = "error", error = "Parameter 'part0' dan 'part1' wajib disertakan." }
+	end
+
+	local part0 = targetModel:FindFirstChild(part0Name, true) :: BasePart?
+	local part1 = targetModel:FindFirstChild(part1Name, true) :: BasePart?
+
+	if not part0 or not part0:IsA("BasePart") then
+		return { status = "error", error = "Part0 '" .. tostring(part0Name) .. "' tidak ditemukan." }
+	end
+	if not part1 or not part1:IsA("BasePart") then
+		return { status = "error", error = "Part1 '" .. tostring(part1Name) .. "' tidak ditemukan." }
+	end
+
+	part1.Anchored = false
+	local joint: JointInstance
+	if jointType == "Weld" then
+		joint = Instance.new("Weld")
+	else
+		joint = Instance.new("Motor6D")
+	end
+
+	joint.Name = jointName or (jointType == "Motor6D" and part1.Name or (part0.Name .. "_" .. part1.Name))
+	joint.Part0 = part0
+	joint.Part1 = part1
+	local c0, c1 = JointMath.computeInitialOffsets(part0, part1)
+	joint.C0 = c0
+	joint.C1 = c1
+	joint.Parent = part0
+
+	return {
+		status = "success",
+		jointName = joint.Name,
+		jointType = joint.ClassName,
+		part0 = part0.Name,
+		part1 = part1.Name,
+		message = string.format("Berhasil membuat %s '%s' antara '%s' dan '%s'", joint.ClassName, joint.Name, part0.Name, part1.Name)
+	}
+end
+
+-- ── 3. Edit Poros Sendi (Offset World / Target Position) ───────────────────────
+function Dispatcher.editPivot(targetModel: Instance, params: { [string]: any }): { [string]: any }
+	local jointName = params.joint_name or params.name
+	if not jointName then
+		return { status = "error", error = "Parameter 'joint_name' wajib diisi." }
+	end
+
+	local joint: JointInstance? = nil
+	for _, desc in ipairs(targetModel:GetDescendants()) do
+		if (desc:IsA("Motor6D") or desc:IsA("Weld")) and desc.Name == jointName then
+			joint = desc
+			break
+		end
+	end
+
+	if not joint then
+		return { status = "error", error = "Joint '" .. tostring(jointName) .. "' tidak ditemukan pada model." }
+	end
+
+	local success = false
+	if params.delta_world and type(params.delta_world) == "table" and #params.delta_world >= 3 then
+		local d = params.delta_world
+		success = JointMath.offsetPivot(joint, Vector3.new(d[1], d[2], d[3]))
+	elseif params.target_world and type(params.target_world) == "table" and #params.target_world >= 3 then
+		local p = params.target_world
+		success = JointMath.setPivotWorld(joint, Vector3.new(p[1], p[2], p[3]))
+	elseif params.rotate_euler_deg and type(params.rotate_euler_deg) == "table" and #params.rotate_euler_deg >= 3 then
+		local r = params.rotate_euler_deg
+		local rad = Vector3.new(math.rad(r[1]), math.rad(r[2]), math.rad(r[3]))
+		success = JointMath.rotatePivot(joint, rad)
+	elseif params.reset == true then
+		success = JointMath.resetPivot(joint)
+	elseif params.align_to == "Part0" or params.align_to == "Part1" then
+		success = JointMath.alignJoint(joint, params.align_to)
+	else
+		return { status = "error", error = "Tindakan edit pivot tidak spesifik. Berikan delta_world, target_world, rotate_euler_deg, reset, atau align_to." }
+	end
+
+	if not success then
+		return { status = "error", error = "Gagal memodifikasi poros sendi '" .. jointName .. "'." }
+	end
+
+	local newPivot = JointMath.getJointWorldPosition(joint)
+	return {
+		status = "success",
+		jointName = joint.Name,
+		newPivotWorld = newPivot and { newPivot.X, newPivot.Y, newPivot.Z } or nil,
+		newC0 = { joint.C0:GetComponents() },
+		newC1 = { joint.C1:GetComponents() },
+		message = "Poros sendi '" .. joint.Name .. "' berhasil diperbarui tanpa dislokasi part."
+	}
+end
+
+-- ── 4. Cerminkan Sendi Simetri Bilateral (Mirror Joints) ──────────────────────
+function Dispatcher.mirrorJoints(targetModel: Instance, params: { [string]: any }): { [string]: any }
+	local sourceSide = params.source_side or "Left"
+	local targetSide = sourceSide == "Left" and "Right" or "Left"
+
+	local mirroredCount = 0
+	local pairsProcessed: { string } = {}
+
+	for _, desc in ipairs(targetModel:GetDescendants()) do
+		if desc:IsA("Motor6D") or desc:IsA("Weld") then
+			if string.find(desc.Name, sourceSide) then
+				local targetName = string.gsub(desc.Name, sourceSide, targetSide)
+				local targetJoint: JointInstance? = nil
+				for _, d2 in ipairs(targetModel:GetDescendants()) do
+					if (d2:IsA("Motor6D") or d2:IsA("Weld")) and d2.Name == targetName then
+						targetJoint = d2
+						break
+					end
+				end
+
+				if targetJoint then
+					JointMath.mirrorJoint(desc, targetJoint)
+					mirroredCount += 1
+					table.insert(pairsProcessed, desc.Name .. " -> " .. targetName)
+				end
+			end
+		end
+	end
+
+	return {
+		status = "success",
+		sourceSide = sourceSide,
+		targetSide = targetSide,
+		mirroredCount = mirroredCount,
+		pairs = pairsProcessed,
+		message = string.format("Berhasil mencerminkan %d sendi dari %s ke %s", mirroredCount, sourceSide, targetSide)
+	}
+end
+
+-- ── 5. Router Eksekusi Utama (Modular Dispatcher) ─────────────────────────────
+function Dispatcher.dispatch(targetInstance: Instance, action: string, data: { [string]: any }): { [string]: any }
+	if action == "inspect" then
+		return Dispatcher.inspectRig(targetInstance)
+	elseif action == "create_joint" or action == "create" then
+		return Dispatcher.createJoint(targetInstance, data)
+	elseif action == "create_weld" then
+		data.joint_type = "Weld"
+		return Dispatcher.createJoint(targetInstance, data)
+	elseif action == "edit_pivot" or action == "edit" or action == "move_pivot" or action == "rotate_pivot" or action == "reset_pivot" or action == "align_joint" then
+		return Dispatcher.editPivot(targetInstance, data)
+	elseif action == "mirror" or action == "mirror_joints" then
+		return Dispatcher.mirrorJoints(targetInstance, data)
+	elseif action == "auto_rig_r6" or action == "rig_r6" then
+		return AutoRigger.rigR6(targetInstance:IsA("Model") and targetInstance or targetInstance:FindFirstAncestorOfClass("Model") :: any)
+	elseif action == "auto_rig_r15" or action == "rig_r15" then
+		return AutoRigger.rigR15(targetInstance:IsA("Model") and targetInstance or targetInstance:FindFirstAncestorOfClass("Model") :: any)
+	elseif action == "rig_weapon" or action == "attach_weapon" then
+		local weapon = data.weapon_path and game:GetService("HttpService") -- akan di-resolve oleh caller jika ada path
+		return AutoRigger.rigWeapon(targetInstance:IsA("Model") and targetInstance or targetInstance:FindFirstAncestorOfClass("Model") :: any, targetInstance, data.target_limb)
+	elseif action == "weld_assembly" or action == "weld_all" then
+		return AutoRigger.weldAssembly(targetInstance, nil)
+	elseif action == "remove_joint" or action == "delete_joint" then
+		local jointName = data.joint_name or data.name
+		local removed = 0
+		for _, desc in ipairs(targetInstance:GetDescendants()) do
+			if (desc:IsA("Motor6D") or desc:IsA("Weld")) and (not jointName or desc.Name == jointName) then
+				if data.reanchor == true and desc.Part1 then
+					desc.Part1.Anchored = true
+				end
+				desc:Destroy()
+				removed += 1
+			end
+		end
+		return { status = "success", removedCount = removed, message = string.format("Berhasil menghapus %d joint", removed) }
+	else
+		return {
+			status = "error",
+			error = "Action tidak dikenal: '" .. tostring(action) .. "'. Pilihan: inspect, create_joint, create_weld, edit_pivot, auto_rig_r6, auto_rig_r15, weld_assembly, mirror_joints, remove_joint."
+		}
+	end
+end
+
+return Dispatcher
+

package/studio-plugin/nv_vfx_serializer.lua

@@ -0,0 +1,363 @@
+--!strict
+-- ══════════════════════════════════════════════════════════════════════
+-- NVStudio Subsystem: nv_vfx_serializer
+-- Deskripsi: Serializer & Deserializer 1:1 Efek Visual Roblox
+-- Mengonversi seluruh properti ParticleEmitter, Beam, Trail, Light,
+-- dan Attachment menjadi tabel data murni (JSON-safe) dan merekonstruksinya
+-- dengan fidelitas 100% pada proyek Roblox mana saja.
+-- ══════════════════════════════════════════════════════════════════════
+
+local Serializer = {}
+
+-- ── 1. Property Whitelist Per ClassName ───────────────────────────────────────
+local PROPERTY_WHITELISTS: { [string]: { string } } = {
+	ParticleEmitter = {
+		"Name", "Enabled", "Texture", "Color", "Size", "Transparency",
+		"Acceleration", "Drag", "EmissionDirection", "Lifetime",
+		"LightEmission", "LightInfluence", "Orientation", "Rate",
+		"RotSpeed", "Rotation", "Shape", "ShapeInOut", "ShapePartial",
+		"ShapeStyle", "Speed", "SpreadAngle", "Squash",
+		"FlipbookFramerate", "FlipbookLayout", "FlipbookMode", "FlipbookStartRandom",
+		"ZOffset", "Brightness", "TimeScale", "VelocityInheritance", "WindAffects"
+	},
+	Beam = {
+		"Name", "Enabled", "Attachment0", "Attachment1", "Color",
+		"CurveSize0", "CurveSize1", "FaceCamera", "LightEmission",
+		"LightInfluence", "Segments", "Texture", "TextureLength",
+		"TextureMode", "TextureSpeed", "Transparency", "Width0",
+		"Width1", "ZOffset", "Brightness"
+	},
+	Trail = {
+		"Name", "Enabled", "Attachment0", "Attachment1", "Color",
+		"FaceCamera", "LightEmission", "LightInfluence", "Lifetime",
+		"MaxLength", "MinLength", "Texture", "TextureLength",
+		"TextureMode", "Transparency", "WidthScale", "Brightness"
+	},
+	Attachment = {
+		"Name", "Visible", "CFrame"
+	},
+	PointLight = {
+		"Name", "Enabled", "Brightness", "Color", "Range", "Shadows"
+	},
+	SpotLight = {
+		"Name", "Enabled", "Brightness", "Color", "Range", "Shadows", "Angle", "Face"
+	},
+	SurfaceLight = {
+		"Name", "Enabled", "Brightness", "Color", "Range", "Shadows", "Face"
+	},
+	Highlight = {
+		"Name", "Enabled", "FillColor", "OutlineColor", "FillTransparency", "OutlineTransparency", "DepthMode"
+	}
+}
+
+-- ── 2. Helper: Encode Roblox Values ke Pure Table ─────────────────────────────
+local function encodeValue(val: any, nodeIndexMap: { [Instance]: number }): any
+	local valType = typeof(val)
+
+	if valType == "nil" or valType == "string" or valType == "number" or valType == "boolean" then
+		return val
+	elseif valType == "Vector3" then
+		return { t = "Vector3", v = { val.X, val.Y, val.Z } }
+	elseif valType == "Vector2" then
+		return { t = "Vector2", v = { val.X, val.Y } }
+	elseif valType == "CFrame" then
+		return { t = "CFrame", v = { val:GetComponents() } }
+	elseif valType == "Color3" then
+		return { t = "Color3", v = { val.R, val.G, val.B } }
+	elseif valType == "NumberRange" then
+		return { t = "NumberRange", v = { val.Min, val.Max } }
+	elseif valType == "NumberSequence" then
+		local kps = {}
+		for _, kp in ipairs(val.Keypoints) do
+			table.insert(kps, { kp.Time, kp.Value, kp.Envelope })
+		end
+		return { t = "NumberSequence", v = kps }
+	elseif valType == "ColorSequence" then
+		local kps = {}
+		for _, kp in ipairs(val.Keypoints) do
+			table.insert(kps, {
+				kp.Time,
+				{ t = "Color3", v = { kp.Value.R, kp.Value.G, kp.Value.B } }
+			})
+		end
+		return { t = "ColorSequence", v = kps }
+	elseif valType == "EnumItem" then
+		return { t = "EnumItem", e = tostring(val.EnumType), v = val.Name }
+	elseif valType == "Instance" then
+		local idx = nodeIndexMap[val]
+		if idx then
+			return { t = "Ref", v = idx }
+		end
+		return { t = "InstanceName", v = val.Name }
+	end
+
+	return tostring(val)
+end
+
+-- ── 3. Helper: Decode Pure Table ke Roblox Values ──────────────────────────────
+local function decodeValue(val: any, createdNodes: { [number]: Instance }, scale: number?): any
+	if type(val) ~= "table" or not val.t then
+		return val
+	end
+
+	local t = val.t
+	local v = val.v
+	local s = scale or 1
+
+	if t == "Vector3" then
+		return Vector3.new(v[1] * s, v[2] * s, v[3] * s)
+	elseif t == "Vector2" then
+		return Vector2.new(v[1], v[2])
+	elseif t == "CFrame" then
+		local c = v
+		if s ~= 1 then
+			return CFrame.new(c[1] * s, c[2] * s, c[3] * s, c[4], c[5], c[6], c[7], c[8], c[9], c[10], c[11], c[12])
+		end
+		return CFrame.new(table.unpack(c))
+	elseif t == "Color3" then
+		return Color3.new(v[1], v[2], v[3])
+	elseif t == "NumberRange" then
+		local minV = tonumber(v[1]) or 0
+		local maxV = tonumber(v[2]) or minV
+		return NumberRange.new(math.min(minV, maxV), math.max(minV, maxV))
+	elseif t == "NumberSequence" then
+		local kps = {}
+		for _, kp in ipairs(v) do
+			if type(kp) == "table" then
+				local timeVal = math.clamp(tonumber(kp[1]) or 0, 0, 1)
+				local numVal = (tonumber(kp[2]) or 0) * s
+				local envVal = (tonumber(kp[3]) or 0) * s
+				table.insert(kps, NumberSequenceKeypoint.new(timeVal, numVal, envVal))
+			end
+		end
+		if #kps >= 2 then
+			table.sort(kps, function(a, b) return a.Time < b.Time end)
+			if kps[1].Time ~= 0 then
+				kps[1] = NumberSequenceKeypoint.new(0, kps[1].Value, kps[1].Envelope)
+			end
+			if kps[#kps].Time ~= 1 then
+				kps[#kps] = NumberSequenceKeypoint.new(1, kps[#kps].Value, kps[#kps].Envelope)
+			end
+			for i = 2, #kps do
+				if kps[i].Time <= kps[i - 1].Time then
+					local newT = math.min(1.0, kps[i - 1].Time + 0.001)
+					kps[i] = NumberSequenceKeypoint.new(newT, kps[i].Value, kps[i].Envelope)
+				end
+			end
+			return NumberSequence.new(kps)
+		elseif #kps == 1 then
+			return NumberSequence.new(kps[1].Value)
+		end
+		return NumberSequence.new(0)
+	elseif t == "ColorSequence" then
+		local kps = {}
+		for _, kp in ipairs(v) do
+			if type(kp) == "table" and kp[2] then
+				local timeVal = math.clamp(tonumber(kp[1]) or 0, 0, 1)
+				local col = kp[2].v or { 1, 1, 1 }
+				table.insert(kps, ColorSequenceKeypoint.new(timeVal, Color3.new(col[1] or 1, col[2] or 1, col[3] or 1)))
+			end
+		end
+		if #kps >= 2 then
+			table.sort(kps, function(a, b) return a.Time < b.Time end)
+			if kps[1].Time ~= 0 then
+				kps[1] = ColorSequenceKeypoint.new(0, kps[1].Value)
+			end
+			if kps[#kps].Time ~= 1 then
+				kps[#kps] = ColorSequenceKeypoint.new(1, kps[#kps].Value)
+			end
+			for i = 2, #kps do
+				if kps[i].Time <= kps[i - 1].Time then
+					local newT = math.min(1.0, kps[i - 1].Time + 0.001)
+					kps[i] = ColorSequenceKeypoint.new(newT, kps[i].Value)
+				end
+			end
+			return ColorSequence.new(kps)
+		elseif #kps == 1 then
+			return ColorSequence.new(kps[1].Value)
+		end
+		return ColorSequence.new(Color3.new(1, 1, 1))
+	elseif t == "EnumItem" then
+		local enumGroup = Enum[val.e]
+		if enumGroup and enumGroup[v] then
+			return enumGroup[v]
+		end
+		return nil
+	elseif t == "Ref" then
+		return createdNodes[v]
+	end
+
+	return val
+end
+
+-- ── 4. Serializer: Mengonversi Instance Hierarchy Menjadi Pure Table ─────────
+function Serializer.serialize(rootInstance: Instance): { [string]: any }
+	assert(typeof(rootInstance) == "Instance", "Root instance harus berupa Roblox Instance")
+
+	-- Kumpulkan seluruh node VFX yang didukung
+	local rawNodes: { Instance } = {}
+	local nodeIndexMap: { [Instance]: number } = {}
+
+	local function collect(inst: Instance)
+		if PROPERTY_WHITELISTS[inst.ClassName] or inst:IsA("Folder") or inst:IsA("Model") or inst:IsA("Configuration") or inst == rootInstance then
+			table.insert(rawNodes, inst)
+			nodeIndexMap[inst] = #rawNodes
+		end
+		for _, child in ipairs(inst:GetChildren()) do
+			collect(child)
+		end
+	end
+
+	collect(rootInstance)
+
+	local nodes = {}
+	local stats = { emitters = 0, beams = 0, trails = 0, lights = 0 }
+
+	for i, inst in ipairs(rawNodes) do
+		local className = inst.ClassName
+		local parentIndex = nil
+		if inst ~= rootInstance and inst.Parent then
+			parentIndex = nodeIndexMap[inst.Parent]
+		end
+
+		local props = {}
+		local whitelist = PROPERTY_WHITELISTS[className]
+		if whitelist then
+			for _, propName in ipairs(whitelist) do
+				local ok, propVal = pcall(function() return (inst :: any)[propName] end)
+				if ok and propVal ~= nil then
+					props[propName] = encodeValue(propVal, nodeIndexMap)
+				end
+			end
+		else
+			props["Name"] = inst.Name
+		end
+
+		-- Perbarui statistik
+		if className == "ParticleEmitter" then
+			stats.emitters += 1
+		elseif className == "Beam" then
+			stats.beams += 1
+		elseif className == "Trail" then
+			stats.trails += 1
+		elseif className:find("Light") then
+			stats.lights += 1
+		end
+
+		nodes[i] = {
+			class = className,
+			name = inst.Name,
+			parent = parentIndex,
+			properties = props
+		}
+	end
+
+	return {
+		version = 1,
+		rootName = rootInstance.Name,
+		rootClass = rootInstance.ClassName,
+		nodeCount = #nodes,
+		stats = stats,
+		nodes = nodes
+	}
+end
+
+-- ── 5. Deserializer: Merekonstruksi Roblox Instances dari Pure Table ───────────
+function Serializer.deserialize(treeData: { [string]: any }, targetParent: Instance, options: { scale: number?, enabled: boolean? }?): { [string]: any }
+	assert(type(treeData) == "table" and treeData.nodes, "Format data treeData tidak valid")
+	assert(typeof(targetParent) == "Instance", "TargetParent harus berupa Instance")
+
+	local opts = options or {}
+	local scale = tonumber(opts.scale) or 1
+	local createdNodes: { [number]: Instance } = {}
+	local refDeferred: { { inst: Instance, propName: string, refIdx: number } } = {}
+	local errors: { string } = {}
+	local createdCount = 0
+
+	-- Pass 1: Buat semua instance dan tetapkan parent dasar
+	for i, node in ipairs(treeData.nodes) do
+		local ok, inst = pcall(function()
+			-- Jika node pertama adalah root dan bertipe Part/Model pembungkus, kita bisa menaruh isinya langsung
+			if i == 1 and (node.class == "Folder" or node.class == "Model" or node.class == "Configuration") and targetParent:IsA("BasePart") then
+				-- Buat container pembungkus di targetParent
+				local container = Instance.new(node.class)
+				container.Name = node.name or "NV_VFX"
+				container.Parent = targetParent
+				return container
+			elseif i == 1 and (node.class == "ParticleEmitter" or node.class == "Beam" or node.class == "Trail" or node.class == "Attachment") then
+				local newInst = Instance.new(node.class)
+				newInst.Name = node.name or "NV_VFX"
+				newInst.Parent = targetParent
+				return newInst
+			else
+				local newInst = Instance.new(node.class)
+				newInst.Name = node.name or ("Node_" .. tostring(i))
+				return newInst
+			end
+		end)
+
+		if ok and inst then
+			createdNodes[i] = inst
+			createdCount += 1
+		else
+			table.insert(errors, "Gagal membuat instance untuk node " .. tostring(i) .. ": " .. tostring(inst))
+		end
+	end
+
+	-- Pass 2: Hubungkan hierarki Parent
+	for i, node in ipairs(treeData.nodes) do
+		local inst = createdNodes[i]
+		if inst and i > 1 then
+			local parentIdx = node.parent
+			if parentIdx and createdNodes[parentIdx] then
+				inst.Parent = createdNodes[parentIdx]
+			else
+				inst.Parent = createdNodes[1] or targetParent
+			end
+		end
+	end
+
+	-- Pass 3: Terapkan Properti (dengan scaling & deferred Attachment ref)
+	for i, node in ipairs(treeData.nodes) do
+		local inst = createdNodes[i]
+		if inst and node.properties then
+			for propName, propData in pairs(node.properties) do
+				if type(propData) == "table" and propData.t == "Ref" then
+					table.insert(refDeferred, { inst = inst, propName = propName, refIdx = propData.v })
+				else
+					local pScale = (propName == "Size" or propName == "Width0" or propName == "Width1" or propName == "Speed" or propName == "Acceleration") and scale or 1
+					local decoded = decodeValue(propData, createdNodes, pScale)
+					if decoded ~= nil then
+						pcall(function()
+							if propName == "Enabled" and opts.enabled ~= nil then
+								(inst :: any)[propName] = opts.enabled
+							else
+								(inst :: any)[propName] = decoded
+							end
+						end)
+					end
+				end
+			end
+		end
+	end
+
+	-- Pass 4: Hubungkan Deferred Attachment References (Beam / Trail)
+	for _, ref in ipairs(refDeferred) do
+		local targetNode = createdNodes[ref.refIdx]
+		if targetNode and targetNode:IsA("Attachment") then
+			pcall(function()
+				(ref.inst :: any)[ref.propName] = targetNode
+			end)
+		end
+	end
+
+	return {
+		status = #errors == 0 and "success" or "partial",
+		createdCount = createdCount,
+		root = createdNodes[1] or targetParent,
+		errors = errors
+	}
+end
+
+return Serializer
+