## 为什么选择 Velvet
其他的库感觉有些过时了。Velvet 采用 2026 年的深色毛玻璃美学风格构建：环境色彩球、柔和的内部发光，以及在 200ms 内完成的微交互。它最初是在平板电脑上采用移动优先（mobile-first）的理念进行设计的，随后才扩展到桌面端，因此触摸目标与手势体验非常自然，而不是后期拼凑的产物。
- **实时搜索栏**：在标题栏中输入内容，所有标签页中的每个元素都会立即进行过滤。
- **激活状态切换徽章**：侧边栏中的每个标签页都会显示一个药丸状（pill）徽章，用于计算其中已开启的 Toggle 数量。只需瞥一眼侧边栏，即可了解当前状态。
- **拖拽互斥**：在移动端，颜色选择器会抢占输入优先级，以免底层的滑块跟着乱动。
- **实时主题切换**：在切换主题时会重新着色所有现有元素。无需重新加载。
- **标签化错误系统**：每个回调都会通过 `safecall(source, fn)` 运行，并通过 `Velvet:OnError(fn)` 路由失败信息，且带有确切的源标签（如 `Toggle:aimbot`、`Slider:fov`）。
- **脉动的 Logo 光晕**：虽然是小细节，但让窗口感觉栩栩如生。
## 安装
```
local Velvet = loadstring(game:HttpGet("https://raw.githubusercontent.com/DexCodeSX/Velvet/main/Library.lua"))()
```
### 可选附加组件
```
local SaveManager = loadstring(game:HttpGet("https://raw.githubusercontent.com/DexCodeSX/Velvet/main/addons/SaveManager.lua"))()
local ThemeManager = loadstring(game:HttpGet("https://raw.githubusercontent.com/DexCodeSX/Velvet/main/addons/ThemeManager.lua"))()
SaveManager:Bind(Velvet, "MyConfig")
ThemeManager:Bind(Velvet)
ThemeManager:LoadSaved()
```
## 快速开始
```
local Velvet = loadstring(game:HttpGet("https://raw.githubusercontent.com/DexCodeSX/Velvet/main/Library.lua"))()
local Window = Velvet:CreateWindow({
Title = "My Script",
SubTitle = "v1.0",
ToggleKey = Enum.KeyCode.RightShift,
ToggleIcon = "sparkles", -- lucide icon name (1700+ available)
})
local Tab = Window:AddTab("Combat", "sword")
local Section = Tab:AddSection("Aimbot")
Section:AddToggle("Aimbot", {
Text = "Enable Aimbot",
Default = false,
Callback = function(v) _G.aimbot = v end,
})
Section:AddSlider("FOV", {
Text = "FOV", Min = 10, Max = 500, Default = 150, Increment = 5,
Callback = function(v) _G.fov = v end,
})
Section:AddDropdown("TargetPart", {
Text = "Target Part",
Values = { "Head", "HumanoidRootPart", "Torso" },
Default = "Head",
VisibleWhen = "Aimbot", -- only show while Aimbot toggle is on
})
```
## 示例
| 文件 | 展示内容 |
|------|---------------|
| [`Example.lua`](Example.lua) | 完整功能演示：所有元素、主题切换、水印、搜索、子标签页 |
| [`KeySystemTest.lua`](KeySystemTest.lua) | 包含已保存密钥与重置功能的独立密钥验证流程 |
```
-- run the full feature demo
loadstring(game:HttpGet("https://raw.githubusercontent.com/DexCodeSX/Velvet/main/Example.lua"))()
-- or test the key system
loadstring(game:HttpGet("https://raw.githubusercontent.com/DexCodeSX/Velvet/main/KeySystemTest.lua"))()
```
## 功能特性
### 元素
Toggle（开关） · Slider（滑块） · Button（按钮） · Dropdown（下拉菜单：单选 + 多选 + 可搜索） · Input（输入框） · ColorPicker（颜色选择器：HSV + hex） · Keybind（快捷键：Toggle / Hold / Always） · Label（标签） · Divider（分割线） · Paragraph（段落） · ProgressBar（进度条） · Log/Console（日志/控制台） · PlayerSelector（玩家选择器）
### 高级用户体验
- 窗口标题栏中的实时元素**搜索栏**
- 每个标签页的**激活状态切换徽章**
- 拖拽**互斥**，防止颜色选择器的拖拽操作干扰滑块
- 子标签页（标签页内的水平药丸状选项行）
- 通过 `VisibleWhen = "flagId"` 实现条件可见性
- 可通过 `Tooltip = "text"` 为任何元素设置提示框
- `elem:OnChanged(fn)` 监听器链式调用
- 带有动态令牌的水印：`{fps}`、`{ping}`、`{time}`、`{user}`、`{flag:id}`
- 以 base64 字符串导入/导出配置
- GitHub release 更新检查
- 侧边栏折叠 + 滑动切换手势（移动端）
- 每个窗口的 UIScale（UI 缩放）
- 触觉反馈模拟
### 美学设计
- 带有环境强调色光晕的深色毛玻璃效果
- 脉动的 Logo 光晕
- 采用 Quint + Back 缓动的高级微交互效果（约 220ms）
- 实时主题重新映射（无需重新加载）
- 5 种内置主题：**Midnight** · **Ocean** · **Rose** · **Emerald** · **Sunset**
- 自定义主题支持
### 健壮性
- 标签化的 `safecall` 错误系统 → `Velvet:OnError(fn)`
- 通过 `Velvet:Destroy()` 完整清理
- 已在 Android 平板（Delta Executor）上通过移动端测试
## API
### Velvet
| 方法 | 描述 |
|--------|-------------|
| `Velvet:CreateWindow(opts)` | 创建主窗口 |
| `Velvet:Notify(opts)` | 显示 Toast 通知 |
| `Velvet:KeySystem(opts)` | 通过密钥列表控制访问权限 |
| `Velvet:CreateWatermark(opts)` | 带有动态令牌的悬浮 HUD 栏 |
| `Velvet:CheckForUpdate(repo)` | 将当前版本与 GitHub releases 进行对比 |
| `Velvet:SetTheme(table)` | 实时重新着色所有元素 |
| `Velvet:GetTheme()` | 获取当前主题表 |
| `Velvet:OnError(fn)` | 钩入 safecall 失败事件 |
| `Velvet:Haptic(strength)` | "light" / "medium" / "strong" |
| `Velvet:Destroy()` | 完整清理 |
| `Velvet.Flags[id]` | 通过 ID 读取任何元素的值 |
### Window（窗口）
| 方法 | 描述 |
|--------|-------------|
| `Window:AddTab(name, icon?)` | 添加标签页。icon 可以是 lucide 名称、asset id 或 URL |
| `Window:Show()` / `:Hide()` / `:Toggle()` | 控制可见性 |
| `Window:SetScale(n)` | UIScale 0.5 – 2.0 |
| `Window:ToggleSidebar()` | 将侧边栏折叠为仅图标模式 |
| `Window:_applySearch(q)` | 以编程方式触发标题栏搜索过滤器 |
| `Window:Destroy()` | 移除窗口 |
### Tab（标签页）
| 方法 | 描述 |
|--------|-------------|
| `Tab:AddSection(name)` | 创建可折叠的区块 |
| `Tab:AddSubTab(name)` | 在标签页内创建水平药丸状子标签页 |
### Section（区块）
| 方法 | 返回值 | 备注 |
|--------|---------|-------|
| `:AddToggle(id, opts)` | Toggle | 计入标签页徽章数量 |
| `:AddSlider(id, opts)` | Slider | 支持拖拽互斥感知 |
| `:AddButton(opts)` | Button | 悬停描边 + 按压闪烁效果 |
| `:AddDropdown(id, opts)` | Dropdown | Multi + 可搜索 |
| `:AddInput(id, opts)` | Input | |
| `:AddColorPicker(id, opts)` | ColorPicker | HSV 画布 + hex 输入框，具有选择器优先级拖拽功能 |
| `:AddKeybind(id, opts)` | Keybind | Toggle / Hold / Always |
| `:AddLabel(opts)` | Label | |
| `:AddDivider()` | nil | |
| `:AddParagraph(opts)` | nil | |
| `:AddProgressBar(id, opts)` | Bar | `bar:Set(n)`，`bar:SetMax(n)`，`bar:SetColor(c)` |
| `:AddLog(opts)` | Log | `log:Info/Warn/Error/Success(msg)`，`log:Clear()` |
| `:AddPlayerSelector(id, opts)` | PS | 在玩家加入/移除时自动刷新 |
### 元素选项标志（适用于任何元素）
| 键名 | 效果 |
|-----|--------|
| `Tooltip = "text"` | 悬停/长按提示框 |
| `VisibleWhen = "flagId"` | 在该 flag 为真值之前保持隐藏 |
| `Default = ...` | 初始值 |
| `Callback = fn` | 在值更改时运行（包裹在 safecall 中） |
每个带有 `id` 的元素都会暴露 `:Set(v)`、`:Get()`、`:OnChanged(fn)` 方法，并且可以通过 `Velvet.Flags[id]` 进行访问。
### 通知
```
Velvet:Notify({
Title = "Velvet",
Content = "loaded",
Duration = 4,
Type = "success", -- info | success | warning | error
})
```
### 密钥系统
```
Velvet:KeySystem({
Title = "Velvet",
SubTitle = "premium access required",
Keys = { "velvet-2026", "let-me-in" },
SaveKey = "VelvetKey.txt", -- optional, remembers passing key
Note = "key auto saves",
DiscordInvite = "https://discord.gg/velvet",
Callback = function(success) end,
})
```
### 水印
```
Velvet:CreateWatermark({
Text = "Velvet | {fps} fps | {ping} ms | {user}",
Position = "TopLeft", -- TopLeft / TopRight / BottomLeft / BottomRight
})
```
### 配置管理器
```
SaveManager:Bind(Velvet, "FolderName")
SaveManager:Save("configName")
SaveManager:Load("configName")
SaveManager:Delete("configName")
SaveManager:GetConfigs()
SaveManager:Export() -- returns base64 string
SaveManager:Import(str)
```
### 主题管理器
```
ThemeManager:Bind(Velvet)
ThemeManager:SetTheme("Ocean")
ThemeManager:GetThemes() -- { "Midnight", "Ocean", "Rose", "Emerald", "Sunset" }
ThemeManager:AddTheme("Custom", { Base = ..., Accent = ..., ... })
ThemeManager:LoadSaved()
```
## Window 选项
```
{
Title = "string",
SubTitle = "string",
Width = number, -- default: 560 PC / fits screen on mobile
Height = number, -- default: 400 PC / fits screen on mobile
TabWidth = number, -- sidebar width
ToggleKey = Enum.KeyCode, -- key that toggles visibility
ToggleText = "string", -- short text on the floating pill
ToggleIcon = "lucide-name | rbxassetid://... | url",
Scale = number, -- UIScale multiplier
SidebarToggle = boolean, -- show the = button (default true)
Gestures = boolean, -- mobile swipe-to-switch (default true)
}
```
## 主题
| 主题 | 强调色 | 氛围 |
|-------|--------|------|
| **Midnight** | 紫罗兰色 `#7c5cfc` | 默认，纯黑 |
| **Ocean** | 蓝色 `#328cff` | 海军蓝，冷色调 |
| **Rose** | 粉红色 `#f0509e` | 温暖深色调 |
| **Emerald** | 绿色 `#32d278` | 森林色 |
| **Sunset** | 橙色 `#ff8232` | 暖棕色 |
## 路线图
- [ ] 拖拽重新排序区块
- [ ] 命令面板 (Ctrl+K)
- [ ] 针对单个元素的动画自定义 API
- [ ] 更多与上游同步的 lucide 图标
## 许可证
MIT，详见 [LICENSE](LICENSE)。
