fortnite-replay-analysis

## 🌐 Language - [English](./README.md) - [日本語](./README.ja.md) # Fortnite Replay Analysis Fortnite の .replay ファイルを解析し、プレイヤー情報・チーム順位・生存時間・スコア計算まで一括で処理できる Node.js ライブラリです。 --- ## 特徴 ✅ Fortnite .replay ファイルを直接解析 ✅ Windows / Linux 対応（自己完結バイナリ） ✅ KillFeed から正確なチーム順位を復元 ※チーム順位は、KillFeed に記録された撃破順を解析することで復元されます。 ✅ Bot 除外・順位ソート対応 ✅ チーム / 個人キル両対応のスコア計算 ✅ 複数マッチのスコアを自動マージ ✅ 平均キル数・平均順位・総生存時間の算出 ✅ Decimal.js による高精度計算 ※ Decimal.js は内部で使用しており、利用者側での追加インストールは不要です。 --- ## 動作環境 - Node.js 18 以上推奨 - Windows x64 / Linux x64 ※ テスト環境 Node.js v22.22.0 ※ macOS は現在未対応です --- ## インストール ```bash npm install fortnite-replay-analysis@latest ``` --- ## 使い方 #### リプレイ解析（最新の .replay を自動選択） ```js const { ReplayAnalysis } = require("fortnite-replay-analysis"); (async () => { const { rawReplayData, rawPlayerData, processedPlayerInfo, processedPlacementInfo } = await ReplayAnalysis("./replay", { bot: false, sort: true }); console.log(processedPlayerInfo); })(); ``` ##### 単一ファイルを指定する場合 ```js await ReplayAnalysis("./replay/match1.replay"); ``` --- ### スコア計算（単一マッチ） ReplayAnalysis の結果をそのまま使って順位ポイント＋キルポイントを計算します。 ```js const { calculateScore } = require("fortnite-replay-analysis"); const scores = await calculateScore({ matchData: processedPlayerInfo.hybrid, points: { 1: 11, 2: 6, 3: 3 }, killMode: "team", killCountUpperLimit: null, killPointMultiplier: 1 }); console.log(scores); ``` ※ calculateScore 内部で sortScores が自動実行されるため、戻り値はすでに公式準拠ルールでソートされています。 --- ### スコアの再ソートのみを行う場合既存のスコア配列を、公式ルール準拠で再ソートしたい場合に使用します。 ```js const { sortScores } = require("fortnite-replay-analysis"); const sortedScores = sortScores([...scores]); ``` ※ sortScores は配列を直接書き換えるため、スプレッド構文でコピーしてから渡すことを推奨します。 --- ### 複数マッチのスコアをマージする場合複数マッチ分のスコア配列を、同一メンバー構成のパーティ単位で統合します。 ```js const { mergeScores } = require("fortnite-replay-analysis"); const mergedScores = mergeScores([ scoresMatch1, scoresMatch2, scoresMatch3 ]); console.log(mergedScores); ``` --- ## API ### ReplayAnalysis(inputPath, options) Fortnite の .replay ファイルを解析し、生データ・整形済みプレイヤー情報・ KillFeed から復元したチーム順位情報を返します。 #### 引数 - inputPath (string) .replay ファイル、または .replay ファイルを含むディレクトリのパスディレクトリを指定した場合は、更新日時が最も新しい .replay ファイルが自動で選択されます。 - options (object, 省略可) - bot (boolean) Bot プレイヤーを含めるかデフォルト: false false の場合、processedPlayerInfo から Bot が除外されます。 - sort (boolean) processedPlayerInfo を Placement 昇順でソートするかデフォルト: true #### 戻り値 Promise<ReplayAnalysisResult> ```ts type ReplayAnalysisResult = { rawReplayData: any; // 解析結果全体の生データ rawPlayerData: any[]; // parsed.PlayerData processedPlayerInfo: { // 整形済みプレイヤー情報 raw: PlayerInfo[]; generated: PlayerInfo[]; hybrid: PlayerInfo[]; }; processedPlacementInfo: { raw: { teams: TeamFromKillFeed[]; placement: Record<number, string[]>; }; generated: { teams: TeamFromKillFeed[]; placement: Record<number, string[]>; }; hybrid: { teams: TeamFromKillFeed[]; placement: Record<number, string[]>; }; }; }; ``` - raw: リプレイファイルに含まれる順位情報をそのまま使用したデータ - generated: KillFeed の撃破順のみを元に復元した順位データ - hybrid: リプレイの順位情報を優先し、存在しない場合は KillFeed 復元結果を使用 --- ### calculateScore(config) ReplayAnalysis の processedPlayerInfo を元に、チーム単位または個人単位でスコアを集計します。 #### 引数 - config (object) - matchData (PlayerInfo[] | string, 必須) ReplayAnalysis の processedPlayerInfo 配列、またはその配列を保存した JSON ファイルへのパス ※ JSON は配列そのものの形式である必要があります。 - points (Record<number, number>, 必須) 順位ごとのポイント設定 ```js { 1: 11, 2: 6, 3: 3 } ``` ※ 指定されていない順位は 0 扱いになります。 - killMode ("team" | "individual", "team_per_match_individual_total") デフォルト: team team → チームメンバー全員のキル数を合算 individual → プレイヤー単位でキル数を集計（partyNumber は保持） - killCountUpperLimit (number | null, 省略可) キル数の上限デフォルト: null（無制限） - killPointMultiplier (number, 省略可) 1 撃破あたりのポイント倍率デフォルト: 1 #### 戻り値 Promise<PartyScore[]> ```ts type PartyScore = { playerId: number | null; // individual 指定時のみ使用 partyNumber: number; partyPlacement: number | null; // 単一マッチ時の順位 partyKills: number; // 上限適用後 partyKillsNoLimit: number; // 上限なし partyKillPoints: number; partyPoint: number; partyScore: number; partyVictoryRoyale: boolean; partyMemberList: string[]; partyMemberIdList: string[]; partyAliveTimeList: Decimal[]; matchName: string | null; }; ``` #### 補足 - 内部で sortScores が自動実行されるため、戻り値は常に公式準拠ルールでソート済みです。 - individual 指定時でも partyNumber は保持されますが、集計キーは playerId になります。 - partyKillsNoLimit は上限適用前、 partyKills は killCountUpperLimit 適用後の値です。 --- ### sortScores(scoreArray) スコア配列を公式ルール準拠でソートします。 #### ソート順（優先度） 1. 累計獲得ポイント 2. Victory Royale 回数 3. 平均撃破数 4. 平均順位（小さい方が上位） 5. 合計生存時間 6. 最初のマッチのパーティ番号（最終タイブレーク） #### 破壊的変更について ```js sortScores(scores); ``` この呼び出しでは scores 配列そのものの並び順が書き換えられます。安全な使い方： ```js sortScores([...scores]); ``` ※ sortScores は Array.prototype.sort を使用するため、破壊的です。 --- ### mergeScores(scoreArrays) パーティの一致判定は、メンバーの Epic Account ID を基準に行われ、順序は考慮されません。複数マッチ分のスコア配列を、同一メンバー構成のパーティ単位でマージします。 #### 戻り値各パーティに overallSummary が追加されます。 ```js type OverallSummary = { totalPoint: number; // 合計スコア victoryCount: number; // Victory Royale 回数 matchCount: number; // 試合数 avgKills: Decimal; // 平均キル数（Decimal.js） avgPlacement: Decimal; // 平均順位（Decimal.js） totalAliveTime: Decimal; // 合計生存時間（Decimal.js） }; ``` --- ## 注意事項 - ディレクトリ指定時は、更新日時が最も新しい .replay ファイルを処理します - Fortnite のアップデートにより挙動が変わる可能性があります - 本ツールの利用により発生した問題について、開発者は責任を負いません - フォークする場合は GitHub の Fork 機能を利用してください --- ## 🔗 使用ライブラリ - [FortniteReplayDecompressor](https://github.com/Shiqan/FortniteReplayDecompressor) © Shiqan — 本プロジェクトは MIT ライセンスのもとで利用しています。