Isle-Portable项目贡献指南与技术规范解析

项目背景与目标

Isle-Portable项目是基于经典游戏LEGO Island的逆向工程成果，专注于实现代码的平台无关性移植。该项目源自一个成熟的逆向工程基础，旨在将原本依赖特定平台的游戏代码重构为可在现代系统上运行的跨平台版本。

代码贡献的核心原则

保持提交的原子性

在参与项目开发时，开发者应遵循"单一职责原则"提交代码：

• 每次提交应专注于一个类或一个功能模块的修改
• 避免大规模跨文件修改（建议不超过10个文件）
• 关联性强的类可以例外，但需保持逻辑完整性

这种做法的优势在于：

1. 降低代码审查难度
2. 减少合并冲突概率
3. 便于追踪修改历史

项目范围界定

项目核心目标是实现平台无关性，因此以下类型的贡献不在接受范围内：

• 单纯优化性能但不涉及平台兼容性的修改
• 替换原生字符串实现（如MxString到std::string）
• 修复游戏逻辑错误
• 提升音视频质量

项目架构解析

主要代码目录结构

1. 3rdparty目录

   • 存放第三方库代码
   • 不适用项目代码风格规范
   • 包含公共领域或自由获取的库文件

2. CONFIG目录

   • 基于逆向的CONFIG.EXE源码
   • 依赖LEGO1部分代码

3. ISLE目录

   • 基于逆向的ISLE.EXE源码
   • 依赖LEGO1部分代码

4. LEGO1目录（核心引擎）

   • 基于逆向的LEGO1.DLL源码
   • 包含Mindscape自研Omni引擎(mx*前缀文件)
   • 包含游戏专用扩展(lego*前缀文件)
   • 包含Mindscape开发的工具库

5. tools目录

   • 现代化改造辅助工具集

6. util目录

   • 现代化改造辅助头文件

代码规范详解

格式化标准

项目采用clang-format和clang-tidy进行代码格式化：

• 配置尽可能还原原始开发者的代码风格
• 要求使用clang 18.x工具链
• 主流编辑器/IDE都有对应的集成插件

格式化要点包括：

• 一致的缩进风格
• 括号位置规范
• 空格和空行使用规则
• 行长度限制

命名约定

项目使用定制版ncc工具维护命名规范：

• 基于clang 16.x工具链
• 配置还原原始命名风格
• 包含类名、方法名、变量名等规范

典型命名特征：

• 类名采用大驼峰式
• 方法名采用小驼峰式
• 成员变量可能有特定前缀
• 常量采用全大写加下划线

最佳实践建议

1. 保持逆向工程一致性

   • 最小化结构调整
   • 优先在基础逆向工程项目中改进命名
   • 保持逆向项目作为"唯一真相源"

2. 模块化开发

   • 按功能模块划分工作
   • 避免跨模块大规模修改
   • 保持接口稳定性

3. 工具链使用

   • 配置IDE集成代码格式化
   • 提交前运行格式检查
   • 定期同步工具链版本

技术决策背后的考量

项目维护团队在制定这些规范时，主要基于以下技术考量：

1. 可维护性优先

   • 小规模提交确保问题可追溯
   • 降低协作开发成本

2. 历史兼容性

   • 保留原始代码风格便于比对
   • 减少合并基础逆向工程的冲突

3. 渐进式改进

   • 先确保功能正确性
   • 再考虑现代化重构
   • 平台兼容性作为首要目标

对于新加入的开发者，建议先从小的、独立的模块入手，熟悉项目风格和规范后，再参与更复杂的部分。项目鼓励通过讨论确定技术方案，避免大规模重构带来的不确定性。