Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/4d-stunts/restunts

A clone of clvn's restunts SVN repository
https://github.com/4d-stunts/restunts

assembly retrogaming stunts

Last synced: 6 months ago
JSON representation

A clone of clvn's restunts SVN repository

Awesome Lists containing this project

README 

          
# Restunts - The Stunts reverse engineering project



https://wiki.stunts.hu/wiki/Restunts



Main repository: https://github.com/4d-stunts/restunts



## Repository contents:

	docs

		Various technical docs related to (re)stunts itself.



	src\execombiner

		Tool which combines the original game and video drivers into a single

		debugable executable.



	src\idc

		Script for IdaPro to generate .asm-files from an ida project.



	src\restunts

		Project directory containing disassembly, ported c and makefiles to

		produce various executables based on the (re)stunts code.



	stunts

		Stunts 1.1 the game.



	tools

		Contains binaries, libraries, headers with a full toolchain for

		building restunts on Windows. The toolchain is based on TASM, TLINK,

		Turbo Debugger, Borland C++, DOSBox, and various other tools.



### Contents of src\restunts:

	src\restunts\game_mod3.idb

		The analysis database for IDAPro.



	src\restunts\asm

		Contains patched, compilable disassembly generated by the script for

		IdaPro. This code is patched to work with our ported c code.

		Note 2025-02-03: the asm is not in sync with IDA any more, since some

		variable names were modified by the script src\restunts\annotate-vars.sh



	src\restunts\asmorig

		Contains the same files as src\restunts\asm, but unpatched and does not

		use any of the ported c code.



	src\restunts\c

		Contains c functions ported from the disassembly.



	src\restunts\dos

		Makefile to build restunts for DOS.



	src\restunts\repldump

		Tool based on the original game code, loads replays and dumps the game

		state contents at each frame in a file for further analysis.



## How to build



### On Windows

	1) Double click tools\mount_stunts_to_s.bat (only needed once per reboot)

	2) Start cmd.exe and enter the following commands:

		S:

		cd \src\restunts

		setpath

		make



### On Linux

	0) You might want to set `git config --worktree core.autocrlf=false` before

	   you make any change, lest git meddles with the DOS newlines

	1) Install Wine

	2) Mount the restunts dir as drive S using winecfg

	3) In the Linux console type `wineconsole cmd`

	4) In the resulting Wine console type (mind the inverted slashes and the lack of tab completion):

	```

	s:

	cd src\restunts

	setpath

	```



### On both platforms



If everything went fine, there should be a new s:\stunts\restunts.exe which can

be run in DOSBox. Note that the drive letter S: is hardcoded many places in the

makefiles, and is also mounted inside DOSBox as a fixed point of reference.



The makefile supports the following targets:



	make  restunts

		The default restunts target builds an executable based on ported C code

		and patched disassembly.



	make  restunts-original

		Builds an executable based on unpatched disassembly with the original

		codepaths intact. Does not use any of the ported C code.



	make  repldump

		Builds the replay dump tool using ported C code and patched

		disassembly.



	make  repldump-original

		Builds the replay dump tool without ported C code.



## Build options



### Assembler selection



Restunts builds per default with TASM32 for Windows, but it can be changed to using

the a 16-bit TASMX by using option `ASSEMBLER=tasmbox` before the target name (or

`ASSEMBLER=tasmx` if one really likes seeing pop-up windows).



E.g. to build restunts with TASMX, type



	make ASSEMBLER=tasmbox restunts 



Building with TASMX is much slower since DOSBox is involved, but it allows to include 

debugging symbols (s. below)



### Linker selection



Restunts links per default with TLINK using dosbox but that can changed to using

the native WLINK executable by using option `LINKER=wlink` before the target name



E.g. to build Restunts with wlink, type



	make LINKER=wlink restunts 



Note that `WLINK` is experimental, and it does not allow to include debug symbols. Its

use can slightly speed up the build process since it avoids calling DOSBox.



### Debugging symbols



The executable can be built with debug symbols by means of the `CONFIG=debug`

option. Note that this requires using TASMX as assembler and TLINK as linker

(TLINK is currently the default but this might change in future)



E.g. to build Restunts with debug symbols, type



	make ASSEMBLER=tasmbox LINKER=tlink CONFIG=debug restunts 



## The toolchain



The toolchain has evolved over the years and it can now (2025) use either

Borland tools or alternative ones. For various reasons, the build process can

uses both 16 and 32-bit tools. In order to compile on modern 64 bit systems,

the 16-bit apps run via DOSBox. A couple of batch files (in

`tools\bin\*box.bat`) take care of starting DOSBox in headless mode to prevent

pop-ups, and copy the output into the Windows console.



### Tools used

Assemblers:

	- TASMX (16-bit, from Borland Turbo Assembler 4.0)

	- TASM32 (32-bit)



Linkers:

	- TLINK (16-bit)

	- WLINK (32-bit, experimental)



Other:

	- Borland C++ 5.2 (Win32)

	- GNU Make 4.4.1 (Win32) - from the Chocolatey Windows Packages



## Analysis in IDA and the development cycle



Analysis happens continously in IDA 6.1 (Win32). Using a custom script in IDA,

the entire disassembly is exported to compilable .asm and .inc files in

src\restunts\asm. This allows using latest analysis results in the build

process. As code is ported manually to C, the custom script is updated and kept

in sync, such that it generates patched assembly code calling into the ported C

functions.



