@adiholick/nvstudio-mcp 2.2.3 → 2.4.0

package/README.md

@@ -1,11 +1,46 @@
 # nvstudio-mcp 🚀
 
-**nvstudio-mcp** adalah jembatan pintar (*Model Context Protocol Bridge*) yang menghubungkan Asisten AI Anda (seperti Antigravity IDE, Cursor, Claude Desktop, atau Windsurf) secara langsung ke dalam **Roblox Studio**. Dengan plugin ini, AI Anda dapat membaca, mengedit script, men-generate terrain, dan berinteraksi dengan API Roblox Studio layaknya seorang asisten *Co-Pilot* sejati.
+**nvstudio-mcp** adalah jembatan pintar (*Model Context Protocol Bridge*) yang menghubungkan Asisten AI Anda (seperti Antigravity IDE, Cursor, Claude Desktop, atau Windsurf) secara langsung ke dalam **Roblox Studio**. Dengan plugin ini, AI Anda dapat membaca dan mengedit skrip, membangun hierarki GUI massal, memindai keamanan model 3D, mencari dokumentasi engine resmi, men-generate terrain, dan berinteraksi dengan API Roblox Studio layaknya seorang asisten *Co-Pilot* sejati.
 
 Sistem ini didesain menggunakan **Hybrid Architecture** yang memisahkan logika Engine (*Studio Plugin*) dan aturan anti-halusinasi (*Agent Plugin*).
 
 ---
 
