README

Matching decompilation of Socher Hayam (סוחר הים)

This repository contains a matching decompilation of the game סוחר הים - source code that compiles to the exact same binary as the original.

Why?

Socher Hayam is a cult classic and a wonderful educational game, which deserves appreciation and preservation.

Reconstructing the source will allow a better understanding of it and the creation of modern ports (pun definitely intended), true to the original.

Contributing

While all variables and functions are already renamed to represent their role, PRs for adding documentation, improving the names or formatting etc. are more than welcome, as long as they don't change the compiled executable.

Requirements

• Python
• DOS emulator, such as DOSBox or dosemu2

Building

First run the script:

./build/reencode.py

Then in your DOS emulator, from within the build folder, run:

compile

Afterwards you should see a new k.com file in the build folder.

Validation

In order to make sure the compiled file still matches the original executable, run the script:

./build/validate.py

Files Overview

????????? GLOBALS.PAS         # Globals and type declarations
????????? CODE.PAS            # Rest of the code
????????? build
???   ????????? reencode.py     # Script for reencoding the files from the
???   ???                     parent folder from UTF-8 to CP862
???   ????????? compile.bat     # Command for compiling the code
???   ????????? validate.py     # Script for validating a compiled file matches
???   ???                     Socher Hayam
???   ????????? K.PAS           # Input file for compilation, includes the
???   ???                     reencoded files
???   ????????? TPCLI.COM       # Patched version of Turbo Pascal 3.01A which
???   ???                     can be used from the command line
???   ????????? GRAPH.P         # Header part of Turbo Pascal's graphics lib
│   └── GRAPH.BIN       # Binary part of Turbo Pascal's graphics lib
????????????????????? Readme.md       # This file

The annotation work is expected to be done exclusively in GLOBALS.PAS and CODE.PAS, while the contents of the build directory is only there for compilation and validation.

You can recreate the CLI version of Turbo Pascal by using the dissassembly tools and applying this patch.

FAQ

What is This Reencoding Step?

The original code used Code page 862 for representing Hebrew characters. For ease of editing, this repository contains the code encoded using UTF-8. This means a reencoding step is required before compilation, which is handled by the build/reencode.py script.

Why are Some Bytes Ignored in the Validation?

There are two segments of bytes in the compiled executable which don't match the original. Both, however, don't really depend on the source code:

1. Timing measurements - During the startup of Turbo Pascal 3.0 or any program compiled by it, there's initialization code that measures how many cycles the CPU runs in a second, to be used later in Delay calls. So this value in the executable both depends on the compilation machine and is recalculated anyway when you start up the executable.
2. Uncrunch stuff - This is only relevant for overlays which Socher Hayam doesn't use, so it's irrelevant for us.