From 51f290b84baa9574a79e4799d1ccdb14d9e7b45e Mon Sep 17 00:00:00 2001 From: Gynt Date: Tue, 19 May 2026 21:27:44 +0200 Subject: [PATCH 1/3] docs: add tutorial about getting started --- docs/wiki.rst | 1 + .../tutorials/reimplementation-tutorial-0.md | 115 ++++++++++++++++++ 2 files changed, 116 insertions(+) create mode 100644 docs/wiki/tutorials/reimplementation-tutorial-0.md diff --git a/docs/wiki.rst b/docs/wiki.rst index 78b3d6f..62a07f2 100644 --- a/docs/wiki.rst +++ b/docs/wiki.rst @@ -12,6 +12,7 @@ About the OpenSHC Project Tutorials ------------- +- :doc:`Getting Started ` - :doc:`Reimplementation tutorial 1: basics ` - :doc:`Reimplementation tutorial 2: function calls ` - :doc:`Reimplementation tutorial 3: arrays and fields ` diff --git a/docs/wiki/tutorials/reimplementation-tutorial-0.md b/docs/wiki/tutorials/reimplementation-tutorial-0.md new file mode 100644 index 0000000..e32126f --- /dev/null +++ b/docs/wiki/tutorials/reimplementation-tutorial-0.md @@ -0,0 +1,115 @@ +# Tutorials + +## Tutorial 0: Getting Started + +### Requirements + +Before you begin, install the following: + +* **Stronghold Crusader 1.41 (Latin version)** + + The Steam release is the easiest version to obtain. Make sure the game installation uses a Latin-language version such as English or German. + +* **CMake 3.24 or later** + + You can install it from: + + * [https://cmake.org/download/](https://cmake.org/download/) + * [https://github.com/Kitware/CMake/releases/](https://github.com/Kitware/CMake/releases/) + + If you already installed the Microsoft Visual C++ Development Tools, you can also install CMake through Visual Studio. + +* **Python 3** + +* **clang-format 22 or later** + + Install it with: + + ```bash + python -m pip install clang-format + ``` + +* **An IDE with CMake support (recommended)** + + The repository is optimized for Visual Studio Code with the Microsoft C/C++ Extension Pack. + + To automatically format and style new C++ files, install the clang-format Extension Pack. + +--- + +## Setup + +### 1. Clone the repository + +Clone the repository with submodules included: + +```bash +git clone --recursive https://github.com/sourcehold/OpenSHC.git +``` + +Then enter the project directory: + +```bash +cd OpenSHC +``` + +> The `--recursive` flag is required because the repository depends on submodules, including the compiler. + +--- + +### 2. Create a symbolic link to the original game + +Run the following command: + +```bash +softlink.bat +``` + +The script will ask for the full path to your Stronghold Crusader installation directory. + +After the link is created, a folder named `_original` will appear in the repository root. + +> This script may require administrator privileges to be able to create the symbolic link + +--- + +### 3. Set up the Python environment for binary comparison + +To set up the binary comparison tools, run: + +```bash +reccmp\dll\setup.bat +``` + +> In the future, if you want to setup comparison of the reimplemented executable instead of the DLL, use: +> ```bash +> reccmp\exe\setup.bat +> ``` + +--- + +## Verifying the Setup + +### 1. Build the project + +From the `OpenSHC` directory, run: + +```bash +build.bat RelWithDebInfo OpenSHC.dll +``` + +--- + +### 2. Run binary comparison + +This verifies byte-level accuracy between the reimplementation and the original binary: + +```bash +reccmp/dll/run reccmp-reccmp --target STRONGHOLDCRUSADER +``` + +> Tip: use `reccmp/dll/run reccmp-reccmp --target STRONGHOLDCRUSADER --verbose ` to investigate code byte mismatches. + +--- + +**If both commands complete successfully, your development environment is ready and you can start working on OpenSHC.** From b6f766af6b5d14b4e3b0cbbb78821333288bdb20 Mon Sep 17 00:00:00 2001 From: Gynt Date: Tue, 19 May 2026 21:35:42 +0200 Subject: [PATCH 2/3] Update reimplementation-tutorial-0.md --- docs/wiki/tutorials/reimplementation-tutorial-0.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/wiki/tutorials/reimplementation-tutorial-0.md b/docs/wiki/tutorials/reimplementation-tutorial-0.md index e32126f..59a2ee3 100644 --- a/docs/wiki/tutorials/reimplementation-tutorial-0.md +++ b/docs/wiki/tutorials/reimplementation-tutorial-0.md @@ -90,6 +90,8 @@ reccmp\dll\setup.bat ## Verifying the Setup +If **both** commands complete successfully, your development environment is ready and you can start working on OpenSHC. + ### 1. Build the project From the `OpenSHC` directory, run: From 1b0e11e95e47831d699e04487b6e12669a4af5cd Mon Sep 17 00:00:00 2001 From: Gynt Date: Tue, 19 May 2026 21:38:11 +0200 Subject: [PATCH 3/3] Update reimplementation-tutorial-0.md --- docs/wiki/tutorials/reimplementation-tutorial-0.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/wiki/tutorials/reimplementation-tutorial-0.md b/docs/wiki/tutorials/reimplementation-tutorial-0.md index 59a2ee3..b719492 100644 --- a/docs/wiki/tutorials/reimplementation-tutorial-0.md +++ b/docs/wiki/tutorials/reimplementation-tutorial-0.md @@ -113,5 +113,3 @@ reccmp/dll/run reccmp-reccmp --target STRONGHOLDCRUSADER > Tip: use `reccmp/dll/run reccmp-reccmp --target STRONGHOLDCRUSADER --verbose ` to investigate code byte mismatches. --- - -**If both commands complete successfully, your development environment is ready and you can start working on OpenSHC.**