+## 🌟 Fitur Unggulan v2.4 (Animation, VFX & Rigging Suite)
+
+- 🏗️ **NV-Rig Engine & Joint Kinematics (`inspect_rig`, `auto_rig`, `edit_rig_joint`, `weld_assembly`, `mirror_rig`)**:
+  - **Pure Headless Dispatcher**: Operasi rigging deterministik instan ($O(1)$) tanpa overhead render visual.
+  - **Hukum Non-Dislokasi Poros (*Non-Dislocation Law*)**: Menggeser/memutar titik engsel sendi di dunia nyata dengan kompensasi otomatis $C_1 = C_{1\text{old}} \times \text{diff}$ tanpa pernah mendislokasi part anak.
+  - **1-Click Auto-Rigging**: Membangun rig lengkap R6 (6 part), R15 (15 part), maupun penautan senjata (`WeaponGrip`) secara instan dengan auto-unanchor.
+  - **Bilateral X-Axis Mirroring & Assembly Welder**: Refleksi simetris sendi kiri $\leftrightarrow$ kanan dan pengelasan seluruh komponen armor/prop ke part jangkar utama.
+- 🏃 **NV-Animation Engine & Kinematics (`animate_character`, `solve_limb_ik`, `scrub_timeline`)**:
+  - **Human-like Motion Synthesis**: Menghasilkan animasi karakter berkualitas tinggi (Walk, Slash, Punch, Idle Breath) berbasis prinsip animasi alami (Anticipation, Follow-Through).
+  - **Interpolasi Kurva Halus**: Menggunakan kurva Cubic Bezier (`PoseEasingStyle.Cubic`) dan Quaternion SLERP 4D rotation interpolation bebas *Gimbal Lock*.
+  - **Analytical 2-Link LimbIK O(1)**: Penyelesaian sudut tekukan siku dan lutut menggunakan Hukum Cosinus sudut tertutup instan dan ekstensi SoftIK anti-snapping.
+  - **Official KeyframeSequence**: Animasi disimpan langsung ke instance resmi di `AnimSaves` karakter, bukan script loop runtime.
+- ✨ **NV-VFX Subsystem & Cross-Project Database (`scan_vfx`, `apply_vfx`, `list_vfx_database`, `delete_vfx`)**:
+  - **1:1 Pure Table Serializer**: Mengonversi `ParticleEmitter`, `Beam`, `Trail`, `Light`, dan `Attachment` menjadi tabel data murni JSON dengan relasi pointer yang aman.
+  - **Database Lintas-Proyek**: Pindai VFX di Project A dan pasang kembali di Project B dengan faktor skala ukuran opsional (`scale`). Dilengkapi 5 preset bawaan (*Cyan Slash*, *Solar Burst*, *Dragon Aura*, *Arcane Rune*, *Emerald Beam*).
+  - **Web Category Browser**: Tab antarmuka web modern dengan filter kategori, pencarian real-time, preview JSON, dan aksi 1-klik.
+- ⚡ **Batch Instance Builder (`batch_create_instances`, `batch_set_properties`)**:
+  - Membangun hierarki objek/UI bersarang puluhan tingkat secara instan dalam 1 putaran request (mengeliminasi 10–20 latency roundtrips).
+  - Pembaruan properti massal secara atomik dengan dukungan penuh tipe data Roblox (`UDim`, `UDim2`, `Vector2`, `Vector3`, `NumberRange`, `Rect`, dll).
+- 🛡️ **Asset Security Scanner (`preview_asset`, `scan_security`, safe `insert_asset`)**:
+  - Audit 10 jenis ancaman berbahaya (backdoor `require`, bytecode/hex obfuscation, `loadstring`, Discord webhook loggers, IP stealer, fake gamepass prompt, off-screen hidden padding).
+  - Pratinjau aset terisolasi sebelum dimasukkan ke game dan auto-sanitasi skrip (`strip_scripts = true` secara default).
+- 📚 **Live Roblox Engine API & Docs Lookup (`get_roblox_docs`)**:
+  - Mengambil dokumentasi resmi terverifikasi langsung dari Roblox Creator Docs (Class, Datatype, Enum, Library, dan Service).
+  - Dilengkapi filter nama member spesifik dan caching disk lokal super cepat (~2 ms) untuk mencegah halusinasi kode Luau.
+- 🎨 **Standarisasi Desain GUI & Smart Responsive Scaling**:
+  - Panduan baku UI modern (*Dark Modern Theme* #1C1C1E, #191919, aksen Cyan #00AAFF).
+  - Deteksi perangkat responsif pintar (`GetDeviceType` memisahkan PC, Phone, Tablet, dan Console secara terisolasi).
+- 🔄 **Real-Time Polling Stream & Visual Dashboard**:
+  - Komunikasi sub-detik yang sangat stabil dan bebas latensi. Buka [http://localhost:3055](http://localhost:3055) di browser Anda untuk memantau antrean perintah, status koneksi Studio, dan log eksekusi.
+- 🧹 **Anti-Zombie Port & Auto-Connect**:
+  - Port `3055` dibersihkan secara otomatis jika terjadi force-close, dan plugin Studio otomatis terhubung tanpa perlu menekan tombol manual.
+
+---
+
 ## 📥 Instalasi
 
 Langkah instalasi dirancang **sangat mudah dan otomatis!**
@@ -32,8 +67,8 @@ curl -fsSL https://raw.githubusercontent.com/Adiholick/nvstudio-mcp/main/install
 **Apa saja yang dilakukan installer ini secara otomatis?**
 1. 📦 Mengunduh source code, memasang dependensi Node.js, dan mengkompilasi TypeScript (*Bridge Server*).
 2. 🧩 **Memasang Plugin Roblox Studio (`nvstudio_mcp.rbxmx`) otomatis** ke folder sistem Roblox Studio Anda (`%LOCALAPPDATA%\Roblox\Plugins` di Windows atau `~/Documents/ROBLOX/Plugins` di macOS).
-3. 🧠 **Universal AI Skill Installer**: Secara cerdas memindai dan mengunduh library skill 29+ *roblox-brain* dan *nvstudio-mcp-guide*, lalu menginjeksinya langsung ke dalam struktur `skills/` dari **AI Agent apapun** yang Anda gunakan (mendukung **Antigravity IDE**, **Cursor**, **Claude Code**, **Codex**, **OpenCode**, dan **Roo Code**).
-4. ⚙️ Melakukan auto-konfigurasi jika mendeteksi editor **Cursor** (`.cursor/mcp.json`) atau **Antigravity** (`mcp_config.json`).
+3. 🧠 **Universal AI Skill Installer**: Menginjeksi skill pemandu (*nvstudio-mcp-guide*, *nvstudio-gui-standards*, *nvstudio-animation-vfx*, *nvstudio-rig-engine*, *nvstudio-assets-terrain-guide*, *nvstudio-roblox-sync-guide*) dan aturan anti-halusinasi langsung ke struktur editor AI Anda (**Antigravity IDE**, **Cursor**, **Claude Code**, **Codex**, **OpenCode**, dan **Windsurf**).
+4. ⚙️ Melakukan auto-konfigurasi registrasi MCP server pada editor yang terdeteksi.
 
 ---
 
@@ -43,18 +78,18 @@ Karena pembatasan keamanan bawaan Roblox Studio, akses HTTP harus diizinkan seka
 1. Buka game/place Anda di **Roblox Studio**.
 2. Di toolbar atas, buka tab **Home** ➔ **Game Settings** ➔ pilih menu **Security**.
 3. Centang (aktifkan) **`Allow HTTP Requests`**, lalu klik **Save**.
-4. **Auto-Detect Aktif!** Plugin Roblox Studio kini memiliki heartbeat pintar yang akan otomatis terhubung (*Auto-Connect*) segera setelah MCP server aktif — Anda tidak perlu lagi repot menekan tombol connect secara manual.
+4. **Auto-Detect Aktif!** Plugin Roblox Studio akan otomatis terhubung (*Connected*) segera setelah server bridge aktif.
 
 ---
 
 ### 📂 Alternatif: Instalasi Plugin Secara Manual (Opsional)
 
 Jika Anda **tidak** menggunakan skrip installer otomatis di atas (misalnya hanya menambahkan server via `npx` di klien AI), pasang file plugin Roblox Studio secara manual:
-1. Ambil file `nvstudio_mcp.rbxmx` dari folder [studio-plugin/nvstudio_mcp.rbxmx](file:///studio-plugin/nvstudio_mcp.rbxmx).
+1. Ambil file `nvstudio_mcp.rbxmx` dari folder `studio-plugin/nvstudio_mcp.rbxmx`.
 2. Pindahkan/salin file tersebut ke direktori plugin Roblox di komputer Anda:
-   - **Windows:** `%LOCALAPPDATA%\Roblox\Plugins` (atau `C:\Users\<Username>\AppData\Local\Roblox\Plugins`)
+   - **Windows:** `%LOCALAPPDATA%\Roblox\Plugins`
    - **macOS:** `~/Documents/ROBLOX/Plugins`
-3. Restart atau buka kembali Roblox Studio. Plugin akan muncul di tab **Plugins**.
+3. Buka atau buka kembali Roblox Studio. Plugin akan muncul di tab **Plugins**.
 
 ---
 
@@ -75,7 +110,6 @@ Tambahkan konfigurasi berikut ke file `mcp.json` Anda:
   }
 }
 ```
-*(AI Anda akan selalu menjalankan versi terbaru dari server Bridge langsung dari NPM!)*
 
 ### Klien Berbasis Instalasi Lokal (Antigravity IDE)
 Jika Anda menggunakan instalasi lokal via installer di `%USERPROFILE%\.nvstudio-mcp`, tambahkan ke `~/.gemini/config/mcp_config.json`:
@@ -94,47 +128,23 @@ Jika Anda menggunakan instalasi lokal via installer di `%USERPROFILE%\.nvstudio-
 
 ---
 
-## 🖥️ Dashboard Visual & Fitur Unggulan v2.1
-
-- **High-Performance Polling Stream & SSE:** Komunikasi antara Roblox Studio dan Bridge Server menggunakan arsitektur snapshot stream sub-detik yang sangat responsif, stabil, dan bebas latensi.
-- **Clean Log Engine:** Log status pada Roblox Studio hanya diperbarui saat ada perubahan status koneksi sebenarnya (bebas dari log spam berulang).
-- **Visual Dashboard Real-time:** Buka [http://localhost:3055](http://localhost:3055) di browser Anda untuk melihat monitor antrean perintah, log aktivitas AI, status koneksi Studio, dan statistik eksekusi secara visual.
-- **Auto-Detect & Auto-Connect:** Plugin Roblox Studio otomatis menyambung ke server saat aktif dan kembali menunggu (*Waiting*) saat server mati tanpa perlu campur tangan manual.
-- **Anti-Zombie Port Handling:** Port `3055` dibersihkan secara otomatis jika terjadi penutupan atau restart IDE secara paksa.
-
----
-
 ## 🗑️ Cara Uninstall (Mencopot Pemasangan)
 
-Jika Anda ingin berhenti menggunakan `nvstudio-mcp`, Anda dapat membersihkannya dari sistem Anda secara menyeluruh dengan 4 langkah berikut:
-
-### 1. Hapus Plugin dari Roblox Studio
-Hapus file plugin dari folder lokal Roblox Anda.
-- **Windows:** Buka folder `%LOCALAPPDATA%\Roblox\Plugins` (atau `AppData\Local\Roblox\Plugins`) dan hapus file `nvstudio_mcp.rbxmx` (atau `nvstudio_mcp.rbxm`).
-- **macOS:** Buka folder `~/Documents/ROBLOX/Plugins` dan hapus file `nvstudio_mcp.rbxmx` (atau `nvstudio_mcp.rbxm`).
-
-### 2. Hapus Agen dari Antigravity (Jika Menggunakan AGY)
-Hapus *bundle* keterampilan *anti-halusinasi* dari memori AI Anda:
-```bash
-rm -rf ~/.gemini/config/plugins/nvstudio-mcp
-```
-*(Untuk pengguna Windows PowerShell, Anda bisa menghapus folder `C:\Users\NamaAnda\.gemini\config\plugins\nvstudio-mcp` secara manual).*
-
-### 3. Hapus File Instalasi Node.js
-Installer `install.sh` sebelumnya mengkloning repositori dan menginstal Node.js di dalam direktori *Home* Anda (secara bawaan di `~/.nvstudio-mcp`). Hapus direktori tersebut:
-```bash
-rm -rf ~/.nvstudio-mcp
-```
-
-### 4. Hapus Konfigurasi dan Skills dari Editor AI Anda
-Jika Anda memasukkan konfigurasi MCP secara otomatis ke Cursor atau secara manual ke Claude Desktop, buka file pengaturan `mcp.json` tersebut dan **hapus blok `"nvstudio-mcp"`** dari dalam objek `mcpServers`.
-
-**Untuk membersihkan skill bawaan (Universal Skill Installer):**
-Anda bisa menghapus manual symlink/folder shortcut (yang bernama awalan `roblox-`) dari dalam folder konfigurasi agen Anda:
-- **Cursor / Workspace Lokal**: Hapus isi `.cursor/skills` dan `.cursor/roblox-brain.md`
-- **Claude Code**: Hapus dari `~/.claude/skills`
-- **Codex / OpenCode**: Hapus dari direktori lokal atau global (`~/.codex/skills`, `~/.opencode/skills`).
+Jika Anda ingin membersihkan `nvstudio-mcp` dari sistem Anda secara menyeluruh:
+
+1. **Hapus Plugin dari Roblox Studio:**
+   - Hapus file `nvstudio_mcp.rbxmx` dari `%LOCALAPPDATA%\Roblox\Plugins` (Windows) atau `~/Documents/ROBLOX/Plugins` (macOS).
+2. **Hapus AI Plugin Antigravity:**
+   ```bash
+   rm -rf ~/.gemini/config/plugins/nvstudio-mcp
+   ```
+3. **Hapus Direktori Instalasi Node.js:**
+   ```bash
+   rm -rf ~/.nvstudio-mcp
+   ```
+4. **Hapus Konfigurasi MCP:**
+   Hapus blok `"nvstudio-mcp"` dari file konfigurasi `mcp.json` editor AI Anda.
 
 ---
 
-**Selamat Menciptakan Game Impian Anda dengan AI! 🎮🤖**
+**Selamat Menciptakan Game Impian Anda dengan AI! 🎮🤖**

package/agent-plugin/mcp_config.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "nvstudio-mcp": {
+      "command": "npx",
+      "args": ["-y", "@adiholick/nvstudio-mcp@latest"]
+    }
+  }
+}

