{"id":25721273,"url":"https://github.com/4d-stunts/restunts","last_synced_at":"2025-05-06T22:07:23.672Z","repository":{"id":279097978,"uuid":"937188543","full_name":"4d-stunts/restunts","owner":"4d-stunts","description":"A clone of clvn's restunts SVN repository","archived":false,"fork":false,"pushed_at":"2025-04-17T19:53:41.000Z","size":8318,"stargazers_count":7,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-06T22:06:25.953Z","etag":null,"topics":["assembly","retrogaming","stunts"],"latest_commit_sha":null,"homepage":"https://forum.stunts.hu/index.php?board=90.0","language":"Assembly","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/4d-stunts.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-22T14:49:27.000Z","updated_at":"2025-04-23T12:07:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"2ddefde0-c08e-442b-98b5-83d5be59c654","html_url":"https://github.com/4d-stunts/restunts","commit_stats":null,"previous_names":["4d-stunts/restunts"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4d-stunts%2Frestunts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4d-stunts%2Frestunts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4d-stunts%2Frestunts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4d-stunts%2Frestunts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/4d-stunts","download_url":"https://codeload.github.com/4d-stunts/restunts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252776579,"owners_count":21802468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assembly","retrogaming","stunts"],"created_at":"2025-02-25T18:35:31.214Z","updated_at":"2025-05-06T22:07:23.663Z","avatar_url":"https://github.com/4d-stunts.png","language":"Assembly","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Restunts - The Stunts reverse engineering project\r\n\r\nhttps://wiki.stunts.hu/wiki/Restunts\r\n\r\nMain repository: https://github.com/4d-stunts/restunts\r\n\r\n## Repository contents:\r\n\tdocs\r\n\t\tVarious technical docs related to (re)stunts itself.\r\n\r\n\tsrc\\execombiner\r\n\t\tTool which combines the original game and video drivers into a single\r\n\t\tdebugable executable.\r\n\r\n\tsrc\\idc\r\n\t\tScript for IdaPro to generate .asm-files from an ida project.\r\n\r\n\tsrc\\restunts\r\n\t\tProject directory containing disassembly, ported c and makefiles to\r\n\t\tproduce various executables based on the (re)stunts code.\r\n\r\n\tstunts\r\n\t\tStunts 1.1 the game.\r\n\r\n\ttools\r\n\t\tContains binaries, libraries, headers with a full toolchain for\r\n\t\tbuilding restunts on Windows. The toolchain is based on TASM, TLINK,\r\n\t\tTurbo Debugger, Borland C++, DOSBox, and various other tools.\r\n\r\n\r\n### Contents of src\\restunts:\r\n\tsrc\\restunts\\game_mod3.idb\r\n\t\tThe analysis database for IDAPro.\r\n\r\n\tsrc\\restunts\\asm\r\n\t\tContains patched, compilable disassembly generated by the script for\r\n\t\tIdaPro. This code is patched to work with our ported c code.\r\n\t\tNote 2025-02-03: the asm is not in sync with IDA any more, since some\r\n\t\tvariable names were modified by the script src\\restunts\\annotate-vars.sh\r\n\r\n\tsrc\\restunts\\asmorig\r\n\t\tContains the same files as src\\restunts\\asm, but unpatched and does not\r\n\t\tuse any of the ported c code.\r\n\r\n\tsrc\\restunts\\c\r\n\t\tContains c functions ported from the disassembly.\r\n\r\n\tsrc\\restunts\\dos\r\n\t\tMakefile to build restunts for DOS.\r\n\r\n\tsrc\\restunts\\repldump\r\n\t\tTool based on the original game code, loads replays and dumps the game\r\n\t\tstate contents at each frame in a file for further analysis.\r\n\r\n\r\n## How to build\r\n\r\n### On Windows\r\n\t1) Double click tools\\mount_stunts_to_s.bat (only needed once per reboot)\r\n\t2) Start cmd.exe and enter the following commands:\r\n\t\tS:\r\n\t\tcd \\src\\restunts\r\n\t\tsetpath\r\n\t\tmake\r\n\r\n### On Linux\r\n\t0) You might want to set `git config --worktree core.autocrlf=false` before\r\n\t   you make any change, lest git meddles with the DOS newlines\r\n\t1) Install Wine\r\n\t2) Mount the restunts dir as drive S using winecfg\r\n\t3) In the Linux console type `wineconsole cmd`\r\n\t4) In the resulting Wine console type (mind the inverted slashes and the lack of tab completion):\r\n\t```\r\n\ts:\r\n\tcd src\\restunts\r\n\tsetpath\r\n\t```\r\n\r\n### On both platforms\r\n\r\nIf everything went fine, there should be a new s:\\stunts\\restunts.exe which can\r\nbe run in DOSBox. Note that the drive letter S: is hardcoded many places in the\r\nmakefiles, and is also mounted inside DOSBox as a fixed point of reference.\r\n\r\nThe makefile supports the following targets:\r\n\r\n\tmake \u003cOPTIONS\u003e restunts\r\n\t\tThe default restunts target builds an executable based on ported C code\r\n\t\tand patched disassembly.\r\n\r\n\tmake \u003cOPTIONS\u003e restunts-original\r\n\t\tBuilds an executable based on unpatched disassembly with the original\r\n\t\tcodepaths intact. Does not use any of the ported C code.\r\n\r\n\tmake \u003cOPTIONS\u003e repldump\r\n\t\tBuilds the replay dump tool using ported C code and patched\r\n\t\tdisassembly.\r\n\r\n\tmake \u003cOPTIONS\u003e repldump-original\r\n\t\tBuilds the replay dump tool without ported C code.\r\n\r\n\r\n## Build options\r\n\r\n### Assembler selection\r\n\r\nRestunts builds per default with TASM32 for Windows, but it can be changed to using\r\nthe a 16-bit TASMX by using option `ASSEMBLER=tasmbox` before the target name (or\r\n`ASSEMBLER=tasmx` if one really likes seeing pop-up windows).\r\n\r\nE.g. to build restunts with TASMX, type\r\n\r\n\tmake ASSEMBLER=tasmbox restunts \r\n\r\nBuilding with TASMX is much slower since DOSBox is involved, but it allows to include \r\ndebugging symbols (s. below)\r\n\r\n### Linker selection\r\n\r\nRestunts links per default with TLINK using dosbox but that can changed to using\r\nthe native WLINK executable by using option `LINKER=wlink` before the target name\r\n\r\nE.g. to build Restunts with wlink, type\r\n\r\n\tmake LINKER=wlink restunts \r\n\r\nNote that `WLINK` is experimental, and it does not allow to include debug symbols. Its\r\nuse can slightly speed up the build process since it avoids calling DOSBox.\r\n\r\n### Debugging symbols\r\n\r\nThe executable can be built with debug symbols by means of the `CONFIG=debug`\r\noption. Note that this requires using TASMX as assembler and TLINK as linker\r\n(TLINK is currently the default but this might change in future)\r\n\r\nE.g. to build Restunts with debug symbols, type\r\n\r\n\tmake ASSEMBLER=tasmbox LINKER=tlink CONFIG=debug restunts \r\n\r\n\r\n## The toolchain\r\n\r\nThe toolchain has evolved over the years and it can now (2025) use either\r\nBorland tools or alternative ones. For various reasons, the build process can\r\nuses both 16 and 32-bit tools. In order to compile on modern 64 bit systems,\r\nthe 16-bit apps run via DOSBox. A couple of batch files (in\r\n`tools\\bin\\*box.bat`) take care of starting DOSBox in headless mode to prevent\r\npop-ups, and copy the output into the Windows console.\r\n\r\n### Tools used\r\nAssemblers:\r\n\t- TASMX (16-bit, from Borland Turbo Assembler 4.0)\r\n\t- TASM32 (32-bit)\r\n\r\nLinkers:\r\n\t- TLINK (16-bit)\r\n\t- WLINK (32-bit, experimental)\r\n\r\nOther:\r\n\t- Borland C++ 5.2 (Win32)\r\n\t- GNU Make 4.4.1 (Win32) - from the Chocolatey Windows Packages\r\n\r\n## Analysis in IDA and the development cycle\r\n\r\nAnalysis happens continously in IDA 6.1 (Win32). Using a custom script in IDA,\r\nthe entire disassembly is exported to compilable .asm and .inc files in\r\nsrc\\restunts\\asm. This allows using latest analysis results in the build\r\nprocess. As code is ported manually to C, the custom script is updated and kept\r\nin sync, such that it generates patched assembly code calling into the ported C\r\nfunctions.\r\n\r\nThe custom script also runs a second pass, where it exports a separate set of\r\n.asm files to src\\restunts\\asmorig. These files are unpatched and produce code\r\nthat behaves 100% identically to the original game.\r\n\r\nWhen doing analysis and (re)naming variables and functions, it is important to\r\nalways check the ported C code if there are any references to the previous\r\nsymbol names. All symbol references in the C code need to be kept in sync with\r\nthe analysis manually. Obviously, the linker will complain about missing\r\nsymbols in case a symbol was renamed in IDA, but not in the C files.\r\n\r\n\r\n## Debugging restunts.exe\r\n\r\nRestunts can be debugged with Turbo Debugger inside DOSBox. In orger to do\r\nthat, the target program must be built with debug symbols, which is possible by\r\nsetting the option `CONFIG=debug` when calling make (see paragraph “Debugging\r\nsymbols” above).\r\n\r\nThe DOSBox debugging environment is an extension of the build environment\r\ndescribed above:\r\n\r\n\t1) Double click tools\\mount_stunts_to_s.bat (only needed once per reboot)\r\n\t2) Start DOSBox and enter the following commands:\r\n\t\tmount S S:\r\n\t\tS:\r\n\t\tcd tools\r\n\t\tsetpath.bat\r\n\t\tcd \\stunts\r\n\t\ttd restunts.exe\r\n\r\nTurbo Debugger is preconfigured to automatically find and show the source code.\r\nSetting breakpoints, stepping etc works. The TD configuration file is stored in\r\nstunts\\tdconfig.td.\r\n\r\n## Notes about the toolchain\r\n\r\n### Notes regarding the linker\r\n\r\nWLINK from the Open Watcom C/C++ compiler suite was originally chosen because\r\nit supports detailed control on how to order segment classes in the final\r\nexecutable image.\r\n\r\nOur requirement is to put the original code and data first in the file, exactly\r\nas in the original game, only patching up function calls and data access.\r\nTLINK and OPTLINK were tested in the early days, but after having difficulties\r\nwith segment ordering and subsequent crashes, the project settled on WLINK.\r\n\r\nThe problems with TLINK were revisited and fixed years later, after an urgent\r\nneed to get debug information for the restunts executable. As WLINK is not able\r\nto use the debug information format created by BCC/TASM, it became necessary to\r\nreplace either of them. After the initial attempts of using TLINK were\r\nsuccessful, no further investigation were made into replacing TASM.  It should\r\nbe noted that MASM seems a promising TASM replacement candidate: the syntax is\r\nclose to TASM, and it produces CodeView debug format usable by WLINK.\r\n\r\n\r\n### Notes regarding 16-bit tasmx, tlink and DOSBox\r\n\r\nThe choice of reverting to TLINK was not easy either. Only the 16-bit version\r\nof TLINK can produce 16-bit executables such as restunts.exe, and it can only\r\nuse object files produced by the 16-bit TASM. In order to use 16-bit tools on a\r\n64-bit Windows host, they need to be emulated. And so DOSBox became\r\nincorporated in the build process. Another problem is the regular 16-bit\r\ntasm.exe exceeds the available 640k of memory when compiling the largest\r\nrestunts source files. This was overcome by using the DPMI-enabled tasmx.exe\r\ninstead.\r\n\r\n\r\n### Notes regarding the CRT (libc)\r\n\r\nWhen linking with cm.lib from Borland C++ 5.1, TLINK is not able to produce an\r\nexecutable. To get around this, the tlib tool was used to extract object files\r\nfrom cm.lib, and now restunts links with these instead.\r\n\r\nWhen the project used WLINK, it was able to link with cm.lib from Borland C++\r\n5.1, but was not able to link correctly with cm.lib from Borland C++ 3.1.\r\nBefore upgrading to Borland C++ 5.1, the makefile would link to single obj\r\nfiles from Borland 3.1's CRT.\r\n\r\nThe linker can complain about weird missing symbols f.ex at first time use of\r\nsome compiler feature or CRT function. This can be fixed by extracting the\r\nobject file from cm.lib, and adding it to the makefile.\r\n\r\ncm.lib is the medium model libc from Borland C++ 5.2. tlib.exe is a 16-bit\r\nBorland utility for manipulating lib files and has to be run via DOSBox.\r\n\r\nUsing a binary file viewer with cm.lib it's possible to locate missing CRT\r\nsymbol names and work out/guess the object file name by looking at strings in\r\nthe binary data before it.\r\n\r\nTo extract the object file\r\n\t1) Double click tools\\mount_stunts_to_s.bat (only needed once per reboot)\r\n\t2) Start DOSBox and initialize the restunts development environment:\r\n\t\tmount S S:\r\n\t\tS:\r\n\t\tcd tools\r\n\t\tsetpath.bat\r\n\t\tcd \\tools\\lib\r\n\t3) Run tlib to extract the object file, some examples:\r\n\t\ttlib cm.lib * GETVECT\r\n\t\ttlib cm.lib * LABS\r\n\t\ttlib cm.lib * STRCPY\r\n\t\ttlib cm.lib * MEMCPY\r\n\t\ttlib cm.lib * FMEMCPY\r\n\t\ttlib cm.lib * H_LDIV\r\n\t\ttlib cm.lib * F_LXMUL\r\n\t\ttlib cm.lib * F_SCOPY\r\n\t\ttlib cm.lib * H_LRSH\r\n\t\ttlib cm.lib * H_PADD\r\n\t\ttlib cm.lib * H_PINA\r\n\t\ttlib cm.lib * H_PADA\r\n\t\ttlib cm.lib * N_PCMP\r\n\t\ttlib cm.lib * F_PCMP\r\n\t\ttlib cm.lib * H_LURSH\r\n\t\ttlib cm.lib * H_PSBP\r\n\t\ttlib cm.lib * H_LLSH\r\n\t4) Add new CRT object files in dos\\makefile - at the end of the line\r\n\t   starting with CTARGETS =\r\n\r\n\r\n## Porting a function from ASM to C\r\n\r\n1. Open src\\idc\\anders.idc in a text editor and locate the PortFuncName()\r\n   function. The IDA script needs to be aware of all the functions that have\r\n   been ported in order to generate asm that does not conflict with the ported\r\n   code. Add a line in PortFuncName() for the function you've chosen.\r\n\r\n2. Run anders.idc from within IDA to regenerate the asm files (or skip step 1+2\r\n   and rename the respective extrn, public and function manually in the .inc\r\n   and asm files)\r\n\r\n3. Add a function stub to one of the existing .c files in src\\restunts\\c\r\n3.1 If you want to add a new .c-file to the project, you need to\r\n\t- add a target for it in c\\makefile\r\n\t- add a reference to the obj in RESTUNTS_OBJFILES in dos\\makefile\r\n\r\n4. Add an extrn for the c-function in asm\\custom.inc\r\n\r\n5. Start make to see if it compiles + links\r\n\r\n6. Port to c!\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4d-stunts%2Frestunts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F4d-stunts%2Frestunts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4d-stunts%2Frestunts/lists"}