Celestial-3D 技能使用说明

📌 技能简介

celestial-3d 是一个用于创建 3D 星际模拟的技能，基于 p5.js WEBGL 模式和 N 体引力物理引擎。

核心特性

• ✅ 真 3D 渲染：使用 WEBGL 渲染立体星球
• ✅ N 体物理引擎：真实的引力模拟（F = Gm1m2/r²）
• ✅ 全中文界面：所有参数和控件都是中文
• ✅ 参数化交互：实时调整物理和视觉参数
• ✅ 种子可重现：相同种子生成相同星系

---

🚀 快速开始

方法 1: 直接打开查看器（最简单）

1. 找到文件：templates/viewer_3d.html（在克隆的仓库目录中）
2. 双击用浏览器打开，或右键选择"打开方式"→ 选择浏览器
3. 立即看到 3D 星际模拟！

交互操作：

• 🖱️ 左键拖动：旋转视角
• 🔍 滚轮：缩放
• 📊 右侧面板：调整所有参数
• 🎲 随机生成：探索不同的星系

---

方法 2: 使用技能生成（完整流程）

在 Claude Code 中调用：

/celestial-3d 创建一个双星系统，有5颗行星绕转

或者更详细：

/celestial-3d 创建一个类似太阳系的系统，1个黄色恒星，8颗不同颜色的行星，其中几颗有卫星

技能会：

1. 创建星际哲学（.md 文件）：描述计算美学理念
2. 生成 3D 场景（.html 文件）：可交互的 WEBGL 模拟

---

📁 技能文件结构

celestial-3d/
├── SKILL.md                          # 技能定义和工作流程（供 Claude AI 阅读）
├── README.md                         # 本文件（使用说明）
├── LICENSE.txt                       # Apache 2.0 许可证
└── templates/
    ├── viewer_3d.html                # 3D 查看器模板（可直接在浏览器打开）
    └── physics_engine_template.js    # 物理引擎参考代码

---

🎛️ 参数说明

天体系统参数

• 恒星数量（1-3）：中心的恒星数量
• 行星数量（1-10）：绕恒星运行的行星数量
• 卫星数量（0-5）：每个行星的卫星数量
• 恒星大小（50-150）：恒星的渲染半径

物理引擎参数

• 引力常数 G（0.1-10）：引力强度，值越大引力越强
• 时间步长 dt（0.005-0.1）：模拟速度，值越大运动越快
• 初始速度倍率（0.5-2.0）：调整轨道速度
• 轨道偏心率（0-0.7）：0=圆形轨道，值越大越椭圆

视觉效果参数

• 星星数量（500-5000）：背景星星密度
• 星云数量（0-10）：星云团数量
• 光照强度（50-255）：恒星点光源强度
• 环境光强度（10-100）：整体环境亮度
• 显示轨道线：勾选显示行星运动轨迹
• 启用碰撞检测：勾选后天体相撞会合并

相机控制

• 相机距离（200-2000）：观察距离
• 自动旋转速度（0-0.01）：场景自动旋转速度
• 启用自动旋转：勾选后自动旋转场景
• 重置相机：恢复默认视角

---

🎨 示例场景

1. 太阳系风格

参数设置：
- 恒星数量：1
- 行星数量：8
- 卫星数量：2-3
- 轨道偏心率：0.1（接近圆形）

2. 双星系统

参数设置：
- 恒星数量：2
- 行星数量：3-5
- 轨道偏心率：0.3-0.5
- 引力常数 G：1.5

3. 密集星团

参数设置：
- 恒星数量：3
- 行星数量：10
- 卫星数量：3-5
- 启用碰撞检测：✓
- 引力常数 G：2.0

4. 抽象星云

参数设置：
- 恒星数量：1
- 行星数量：3
- 星云数量：8-10
- 星星数量：3000+

---

⚙️ 技术细节

N 体物理引擎

使用牛顿万有引力定律：

F = G * m1 * m2 / r²

其中：
- F = 引力
- G = 引力常数
- m1, m2 = 两个天体的质量
- r = 距离

轨道初始化

使用 vis-viva 方程计算稳定轨道速度：

v = sqrt(G * M / r)

其中：
- v = 轨道速度
- G = 引力常数
- M = 中心天体质量
- r = 轨道半径

3D 渲染

• 使用 p5.js WEBGL 模式
• sphere() 创建球体
• orbitControl() 鼠标交互
• emissiveMaterial() 恒星发光
• pointLight() 动态光源

---

🎯 使用技巧

1. 创建稳定轨道

• 设置偏心率 = 0（完全圆形轨道）
• 初始速度倍率 = 1.0
• 引力常数 G = 1.0

2. 创建混沌系统

• 设置偏心率 = 0.5-0.7（高椭圆轨道）
• 引力常数 G = 2.0+
• 启用碰撞检测

3. 性能优化

• 降低星星数量（< 2000）
• 降低球体细分（已在代码中优化）
• 减少天体总数

4. 截图保存

点击"下载截图"按钮，保存当前 3D 场景为 PNG 图片。

---

🐛 常见问题

Q: 为什么行星飞走了？ A: 初始速度不合适。尝试降低"初始速度倍率"或调整"引力常数 G"。

Q: 为什么画面卡顿？ A: 天体数量太多。减少"星星数量"、"星云数量"或"行星数量"。

Q: 如何让天体碰撞？ A: 勾选"启用碰撞检测"，然后增加"引力常数 G"让轨道更不稳定。

Q: 为什么会显示警告信息？ A: 系统会自动检测和修正不合理的参数：

• ⚠️ 参数超出安全范围会自动调整
• ✅ 系统会在控制台显示警告信息（按 F12 查看）
• 🛡️ 所有参数都有上下限保护

Q: 如何恢复默认设置？ A: 点击"重置参数"按钮。

---

🛡️ 内置保护机制

参数验证

• ✅ 恒星数量：自动限制在 [1, 3]
• ✅ 行星数量：自动限制在 [0, 10]
• ✅ 卫星数量：自动限制在 [0, 5]
• ✅ 引力常数 G：自动限制在 [0.1, 10]
• ✅ 时间步长 dt：自动限制在 [0.005, 0.1]
• ✅ 天体总数：自动限制在 80 个以内（性能保护）

运行时保护

• ✅ 空指针检查：防止访问无效对象
• ✅ 边界检测：防止天体飞出可视范围
• ✅ 引力上限：防止引力过大导致数值爆炸
• ✅ 距离约束：防止距离过小导致除零错误
• ✅ 错误捕获：try-catch 包裹所有渲染代码
• ✅ 友好提示：屏幕显示错误信息而不是崩溃

自动修复

• ⚙️ 参数超出范围时自动调整
• 🔄 初始化失败时自动降级
• 🎨 渲染错误时显示友好提示
• 📊 控制台输出详细日志（F12 查看）

---

📚 参考资源

• p5.js WEBGL 教程: https://p5js.org/tutorials/lights-camera-materials/
• N 体模拟: https://en.wikipedia.org/wiki/N-body_simulation
• 轨道力学: https://en.wikipedia.org/wiki/Orbital_mechanics

---

📝 开发信息

• 技能名称: celestial-3d
• 版本: 1.0
• 创建日期: 2026-01-15
• 作者: hhhh124hhhh
• 许可证: Apache 2.0

---

🎉 享受星际探索！

现在你可以：

1. 打开 viewer_3d.html 直接体验
2. 调整参数观察实时变化
3. 探索不同种子的宇宙
4. 使用 /celestial-3d 命令创建定制场景

祝你探索愉快！🚀✨