isledecomp/isle
1
0
Fork 0
mirror of https://github.com/isledecomp/isle.git synced 2026-01-20 14:51:15 +00:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity

Update README

Browse Source
This commit is contained in:
Mark Langen 2023-07-02 20:52:03 -07:00
parent a32c041ab5
commit b03d67e342
1 changed files with 49 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
README.md
View File

@ -2,58 +2,78 @@
[Development Vlog](https://www.youtube.com/playlist?list=PLbpl-gZkNl2COf_bB6cfgTapD5WduAfPz) | [Contributing](https://github.com/isledecomp/isle/blob/master/CONTRIBUTING.md) | [Matrix](https://matrix.to/#/#isledecomp:matrix.org) | [Forums](https://forum.mattkc.com/viewforum.php?f=1) | [Patreon](https://www.patreon.com/mattkc)
This is a **work-in-progress** decompilation of LEGO Island version 1.1. It aims to be as accurate as possible, matching the recompiled instructions to the original machine code as much as possible. The goal is to provide a workable codebase that can be modified, improved, and ported to other platforms later on.
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
<img src="https://legoisland.org/progress/ISLEPROGRESS.SVG" width="50%"><img src="https://legoisland.org/progress/LEGO1PROGRESS.SVG" width="50%">
Currently `ISLE.EXE` is completely decompiled and behaves identically to the original. A handful of stubborn instructions are not yet matching, however we anticipate they will as more of the overall codebase is implemented.
* `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 much incomplete and cannot be used at this time. Instead, if you want to test this, it is recommended to pair the recompiled `ISLE.EXE` with the `LEGO1.DLL` from the original game.
* `LEGO1.DLL` is still very incomplete and not close to playable yet.
## Building
* If you want to test things out, pair the decompiled `ISLE.EXE` with the `LEGO1.DLL` from the original game.
This projects uses the [CMake](https://cmake.org/) build system, which allows for a high degree of versatility regarding compilers and development environments. For the most accurate results, it is recommended to use Microsoft Visual C++ 4.20 (the same compiler used to build the original game). Since we're trying to match this to the original executable as closely as possible, all contributions will be graded with the output of this compiler.
## Build Requirements
Here are all the artifacts involved in the build process in some way:
These instructions will outline how to compile this repository into an accurate instruction-matching binary with Visual C++ 4.2. If you wish, you can try using other compilers, but this is at your own risk and won't be covered in this guide.
* **[CMake](https://cmake.org/)** *(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.
#### Prerequisites
* **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.
You will need the following software installed:
* **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](https://github.com/itsmattkc/msvc420) instead.
- Microsoft Visual C++ 4.2. This can be found on many abandonware sites, but the installer can be a little iffy on modern versions of Windows. For convenience, I made a [portable version](https://github.com/itsmattkc/msvc420) that can be downloaded and used quickly instead.
- DirectX 5 SDK. Similarly, this can be found on many abandonware sites.
- [CMake](https://cmake.org/). 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.
* **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.
#### Compiling From Command Line
## Building (Default Workflow)
### Default Workflow with VSCode
1. Open a Command Prompt (`cmd`).
1. From Visual C++ 4.2, run `BIN/VCVARS32.BAT x86` to populate the path and other environment variables for compiling with MSVC.
1. Make a folder for compiled objects to go, such as a `build` folder inside the source repository (the folder you cloned/downloaded to).
1. In your Command Prompt, `cd` to the build folder.
1. Configure the project with CMake by running:
```
cmake <path-to-source> -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=RelWithDebInfo
```
- Replace `<path-to-source>` with the source repository. Can be `..` if your build folder is inside the source repository.
- `RelWithDebInfo` is recommended because it will produce debug symbols useful for further decompilation work. However, you can change this to `Release` if you don't need them. `Debug` builds are not recommended because they are unlikely to be compatible with the retail `LEGO1.DLL`, which is currently the only way to really use this decomp.
- `NMake Makefiles` is most recommended because it will be immediately compatible with Visual C++ 4.2. For faster builds, you can use `Ninja` (if you have it installed), however due to limitations in Visual C++ 4.2, you can only build `Release` builds this way (debug symbols cannot be generated with `Ninja`).
1. Build the project by running `nmake` or `cmake --build <build-folder>`
1. When this is done, there should a recompiled `ISLE.EXE` and `LEGO1.DLL` in the build folder.
This projects uses the [CMake](https://cmake.org/) build system, which allows for a high degree of versatility regarding compilers and development environments.
If you have a CMake-compatible IDE, it should be pretty straightforward to use this repository, as long as you can use `VCVARS32.BAT` and set the generator to `NMake Makefiles`.
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 <kbd>Ctrl+Shift+B</kbd>, and run `Configure decomp with standard setup` followed by `Build decomp`.
## Usage
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.
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.
### 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](https://github.com/isledecomp/isle/blob/master/CONTRIBUTING.md) page.
## Additional Information
## 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`).
1. Run `<MSVCPath>/BIN/VCVARS32.BAT x86` from your copy of Visual C++ 4.2 to set up the environment variables for the compiler.
1. Make a `build` folder in the source repository (the folder you cloned/downloaded).
1. `cd` to the build folder.
1. Configure the project with CMake by running:
`cmake .. -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=RelWithDebInfo`
1. `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`.
1. `"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.
1. Build the project by running `nmake` or `cmake --build .` from the build folder.
1. 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?