@adiholick/nvstudio-mcp 2.2.3 → 2.4.0

package/agent-plugin/skills/nvstudio-gui-standards/SKILL.md

@@ -0,0 +1,419 @@
+---
+name: nvstudio-gui-standards
+description: Panduan standar arsitektur dan taste desain StarterGui Roblox (Struktur Instance, Smart Device Detection NVSelfTitle/NVDance, Layout Hierarchy, dan NV Dark Modern Aesthetics).
+---
+
+# NVStudio Roblox GUI Design Standards & Taste Guide
+
+Gunakan skill ini sebagai acuan mutlak setiap kali membuat atau memodifikasi GUI di Roblox Studio (`StarterGui`). Semua GUI dirancang mengikuti filosofi arsitektur **NV-Series** (`NVMembership`, `NVMusic`, `NVSelfTitle`, `NVServer`, `NVDance`).
+
+---
+
+## 1. Aturan Fundamental Arsitektur GUI
+
+1. **Roblox Instance Penuh (Bukan Pure Script):**
+   - GUI dibuat sebagai hierarki **Instance nyata di Roblox Studio** (menggunakan MCP `create_instance` / `set_properties` atau builder helper Luau).
+   - DILARANG membuat GUI murni on-the-fly dari script kosong dengan ratusan baris `Instance.new`.
+   - Script Luau (`LocalScript` / `ModuleScript`) hanya bertindak sebagai **UI Controller** yang mengontrol state, event click/input, tweening, dan integrasi server.
+
+2. **Hierarki ScreenGui & MainFrame:**
+   - Setiap GUI berada di bawah `ScreenGui` dengan properti:
+     - `ResetOnSpawn = false`
+     - `ZIndexBehavior = Enum.ZIndexBehavior.Sibling`
+     - `IgnoreGuiInset = false`
+   - Child utama dari `ScreenGui` WAJIB berupa Frame bernama **`MainFrame`** (atau `ContainerFrame` yang membungkus `MainFrame`).
+   - `MainFrame.AnchorPoint` default: `Vector2.new(0.5, 0.5)` dengan posisi tengah `UDim2.new(0.5, 0, 0.5, 0)`.
+
+3. **Aturan Wajib Layout Frame:**
+   - **Setiap Frame** WAJIB memiliki:
+     - `UIListLayout` (atau `UIGridLayout` jika grid konten) dengan `SortOrder = Enum.SortOrder.LayoutOrder`.
+     - `UIPadding` (memberikan padding konsisten agar elemen tidak menempel ke tepi).
+   - **Setiap Item di dalam Frame** WAJIB memiliki properti `LayoutOrder` eksplisit (0, 1, 2, 3...) agar susunan elemen teratur secara deterministik.
+
+4. **Aturan Wajib ScrollingFrame:**
+   - Setiap `ScrollingFrame` WAJIB memiliki Frame transparan pembatas bernama **`Spacer`** atau **`SPACER`**:
+     - `Name = "Spacer"`
+     - `BackgroundTransparency = 1`
+     - `BorderSizePixel = 0`
+     - `LayoutOrder = 99999` (atau `999999999`)
+     - Size: `UDim2.new(1, 0, 0.15, 0)` atau `UDim2.new(0, 0, 0, 20)` (menyesuaikan orientasi scroll vertical/horizontal).
+   - Ini memastikan elemen paling bawah/ujung tidak terpotong saat pemain melakukan scroll.
+
+5. **Pembangun Deklaratif Cepat (`batch_create_instances`):**
+   - Sangat disarankan membangun seluruh pohon GUI menggunakan tool `batch_create_instances` dengan mode `tree` bersarang.
+   - Contoh payload tree:
+     ```json
+     {
+       "target": "StarterGui.MyScreen",
+       "tree": {
+         "className": "Frame",
+         "name": "MainFrame",
+         "properties": {
+           "Size": [0.5, 0, 0.6, 0],
+           "Position": [0.5, 0, 0.5, 0],
+           "AnchorPoint": [0.5, 0.5],
+           "BackgroundColor3": [28, 28, 30]
+         },
+         "children": [
+           { "className": "UICorner", "properties": { "CornerRadius": [0, 10] } },
+           { "className": "UIStroke", "properties": { "Color": [63, 63, 63], "Thickness": 1 } },
+           { "className": "UIListLayout", "properties": { "SortOrder": "LayoutOrder" } },
+           { "className": "UIPadding", "properties": { "PaddingTop": [0, 10], "PaddingBottom": [0, 10] } }
+         ]
+       }
+     }
+     ```
+
+---
+
+## 2. Smart Device Detection & Responsive Scaling System
+
+Diadopsi langsung dari **`NVSelfTitle`** dan **`NVDance`**. Sistem ini membedakan ukuran perangkat secara akurat dan memisahkan skala PC, Mobile, Tablet, dan Console secara independen.
+
+### Modul Logika Deteksi Perangkat:
+```lua
+local GuiService = game:GetService("GuiService")
+local UserInputService = game:GetService("UserInputService")
+local Workspace = game:GetService("Workspace")
+
+-- [KONFIGURASI SKALA INDEPENDEN PER PERANGKAT]
+local PC_Scale               = 1.0   -- Skala normal PC / Laptop
+local PC_Portrait_Scale      = 1.2   -- Jendela PC orientasi portrait
+local Mobile_Landscape_Scale = 1.45  -- Smartphone landscape
+local Mobile_Portrait_Scale  = 1.7   -- Smartphone portrait
+local Tablet_Landscape_Scale = 1.25  -- Tablet / iPad landscape
+local Tablet_Portrait_Scale  = 1.45  -- Tablet / iPad portrait
+local Console_Scale          = 1.15  -- PlayStation / Xbox / TV
+local GlobalScaleMultiplier  = 1.0
+
+-- Fungsi Cerdas Deteksi Perangkat (NVSelfTitle / NVDance Standard)
+local function GetDeviceType(vw: number, vh: number, mainFrame: GuiObject): string
+    -- 1. Opsi override untuk testing di Studio lewat Attribute "ForceDevice" pada MainFrame:
+    local forceDevice = mainFrame:GetAttribute("ForceDevice")
+    if forceDevice and (forceDevice == "Phone" or forceDevice == "Tablet" or forceDevice == "PC" or forceDevice == "Console") then
+        return forceDevice :: string
+    end
+
+    -- 2. Console (PlayStation / Xbox / Smart TV)
+    if GuiService:IsTenFootInterface() then
+        return "Console"
+    end
+
+    -- 3. Touch Device (Smartphone vs Tablet)
+    -- Touchscreen aktif dan keyboard fisik tidak aktif
+    if UserInputService.TouchEnabled and not UserInputService.KeyboardEnabled then
+        local smallerDimension = math.min(vw, vh)
+        -- Dimensi logika layar smartphone di Roblox umumnya < 550 pixel, Tablet >= 550 pixel
+        if smallerDimension > 0 and smallerDimension < 550 then
+            return "Phone"
+        else
+            return "Tablet"
+        end
+    end
+
+    -- 4. Default: Desktop / PC / Laptop
+    return "PC"
+end
+```
+
+### Handler Update Skala & Event Listener:
+```lua
+local function UpdateMainFrameScale(mainFrame: Frame, defaultSize: UDim2, isOpen: boolean)
+    local camera = Workspace.CurrentCamera
+    if not camera then return end
+
+    local vw, vh = camera.ViewportSize.X, camera.ViewportSize.Y
+    local isPortrait = vh > vw
+    local deviceType = GetDeviceType(vw, vh, mainFrame)
+
+    local baseScale = 1.0
+    if deviceType == "Phone" then
+        baseScale = isPortrait and Mobile_Portrait_Scale or Mobile_Landscape_Scale
+    elseif deviceType == "Tablet" then
+        baseScale = isPortrait and Tablet_Portrait_Scale or Tablet_Landscape_Scale
+    elseif deviceType == "Console" then
+        baseScale = Console_Scale
+    else
+        baseScale = isPortrait and PC_Portrait_Scale or PC_Scale
+    end
+
+    local totalScale = GlobalScaleMultiplier * baseScale
+
+    mainFrame.Size = UDim2.new(
+        defaultSize.X.Scale * totalScale,
+        defaultSize.X.Offset * totalScale,
+        defaultSize.Y.Scale * totalScale,
+        defaultSize.Y.Offset * totalScale
+    )
+
+    if isOpen then
+        mainFrame.Position = UDim2.new(0.5, 0, 0.5, 0)
+    end
+end
+```
+
+### Studio Attributes Testing Support:
+Pasang Attribute pada `MainFrame`:
+- `ForceDevice` (`String`: `"Phone"`, `"Tablet"`, `"PC"`, `"Console"`)
+- `PCScale` (`Number`)
+- `MobileScale` (`Number`)
+
+---
+
+## 3. NV Dark Modern Taste & Design Tokens
+
+Semua GUI NV-Series menggunakan tema gelap elegan (*business-grade dark mode*) dengan kontras tinggi dan sentuhan rounded halus.
+
+| Komponen | Token Warna / Properti | Nilai RGB / Hex | Kegunaan |
+| :--- | :--- | :--- | :--- |
+| **MainFrame Background** | `BackgroundColor3` | `Color3.fromRGB(28, 28, 30)` (`#1C1C1E`) | Latar belakang frame utama jendela |
+| **Card / Item Background** | `BackgroundColor3` | `Color3.fromRGB(25, 25, 25)` (`#191919`) | Latar belakang list item, segment container |
+| **Sub-Frame / Input** | `BackgroundColor3` | `Color3.fromRGB(13, 13, 13)` (`#0D0D0D`) | Textbox search, area preview, inner box |
+| **Border / UIStroke** | `Color`, `Thickness = 1` | `Color3.fromRGB(63, 63, 63)` (`#3F3F3F`) | Garis tepi halus (`ApplyStrokeMode.Border`) |
+| **Active Accent (Cyan)** | `Color3` | `Color3.fromRGB(0, 170, 255)` / `fromRGB(0, 255, 255)` | Tab aktif, border seleksi (`SelectStroke`) |
+| **Text Primary** | `TextColor3` | `Color3.fromRGB(255, 255, 255)` (`#FFFFFF`) | Judul, label penting, nama item |
+| **Text Secondary** | `TextColor3` | `Color3.fromRGB(163, 162, 165)` (`#A3A2A5`) | Deskripsi, subtitle, teks tidak aktif |
+
+### Corner Radius (`UICorner`):
+- `MainFrame`: `UDim.new(0, 10)` atau `UDim.new(0.03, 0)`
+- `Card / Container Frame`: `UDim.new(0, 8)` atau `UDim.new(0, 10)`
+- `Buttons / Pills / Tags`: `UDim.new(0.2, 0)` atau `UDim.new(0.5, 0)`
+
+### Tipografi (`Font`):
+- **Judul & Header:** `Enum.Font.GothamBold`
+- **Teks Tubuh & List:** `Enum.Font.Gotham` atau `Enum.Font.GothamMedium`
+- **Aksen / Badge:** `Enum.Font.FredokaOne` atau `Enum.Font.SourceSansBold`
+
+---
+
+## 4. UI Controller Script Template (LocalScript)
+
+Setiap ScreenGui memiliki Controller (`LocalScript`) dengan struktur standar berikut:
+
+```lua
+--!strict
+local Players = game:GetService("Players")
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local TweenService = game:GetService("TweenService")
+local UserInputService = game:GetService("UserInputService")
+local GuiService = game:GetService("GuiService")
+local Workspace = game:GetService("Workspace")
+
+local Modules = ReplicatedStorage:WaitForChild("Modules")
+local Maid = require(Modules:WaitForChild("Maid"))
+local Icon = require(ReplicatedStorage:WaitForChild("Icon")) -- TopbarPlus
+
+local GUI = script.Parent
+local MainFrame = GUI:WaitForChild("MainFrame") :: Frame
+local ScrollingFrame = MainFrame:FindFirstChildWhichIsA("ScrollingFrame", true)
+
+local Controller = {
+    _maid = Maid.new(),
+    IsOpen = false,
+    DefaultSize = MainFrame.Size,
+}
+
+-- [1] ANIMASI TOGGLE WINDOW (Pop-In & Slide)
+function Controller:Toggle(state: boolean)
+    self.IsOpen = state
+    local tweenInfo = TweenInfo.new(0.4, Enum.EasingStyle.Quint, Enum.EasingDirection.Out)
+    local targetPos = state and UDim2.new(0.5, 0, 0.5, 0) or UDim2.new(0.5, 0, -0.6, 0)
+
+    if state then
+        MainFrame.Visible = true
+        UpdateMainFrameScale(MainFrame, self.DefaultSize, true)
+    end
+
+    local tween = TweenService:Create(MainFrame, tweenInfo, { Position = targetPos })
+    tween:Play()
+
+    if not state then
+        tween.Completed:Connect(function()
+            if not self.IsOpen then
+                MainFrame.Visible = false
+            end
+        end)
+    end
+end
+
+-- [2] SELEKSI TOMBOL INTERAKTIF (Pola SelectStroke)
+function Controller:HighlightButton(parentContainer: Instance, activeBtn: Instance?)
+    for _, child in ipairs(parentContainer:GetChildren()) do
+        if child:IsA("TextButton") or child:IsA("ImageButton") then
+            local stroke = child:FindFirstChild("SelectStroke") :: UIStroke?
+            if not stroke then
+                stroke = Instance.new("UIStroke")
+                stroke.Name = "SelectStroke"
+                stroke.Thickness = 1
+                stroke.ApplyStrokeMode = Enum.ApplyStrokeMode.Border
+                stroke.Parent = child
+            end
+            if child == activeBtn then
+                stroke.Color = Color3.fromRGB(0, 255, 255)
+            else
+                stroke.Color = Color3.fromRGB(60, 60, 65)
+            end
+        end
+    end
+end
+
+-- [3] SETUP TOPBARPLUS ICON
+local topbarIcon = Icon.new()
+topbarIcon:setLabel(GUI.Name)
+topbarIcon.toggled:Connect(function(isSelected: boolean)
+    Controller:Toggle(isSelected)
+end)
+
+-- [4] HOOK CAMERA & ATTRIBUTES
+local function hookCamera()
+    local cam = Workspace.CurrentCamera
+    if cam then
+        cam:GetPropertyChangedSignal("ViewportSize"):Connect(function()
+            UpdateMainFrameScale(MainFrame, Controller.DefaultSize, Controller.IsOpen)
+        end)
+        UpdateMainFrameScale(MainFrame, Controller.DefaultSize, Controller.IsOpen)
+    end
+end
+hookCamera()
+Workspace:GetPropertyChangedSignal("CurrentCamera"):Connect(hookCamera)
+```
+
+---
+
+## 5. Komponen Interaktif Standar NV-Series
+
+### A. Vertical Slider (`VerticalSlider`)
+Diadopsi dari `NVMusic` (Volume Fader Master, Deck A/B Volume, Speed Control):
+- **Struktur Instance:**
+  - `SliderFrame` (Frame Track Vertikal: Width `0.12` - `0.2`, Height `0.85`, background `#101010`, `UICorner`, `UIStroke`, `UIPadding`).
+  - `Button` (Draggable Knob: AnchorPoint `0.5, 0.5`, `UICorner`).
+  - `ValueTextTarget` (TextLabel indikator nilai).
+- **Logika Luau:**
+  ```lua
+  local function ProcessVerticalInput(inputY, sliderFrame, minVal, maxVal, step)
+      local frameY = sliderFrame.AbsolutePosition.Y
+      local frameH = sliderFrame.AbsoluteSize.Y
+      if frameH <= 0 then return minVal end
+
+      local relativeY = math.clamp(inputY - frameY, 0, frameH)
+      local ratio = 1 - (relativeY / frameH) -- Dari bawah ke atas
+      local rawVal = minVal + ratio * (maxVal - minVal)
+      local steps = math.floor(rawVal / step + 0.5)
+      return math.clamp(steps * step, minVal, maxVal), ratio
+  end
+
+  local function UpdateVerticalVisual(button, ratio, textLabel, val)
+      button.Position = UDim2.new(
+          button.Position.X.Scale,
+          button.Position.X.Offset,
+          (1 - ratio),
+          -button.Size.Y.Offset / 2
+      )
+      if textLabel then
+          textLabel.Text = tostring(math.floor(val * 100) / 100)
+      end
+  end
+  ```
+
+---
+
+### B. Horizontal Slider (`HorizontalSlider`)
+Diadopsi dari `NVMusic` (Volume Horizontal, Master Crossfade) dan `NVDance` (Emote Speed Slider):
+- **Struktur Instance:**
+  - `SliderFrame` (Track Horizontal: Height `0.2` - `0.25`, Width `1.0`, background `#101010`, `UICorner`, `UIStroke`).
+  - `Fill` (Frame Bar kemajuan aksen Cyan/Putih, Size `UDim2.new(ratio, 0, 1, 0)`).
+  - `Button` / `Knob` (Frame/Button bulat, Position `UDim2.new(ratio, 0, 0.5, 0)`).
+  - `Trigger` (TextButton transparan pembungkus input sentuh `Size = UDim2.new(1, 0, 1, 0)`).
+- **Logika Luau:**
+  ```lua
+  local function ProcessHorizontalInput(inputX, barFrame, minVal, maxVal, step)
+      local frameX = barFrame.AbsolutePosition.X
+      local frameW = barFrame.AbsoluteSize.X
+      if frameW <= 0 then return minVal end
+
+      local relX = math.clamp((inputX - frameX) / frameW, 0, 1)
+      local rawVal = minVal + relX * (maxVal - minVal)
+      local steps = math.floor(rawVal / step + 0.5)
+      return math.clamp(steps * step, minVal, maxVal), relX
+  end
+
+  local function UpdateHorizontalVisual(fillFrame, knobFrame, ratio, valueLabel, val)
+      if fillFrame then fillFrame.Size = UDim2.new(ratio, 0, 1, 0) end
+      if knobFrame then knobFrame.Position = UDim2.new(ratio, -knobFrame.Size.X.Offset / 2, 0.5, 0) end
+      if valueLabel then valueLabel.Text = string.format("%.2f", val) end
+  end
+  ```
+
+---
+
+### C. Switch Button / Toggle (`ToggleSwitch`)
+Diadopsi dari `NVMusic.GuiController.ToggleSwitch` (DJ Switch Controller):
+- **Struktur Instance:**
+  - `SwitchContainer` (Frame Pill / Kapsul: `UICorner` CornerRadius `UDim.new(1, 0)`, background `#141414`).
+  - `SwitchFrame` (Indicator bulat / knob kecil di dalam container, `UICorner` `UDim.new(1, 0)`).
+  - `SwitchButton` (TextButton transparan `Size = UDim2.new(1, 0, 1, 0)`, `BackgroundTransparency = 1`).
+- **Logika & Animasi Tween Luau:**
+  ```lua
+  local ThemeColors = {
+      ActiveItem = Color3.fromRGB(0, 170, 255), -- Cyan saat ON
+      Background = Color3.fromRGB(20, 20, 20),   -- Gelap saat OFF
+      White = Color3.fromRGB(255, 255, 255),
+      SubText = Color3.fromRGB(150, 150, 150)
+  }
+
+  local function SetToggleState(isOn: boolean, container: Frame, indicator: Frame, animate: boolean)
+      local bgColor = isOn and ThemeColors.ActiveItem or ThemeColors.Background
+      local offset = indicator and indicator.Size.X.Offset or 14
+      local indicatorPos = isOn and UDim2.new(1, -(offset + 2), 0.5, 0) or UDim2.new(0, 2, 0.5, 0)
+      local indicatorColor = isOn and ThemeColors.White or ThemeColors.SubText
+
+      if animate then
+          TweenService:Create(container, TweenInfo.new(0.2), { BackgroundColor3 = bgColor }):Play()
+          TweenService:Create(indicator, TweenInfo.new(0.2), { Position = indicatorPos, BackgroundColor3 = indicatorColor }):Play()
+      else
+          container.BackgroundColor3 = bgColor
+          indicator.Position = indicatorPos
+          indicator.BackgroundColor3 = indicatorColor
+      end
+  end
+  ```
+
+---
+
+### D. Segment Frame (Tab Bar Segment)
+Diadopsi dari `NVMembership`, `NVServer`, `NVMusic`, dan `NVDance`:
+- **Struktur Instance:**
+  - `SegmentFrame` (Container Tab Horizontal: `BackgroundColor3 = Color3.fromRGB(25, 25, 25)`, `UICorner` kapsul `UDim.new(1, 0)` atau `0.5`, `UIPadding`, `UIStroke`).
+  - `UIListLayout` (FillDirection `Horizontal`, HorizontalAlignment `Center`, SortOrder `LayoutOrder`).
+  - Tab Buttons (`ServerListButton`, `PlayerListButton`, `ManageButton`, dll) dengan `UICorner` rounded.
+- **Logika Luau:**
+  ```lua
+  local function SetActiveTab(tabButtons: { [string]: TextButton }, activeTabName: string, contentFrames: { [string]: GuiObject })
+      for name, btn in pairs(tabButtons) do
+          if name == activeTabName then
+              btn.BackgroundColor3 = Color3.fromRGB(55, 55, 60) -- Active Tab
+          else
+              btn.BackgroundColor3 = Color3.fromRGB(25, 25, 25) -- Inactive Tab
+          end
+      end
+
+      for name, frame in pairs(contentFrames) do
+          frame.Visible = (name == activeTabName)
+      end
+  end
+  ```
+
+---
+
+### E. Standar Tombol Aktif & Inaktif (Button State Styling)
+1. **Gaya Tab / Segment (`ThemeColors`):**
+   - **Active:** `Color3.fromRGB(55, 55, 60)` (abu-abu terang kontras).
+   - **Inactive:** `Color3.fromRGB(25, 25, 25)` (abu-abu gelap menyatu dengan background).
+2. **Gaya Seleksi Item (`SelectStroke`):**
+   - Menggunakan child `UIStroke` bernama `SelectStroke` pada tombol:
+     - **Active (Selected):** `Color3.fromRGB(0, 255, 255)` (Cyan menyala).
+     - **Inactive:** `Color3.fromRGB(60, 60, 65)` (Outline abu-abu gelap).
+3. **Gaya Disable / Cooldown (`AutoButtonColor`):**
+   - Saat dalam cooldown / limit habis: `AutoButtonColor = false`, teks diubah menjadi `"WAIT (Xs)"` atau `"OUT OF QUOTA"`, dan warna teks/latar diredupkan.
+
+

