RA3-Replay-Parser

用于解析红色警戒三(Command & Conquer: Red Alert 3)的回放文件 .RA3Replay

Installation

NPM

npm install replay-parser

手动编译

已测试基于Ubuntu20.04使用 Node-Gyp 进行编译

npm install -g node-gyp
node-gyp configure
node-gyp build

输出位置: build/Release/replayParser.node

Usage

const parser = require("replay-parser");
// parseReplay为一个同步方法
const data = parser.parseReplay("absolute-path-to-replay");

返回值参考以下API Doc

API Doc

C++模块：namespace: `ReplayParser`

方法: parseReplayFile
- 接受参数
  - fileName: char[]，回放文件的绝对路径
- 返回值：
  - jsonData: string, 一段JSON字符串
- 返回值格式
  - status: boolean, 表示是否解析成功
  - message: string, 若 status 为false，则表示错误信息
  以下属性在 status 为 true时出现
  - gameVersion: string
  - mapCRC: string, 以键值对字符串形式出现，格式为 MC=CRC校验码，CRC校验码以16进制形式表示
  - mapID: string
  - mapName: string
  - mapRealName: string, 建议后续截取最后一段
  - matchConf: string, 以键值对字符串的形式出现，键为 RU，具体格式表示的信息可查看下文
  - matchDescription: string
  - matchSeed: string, 以键值对形式出现，对战的初始随机数种子（猜测）
  - modInfo: Array<string>
  - playerDetailedInfo: Array<PlayerInfo>, PlayerInfo格式见下文
  - playerNumber: int
  - replayTitle: string
  - timestamp: uint32_t, 保存录像时的时间戳，使用时需乘以1000
- PlayerDetailedInfo
  - faction: int, 阵营
```
std::string getFaction(unsigned int f) {
    switch(f)
    {
        case 1:  return "天眼帝国";
        case 3:  return "Commentator";
        case 4:  return "盟军";
        case 8:  return "苏联";
        case 2:  return "帝国";
        case 7:  return "随机";
        case 9:  return "神州";
        default: return "未知";
    }
}
```
  - isPlayer: boolean, 是否为玩家
  - otherData: 见下文中的 S=字段，从第三个开始

RA3 Replay文件格式

主体结构

.ra3replay 包含以下的结构：

Header
Chunks(长度不固定)
End-of-chunks terminator
Footer

主要数据类型

char: 长度一个字节，用来表示纯文本
byte: 长度一个字节，用来表示数值变量
uint16_t: 无符号的两字节长的整型，以小端排序存储
uint32_t: 无符号的四字节长的整型，以小段排序存储
tb_ch: 无符号的双字节值，用于表示BMP Unicode码位**(?)**，以小端排序存储
tb_str: 双字节小端排序的unicode字符串，以两个separator结尾
player_t: 玩家部分信息
- player_id: uint32_t
- player_name: tb_str
- team_number: byte

常量

MAGIC_SIZE = 17
U1_SIZE = 31
U2_SIZE = 20

Header部分格式

值得注意一点，录像的Header部分在多人游戏和遭遇战的情况下有些许不同，根据字段 hnumber 判断是否是多人游戏。

字段如下(顺序从前到后):

str_magic: char, 固定为 RA3 REPLAY HEADER，长度为 MAGTIC_SIZE 字节
hnumber1: byte, 若为遭遇战(skirmish)则值为 0x04, 若为多人游戏则值 0x05==(待验证)==
vermajor: uint32_t
verminor: uint32_t
buildmajor: uint32_t
buildminor: uint32_t
hnumber2: byte, 有评论值为 0x1E, 无评论值为 0x06
zero1: byte, 值固定为 0x00, ==但实际有0x20的情况==，根据版本号不同分隔符也不同
match_title: tb_str，初步观察 0x E0 65 F9 5B 18
match_description: tb_str
match_map_name: tb_str
match_map_id: tb_str
number_of_players: byte
player_data: player_t[number_ofplayers + 1]
- uint32_t player_id
- tb_str player_name
- IF hnumber1 == 0x05 byte team_number
- ENDIF
offset: uint32_t, 是介于第一个chunk的开始和str_repl_magic 的开始的分隔符？
str_repl_leng: uint32_t，固定为0x08
str_repl_magic: char[str_repl_leng]
mod_info: char[22], 默认为 RA3
timestamp: uint32_t, 是GMT格式的标准Unix时间戳
unknow1: byte[U1_SIZE], 全零, 文档为31，==但实测为35，且会出现非全0的情况==
header_len: uint32_t
header: char[header_len]
replay_saver: byte, 是从0开始的玩家数组中保存录像者的索引号
zero3: uint32_t, 0x00000000
zero4: uint32_t, 0x00000000
filename_length: uint32_t
filename: tb_ch[filename_length]
date_time: tb_ch[8]

