Greavesy1899/MafiaToolkit

# Mafia Toolkit [](https://ci.appveyor.com/project/Greavesy1899/mafia2toolkit) [](https://github.com/Greavesy1899/MafiaToolkit/actions/workflows/dotnet.yml) 一款适用于 Mafia 系列的 Windows 模组制作工具包，包含文件格式解析器、编辑器以及 3D 地图编辑器。 ## 支持的游戏 | 游戏 | SDS | Materials | Map Editor | XBin | |------|-----|-----------|------------|------| | Mafia II | ✓ | ✓ | ✓ | - | | Mafia II: Definitive Edition | ✓ | ✓ | ✓ | - | | Mafia III | ✓ | ✓ | - | ✓ | | Mafia I: Definitive Edition | ✓ | ✓ | - | ✓ | 不支持 Mafia 1 Classic。 ## 构建 **要求：** Windows, .NET 8 SDK, Visual Studio 2022 ``` # 构建 toolkit dotnet build MafiaToolkit.sln # 或指定 output directory dotnet build --output "_out" ``` ### M2FBX (可选原生库) FBX 模型导入/导出和碰撞烹饪所需。 **额外要求：** [Autodesk FBX SDK](https://adsdk.autodesk.com/fbx), PhysX 2.8.X ``` cd M2FBX/M2FBX premake5 vs2022 # 在 Visual Studio 中打开 M2FBX.sln 并构建 ``` ## 编辑器 | 编辑器 | 文件类型 | 描述 | |--------|------------|-------------| | **Map Editor** | `FrameResource.fr` | 具有 DirectX 11 渲染功能的 3D 场景编辑器。编辑几何体、碰撞体、材质。通过 FBX 导出/导入。 | | **Material Editor** | `.mtl` | 编辑材质、参数、采样器。支持 MTL 版本 57, 58, 63。在文件之间合并材质。 | | **XBin Editor** | `.xbin` | 编辑游戏数据容器。XML 导出/导入。 | | **Translokator Editor** | `Translokator_*.tra` | 对象放置和实例化。 | | **Table Editor** | Game tables | 编辑游戏数据表。 | | **City Editors** | `cityareas.bin`, `cityshops.bin` | 编辑城市区域和商店。 | | **Actor Editor** | `.act`, `.fxa`, `.fas` | 编辑游戏实体和动画。 | | **Cutscene Editor** | `.cut` | 编辑过场动画序列。 | ## SDS Archive 支持 - 解包/打包 SDS archives（基于 [Gibbed.Illusion](https://github.com/gibbed/Gibbed.Illusion)） - 自动 XML 和表反编译 - 可选 Lua 反编译 - 压缩和非压缩输出 - 兼容 ZModeler3 的导出格式 ## MCP Server (AI Integration) MafiaToolkit 包含一个集成的 MCP (Model Context Protocol) 服务器，允许像 Claude 这样的 AI 助手以编程方式浏览和检查 Mafia 游戏文件。服务器在 MafiaToolkit 启动时自动启动。 ### 配置 在你的项目目录中创建一个 `.mcp.json` 文件（或添加到你的 Claude Code 设置中）： ``` { "mcpServers": { "mafia-toolkit": { "type": "http", "url": "http://localhost:5123/" } } } ``` ### 使用 1. 启动 MafiaToolkit（MCP 服务器在端口 5123 上自动启动） 2. 在 Claude Code 中，运行 `/mcp` 连接到服务器 3. 使用可用的工具浏览 SDS archives 和游戏文件 ### 可用工具（共 24 个） #### SDS Archive 工具（8 个工具） | 工具 | 参数 | 描述 | |------|------------|-------------| | `list_sds_files` | `directoryPath`, `recursive` | 列出目录中的所有 `.sds` 文件。返回找到的每个 archive 的文件路径、名称和大小。 | | `open_sds_file` | `filePath`, `gameType?` | 打开一个 SDS archive 并获取完整的元数据，包括版本、平台、资源类型以及带有大小的完整资源列表。 | | `get_sds_header` | `filePath` | 获取 SDS 头信息：版本（19=Mafia II, 20=Mafia III）、平台、字节序、RAM/VRAM 需求。 | | `list_resources` | `filePath`, `typeFilter?`, `offset`, `limit` | 列出资源，支持可选的类型过滤（如 "Texture", "Sound"）和分页。 | | `get_resource_info` | `filePath`, `resourceIndex` | 获取特定资源的详细信息：类型、版本、数据大小、内存需求、文件哈希。 | | `search_resources` | `filePath`, `pattern`, `typeFilter?`, `limit` | 按名称模式搜索资源（不区分大小写）。可选择按资源类型过滤。 | | `extract_resource` | `filePath`, `resourceIndex`, `maxBytes?` | 将原始资源数据提取为 base64。支持限制大型资源的大小。 | | `get_sds_stats` | `filePath` | 获取摘要统计信息：总资源数、按类型的数量和大小细分、压缩信息。 | #### Texture 工具（4 个工具） | 工具 | 参数 | 描述 | |------|------------|-------------| | `inspect_dds_file` | `filePath` | 检查独立的 DDS 纹理文件。返回尺寸、格式（DXT1/DXT5/BC7 等）、mip 数量、标志。 | | `inspect_sds_texture` | `sdsPath`, `resourceIndex` | 检查 SDS archive 内的纹理资源。显示纹理头（名称哈希、mip 标志）和 DDS 元数据。 | | `list_sds_textures` | `sdsPath`, `includeMetadata?` | 列出 SDS 中的所有纹理资源。可选择包含每个纹理的完整 DDS 元数据（尺寸、格式）。 | | `inspect_dds_bytes` | `base64Data` | 从 base64 编码的字节检查 DDS 纹理。用于分析提取的纹理数据。 | #### Material 工具（4 个工具） | 工具 | 参数 | 描述 | |------|------------|-------------| | `open_mtl_file` | `filePath` | 打开 Material Library (.mtl) 文件。返回版本（V57/V58/V63）、材质数量以及带有着色器信息的材质列表。 | | `list_mtl_files` | `directoryPath`, `recursive` | 列出目录中的所有 MTL 文件，并附带每个文件的快速元数据（版本、材质数量）。 | | `get_material_info` | `filePath`, `materialIndex` | 获取详细的材质信息：着色器 ID/哈希、标志、带有纹理名称的采样器以及所有参数。 | | `search_materials` | `filePath`, `pattern`, `limit` | 按名称模式搜索材质（不区分大小写的子字符串匹配）。 | #### 实用工具（8 个工具） | 工具 | 参数 | 描述 | |------|------------|-------------| | `get_configured_games` | *(无)* | 获取 MafiaToolkit 中配置的所有游戏及其安装路径、选定的游戏以及路径有效性状态。 | | `hash_fnv32` | `input`, `useCodePage1252?` | 计算字符串的 FNV32 哈希。Mafia 游戏用于资源识别。返回十进制、十六进制和有符号值。 | | `hash_fnv64` | `input`, `useCodePage1252?` | 计算字符串的 FNV64 哈希。用于文件/纹理识别。返回十进制、十六进制和有符号值。 | | `hash_batch` | `inputs` | 计算多个字符串的 FNV32 和 FNV64 哈希（以逗号或换行符分隔）。 | | `detect_file_format` | `filePath` | 从魔数检测文件格式。识别 SDS, MTL, DDS, BNK, LUA, XML, PNG 以及特定游戏格式。 | | `detect_format_from_bytes` | `base64Data`, `extensionHint?` | 从 base64 编码的字节检测文件格式。用于识别提取的资源。 | | `convert_number` | `input` | 在十进制、十六进制 (0x) 和二进制 (0b) 之间转换。返回所有表示形式以及有符号值和字节数组。 | | `list_game_files` | `directoryPath`, `extensionFilter?`, `recursive` | 列出匹配常见 Mafia 扩展名（.sds, .mtl, .dds, .act, .nav, .xbin 等）的游戏文件。 | ### 支持的格式 - **SDS Archives**：版本 19 (Mafia II/DE)，版本 20 (Mafia III/I:DE) - **压缩**：zlib 和 Oodle（需要游戏目录中的 `oo2core_8_win64.dll`） - **加密的 SDS**：使用 TEA 密码自动解密 ## 项目结构 ``` Mafia2Libs/ # Main C# toolkit ├── Core/IO/ # File format handlers ├── ResourceTypes/ # Game data structures ├── Rendering/ # DirectX 11 engine ├── Forms/ # Editor windows ├── MCP/ # Integrated MCP server │ ├── Services/ # SDS parsing service │ └── Tools/ # MCP tool definitions └── Gibbed.*/ # Archive serialization M2FBX/ # Native C++ FBX library ``` ## 链接 - [问题反馈](https://github.com/Greavesy1899/Mafia2Toolkit/issues) - [Discord](https://discord.gg/HFCksVXXWy)

标签：3D 编辑器, DirectX 11, FBX, Mafia DE, Mafia II, Mafia III, .NET 8, PhysX, rizin, SDS 解包, Visual Studio 2022, Windows 软件, XBin, 二进制编辑, 地图编辑器, 开源工具包, 文件格式解析, 材质编辑器, 模型导入导出, 游戏开发, 游戏模组工具, 碰撞烹饪