The custom script also runs a second pass, where it exports a separate set of

.asm files to src\restunts\asmorig. These files are unpatched and produce code

that behaves 100% identically to the original game.



When doing analysis and (re)naming variables and functions, it is important to

always check the ported C code if there are any references to the previous

symbol names. All symbol references in the C code need to be kept in sync with

the analysis manually. Obviously, the linker will complain about missing

symbols in case a symbol was renamed in IDA, but not in the C files.



## Debugging restunts.exe



Restunts can be debugged with Turbo Debugger inside DOSBox. In orger to do

that, the target program must be built with debug symbols, which is possible by

setting the option `CONFIG=debug` when calling make (see paragraph “Debugging

symbols” above).



The DOSBox debugging environment is an extension of the build environment

described above:



	1) Double click tools\mount_stunts_to_s.bat (only needed once per reboot)

	2) Start DOSBox and enter the following commands:

		mount S S:

		S:

		cd tools

		setpath.bat

		cd \stunts

		td restunts.exe



Turbo Debugger is preconfigured to automatically find and show the source code.

Setting breakpoints, stepping etc works. The TD configuration file is stored in

stunts\tdconfig.td.



## Notes about the toolchain



### Notes regarding the linker



WLINK from the Open Watcom C/C++ compiler suite was originally chosen because

it supports detailed control on how to order segment classes in the final

executable image.



Our requirement is to put the original code and data first in the file, exactly

as in the original game, only patching up function calls and data access.

TLINK and OPTLINK were tested in the early days, but after having difficulties

with segment ordering and subsequent crashes, the project settled on WLINK.



The problems with TLINK were revisited and fixed years later, after an urgent

need to get debug information for the restunts executable. As WLINK is not able

to use the debug information format created by BCC/TASM, it became necessary to

replace either of them. After the initial attempts of using TLINK were

successful, no further investigation were made into replacing TASM.  It should

be noted that MASM seems a promising TASM replacement candidate: the syntax is

close to TASM, and it produces CodeView debug format usable by WLINK.



### Notes regarding 16-bit tasmx, tlink and DOSBox



The choice of reverting to TLINK was not easy either. Only the 16-bit version

of TLINK can produce 16-bit executables such as restunts.exe, and it can only

use object files produced by the 16-bit TASM. In order to use 16-bit tools on a

64-bit Windows host, they need to be emulated. And so DOSBox became

incorporated in the build process. Another problem is the regular 16-bit

tasm.exe exceeds the available 640k of memory when compiling the largest

restunts source files. This was overcome by using the DPMI-enabled tasmx.exe

instead.



### Notes regarding the CRT (libc)



When linking with cm.lib from Borland C++ 5.1, TLINK is not able to produce an

executable. To get around this, the tlib tool was used to extract object files

from cm.lib, and now restunts links with these instead.



When the project used WLINK, it was able to link with cm.lib from Borland C++

5.1, but was not able to link correctly with cm.lib from Borland C++ 3.1.

Before upgrading to Borland C++ 5.1, the makefile would link to single obj

files from Borland 3.1's CRT.



The linker can complain about weird missing symbols f.ex at first time use of

some compiler feature or CRT function. This can be fixed by extracting the

object file from cm.lib, and adding it to the makefile.



cm.lib is the medium model libc from Borland C++ 5.2. tlib.exe is a 16-bit

Borland utility for manipulating lib files and has to be run via DOSBox.



Using a binary file viewer with cm.lib it's possible to locate missing CRT

symbol names and work out/guess the object file name by looking at strings in

the binary data before it.



To extract the object file

	1) Double click tools\mount_stunts_to_s.bat (only needed once per reboot)

	2) Start DOSBox and initialize the restunts development environment:

		mount S S:

		S:

		cd tools

		setpath.bat

		cd \tools\lib

	3) Run tlib to extract the object file, some examples:

		tlib cm.lib * GETVECT

		tlib cm.lib * LABS

		tlib cm.lib * STRCPY

		tlib cm.lib * MEMCPY

		tlib cm.lib * FMEMCPY

		tlib cm.lib * H_LDIV

		tlib cm.lib * F_LXMUL

		tlib cm.lib * F_SCOPY

		tlib cm.lib * H_LRSH

		tlib cm.lib * H_PADD

		tlib cm.lib * H_PINA

		tlib cm.lib * H_PADA

		tlib cm.lib * N_PCMP

		tlib cm.lib * F_PCMP

		tlib cm.lib * H_LURSH

		tlib cm.lib * H_PSBP

		tlib cm.lib * H_LLSH

	4) Add new CRT object files in dos\makefile - at the end of the line

	   starting with CTARGETS =



## Porting a function from ASM to C



1. Open src\idc\anders.idc in a text editor and locate the PortFuncName()

   function. The IDA script needs to be aware of all the functions that have

   been ported in order to generate asm that does not conflict with the ported

   code. Add a line in PortFuncName() for the function you've chosen.



2. Run anders.idc from within IDA to regenerate the asm files (or skip step 1+2

   and rename the respective extrn, public and function manually in the .inc

   and asm files)



3. Add a function stub to one of the existing .c files in src\restunts\c

3.1 If you want to add a new .c-file to the project, you need to

	- add a target for it in c\makefile

	- add a reference to the obj in RESTUNTS_OBJFILES in dos\makefile



4. Add an extrn for the c-function in asm\custom.inc



5. Start make to see if it compiles + links



6. Port to c!