isledecomp/isle
1
0
Fork 0
mirror of https://github.com/isledecomp/isle.git synced 2026-01-20 23:01:16 +00:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity
b03d67e342
isle/README.md
Mark Langen b03d67e342 Update README
2023-07-02 20:52:03 -07:00

7.0 KiB
Raw Blame History

LEGO Island Decompilation

Development Vlog | Contributing | Matrix | Forums | Patreon

This is a work-in-progress decompilation of LEGO Island version 1.1. It aims to 100% match the original instructions where possible. The goal is to provide a codebase that can be modified, improved, and ported to other platforms.

Status

  • ISLE.EXE is completely decompiled and behaves identically to the original. A handful of instructions aren't matching, however we anticipate they will as more of the overall codebase is implemented.

  • LEGO1.DLL is still very incomplete and not close to playable yet.

  • If you want to test things out, pair the decompiled ISLE.EXE with the LEGO1.DLL from the original game.

Build Requirements

Here are all the artifacts involved in the build process in some way:

  • CMake (you must install this) - A copy is often included with the "Desktop development with C++" workload in newer versions of Visual Studio, however it can also be installed as a standalone app.

  • Lego Island 1.1 (downloaded automatically by build) - A copy of the original game is needed to compare the decomped results against. A copy of LEGO1.DLL will be downloaded automatically for comparison purposes, but you will need to acquire the game assets yourself to pair with the exe / dll if you want to play the game.

  • Microsoft Visual C++ 4.2 (downloaded automatically by build) - This compiler was used to build the original game. It can be found on many abandonware sites, but the installer can be a little iffy on modern versions of Windows. The default workflow downloads and uses this portable version instead.

  • DirectX 5 SDK (not currently needed). Similarly, this can be found on many abandonware sites. Currently not needed by the code decomped so far but will be needed in the future once we get to 3d rendering functions.

Building (Default Workflow)

Default Workflow with VSCode

This projects uses the CMake build system, which allows for a high degree of versatility regarding compilers and development environments.

We provide a default development workflow through configure.py and build.py, along with an associated tasks.json, such that VSCode can build the isle repo out of the box and you can dive right into writing code. If you want to use the default workflow, open your clone of the repo in VSCode, hit Ctrl+Shift+B, and run Configure decomp with standard setup followed by Build decomp.

The standard decomping workflow is to repeatedly make edits to a function and run Build decomp and inspect function by cursor to work towards a 100% match of that function which can be contributed to the project.

Default Workflow with Other Editors

The VSCode tasks above are just thin wrappers around invoking configure.py and build.py. Invoking them with no arguments will do a basic build of the project. You can invoke them from the command line or configure your editor of choice to invoke them.

Playing the Result

Simply place the compiled ISLE.EXE into LEGO Island's install folder (usually C:\Program Files\LEGO Island or C:\Program Files (x86)\LEGO Island).

Unless you're a developer, disregard the compiled LEGO1.DLL for now as it is too incomplete to be usable. Alternatively, LEGO Island can run from any directory as long as ISLE.EXE and LEGO1.DLL are in the same directory, and the registry keys point to the correct location for the asset files.

Contributing

If you're interested in helping/contributing to this project, check out the CONTRIBUTING page.

Building (Custom Workflow)

For those who wish to understand the build in more detail:

Microsoft Visual C++ 4.20 was used to build the original game. The default workflows above download and use a copy of that specific compiler in order for us to get our desired 100% matching instructions.

The game can be built using a contemporary compiler by invoking cmake with your compiler / build system of choice. This will still produce a working game, however it will not result in matching instructions which can be contributed to the project.

Example Custom Build Setup

The following steps produce a working build with matching instructions without using the auto configure / build scripts:

  1. Open a Command Prompt (cmd).
  2. Run <MSVCPath>/BIN/VCVARS32.BAT x86 from your copy of Visual C++ 4.2 to set up the environment variables for the compiler.
  3. Make a build folder in the source repository (the folder you cloned/downloaded).
  4. cd to the build folder.
  5. Configure the project with CMake by running: cmake .. -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=RelWithDebInfo
  6. RelWithDebInfo is used to produce debug symbols for decompilation work. Release will just produce an executable. Debug builds are unlikely to be useful since they will differ in code generation from the retail LEGO1.DLL.
  7. "NMake Makefiles" is the native build tool of Visual C++ 4.2. The standard workflow downloads and uses the more modern "Ninja" build tool for faster builds.
  8. Build the project by running nmake or cmake --build . from the build folder.
  9. When this is done, there should a recompiled ISLE.EXE and LEGO1.DLL in the build folder.

Additional Details

Which version of LEGO Island do I have?

Right click on LEGO1.DLL, select Properties, and switch to the Details tab. Under Version you should either see 1.0.0.0 (1.0) or 1.1.0.0 (1.1). Additionally, you can look at the game disc files; 1.0's files will all say August 8, 1997, and 1.1's files will all say September 8, 1997. Version 1.1 is by far the most common, especially if you're not using the English or Japanese versions, so that's most likely the version you have.

SmartHeap

Both ISLE.EXE and LEGO1.DLL were originally statically linked with SmartHeap, a drop-in replacement for malloc/free that presumably provides better heap memory management on the old low-memory (16MB) systems this game was designed for. Unfortunately, acquiring SmartHeap legally is expensive, and the chances of acquiring the exact same version used by Mindscape in the late 90s is very low. Since it's a drop-in binary-compatible replacement, this decomp can just stick with the standard malloc/free functions while still achieving matching assembly on a per-function level, however the resulting binaries will never be byte accurate as a result of this. If you notice significant size disparities, particularly in ISLE.EXE, the lack of statically linked SmartHeap libraries is why.