package/agent-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "nvstudio-mcp",
+  "version": "1.0.0",
+  "description": "Roblox Studio MCP plugin with AI Agent Skills for Claude/Antigravity",
+  "author": "Antigravity IDE User"
+}

package/agent-plugin/rules/AGENTS.md

@@ -0,0 +1,118 @@
+# NVStudio GUI Design Rules & Aesthetic Taste
+
+Saat diminta membuat, memperbarui, atau merancang GUI di Roblox Studio (`StarterGui`), Anda WAJIB mematuhi aturan standar NV-Series (`NVMembership`, `NVMusic`, `NVSelfTitle`, `NVServer`, `NVDance`) di bawah ini:
+
+## 1. Instance Structure Rule (Bukan Script Murni)
+- **MUTLAK:** Semua GUI dibuat dalam bentuk **Roblox Instance konkret di dalam `StarterGui`**, BUKAN script Luau murni yang membangun ratusan baris `Instance.new` saat runtime.
+- Bangun hierarki instance menggunakan tool MCP (`create_instance`, `set_properties`, atau generator Luau studio).
+- Script Luau (`LocalScript`) HANYA bertindak sebagai Controller / Listener event, animasi `TweenService`, state, dan komunikasi jaringan.
+
+## 2. Root & MainFrame Standard
+- **ScreenGui Root:**
+  - Wajib menyetel `ResetOnSpawn = false`.
+  - Wajib menyetel `ZIndexBehavior = Enum.ZIndexBehavior.Sibling`.
+- **MainFrame:**
+  - Setiap `ScreenGui` WAJIB memiliki child utama bertipe `Frame` bernama **`MainFrame`** (atau `ContainerFrame` pembungkus `MainFrame`).
+  - AnchorPoint standar: `Vector2.new(0.5, 0.5)` dengan Position di tengah layar `UDim2.new(0.5, 0, 0.5, 0)`.
+
+## 3. Frame Layout & Deterministic Order Rules
+- **Wajib UIListLayout & UIPadding:**
+  - **Setiap `Frame`** (termasuk `MainFrame`, container, header, sub-frame, list container) WAJIB memiliki `UIListLayout` (dengan `SortOrder = Enum.SortOrder.LayoutOrder`) dan `UIPadding`.
+- **Wajib LayoutOrder pada Setiap Item:**
+  - Semua child `GuiObject` di dalam Frame yang menggunakan layout WAJIB disetel properti `LayoutOrder`-nya secara eksplisit (0, 1, 2, 3...) agar tidak ada tumpang tindih acak.
+
+## 4. ScrollingFrame Spacer Rule
+- **Wajib Frame Spacer:**
+  - Setiap `ScrollingFrame` WAJIB memiliki child Frame pembatas transparan bernama **`Spacer`** atau **`SPACER`**.
+  - Properti Spacer: `BackgroundTransparency = 1`, `BorderSizePixel = 0`, dan `LayoutOrder = 99999` (atau `999999999`).
+  - Spacer berfungsi sebagai margin penutup agar elemen list paling bawah tidak terpotong tepi scrolling frame.
+
+## 5. Smart Device Detection & Responsive Scaling
+Setiap Controller GUI wajib menyertakan fungsi cerdas pendeteksi perangkat yang diadopsi dari `NVSelfTitle` dan `NVDance`:
+```lua
+local function GetDeviceType(vw: number, vh: number, mainFrame: GuiObject): string
+    local forceDevice = mainFrame:GetAttribute("ForceDevice")
+    if forceDevice and (forceDevice == "Phone" or forceDevice == "Tablet" or forceDevice == "PC" or forceDevice == "Console") then
+        return forceDevice :: string
+    end
+
+    if game:GetService("GuiService"):IsTenFootInterface() then
+        return "Console"
+    end
+
+    local uis = game:GetService("UserInputService")
+    if uis.TouchEnabled and not uis.KeyboardEnabled then
+        local smaller = math.min(vw, vh)
+        if smaller > 0 and smaller < 550 then
+            return "Phone"
+        else
+            return "Tablet"
+        end
+    end
+
+    return "PC"
+end
+```
+- Skala responsif PC, Mobile (Phone), Tablet, dan Console dihitung secara terpisah agar perubahan skala HP tidak merusak tampilan PC.
+- Berikan listener pada `Workspace.CurrentCamera:GetPropertyChangedSignal("ViewportSize")`.
+
+## 6. NV Dark Modern Taste & Design Tokens
+- **Background Utama (MainFrame):** `Color3.fromRGB(28, 28, 30)` (`#1C1C1E`).
+- **Background Card / Item / Container:** `Color3.fromRGB(25, 25, 25)` (`#191919`).
+- **Background Sub-box / Search / Input:** `Color3.fromRGB(13, 13, 13)` (`#0D0D0D`).
+- **Border / Outline:** Gunakan `UIStroke` dengan `Color = Color3.fromRGB(63, 63, 63)` (`#3F3F3F`), `Thickness = 1`, `ApplyStrokeMode = Enum.ApplyStrokeMode.Border`.
+- **Aksen Aktif & Seleksi:** Cyan `Color3.fromRGB(0, 170, 255)` atau `Color3.fromRGB(0, 255, 255)`.
+- **Corner Radius:** Selalu gunakan `UICorner` (`UDim.new(0, 8)` s/d `UDim.new(0, 10)` untuk Frame/Card, dan `UDim.new(0.2, 0)` atau `UDim.new(0.5, 0)` untuk tombol/chip).
+- **Tipografi:** Wajib menggunakan `Enum.Font.GothamBold` untuk judul/header, `Enum.Font.Gotham` / `GothamMedium` untuk teks isi.
+
+## 7. Interactive Component Rules (Slider, Switch, Segment & Buttons)
+Saat merancang komponen interaktif khusus, patuhi pola NV-Series:
+- **Vertical Slider:**
+  - Bangun `SliderFrame` (track vertikal), `Button` (knob draggable), dan `ValueTextTarget`.
+  - Hitung ratio dari bawah ke atas: `ratio = 1 - (relativeY / frameH)`.
+- **Horizontal Slider:**
+  - Bangun `SliderFrame` (track horizontal), `Fill` (bar progress), `Knob`/`Button`, dan `Trigger` (TextButton transparan full-size).
+  - Hitung ratio dari kiri ke kanan: `ratio = relativeX / frameW`.
+- **Switch Button (Toggle):**
+  - Gunakan `SwitchContainer` (pill frame capsule), `SwitchFrame` (knob bulat), dan `SwitchButton` transparan overlay.
+  - State ON: Container warna Cyan `Color3.fromRGB(0, 170, 255)`, indikator bergeser ke kanan dengan warna putih.
+  - State OFF: Container warna gelap `Color3.fromRGB(20, 20, 20)`, indikator bergeser ke kiri dengan warna abu-abu.
+- **Segment Frame (Tab Bar):**
+  - Bungkus tab di dalam `SegmentFrame` (background `Color3.fromRGB(25, 25, 25)`, `UICorner` kapsul, `UIListLayout` horizontal).
+- **Active & Inactive Button Styling:**
+  - **Tab Segment:** Active = `Color3.fromRGB(55, 55, 60)`, Inactive = `Color3.fromRGB(25, 25, 25)`.
+  - **Item Seleksi:** Gunakan `UIStroke` bernama `SelectStroke`: Active = `Color3.fromRGB(0, 255, 255)` (Cyan), Inactive = `Color3.fromRGB(60, 60, 65)`.
+  - **Tombol Non-Aktif / Limit:** Set `AutoButtonColor = false` dan teks status (contoh: `"WAIT (Xs)"`, `"OUT OF QUOTA"`).
+
+## 8. NV-Animation Engine & Kinematics (Anti-Hallucination Ground Truth)
+Saat diminta menganimasikan karakter di Roblox Studio, Anda WAJIB mematuhi ground truth berikut:
+- **DILARANG MENGGUNAKAN LOOP RUNTIME**: Animasi karakter tidak boleh dibuat menggunakan script loop `while true do task.wait() ...`. Animasi wajib dibuat sebagai instance resmi `KeyframeSequence` di dalam `AnimSaves` rig (gunakan tool semantic `animate_character` atau `solve_limb_ik`).
+- **SENSITIVITAS SPASI NAMA MOTOR6D**:
+  - Karakter R15: Menggunakan CamelCase TANPA SPASI (`LeftShoulder`, `LeftElbow`, `LeftWrist`, `LeftHip`, `LeftKnee`, `LeftAnkle`, `Waist`, `Neck`, `Root`).
+  - Karakter R6: WAJIB MENGGUNAKAN SPASI (`Left Shoulder`, `Right Shoulder`, `Left Hip`, `Right Hip`, `Neck`, `RootJoint`).
+- **BATAS SUDUT ANATOMIS AMAN**:
+  - Siku (`LeftElbow`, `RightElbow`) dan Lutut (`LeftKnee`, `RightKnee`) adalah sendi engsel (hinge joint). Dilarang memutar sumbu Roll/Yaw. Sudut tekukan Pitch hanya $0^\circ \dots 145^\circ$ untuk siku dan $0^\circ \dots 135^\circ$ untuk lutut. Dilarang menekuk siku atau lutut ke arah berlawanan (dislokasi).
+  - Torso/Waist pitch dibatasi $-25^\circ \dots 35^\circ$, twist yaw $\pm 45^\circ$.
+- **PRINSIP GERAKAN HALUS (Disney 12 Principles)**:
+  - Setiap gerakan wajib memiliki fase ancang-ancang (*Anticipation*), interpolasi pelambatan (*QuadInOut* atau *CubicInOut*), dan peredaman akhir (*Follow-Through*).
+
+## 9. NV-VFX Serializer & Cross-Project Database Protocols
+Saat memindai, merekonstruksi, atau menerapkan efek visual antar-proyek:
+- **ATTACHMENT HARUS VALID**: Properti `Attachment0` dan `Attachment1` pada `Beam` atau `Trail` HANYA BOLEH menunjuk ke instance bertipe `Attachment`. Dilarang keras menunjuk ke Part atau Model.
+- **ATURAN URUTAN KEYPOINT**: Setiap `ColorSequence` dan `NumberSequence` WAJIB memiliki keypoint awal pada $t = 0.0$ dan keypoint akhir pada $t = 1.0$.
+- **ALUR KERJA LINTAS-PROYEK**:
+  - Gunakan tool `scan_vfx` pada Project A untuk mengonversi partikel, beam, trail, dan light menjadi tabel data murni yang disimpan secara persisten di database MCP.
+  - Gunakan tool `apply_vfx` pada Project B untuk menginstansiasi efek dari database ke target objek dengan parameter `scale` opsional.
+  - Dokumentasi referensi lengkap: lihat `docs/NV_ANIMATION_AND_VFX_GUIDE.md`.
+
+## 10. NV-Rig Engine & Joint Kinematics Protocols (Anti-Hallucination Ground Truth)
+Saat memeriksa, membuat, atau memodifikasi sendi karakter (`Motor6D` / `Weld`):
+- **PERSAMAAN KESEIMBANGAN SAMBUNGAN**: Hubungan spasial sendi diatur oleh `Part0.CFrame * C0 = Part1.CFrame * C1`.
+- **HUKUM NON-DISLOKASI PIVOT**: Saat menggeser atau memutar poros sendi, DILARANG hanya mengubah `C0` sepihak karena akan mendislokasi posisi fisik `Part1`. Nilai `C1` WAJIB dikompensasi secara simultan: `diff = C0_old:ToObjectSpace(C0_new); C1_new = C1_old * diff` (gunakan tool `edit_rig_joint`).
+- **ATURAN WAJIB UNANCHOR**: Seluruh part anak (`Part1`) yang dihubungkan dengan `Motor6D` atau `Weld` WAJIB disetel `Anchored = false`. Part yang berstatus anchored tidak akan dapat bergerak dalam simulasi fisika atau animasi.
+- **URUTAN KERJA RIGGING SEBELUM ANIMASI**: Dilarang memanggil `animate_character` pada model yang belum memiliki hierarki sendi valid. Selalu jalankan `inspect_rig` untuk diagnosa atau `auto_rig` untuk membuat kerangka standar.
+- **PENGELASAN ASSEMBLY SENJATA/PROP**: Gunakan `weld_assembly` untuk menyatukan seluruh komponen prop/senjata secara kaku ke part pegangan sebelum ditautkan ke karakter.
+- **DOKUMENTASI REFERENSI LENGKAP**: lihat `docs/NV_RIG_ENGINE_GUIDE.md`.
+
+
+