根据位置对应数字有以下意义：

0: year, 1: month, 2: weekday(0-6=Sun-Sat), 3: day, 4: hour, 5: minute, 6: second, 7: unknown
vermagic_len: uint32_t
vermagic: char[vermagic_len], 包含了版本号
magic_hash: uint32_t, not clear
zero4: byte, 0x00

其中，Header的主体是一段包含以键值对出现的信息的纯文本序列，其含义如下：

M=
- unknown: short
- MapName, 地图名: char[]
MC=
- Map CRC, 地图CRC校验码?: int
MS=
- Map File Size ,地图文件大小: int
SD=
- Seed?: int
GSID=
- GameSpy (Match) ID: short
GT=
- unknown: int
PC=
- Post Commentator: int
RU=
- Initial Camera Player: int
- Game Speed: int
- Initial Resources: int
- Broadcast Game: bool
- Allow Commentary: bool
- Tape Delay: int
- Random Crates: bool
- Enable VoIP: bool
- unkwn: int, -1
- unkwn: int, -1
- unkwn: int, -1
- unkwn: int, -1
- unkwn: int, -1
S=
- player name: char[]
  - H[Human]PlayerName || C(CPU)(E(Easy) || M(Medium) || H(Hard) || B(Brutal))
- IP: int
- unkwn: int
- TT|FT
- unkwn: int
- Faction: 1 based, 与ini对应
  
  1: Observer
  
  3: Commentator
  
  7: Random
  
  2: Empire
  
  4: Allies
  
  8: Soviets
- unkwn: int
- unkwn: int
- unkwn: int
- unkwn: int
- unkwn: int
- Clan tag: char[]

特殊情况：

MS=
- File Size = 0, 第三方地图
GSID
- GameSpy (Match) ID = 0x5D91, 遭遇战情况
RU
- Initial Camera Player, 1 based ?

Body

.ra3replay的Body部分由多个 chunk 构成，每个 chunk 的结构如下：

time_code: uint32_t
chunk_type: byte

值为1、2、3、4
chunk_size: uint32_t
data: byte[chunk_size]
zero: uint32_t

固定为0x00000000

连续chunk之前存在先序后序的关系，必须按照顺序连续读取，其中最后一个 chunk 的 time_code 的值固定为 0x7FFFFFFF

一个 chunk 的 time_code 对应两帧(1/15 秒)

`chunk` 的含义

chunk的类型根据 chunk_type 判断

其中 chunk_type=3 和 chunk_type=4 只出现在包含 commentary track 的回放中，type=3 包含音频数据，type=4 包含 telestrator data~~👴不知道咋翻译~~

chunk_type=1 和 chunk_type=2 的 data 字段的首位均为1

`chunk_type=1` 的`data` 字段的格式

default: byte

默认为1
number_of_commands: uint32_t
payload: byte[chunk_size-5]

其中 payload 字段包含命令个数，每个命令之间使用 0xFF 进行分隔

命令的格式:

command_id: byte
player_id: byte
code: byte[command_size - 3]
terminator: byte

固定为0xFF

其中 command_size 由command_id 决定

部分命令 command_size 固定
部分长度可变但是具有标准布局(standard layout)，这个布局依赖于一个单一的偏移量 n

Standard layout 命令

payload[0]: CommandID
payload[1]: PlayerID

换算算法

player index = player_id /8 - k, k = 2
如果n > 2，则
1. Here comes a loop: Letxbe a byte, and set x = payload[n];
  - If x == 0xFF stop, you have reached the end of the command.
  - Let c = (x >> 4) + 1;, i.e. take the upper four bits of x and add one.
  - Read in c values that are 32-bit integers.
  - Read in one more byte and assign it to x, and repeat the loop.

命令具体信息见文件末尾

`chunk_type=2` 的`data` 字段的格式(没怎么读明白)

default1: byte

固定为1
default2: byte

固定为0
n: uint32_t

玩家的索引号，对应于Header中的玩家信息列表
default3: byte

固定为0x0F
time_code: uint32_t
payload: byte[chunk_size - 11]

据观察 type=2 的 chunk 只在 chunk_size=24 或 chunk_size=40 时出现。

