game-physics

game-physics

用途

此技能用于处理游戏物理模拟，重点涵盖碰撞检测、刚体动力学和力的施加等核心机制。它与游戏引擎集成，以模拟逼真的交互，确保 2D/3D 环境中的物理行为准确。

适用场景

开发需要物理效果的游戏时使用此技能，例如平台游戏、模拟游戏或多人世界。适用于涉及物体交互（如球体弹跳、角色移动）、性能要求严苛的模拟，或扩展 Unity、Godot 等现有游戏引擎的场景。非游戏应用或简单动画不适用。

主要功能

• 碰撞检测：支持 AABB、OBB 和基于球体的检测；使用 SAT 等算法实现精确相交检测。
• 刚体动力学：模拟速度、加速度和扭矩；结合牛顿定律施加力。
• 力处理：施加冲量、重力和摩擦力；可通过向量输入配置（例如，[x, y, z] 力）。
• 模拟控制：暂停、逐步运行或重置模拟；支持慢动作效果的时间缩放。
• 优化：使用空间分区（例如四叉树）减少大型场景中的计算量。

使用模式

通过 OpenClaw 的 CLI 或 API 调用此技能，以实现模块化集成。首先加载场景配置，然后在循环中运行模拟。使用 CLI 时，从文件传入输入；使用 API 时，传入 JSON 负载。务必在环境中设置 $OPENCLAW_API_KEY 进行身份验证。示例流程：加载配置 → 初始化模拟 → 更新循环 → 输出结果。

常用命令/API

使用以下 CLI 命令或 API 端点进行交互。所有命令都需要通过 $OPENCLAW_API_KEY 进行身份验证。

• CLI 命令：openclaw game-physics simulate --file scene.json --steps 100 --gravity 9.8

  • 标志：--file 用于指定 JSON 配置（例如，{"objects": [{"mass": 1.0, "position": [0,0,0]}]}），--steps 用于指定模拟迭代次数，--gravity 用于指定向量 [x,y,z]。
  • 示例：使用 export OPENCLAW_API_KEY=your_key; openclaw game-physics simulate --file input.json 运行。

• API 端点：POST /api/game-physics/simulate

  • 负载：JSON，例如 {"scene": {"objects": [{"id": "ball", "mass": 2.0, "velocity": [1,0,0]}]}, "steps": 50}
  • 请求头：包含 Authorization: Bearer $OPENCLAW_API_KEY
  • 响应：包含结果的 JSON，例如 {"positions": [{"id": "ball", "newPosition": [5,0,0]}]}

• 代码片段（Python CLI 封装）：

  import os
  import subprocess
  api_key = os.environ.get('OPENCLAW_API_KEY')
  subprocess.run(['openclaw', 'game-physics', 'simulate', '--file', 'scene.json', '--steps', '10'])
  

• 代码片段（使用 requests 调用 API）：

  import requests
  headers = {'Authorization': f'Bearer {os.environ.get("OPENCLAW_API_KEY")}'}
  data = {'scene': {'objects': [{'mass': 1.0, 'position': [0,0,0]}]}, 'steps': 20}
  response = requests.post('https://api.openclaw.ai/api/game-physics/simulate', json=data, headers=headers)
  

配置格式：场景使用 JSON，例如 {"objects": [{"id": "obj1", "shape": "sphere", "radius": 1.0, "mass": 5.0, "position": [0,0,0]}]}。请使用以下架构验证：objects 必须包含 "id"、"shape" 和物理属性。

集成说明

将此技能封装在游戏循环中即可集成：在用户输入后或固定时间间隔调用 simulate。对于游戏引擎，将结果导出为向量以供渲染。使用钩子实现自定义回调，例如在 CLI 中通过 --callback-url 设置。与其他 OpenClaw 技能配合使用时，可串联输出（例如，将模拟结果传递给渲染技能）。确保数据格式兼容；物理输出使用标准数组 [x,y,z]。对于异步操作，请使用带 Webhook 的 API。

错误处理

常见错误包括配置无效（例如缺少 "mass" 字段）、身份验证失败或模拟溢出。请按以下方式处理：

• 在运行命令前检查 $OPENCLAW_API_KEY；未设置时返回错误。
• 使用 jsonschema 等库验证 JSON 架构；例如，如果响应状态为 400，则解析错误消息，如 "Missing field: mass"。
• 代码片段（Python 错误处理）：

  try:
      result = subprocess.run(['openclaw', 'game-physics', 'simulate', '--file', 'invalid.json'], check=True)
  except subprocess.CalledProcessError as e:
      print(f"Error: {e.returncode} - {e.stderr.decode()}")
  

• 对于 API：捕获 HTTP 错误（例如，身份验证问题导致的 401），并使用指数退避进行重试。使用 CLI 中的 --debug 标志记录详细错误。

具体使用示例

1. 模拟弹跳的球： 用于简单的物理演示。命令：openclaw game-physics simulate --file ball.json --steps 50 --gravity [0,-9.8,0]。在代码中：使用 {"objects": [{"id": "ball", "shape": "sphere", "position": [0,10,0], "velocity": [5,0,0], "bounciness": 0.8}]} 加载 "ball.json"，然后每帧应用它来更新游戏中的位置。

2. 检测游戏关卡中的碰撞： 在平台游戏中检测碰撞。API 调用：POST /api/game-physics/simulate，传入 {"scene": {"objects": [{"id": "player", "position": [1,2,0]}, {"id": "wall", "shape": "box", "position": [0,0,0]}]}, "steps": 1}。处理响应以检查是否发生碰撞，并据此调整玩家的移动。

图谱关系

• 关联集群：game-dev（例如，与渲染或 AI 技能共享数据）。
• 关联技能：rendering（输出位置以供可视化）、pathfinding（在动态环境中使用物理）。
• 依赖项：需要核心 OpenClaw 服务进行身份验证；与非游戏集群没有直接关联。