sp00nznet/xboxdashboard
GitHub: sp00nznet/xboxdashboard
Xbox仪表板静态重编译，实现Xbox系统界面在PC上的运行。
Stars: 1 | Forks: 0
# Xbox仪表板重编译
**原始Xbox仪表板的首次原生PC移植。**
还记得那个绿色的球体吗？飞船控制室的环绕嗡嗡声？滚动菜单时的满足的*bwoom*声？我们将它带回——不是通过仿真，而是通过将原始`xboxdash.xbe`静态重编译成原生Windows可执行文件。
该项目使用[xboxrecomp](https://github.com/sp00nznet/xboxrecomp)将Xbox仪表板的x86机器代码翻译成C，然后使用MSVC编译，针对替换的运行时库（D3D8->D3D11，Xbox内核->Win32等）进行编译。结果是运行原始仪表板代码的独立`.exe`文件。
## 状态
**目标：仪表板构建3944（v1.0 - 与启动控制台一起发货的版本**）
| 阶段 | 描述 | 状态 |
|-------|-------------|--------|
| 0 | 项目设置与XBE提取 | 完成 |
| 1 | XBE分析（解析，反汇编，func_id） | 完成 - 6,323个函数，134个内核导入 |
| 2 | 提升到C和首次构建 | 完成 - 628K行C代码，~6MB原生可执行文件 |
| 3 | 仪表板运行时（路径，EEPROM，存根） | 完成 - 50+个内核调用，完整的初始化链 |
| 4 | UI渲染（D3D8初始化，3D球体，字体） | 完成 - 绿色球体@60fps，12个D3D8→D3D11桥接 |
| 4.5 | XAP/XIP场景引擎启动 | 进行中 - 引擎完全映射；真实的XIP加载器现在运行（见下文） |
| 5 | 精细调整（输入，音频，设置） | 待定 |
### 阶段4.5 — XAP/XIP场景引擎（当前重点）
仪表板UI由**`default.xip`**驱动，其中包含场景作为**VRML97风格的文本**（`DEF theScreen Screen { ... }`）以及**JavaScript行为脚本**。仪表板实际上是一个小的**VRML + ECMAScript引擎**：文本被编译成**堆栈机字节码**，由VM（`sub_00031DDE`）在**节点类反射注册表**（以C-前缀的类`CScreenSaver`/`CTextNode`/`CLevel`/…具有`{name, member-offset, type}`字段表）上执行，以构建场景图。这远不止一个“XAP解析器”，在兄弟重编译项目中没有类似物。
使用**Ghidra**（FidDb名称恢复）和**无头IDA Pro 9.1**（Hex-Rays）进行逆向工程。真实加载路径：`sub_0003534B`（XIP加载）→工作线程/同步→`sub_00035176`（打开`y:\default.xip`，读取标题/入口表/字符串表/数据，`sub_0003503E`按类型处理资源）→资源提供者→编译器→字节码VM→反射→渲染。
**本阶段已落地的修复**（见`docs/GEN_PATCHES.md`以获取gitignored gen-file补丁）：
- **`Y:`驱动器映射**——仪表板打开`y:\default.xip`；内核路径层没有`Y:`规则。添加了`Y:\ → game/`（xboxrecomp `kernel_path.c`）。
- **CRT分配器重定向**——CRT堆（句柄`0x12DED0`）无效；`nh_malloc`（`malloc`/`operator new`的通道）现在路由到工作的`xbox_HeapAlloc`，因此真正的加载器的分配（例如，文件名缓冲区）对直接和间接调用都是有效的。
- **强制同步XIP加载**——加载器在一个`PsCreateSystemThreadEx`工作线程上运行，其模拟堆栈损坏FPO堆栈本地；强制同步/主线程路径（原始版本采取的路径）修复了这类损坏。
**当前阻塞器**：FPO调用链深处的运行时ESP/帧不同步（`sub_00035176 → sub_0002A90B → sub_2A66D`）向`CreateFile`返回空文件名。重编译器的*输出已验证正确*（regen是字节相同的），因此这是一个运行时模拟问题，需要调试——而不是代码生成问题。
## 仪表板内部有什么
Xbox仪表板不仅仅是任何XBE。它是微软定制的3D系统外壳：
- **20个XIP存档**，包含UI资产、3D网格和XAP脚本
- **2个Xbox位图字体**（Xbox.xtf，Xbox Book.xtf），总计31MB
- **71个WAV音频文件**，跨越5个类别：环境引擎室声音、菜单点击、过渡嗡嗡声和通信聊天
- **自定义3D UI**，具有标志性的绿色球体、飞行的面板和粒子效果
- **EEPROM设置**管理（语言、时区、家长控制、视频输出）
- **没有游戏引擎**——这是手工制作的微软代码，不是RenderWare或Unreal
### 仪表板文件清单
```
game/
xboxdash.xbe (1.39 MB - the main executable)
Audio/
AmbientAudio/ (39 files - engine room hums, comm chatter, steam hisses)
MainAudio/ (11 files - button clicks, scroll beeps, error tones)
MemoryAudio/ (3 files - controller/slot/game select sounds)
MusicAudio/ (5 files - info screen transitions, CD select)
SettingsAudio/ (2 files - language and parental submenu sounds)
TransitionAudio/ (12 files - menu in/out swooshes per section)
*.xip (20 archives - UI scenes, meshes, textures, scripts)
Xbox.xtf, Xbox Book.xtf (bitmap fonts)
```
## XBE分析
| 属性 | 值 |
|----------|-------|
| 标题 | Xbox仪表板 |
| 标题ID | 0xFFFE0000（系统应用程序） |
| 构建 | 3944（v1.0） |
| 构建日期 | 2001-10-25 |
| 内部名称 | "xapp"（Xbox应用程序） |
| 调试路径 | `d:\xboxret\private\ui\xapp\obj\i386\xboxdash.exe` |
| 入口点 | 0x00052A81 |
| 图像大小 | 1.38 MB |
| 部分 | 19 (.text 637KB，D3D，D3DX，XGRPH，DSOUND，WMA，XPP，DOLBY，XIPS，6语言表） |
| 内核导入 | 134（32 Nt*文件I/O，25 Ke*线程，14 Mm*内存，7 Hal*硬件） |
| 库 | D3D8，D3DX8，XGRAPHC，DSOUND，LIBC，LIBCPMT（所有XDK 3944） |
| 函数 | 发现6,323个，6,258个翻译成C（98.97%成功） |
| 生成代码 | 628,227行C代码，跨越7个源文件 |
| 可执行文件 | ~6 MB原生x86-64 Windows .exe |
### 当前启动状态
```
=== Xbox Dashboard - Static Recompilation ===
Loading XBE... 1,394,036 bytes
Initializing Xbox memory layout... 19 sections, 27/28 RAM mirrors
Initializing kernel bridge... 134/134 resolved (62 bridged, 72 stubbed)
NV2A GPU initialized: VRAM=64MB RAMIN=1024KB
Starting dashboard...
PsCreateSystemThreadEx -> CRT _threadstart -> SEH prolog -> TLS copy
_initterm (CRT initializers) -> OK
Dashboard main (sub_00052A12) entered
D3D/system init (sub_000558D0):
Timer/DPC init -> KeSetTimer + DPC dispatch OK
NV2A device creation (sub_00053DCE) -> SUCCESS (1MB at 0x00F80000)
D3D device setup (sub_0005387F) -> OK
File system:
C:\tdata, C:\tdata\fffe0000, C:\tdata\fffe0000\music -> opened OK
XIP archive paths ready (C:\ -> game/)
Xapp init chain (7 steps):
[1] Heap setup -> OK
[2] CRT lock init -> OK
[3] File/path init -> OK (NtCreateFile, RtlInitAnsiString)
[4] Random seed -> OK
[5] Display config -> OK
[6] Settings/EEPROM -> OK (NtReadFile, ExQueryPoolBlockSize)
[7] App init (sub_00029D34) -> OK (scene manager + real scene root created)
[8] XIP/asset load (sub_0003534B) -> real loader opens Y:\default.xip
[12/13] Scene setup (sub_00029832 / sub_0002E891) -> scene root + manager wired
Render: green orb (Xbox logo sphere) on black @60fps via D3D8->D3D11 bridges
```
**44+个内核调用执行正确**，包括：
- `NtAllocateVirtualMemory`（1MB GPU内存），`NtCreateFile`（目录创建）
- `RtlInitAnsiString`，`RtlEnter/LeaveCriticalSection`（CRT锁定）
- `KeSetTimer`，`HalRequestSoftwareInterrupt`（DPC调度）
- `ExAllocatePoolWithTag`，`ExFreePool`（堆管理）
- NV2A MMIO钩子激活，用于GPU寄存器访问在0xFD000000
**以60 FPS渲染**：一个640x480的D3D11窗口通过xboxrecomp D3D8→D3D11层在黑色背景上呈现仪表板的绿色球体（12个桥接：SetRenderState/SetTransform/SetTexture/CreateVertexBuffer/DrawVertices/Swap/…）。完整的XApp初始化链运行，并创建了场景管理器和真实的场景根。
**当前重点——XAP/XIP场景引擎（如上所述阶段4.5）：**仪表板的自己的XIP加载器现在打开`Y:\default.xip`，并执行真实的加载路径。剩余的工作是仪表板的文本→字节码**编译→VM→反射**管道，将VRML/JS场景源转换为实时场景图。使用Ghidra（符号恢复）和headless IDA Pro（Hex-Rays）进行逆向工程。有关将加载器上线所进行的运行时修复，请参阅`docs/GEN_PATCHES.md`。
## 构建
### 预先条件
- Windows 10/11与Visual Studio 2022（MSVC）
- CMake 3.20+
- Python 3.10+（用于重编译管道）
- [xboxrecomp](https://github.com/sp00nznet/xboxrecomp)克隆为同级目录
### 设置
```
# 克隆仓库并排
git clone https://github.com/sp00nznet/xboxrecomp.git
git clone https://github.com/sp00nznet/xboxdashboard.git
# 从 Xbox HDD 映像中提取仪表板文件到 dashboard/game/
# （您需要：xboxdash.xbe, *.xip, *.xtf, 音频/）
# 构建
cd xboxdashboard
cmake -B build -G "Visual Studio 17 2022"
cmake --build build --config Release
```
### 运行
```
bin/Release/xboxdash.exe
```
可执行文件期望原始仪表板文件位于`game/`子目录中。
### 到目前为止的关键里程碑
- **FATX提取** - 编写了自定义QCOW2 + FATX文件系统工具，从Xbox HDD镜像中提取仪表板
- **XBE分析** - 19个部分，134个内核导入，内部名称“xapp”（Xbox应用程序）
- **函数恢复** - 通过扫描存根调用目标恢复了反汇编器遗漏的3,087个“split-tail”函数
- **CRT线程初始化** - 手动翻译`_threadstart`以修复SEH前缀和调用者之间`g_seh_ebp`帧指针共享
- **DPC调度** - 实现了`HalRequestSoftwareInterrupt`，具有延迟过程调用队列，关闭看门狗定时器运行
- **SEH前缀修复** - 修复了生成的`__SEH_prolog`以写入`g_seh_ebp`，以及后处理了48个调用点
- **NV2A设备创建** - GPU实例内存（1MB）分配和初始化，设备设置成功
- **CRT memcpy修复** - 替换了损坏的`sub_00055E90`（有未解决的跳转表目标破坏esi/edi）
- **CRT锁定表** - 预先初始化了36个临界区条目，以防止`_mtinitlocknum`中的无限递归
- **完整的初始化链** - 所有7个xapp初始化步骤执行：堆、锁定、文件、RNG、显示、设置、应用程序初始化
- **文件系统** - `C:\`驱动器映射到`game/`，`RtlInitAnsiString`桥接以正确处理路径
- **D3D8窗口** - 640x480窗口，具有D3D11交换链，以~33 FPS的速度呈现，具有VSync
- **D3D桥接** - SetRenderState和SetTransform路由到D3D8-to-D3D11层
- **主循环** - 仪表板的tick+渲染循环连续运行，并呈现帧
- **场景图** - 绿色球体通过ICALL调度绘制；创建了真实的场景根和场景管理器
- **符号恢复** - Ghidra FidDb遍历恢复了133个CRT/XDK名称（包括LZX/XIP解压缩器）；应用于重编译的C
- **XAP/XIP引擎映射** - 识别为VRML97 + JavaScript引擎：文本→字节码编译器+堆栈机VM（`sub_00031DDE`）+节点类反射注册表（通过无头IDA Pro Hex-Rays）
- **真实的XIP加载器运行** - `Y:`驱动器映射+CRT-堆分配器重定向+强制同步加载将仪表板的*自己的* `sub_0003534B`→`sub_00035176`加载路径上线（替换了手工制作的加载器）
## 工作原理
```
xboxdash.xbe (Xbox x86)
|
[xbe_parser] -- extract sections, kernel imports, entry point
|
[disassembler] -- discover functions, build call graph
|
[func_id] -- classify CRT, D3D8, XDK library functions
|
[lifter] -- translate each x86 instruction to C
|
recomp_*.c (millions of lines of mechanical C)
|
[MSVC] + xboxrecomp runtime libraries
|
xboxdash.exe (native Windows x86-64)
```
运行时库替换了Xbox硬件和OS：
- **xbox_kernel** - Xbox内核调用 -> Win32 API
- **xbox_d3d8** - Direct3D 8 -> Direct3D 11
- **xbox_dsound** - DirectSound -> Windows音频
- **xbox_apu** - MCPX APU仿真
- **xbox_nv2a** - NV2A GPU寄存器处理
- **xbox_input** - Xbox游戏手柄 -> XInput
## 为什么这不同
与游戏重编译不同，仪表板是一个**系统应用程序**：
1. 它管理硬件设置（EEPROM、显示模式、时区）
2. 它使用XIP存档，其中包含嵌入式脚本引擎（XAP）
3. 3D UI完全是定制的——没有游戏引擎可以依赖
4. 它是启动Xbox上所有其他内容的壳
这意味着我们需要比游戏所需的仪表板特定运行时支持：EEPROM模拟、XIP感知文件I/O，以及可能针对XAP脚本层的一些创造性解决方案。
## 法律
此项目不包括任何受版权保护的Xbox软件。您必须提供自己的`xboxdash.xbe`和从原始Xbox控制台提取的支持文件。
## 参见
- [xboxrecomp](https://github.com/sp00nznet/xboxrecomp) - 此项目背后的静态重编译工具包
- [xboxdevwiki](https://xboxdevwiki.net/) - Xbox内部社区的文档
标签：3D Orb, Binary Translation, Bytecode, CMS安全, Code Analysis, Console Emulation, D3D8 to D3D11, Dashboard, Disassembly, Driver Development, ECMAScript, Function Parsing, Game Development, Graphics Programming, JavaScript, Kernel Calls, Kernel Imports, Linux, Menu Scrolling, Native Executable, PC Port, Recompilation, Reflection Registry, Reverse Engineering, Runtime Libraries, Scene Engine, Scene Graph, Software Engineering, Static Compilation, Text Parsing, Text Rendering, VM Execution, VRML, VRML97, Win32, Windows Development, x86 to C, XAP/XIP, Xbox, Xbox Kernel, xboxrecomp, 安全意识培训, 客户端加密, 开放策略代理