package/agent-plugin/skills/nvstudio-mcp-guide/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: nvstudio-mcp-guide
+description: Panduan umum untuk berinteraksi dengan Roblox Studio menggunakan MCP nvstudio-mcp.
+---
+# nvstudio-mcp-guide
+
+Gunakan skill ini sebagai referensi umum saat bekerja dengan Roblox Studio via `nvstudio-mcp`.
+
+## Dasar Pemanggilan
+1. Jika target path tidak diketahui, gunakan perintah eksplorasi seperti `get_children` atau `search_instance` (khusus pencarian berdasarkan nama) terlebih dahulu.
+2. Tentukan target path string yang valid (misalnya `game.Workspace.Model.Part`). LLM/Agent tidak bisa berinteraksi menggunakan reference Luau langsung.
+3. Gunakan native semantic tools yang tersedia (`execute_luau`, `batch_create_instances`, `get_roblox_docs`, dll.) atau gunakan legacy dispatcher `call_mcp_tool` untuk kompatibilitas.
+
+## Batch Instance Builder (`batch_create_instances` & `batch_set_properties`)
+Saat membuat banyak instance (terutama struktur GUI seperti `MainFrame`, `UICorner`, `UIStroke`, `UIListLayout`, `UIPadding`, `ScrollingFrame`, `Spacer`), **JANGAN** membuat instance satu per satu dengan `create_instance`. Gunakan `batch_create_instances`:
+- **Mode `tree` (Rekomendasi Utama UI):**
+  Membangun seluruh hierarki bersarang dalam 1 roundtrip:
+  ```json
+  {
+    "target": "StarterGui.NVMenu",
+    "tree": {
+      "className": "Frame",
+      "name": "MainFrame",
+      "properties": {
+        "Size": [0.5, 0, 0.6, 0],
+        "Position": [0.5, 0, 0.5, 0],
+        "AnchorPoint": [0.5, 0.5],
+        "BackgroundColor3": [28, 28, 30]
+      },
+      "children": [
+        { "className": "UICorner", "name": "UICorner", "properties": { "CornerRadius": [0, 10] } },
+        { "className": "UIStroke", "name": "UIStroke", "properties": { "Color": [63, 63, 63], "Thickness": 1 } },
+        { "className": "UIListLayout", "name": "UIListLayout", "properties": { "SortOrder": "LayoutOrder" } },
+        { "className": "UIPadding", "name": "UIPadding", "properties": { "PaddingTop": [0, 10] } }
+      ]
+    }
+  }
+  ```
+- **Mode `instances` (Flat Array):**
+  Membuat banyak objek di berbagai parent berbeda sekaligus:
+  ```json
+  {
+    "instances": [
+      { "className": "Part", "name": "LightA", "parent": "Workspace.Lights", "properties": { "Anchored": true } },
+      { "className": "Part", "name": "LightB", "parent": "Workspace.Lights", "properties": { "Anchored": true } }
+    ]
+  }
+  ```
+- **Pembaruan Massal (`batch_set_properties`):**
+  Untuk mengubah properti banyak instance secara atomik dalam 1 pemanggilan:
+  ```json
+  {
+    "updates": [
+      { "target": "Workspace.PartA", "properties": { "Transparency": 0.5, "CanCollide": false } },
+      { "target": "Workspace.PartB", "properties": { "Color": [255, 0, 0] } }
+    ]
+  }
+  ```
+
+## Verifikasi Dokumentasi Engine Resmi (`get_roblox_docs`)
+Sebelum menulis skrip Luau atau menggunakan API/Service yang belum pasti nama properti atau method-nya, **selalu panggil `get_roblox_docs`**:
+- **Format Panggilan:**
+  - `query`: Nama class, service, datatype, enum, atau library (contoh: `"TweenService"`, `"CanvasGroup"`, `"UDim2"`, `"EasingStyle"`, `"task"`).
+  - `member` *(opsional)*: Untuk menghemat token, tentukan nama method atau properti spesifik (contoh: `query: "CanvasGroup", member: "GroupTransparency"`).
+- **Keunggulan:** Tool ini membaca data resmi terverifikasi dari Creator Docs dengan caching lokal berkecepatan tinggi (~2 ms) untuk mencegah halusinasi kode Luau.
+
+## Modifikasi Skrip Cerdas (`patch_script_source`)
+- Jika hanya ingin mengubah sebagian baris kode tanpa menimpa seluruh file skrip, gunakan `patch_script_source` dengan parameter `search` dan `replacement`.
+- Untuk penggantian skrip utuh, gunakan `update_script_source` (otomatis dicek oleh AST Validator di Node.js untuk mencegah syntax error fatal).
+
+## Rigging, Animasi Karakter & Efek Visual (v2.4+)
+nvstudio-mcp dilengkapi dengan rangkaian modular tripartit:
+1. **NV-Rig Engine** (lihat skill `nvstudio-rig-engine`):
+   - Gunakan `inspect_rig` untuk diagnosa kesehatan sendi & anchor status.
+   - Gunakan `auto_rig` untuk membuat rig R6, R15, atau menautkan senjata (`Weapon`).
+   - Gunakan `edit_rig_joint` untuk memindahkan pivot tanpa dislokasi part anak.
+   - Gunakan `weld_assembly` untuk menyatukan armor/prop/kendaraan.
+2. **NV-Animation Engine** (lihat skill `nvstudio-animation-vfx`):
+   - Gunakan `animate_character` untuk membuat animasi resmi `KeyframeSequence` di `AnimSaves` (Walk, Slash, Punch, Idle).
+   - Gunakan `solve_limb_ik` untuk analytical 2-link LimbIK ke koordinat 3D.
+   - Gunakan `scrub_timeline` untuk scrubbing playhead waktu deterministik.
+3. **NV-VFX Subsystem** (lihat skill `nvstudio-animation-vfx`):
+   - Gunakan `scan_vfx` untuk memindai efek visual dan `apply_vfx` untuk merekonstruksinya dari database persisten.

