Contributing

Important Note

We are thrilled about the interest in reverse engineering LEGO Island and welcome contributions from anyone eager to advance the project. However, proposed changes must meet a certain standard of engineering quality. While our established contributors are happy to provide code reviews and constructive feedback, they cannot teach contributors C++ or decompilation fundamentals.

This project depends on contributors' free time, a resource often in short supply. Poorly constructed contributions, though well-intentioned, can hinder progress in the long term. If you're not confident in your decompilation abilities, we recommend returning once you have a stronger grasp of the process.

Decompilation is an advanced skill. Depending on your proficiency in C/C++ and x86 assembly, it might take months or even years to develop the necessary skills. For beginners, Part 1 of the decompilation vlog provides an excellent introduction. Please familiarize yourself with this process before contributing code.

Ghidra Server

We use Ghidra (free and open source) to document the original binaries and generate pseudocode for decompilation. Collaboration is facilitated through a shared Ghidra repository. You are welcome to explore it locally, but push access requires permission to prevent sabotage. Contact us in the Matrix room to request access.

Repository details:

Address: server.mattkc.com
Port: 13100

Note: Much of the information on the Ghidra server is outdated. The source code in this repository is the most accurate "source of truth" and should be referenced whenever possible.

General Guidelines

If you're ready to contribute, feel free to create a pull request (PR). We will review and merge it—or provide feedback—as soon as possible.

Pull Request Tips:

Keep PRs small and understandable to facilitate collaboration and reduce errors.
Large PRs (modifying more than ~10 files) increase the likelihood of merge conflicts and errors.
Aim to focus on one class per PR. Interlinked classes may require exceptions but proceed cautiously.

Project Goals:

This repository's sole objective is accuracy to the original executables.

We prioritize byte/instruction matching the original compiler (MSVC 4.20).
Modernizations or bug fixes will likely be rejected for now.

Overview

3rdparty: Libraries from third parties (excluding Mindscape). These are public domain or freely available files. Our style guide does not apply here.
CONFIG: Decompilation of CONFIG.EXE, dependent on LEGO1 code.
ISLE: Decompilation of ISLE.EXE, dependent on LEGO1 code.
LEGO1: Decompilation of LEGO1.DLL, containing:
- Omni: Mindscape's custom in-house engine (mx* files).
- LEGO-specific code: Extensions and game-specific libraries (lego* files).
- Utility libraries developed by Mindscape.
tools: Aiding tools for decompilation.
util: Utility headers supporting the effort.

Tooling

Refer to the tooling and annotations guide. Familiarity with these tools is essential for contributing.

Notes on MSVC 4.20

As outlined in the README, we use Microsoft Visual C++ 4.20 to compile the game.

Compiler Randomness

The compiler's code generation can behave erratically, introducing "compiler randomness" or entropy.
Changes in headers, even unrelated ones (e.g., adding an unused inline function), may alter unrelated function outputs.
This issue affects ~5% of decompiled functions, complicating efforts to achieve 100% matching binaries.

If you have insights into this phenomenon, please contact us.

Code Style

Formatting

We use:

clang-format and clang-tidy with configuration files replicating the original formatting.
Required clang version: 18.x.

Naming Conventions

We use a customized version of ncc to replicate original naming conventions.

Required clang version: 16.x.
Refer to the ncc tool guide and GitHub action for details.

Questions?

For further questions, reach out via:

4.4 KiB Raw Blame History