| name | shardxl-development |
| description | ShardXL cross-platform Minecraft Java launcher development assistant. Invoke when developing Flutter UI, Rust backend, FFI bindings, or Android platform features for ShardXL project. |
ShardXL Development Skill
ShardXL 跨平台 Minecraft Java 版启动器开发辅助技能。
能力范围
Flutter UI 开发
- shadcn-ui 设计风格实现
- Material 3 主题系统
- Riverpod 状态管理
- 毛玻璃效果组件
- 响应式布局
Rust 后端开发
- FFI 绑定编写
- 游戏启动逻辑
- 版本管理
- 模组加载器集成
- 认证系统
Android 平台开发
- PojavLauncher 集成
- JNI 原生层开发
- OpenGL ES/Vulkan 渲染
上下文感知
项目类型
type: cross_platform_app
framework: flutter
backend: rust
state_management: riverpod
theme_system: material3_shadcn
目标平台
platforms:
- windows
- macos
- linux
- android
核心目录
directories:
flutter_ui: lib/
rust_core: external/ShardXL-Lib/
android_core: external/ShardXL-AndroidCore/
ffi_bindings: lib/frb/shardxl_ffi_bindings.dart
技术约束
constraints:
- UI 使用 shadcn-ui 设计风格
- 游戏逻辑使用 Rust 实现
- 默认深色模式
- 支持毛玻璃效果
- UTF-8 字符串编码 (FFI)
代码生成规则
Flutter 组件生成
生成组件时：
- 优先复用
core/widgets/ 已有组件
- 使用 ConsumerWidget 或 ConsumerStatefulWidget
- 通过 ref 访问 Provider
- 使用 Theme.of(context) 获取主题
- 添加 const 构造函数
- 遵循 shadcn-ui 设计规范
Provider 生成
生成 Provider 时：
- 使用 Notifier 处理复杂状态
- 提供 copyWith 方法
- 实现持久化逻辑
- 添加错误处理
Rust FFI 函数生成
添加新 FFI 函数时：
- 在 Rust 侧实现并导出
- 在 shardxl_ffi_bindings.dart 添加绑定
- 使用
utf8.decode 处理字符串
- 添加内存释放函数
- Dart 侧捕获异常
已有组件库
UI 组件 (core/widgets/)
| 组件 | 用途 |
|---|
| GlassCard | 毛玻璃卡片容器 |
| ShadcnButton | shadcn 风格按钮 |
| ShadcnInput | 输入框 |
| ShadcnBadge | 标签徽章 |
| ShadcnTabs | 选项卡 |
| ShadcnProgress | 进度条 |
| ShadcnSwitch | 开关 |
| ShadcnTooltip | 提示框 |
| ShardBottomNavBar | 底部导航栏 |
| ShardBackground | 背景效果 |
Rust 模块 (external/ShardXL-Lib/crates/)
| Crate | 职责 |
|---|
| auth | 微软/离线/Azuriom 认证 |
| core | 应用状态、下载、解压、哈希 |
| event | 事件系统，跨模块通信 |
| java | Java 发行版管理、下载、安装 |
| launch | 游戏启动、实例管理、参数构建 |
| loaders | 模组加载器 (Fabric/Forge/NeoForge/Quilt/OptiFine) |
| version | 版本构建、元数据处理 |
shadcn-ui 设计规范
核心原则
- 简洁克制 - 避免过度装饰
- 一致性 - 统一圆角、间距、阴影
- 微妙动效 - 平滑过渡，不过于花哨
- 深色优先 - 默认深色主题
尺寸规范
- 圆角: 默认 6px，卡片 16px，按钮 8px
- 边框: 1px，透明度 5-10%
- 阴影: 悬停时显示，primary 色调
- 间距: 8px 基准单位
颜色使用
// 正确: 使用 ColorScheme
final colorScheme = Theme.of(context).colorScheme;
Container(color: colorScheme.primaryContainer);
// 错误: 硬编码颜色
Container(color: Color(0xFF7C4DFF));
FFI 绑定示例
字符串处理
// Rust 返回 UTF-8 字符串
String _fromCString(Pointer<Int8> ptr) {
if (ptr == nullptr) return '';
final bytes = <int>[];
var i = 0;
while (true) {
final b = ptr.elementAt(i).value;
if (b == 0) break;
bytes.add(b & 0xFF);
i++;
}
return utf8.decode(bytes);
}
调用 Rust 函数
List<String> getInstalledVersions(String gameDirectory) {
final gameDirPtr = _toCString(gameDirectory);
final countPtr = calloc<Int64>();
try {
final resultPtr = shardxlFfi.getInstalledVersionsFunc(gameDirPtr, countPtr);
// 处理结果...
shardxlFfi.freeStringArrayFunc(resultPtr, count);
return versions;
} finally {
calloc.free(gameDirPtr);
calloc.free(countPtr);
}
}
调试技能
常见问题
- 版本列表不显示: 检查 FFI 字符串编码，确保使用 utf8.decode
- 玻璃效果不显示: 检查 enableGlassEffect 和 cardOpacity
- 点击事件无效: 检查 Stack 中的 Positioned.fill 是否阻挡事件
- 颜色不正确: 检查 ColorScheme.fromSeed 参数
性能优化
- 使用 const 构造函数
- 避免不必要的 rebuild
- 使用 Selector 精确监听
- Rust 侧避免频繁内存分配
开发工作流
添加新功能
- 在 Rust 侧实现核心逻辑 (ShardXL-Lib)
- 添加 FFI 绑定 (shardxl_ffi_bindings.dart)
- 创建 Provider 封装 (features/[name]/providers/)
- 实现 UI 页面 (features/[name]/pages/)
- 复用已有组件 (core/widgets/)
添加新 UI 组件
- 检查 core/widgets/ 是否已有类似组件
- 遵循 shadcn-ui 设计规范
- 支持深色/浅色主题
- 添加 hoverable 等交互属性
Git 提交规范
| 前缀 | 说明 |
|---|
| feat | 新功能 |
| fix | 修复 bug |
| refactor | 重构代码 |
| docs | 文档更新 |
| style | 样式调整 |
| perf | 性能优化 |
| test | 测试相关 |
| chore | 构建/工具 |