package/agent-plugin/skills/nvstudio-rig-engine/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: nvstudio-rig-engine
+description: Panduan AI Agent untuk memeriksa, membuat, mengedit poros (C0/C1 tanpa dislokasi), auto-rigging R6/R15/senjata, dan mengelas assembly model di Roblox Studio menggunakan NV-Rig Engine.
+---
+
+# NV-Rig Engine: Headless Modular Rigging Suite Guide
+
+Panduan resmi untuk AI Agent dalam mengoperasikan sistem rigging Roblox secara headless menggunakan **NV-Rig Engine**. Modul ini melengkapi **NV-Animation Engine** dan **NV-VFX Subsystem** untuk menghasilkan alur kerja karakter yang lengkap dan anti-halusinasi.
+
+---
+
+## 1. Kapan Harus Menggunakan NV-Rig Engine
+
+Gunakan tool-tool NV-Rig Engine saat:
+- Karakter atau model impor belum memiliki `Motor6D` / sendi gerak.
+- Titik tumpu (*pivot*) bahu, siku, lutut, atau sayap berada di posisi yang salah dan perlu digeser tanpa merusak susunan visual part.
+- Bagian tubuh masih ter-anchor (`Anchored = true`) sehingga animasi tidak dapat menggerakkannya.
+- Ingin menautkan senjata, perisai, atau pedang ke tangan karakter (`Weapon Grip`).
+- Ingin mengelas (*weld*) seluruh komponen helm, armor, atau kendaraan menjadi satu kesatuan kaku.
+- Ingin menyalin konfigurasi sendi sisi kiri ke sisi kanan secara simetris cermin (*X-axis mirror*).
+
+---
+
+## 2. Inspeksi Rig Mendalam (`inspect_rig`)
+
+Selalu awali dengan memanggil `inspect_rig` sebelum melakukan rigging atau animasi untuk mendeteksi potensi masalah secara dini:
+
+```json
+{
+  "target": "Workspace.CharacterModel"
+}
+```
+
+### Yang Didiagnosis oleh `inspect_rig`:
+1. **Daftar Joint**: Semua `Motor6D` dan `Weld`, lengkap dengan nama `Part0`, `Part1`, $C_0$, $C_1$, dan koordinat poros dunia 3D.
+2. **Anchor Warning**: Mendeteksi part yang masih `Anchored = true`. Part anak yang ter-anchor tidak akan bergerak saat dianimasikan!
+3. **Circular Dependency**: Mendeteksi jika ada siklus sambungan tertutup yang dapat membekukan simulasi fisika Roblox.
+4. **Root Part**: Menemukan calon part induk utama (misal `HumanoidRootPart` atau `Torso`).
+
+---
+
+## 3. Auto-Rigging Cerdas 1-Klik (`auto_rig`)
+
+Alih-alih membuat belasan sendi satu per satu, gunakan `auto_rig` untuk membangun pohon hierarki standar dalam sekejap:
+
+### A. Auto-Rig Avatar R15
+Membangun 15 sambungan Motor6D lengkap (`Root`, `Waist`, `Neck`, bahu, siku, pergelangan tangan, panggul, lutut, pergelangan kaki):
+```json
+{
+  "target": "Workspace.CustomR15Avatar",
+  "rig_type": "R15"
+}
+```
+
+### B. Auto-Rig Avatar R6
+Membangun 6 sambungan Motor6D klasik (`RootJoint`, `Neck`, `Left Shoulder`, `Right Shoulder`, `Left Hip`, `Right Hip`):
+```json
+{
+  "target": "Workspace.CustomR6Avatar",
+  "rig_type": "R6"
+}
+```
+
+### C. Auto-Rig Senjata / Tool
+Menghubungkan senjata ke tangan karakter dengan `Motor6D` dinamai `WeaponGrip` dan mengelas seluruh bagian senjata lainnya ke `Handle`:
+```json
+{
+  "target": "Workspace.Knight",
+  "rig_type": "Weapon",
+  "weapon_target": "Workspace.GreatSword",
+  "target_limb": "RightHand"
+}
+```
+
+---
+
+## 4. Manipulasi Poros Sendi Presisi (`edit_rig_joint`)
+
+Gunakan `edit_rig_joint` untuk menggeser, memutar, mereset, menyelaraskan, atau membuat sendi baru.
+
+### A. Geser Poros Sendi (Non-Dislocation Law)
+Menggeser titik engsel sendi di dunia nyata tanpa membuat part anak terlempar:
+```json
+{
+  "target": "Workspace.CharacterModel",
+  "action": "edit_pivot",
+  "joint_name": "RightShoulder",
+  "delta_world": [0, 0.5, 0]
+}
+```
+
+### B. Pindahkan Poros ke Koordinat Dunia Tertentu
+Menempatkan titik engsel tepat pada koordinat target 3D:
+```json
+{
+  "target": "Workspace.CharacterModel",
+  "action": "edit_pivot",
+  "joint_name": "RightElbow",
+  "target_world": [10.5, 5.0, -12.3]
+}
+```
+
+### C. Putar Orientasi Poros
+Memutar orientasi sumbu lokal sendi sebesar sudut Euler derajat:
+```json
+{
+  "target": "Workspace.CharacterModel",
+  "action": "rotate_pivot",
+  "joint_name": "Neck",
+  "rotate_euler_deg": [0, 90, 0]
+}
+```
+
+### D. Reset Poros ke Pusat Part Anak
+Mengembalikan $C_0$ langsung ke origin Part1 dan mengosongkan $C_1$:
+```json
+{
+  "target": "Workspace.CharacterModel",
+  "action": "reset_pivot",
+  "joint_name": "LeftShoulder"
+}
+```
+
+### E. Buat Sendi Baru Secara Spesifik
+```json
+{
+  "target": "Workspace.CharacterModel",
+  "action": "create_joint",
+  "joint_name": "TailJoint1",
+  "part0": "LowerTorso",
+  "part1": "TailBase"
+}
+```
+
+---
+
+## 5. Pengelasan Assembly Model (`weld_assembly`)
+
+Gunakan `weld_assembly` untuk menyatukan seluruh komponen pada sebuah model (aksesori, sayap dekoratif, helm, armor, kendaraan) ke part jangkar utama:
+```json
+{
+  "target": "Workspace.ArmorSet",
+  "primary_part": "Chestplate"
+}
+```
+*Catatan: Semua part anak otomatis di-unanchor dan dilas ke `Chestplate` menggunakan transformasi $C_0$ yang presisi.*
+
+---
+
+## 6. Pencerminan Simetri Bilateral (`mirror_rig`)
+
+Jika Anda telah mengonfigurasi poros sendi sisi kiri (`LeftShoulder`, `LeftElbow`, dll.), gunakan `mirror_rig` untuk mencerminkan nilai $C_0$ dan $C_1$ ke sisi kanan secara simetris sepanjang sumbu $X$:
+```json
+{
+  "target": "Workspace.CharacterModel",
+  "source_side": "Left"
+}
+```
+
+---
+
+## 7. Alur Kerja Komprehensif: Rigging $\rightarrow$ Animasi $\rightarrow$ VFX
+
+Ketika pengguna meminta animasi pertarungan lengkap:
+1. **Langkah 1**: Panggil `inspect_rig` pada karakter. Jika belum ada joint, jalankan `auto_rig` (mode `"R15"`).
+2. **Langkah 2**: Jika ada senjata, panggil `weld_assembly` pada senjata, lalu panggil `auto_rig` mode `"Weapon"`.
+3. **Langkah 3**: Buat animasi halus menggunakan `animate_character` (misal aksi `"melee_slash"` dengan `vfx_events`).
+4. **Langkah 4**: Pasang efek visual menggunakan `apply_vfx` dari database persisten.
+5. **Langkah 5**: Scrub timeline menggunakan `scrub_timeline` ke timestamp tebasan untuk memverifikasi pose dan partikel.
+

package/agent-plugin/skills/nvstudio-roblox-sync-guide/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: nvstudio-roblox-sync-guide
+description: Aturan anti-halusinasi untuk membaca, mengedit, dan me-rollback script Roblox.
+---
+# nvstudio-roblox-sync-guide
+
+Panduan sinkronisasi dan manajemen skrip (properti `.Source`) di Roblox Studio.
+
+## Aturan update_script_source
+1. **PENTING:** Anda WAJIB melakukan `get_script_source` terlebih dahulu sebelum mengedit script apa pun. Ini agar Anda memahami kode apa yang ada saat ini dan mencegah hilangnya kode krusial.
+2. Operasi ini menimpa KESELURUHAN kode di dalam skrip.
+3. Server jembatan memiliki "Luau AST Validator" internal. Jika script Anda mengandung syntax error fatal (seperti lupa `end`), file tidak akan diupdate dan Anda akan menerima pesan error. 
+
+## Aturan rollback_script
+1. Anda dapat membatalkan perubahan terakhir pada script dengan memanggil `rollback_script`.
+2. Pastikan target path cocok persis dengan script yang baru saja Anda edit.