package/agent-plugin/skills/nvstudio-animation-vfx/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: nvstudio-animation-vfx
+description: Panduan AI Agent untuk membuat animasi karakter halus (Walk, Slash, Punch, Idle, Custom IK) menggunakan NV-Animation Engine dan mengelola efek visual lintas-proyek dengan NV-VFX Database di Roblox Studio.
+---
+
+# NVStudio Animation Engine & VFX Subsystem Guide
+
+Panduan resmi untuk AI Agent dalam memanfaatkan kemampuan pembuatan animasi karakter manusiawi (*Human-like Motion Synthesis*) dan sistem efek visual portabel lintas-proyek.
+
+---
+
+## 1. Pembuatan Animasi Karakter (`animate_character`)
+
+Gunakan tool `animate_character` untuk menghasilkan animasi yang halus (*smooth*) dengan kurva interpolasi Bezier, pelambatan *easing*, dan *LimbIK* analitis tanpa perlu menghitung sudut CFrame secara manual.
+
+### Parameter Utama:
+- `target`: Path ke Model karakter rig R6 atau R15 di Studio (contoh: `"Workspace.Dummy"`).
+- `action`: Jenis gerakan yang ingin disintesis:
+  - `"walk_cycle"`: Siklus berjalan seimbang dengan pergeseran berat badan dan ayunan tangan berlawanan.
+  - `"melee_slash"`: Serangan tebasan pedang dengan ancang-ancang (*wind-up*), *acceleration snap*, dan *follow-through*.
+  - `"punch"`: Pukulan terarah dengan pemanfaatan LimbIK ke sasaran dan putaran bahu.
+  - `"idle_breath"`: Pernapasan lembut dengan ritme naik-turun dada dan sedikit kemiringan kepala.
+  - `"custom"`: Pose kunci kustom yang disediakan di parameter `key_poses`.
+- `parameters` (opsional):
+  - `duration`: Durasi animasi dalam detik (contoh: `1.0`).
+  - `intensity`: Skala intensitas gerakan (contoh: `1.2`).
+  - `easing`: Jenis kurva interpolasi (`"QuadInOut"`, `"CubicInOut"`, `"BackOut"`, `"ElasticOut"`, dll).
+  - `loop`: Boolean apakah animasi berulang (default: `true` untuk walk/idle, `false` untuk serangan).
+  - `clipName`: Nama klip animasi di `AnimSaves`.
+
+### Contoh Pemanggilan Tool:
+```json
+{
+  "target": "Workspace.Dummy",
+  "action": "melee_slash",
+  "parameters": {
+    "duration": 0.8,
+    "intensity": 1.2,
+    "easing": "CubicInOut",
+    "loop": false,
+    "clipName": "KatanaSlash"
+  }
+}
+```
+
+Hasilnya akan secara otomatis terkompilasi menjadi `KeyframeSequence` resmi di dalam folder `AnimSaves` karakter pada Studio.
+
+---
+
+## 2. Kalkulasi Kinematika Lengan / Kaki (`solve_limb_ik`)
+
+Gunakan tool `solve_limb_ik` untuk mengarahkan telapak tangan atau kaki karakter ke target koordinat 3D secara instan menggunakan solver analitis sudut tertutup $O(1)$ (Hukum Cosinus).
+
+### Parameter:
+- `target`: Path ke karakter rig (contoh: `"Workspace.Dummy"`).
+- `limb`: Anggota tubuh (`"LeftArm"`, `"RightArm"`, `"LeftLeg"`, atau `"RightLeg"`).
+- `goal`: Array posisi 3D `[X, Y, Z]` di world space.
+- `pole`: Array arah tekukan siku/lutut `[X, Y, Z]` (opsional).
+- `apply_to_rig`: Boolean apakah langsung diterapkan ke sendi karakter di Studio (default: `true`).
+
+---
+
+## 3. Scrubbing Timeline & Preview VFX (`scrub_timeline`)
+
+Gunakan tool `scrub_timeline` untuk menggeser playhead waktu animasi dan memicu semburan (burst) partikel VFX pada timestamp tertentu langsung di Viewport Studio tanpa perlu memutar animasi secara penuh:
+
+### Parameter:
+- `target`: Path model karakter rig atau folder VFX (contoh: `"Workspace.Dummy"`).
+- `time`: Posisi timestamp waktu dalam detik (contoh: `0.35`).
+- `action`: Aksi animasi yang di-scrub (`"melee_slash"`, `"walk_cycle"`, `"punch"`, `"idle_breath"`).
+- `emit_vfx`: Boolean apakah memicu semburan partikel pada frame waktu ini (default: `true`).
+- `emit_count`: Jumlah partikel yang disemburkan (default: `20`).
+
+---
+
+## 4. Modifikasi Properti Partikel & VFX (`set_properties` / `batch_set_properties`)
+
+Gunakan `set_properties` untuk mengubah properti partikel VFX secara granular, termasuk `ColorSequence`, `NumberSequence`, `NumberRange`, dan `Rate`:
+```json
+{
+  "target": "Workspace.FlameBurst.ParticleEmitter",
+  "properties": {
+    "Rate": 50,
+    "Speed": [15, 30],
+    "Size": [
+      [0, 1.5, 0],
+      [1, 0.2, 0]
+    ],
+    "Color": [
+      [0, [1, 0.8, 0.2]],
+      [1, [0.8, 0.1, 0]]
+    ]
+  }
+}
+```
+
+---
+
+## 5. Pindai Efek Visual Lintas-Proyek (`scan_vfx`)
+
+Gunakan tool `scan_vfx` pada Project A untuk mengekstrak seluruh hierarki partikel, beam, trail, dan light menjadi tabel data murni yang disimpan secara persisten di database MCP.
+
+### Parameter:
+- `target`: Path objek di Studio (contoh: `"Workspace.FireSpell"`).
+- `name`: Nama efek visual di database (contoh: `"FlameBurst_Ultimate"`).
+- `category`: Kategori efek (`"Slash"`, `"Explosion"`, `"Aura"`, `"Projectile"`, `"Magic"`, `"Impact"`, `"Beam"`, atau `"Ambient"`).
+- `tags`: Array kata kunci (contoh: `["fire", "orange", "anime"]`).
+
+---
+
+## 4. Terapkan Efek Visual di Proyek Lain (`apply_vfx`)
+
+Buka proyek baru (Project B), lalu panggil `apply_vfx` untuk menginstansiasi efek visual yang tersimpan dengan fidelitas 100%.
+
+### Parameter:
+- `vfx_id`: ID efek visual dari database (contoh: `"preset-cyan-slash"`).
+- `target`: Path objek tujuan di Studio (contoh: `"Workspace.Boss.RightHand"`).
+- `scale`: Skala ukuran efek (contoh: `1.5` untuk memperbesar 50%, `0.8` untuk mengecilkan 20%).
+- `enabled`: Boolean opsional untuk menyalakan/mematikan seluruh emitter saat pertama dibuat.
+

