game-analytics

目的

このスキルは、ゲームのログ、セッション、メトリクスを処理して、プレイヤーの行動を追跡し、パフォーマンスを最適化するために、ゲームデータのメトリクスを分析します。

使用する場面

レベル内でプレイヤーが離脱する箇所の特定、リソース使用量の最適化、リアルタイムマルチプレイヤーゲームのパフォーマンスボトルネックのデバッグなど、開発中にゲーム内データを処理する場合にこのスキルを使用します。

主な機能

• JSON 形式のゲームログを解析して、セッション時間やプレイヤーのアクションなどのメトリクスを抽出します（例：claw game-analytics parse --input logs.json）。
• GET /api/analytics/reports/heatmap?gameId=123 API エンドポイントを使用して、プレイヤーの移動ヒートマップなど、行動追跡レポートを生成します。
• YAML の設定例 metrics: [latency > 500ms] のような SQL 風のフィルターで、高レイテンシのイベントを検索するなど、最適化クエリを実行します。
• 組み込み関数 claw game-analytics predict --model churn.json を使用してプレイパターンから離脱を予測するなど、予測分析のために ML モデルと連携します。

使用パターン

環境変数 $GAME_ANALYTICS_API_KEY を使用して、必ず認証を初期化してください。CLI の場合は、ゲームデータファイルがあるプロジェクトディレクトリでコマンドを実行します。コードでは、モジュールをインポートして関数を直接呼び出します。大規模なデータセットで処理がブロックされないよう、非同期パターンを使用してください。たとえば、まずデータを解析し、次に分析するという順でコマンドを連結します。ほかのツールにパイプできるよう、出力は JSON ストリームとして処理してください。

主なコマンド／API

• CLI コマンド：claw game-analytics analyze --file data.json --metric player-session --output report.csv（ファイルを解析し、メトリクスでフィルタリングして CSV に保存します。$GAME_ANALYTICS_API_KEY が必要です）。
• API エンドポイント：本文 { "event": "player_login", "data": { "sessionId": "abc123", "timestamp": "2023-10-01T12:00:00Z" } } を指定した POST /api/analytics/track（追跡データを送信します。$GAME_ANALYTICS_API_KEY の Bearer トークンで認証してください）。
• コードスニペット（Python）：

  import claw
  api_key = os.environ.get('GAME_ANALYTICS_API_KEY')
  response = claw.analytics.track(event='level_complete', data={'level': 5}, api_key=api_key)
  print(response.json())
  

• 設定形式：カスタムメトリクス用の YAML ファイル。例：

  metrics:
    - name: session_length
      threshold: 300  # seconds
    filters:
      - player_type: 'new'
  

  claw game-analytics load-config config.yaml で読み込みます。

統合に関する注意

コマンドを実行する前に、環境変数として $GAME_ANALYTICS_API_KEY を設定して統合します。Web アプリでは、claw game-analytics auth --provider google で OAuth を使用してトークンを取得します。Node.js プロジェクトでは、モジュールを読み込み、プロミスを処理します：

const claw = require('claw');
claw.analytics.setKey(process.env.GAME_ANALYTICS_API_KEY);
claw.analytics.analyze({ file: 'data.json' }).then(data => console.log(data));

データ形式が一致していることを確認してください（例：JSON 入力のみ）。クラスター統合では、claw game-dev game-analytics analyze のようにコマンドの先頭にプレフィックスを付けて、'game-dev' ツールと連携します。

エラー処理

CLI の終了コードを確認してエラーを調べます（例：コード 401 は認証失敗を示します。claw game-analytics retry --command analyze で再試行してください）。API 呼び出しでは、HTTP エラーを捕捉します。ステータスが 403 の場合は「Invalid API key」と記録し、$GAME_ANALYTICS_API_KEY のリセットを促します。コードスニペットでは try-except を使用します：

try:
    result = claw.analytics.analyze(file='data.json')
except claw.AnalyticsError as e:
    if e.code == 'AUTH_FAILED':
        print("Set GAME_ANALYTICS_API_KEY and retry")

解析エラーを防ぐため、処理の前に必ず入力を検証してください（例：JSON が正しい形式であることを確認します）。

具体的な使用例

1. モバイルゲームでプレイヤーの行動を追跡するには、まずログを JSON にエクスポートし、次に claw game-analytics analyze --file player_logs.json --metric drop-off を実行して、離脱率の高いレベルを特定します。出力をゲームデザインの調整に使用します。たとえば、API で { "suggestions": true } を指定した POST /api/analytics/optimize を使用します。
2. マルチプレイヤーサーバーのパフォーマンスを最適化するには、claw game-analytics load-config perf.yaml で設定を読み込み、claw game-analytics query --metric latency --filter 'server=prod' を実行してレポートを取得します。コードを使用して CI/CD パイプラインに統合し、チェックを自動化します：

   claw.analytics.query({ metric: 'latency' }).then(results => {
       if (results.avg > 100) console.log('Optimize server');
   });
   

グラフ上の関連性

• 関連：game-dev クラスター（親）、player-tracking スキル（依存）、data-metrics スキル（兄弟）。
• 連携先：入力データの game-logging、アクション出力の performance-optimization。