从 payload + 12 位置开始的 chunk data由3或7个32位的IEEE 754的浮点型变量构成。前三个与以英尺为单位的地图坐标相关，最后四个决定了相机视角的角度和缩放。

byte      flags;        // 0x01: position, 0x02: rotation
IF flags & 0x01
  float32 position[3];  // (x, z, height) in units of feet
ENDIF
IF flags & 0x02
  float32 rotation[4];  // quaternion components?
ENDIF

目前最明确的是该类的 chunk 包含视角移动数据，玩家数量和 heartbeat

`heartbeats` 类型

几种类型的回放数据是自动生成的，并且不包含任何用户操作，因此统一称为 heartbeat，其数据的具体意义是未知的，但是它明确用于确认多人个玩家之间游戏状态的完整性。

每个活跃的玩家每秒和最开始的时候创建一个 chunk_type=2 的 chunk，这个 chunk 的长度固定为40字节，其包含在这个时间点完整的相机视角配置。

在 chunk_type=1的 chunk 中也存在 heatbeat: 每三秒当时间码的形式是45k+1(?)时，每个玩家触发一次ID为 0x21 的 heatbeat命令。

command_id	command_size	Description
0x00	45	Harder secundary ability, like the bunker of Soviet Combat Engineer??
0x01	special	For example at the end of every replay; shows the creator of the replay; also observed in other places.
0x02	special	Set rally point.(设置集结点)
0x03	17	Start/resume research upgrade.(开始/继续研究升级)
0x04	17	Pause/cancel research upgrade.(暂停/取消研究升级)
0x05	20	Start/resume unit production.(开始/继续单位生产)
0x06	20	Pause/cancel unit production.(暂停/取消单位生产)
0x07	17	Start/resume building construction. (Allies and Soviets only, Empire Cores are treated as units.)(开始/继续建筑建造，帝国核心被当作单位处理)
0x08	17	Pause/cancel building construction.(取消/暂停建筑建造)
0x09	35	Place building on map (Allies and Soviets only).
0x0A	std: 2	Sell building.(售卖建筑)
0x0C	special	Possibly ungarrison?(可能是取消占据房屋)
0x0D	std: 2	Attack.(攻击)
0x0E	std: 2	Force-fire.(强制攻击)
0x0F	16
0x10	special	Garrison a building.(占据房屋)
0x12	std: 2
0x14	16	Move units.(移动单位)
0x15	16	Attack-move units.(警戒移动)
0x16	16	Force-move units.(强制移动？)
0x1A	std: 2	Stop command.(停止指令)
0x1B	std: 2
0x21	20	A heartbeat that every player generates at 45`n` + 1 frames (every 3 seconds).
0x28	std: 2	Start repair building.(开始维修建筑)
0x29	std: 2	Stop repair building.(停止维修建筑)
0x2A	std: 2	‘Q’-select.
0x2C	29	Formation-move preview.(预览队形？)
0x2E	std: 2	Stance change.
0x2F	std: 2	Possibly related to waypoint/planning?
0x32	53	Harder Security Point usage like Surveillance Sweep.
0x33	special	Some UUID followed by an IP address plus port number.
0x34	45	Some UUID.
0x35	1049	Player info?
0x36	16
0x37	std: 2	“Scrolling”, an irregularly, automatically generated command.
0x47	std: 2	Unknown, always appears in logical frame 5, and than this logical frame contains this command equally as the number of players.
0x48	std: 2
0x4B	special	Place beacon.
0x4C	std: 2	Delete beacon (F9 has something to do with this??).
0x4D	???	Place text in beacon.
0x4E	std: 2	Player power (Secret Protocols).
0x52	std: 2
0x5F	11
0xF5	std: 5	Drag a selection box and/or select units.
0xF6	std: 5	Unknown. You get this command when building a Empire Dojo Core and deploying it. Than it should appear once, no idea what it does.
0xF8	std: 4	Left mouse button click.
0xF9	std: 2
0xFA	std: 7	Create group.
0xFB	std: 2	Select group.
0xFC	std: 2
0xFD	std: 7
0xFE	std: 15	Simple use of secundary ability, like those of War Bear, Conscript and Flaktrooper.
0xFF	std: 34	Simple select and klick Security Point usage like Sleeper Ambush.

感谢

感谢远古大佬 louisdx (Louis Delacroix) (github.com)制作的RA3 Replay文件格式文档。

NeWive/RA3ReplayParser