package/agent-plugin/skills/nvstudio-assets-terrain-guide/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: nvstudio-assets-terrain-guide
+description: Panduan untuk memasukkan aset aman, audit keamanan backdoor, dan membuat terrain di Roblox Studio.
+---
+# nvstudio-assets-terrain-guide
+
+## Alur Kerja Aman Creator Store & Asset Security
+
+### 1. Pratinjau & Audit Keamanan (`preview_asset`)
+Sebelum memasukkan model publik dari Creator Store, **selalu jalankan `preview_asset` terlebih dahulu**:
+- Memuat aset di lingkungan terisolasi sementara untuk memeriksa struktur hierarki dan memindai skrip berbahaya (backdoor `require`, obfuscation byte/hex, webhook discord, loadstring, atau off-screen hidden code).
+- Model sementara akan langsung dihapus dari memori secara otomatis.
+
+### 2. Memasukkan Aset Secara Aman (`insert_asset`)
+- **Sanitasi Skrip Otomatis (`strip_scripts = true`):**
+  - Secara default bernilai `true`. Seluruh skrip di dalam model 3D/bangunan/furnitur akan otomatis dihapus sebelum model diletakkan di `Workspace`.
+  - Jika Anda memasukkan kit sistem yang terpercaya dan memang membutuhkan skrip untuk berfungsi, setel `strip_scripts = false`.
+- **Target Parent:** Tentukan target tujuan (default: `game.Workspace`).
+
+### 3. Audit Keamanan Tempat Kerja (`scan_security`)
+- Gunakan `scan_security` untuk memindai model, folder, atau seluruh `Workspace` yang sudah ada di game untuk mendeteksi virus lama atau infeksi terselubung.
+- Opsi `clean_threats = true` dapat digunakan untuk secara otomatis memusnahkan skrip berbahaya yang terdeteksi.
+
+## Aturan generate_terrain
+1. Suplai parameter berupa string JSON ke argumen `data`.
+2. Parameter yang diperlukan: `Size` (array angka), `Position` (array angka), dan `Material` (string valid `Enum.Material` seperti "Grass", "Water", "Sand", dsb).
+Contoh payload JSON: `{"Size": [100, 10, 100], "Position": [0, -5, 0], "Material": "Grass"}`