{"id":17071262,"url":"https://github.com/s-macke/starflight-reverse","last_synced_at":"2026-03-09T12:03:57.860Z","repository":{"id":26938898,"uuid":"58882099","full_name":"s-macke/starflight-reverse","owner":"s-macke","description":"Reversed engineered game Starflight (1986)","archived":false,"fork":false,"pushed_at":"2023-09-20T12:15:52.000Z","size":56760,"stargazers_count":138,"open_issues_count":2,"forks_count":13,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-04-12T19:52:54.151Z","etag":null,"topics":["forth","game","game-starflight","reverse-engineering"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"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/s-macke.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}},"created_at":"2016-05-15T20:11:12.000Z","updated_at":"2025-04-07T04:07:49.000Z","dependencies_parsed_at":"2023-01-14T08:45:15.641Z","dependency_job_id":null,"html_url":"https://github.com/s-macke/starflight-reverse","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s-macke%2Fstarflight-reverse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s-macke%2Fstarflight-reverse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s-macke%2Fstarflight-reverse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s-macke%2Fstarflight-reverse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/s-macke","download_url":"https://codeload.github.com/s-macke/starflight-reverse/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248625509,"owners_count":21135513,"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":["forth","game","game-starflight","reverse-engineering"],"created_at":"2024-10-14T11:35:42.654Z","updated_at":"2026-03-09T12:03:57.845Z","avatar_url":"https://github.com/s-macke.png","language":"C","funding_links":[],"categories":["Games"],"sub_categories":[],"readme":"# Starflight-Reverse #\n\n## What is Starflight? ##\n\n![Starflight 1 for the PC](images/starflight-game.gif)\n\nBack in the 80ths, an unknown company called Binary Systems published the game Starflight. The game puts the player in the role of a starship captain sent to explore the galaxy. There is no set path, allowing players to switch freely between mining, ship-to-ship combat, and alien diplomacy. The broader plot of the game emerges slowly, as the player discovers that an ancient race of beings is causing stars to flare and destroy all living creatures.\nThe game has been widely praised by both contemporary and modern critics, and is one of the earliest instances of a sandbox game. The game influenced the design of numerous other games for decades after its release. \n\nTo find out more about the game check the following links:\n\n * [Wikipedia](https://de.wikipedia.org/wiki/Starflight)\n * [The Digital Antiquarian](https://www.filfre.net/2014/10/starflight/)\n * [Starflight Resource Pages](http://starflt.com)\n * [Technical Articles Saved from Oblivion](https://github.com/s-macke/starflight-reverse/tree/master/webarchive)\n * [Review of Starflight 1](http://crpgaddict.blogspot.de/search/label/Starflight)\n * [Review of Starflight 2](http://crpgaddict.blogspot.de/search/label/Starflight%20II)\n * Other fan sites or projects [1](http://bravearmy.com/starflight/) [2](http://otherelectricities.com/neckdeep/starflight.html) [3](https://www.dosgameclub.com/starflight/) [4](http://blakessanctum.x10.mx/Games/Starflight/) [5](https://www.starflight3.com/)\n\nYou can buy the game at [GoG](https://www.gog.com/game/starflight_1_2)\n\n## What is this project about? ##\n\nThe first time I heard about the game I wanted to play it. However, I was too young and could not speak English. 20 later I tried again and it was a very pleasant experience. The exploration is fun, the storyline is epic and ends with a surprise, that is one of the best I have experienced. Sure, the game hasn't aged well, but you can feel the devotion of the developers to the game. There’s an art aspect to this game as well as a craftman’s attention to detail.\n\nAs much as playing this truly amazing game is fun, so is reverse engineering this game. You follow in the footsteps of the developers and experience their thought processes as if it were the year 1985 again.\nFor this game expect the unexpected. Normally when you reverse engineer such an old game you have to receive ten thousands of lines of pure assembler code, which you can analyze with the usual tools such as IDA Pro. But not this time. Actually for this game you can throw the usual tools away. They are useless. You are on your own. The reason is that Starflight was written in [Forth](https://en.wikipedia.org/wiki/Forth_(programming_language)), a language I barely knew about.\n\n## Forth ##\n\nForth is the language with the ultimate minimalism regarding syntax. There is no more syntax than the space between \"words\". You can write a Forth reader and interpreter basically in a few lines of code.\n\nIn a modern language you write something like\n\n```PYTHON\nprint(2+3)\n```\nto print the result of 2+3. In Forth however it looks like this.\n\n```FORTH\n2 3 + .\n```\nForth is a stack machine, with a [reverse Polish notation](https://en.wikipedia.org/wiki/Reverse_Polish_notation). The interpretation is as follows\n\n* push 2 on top of the stack\n* push 3 on top of the stack\n* pop the last two stack entries and add them together. Push the result back on top of the stack. \n* pop the top value from the stack and print it\n\nThe syntax is simple and the interpreter is simple. \"2\", \"3\", \"+\" and \".\" are just called \"words\". There is no syntactic distinction between data and code. Certainly a language that lived up to the limitations of the early home computers.\n\n## Disassembly description ##\n\nWhen you dissect the executable STARFLT.COM it reveals some fantastic internals\n * The compiled code retains the structure of the Forth source code. No optimization by the compiler. A word in the source code are two bytes in the compiled code.\n * The x86-assembly code consumes less than 5% of the size of the exectuable\n * More than 90% of the executable are actually 16-Bit pointers.\n * 2000 of around 6000 word names, which you would call debugging symbols nowadays, are still in the code, but encrypted. This enables us to reverse engineer a high portion of the original source code.\n * The Forth interpreter (not compiler) is still part of the executable and can be enabled\n * The executable is slow. Besides of some assembler optimized routines, the code wastes at least 50% of the CPU cycles just by jumping around in the code.\n * The executable makes heavily use of code overlays, which makes the decoding much more complicated\n\n## The main building block ##\n\nAs explained above Forth is a stack machine. As coding mechanic it uses [indirect threading](https://en.wikipedia.org/wiki/Threaded_code#Indirect_threading), a very space efficient method to store your compiled code. Threaded code has a form that essentially consists entirely of calls to subroutines. Indirect threading uses pointers to locations that in turn point to machine code.\n\nLet's say your instruction pointer points to the address 0x1000 and contains the 16-Bit value Read16(0x1000)=0x0f72.\n\n```Asm\n0x1000: dw 0x0f72\n```\n\nThe value 0x0f72 is the coded equivalent of the Forth word '+'. Remember the description above. The word '+' pops the last two stack entries, adds them together and pushes the result back on top of the stack. According to indirect threading this 16-Bit value 0x0f72 is a pointer to a location that in turn points to machine code. When you read the memory content Read16(0x0f72) you get the pointer to 0x0f74. And indeed, when you look at this memory location and disassemble it, you receive the following\n\n```Asm\n0x0f72: dw 0x0f74\n0x0f74: pop ax\n0x0f75: pop bx\n0x0f76: add ax, bx\n0x0f78: push ax\n0x0f79: lodsw\n0x0f7a: mov bx, ax\n0x0f7c: jmp word ptr [bx]\n```\n\nThe first four instructions perform exactly the operations that the word \"+\" should perform. The last three assembler instructions starting from the \"lodsw\" increase the instruction pointer and jump to the next code. \n\nLet us go on. Now the instruction pointer points to 0x1002\n\n```Asm\n0x1002: dw 0x53a3\n```\n\nReading the address 0x53a3 reveals\n\n```Asm\n0x53a3: dw 0x1d29\n0x53a5: dw 0x0001\n```\nand the corresponding code\n\n```Asm\n0x1d29: inc bx\n0x1d2a: inc bx\n0x1d2b: push bx\n0x1d2c: lodsw\n0x1d2d: mov bx,ax\n0x1d2f: jmp word ptr [bx]\n```\n\nAt this time the register bx contains the word address 0x53a3. So this code just pushes the address 0x53a5 on top of the stack. What we have done is to provide the program a pointer to a variable. The variable has the content 0x0001. The Forth word '@' would pop the address from the stack, reads its content and pushes it back on the stack.\n\nSo far I could identify 6256 words that contain either code or data.\n\n* 3711 are words, which execute other words. I guess you can call them functions.\n* 906 16-Bit variables or data arrays. In very rare cases (~20) the data array contains x86 machine code\n* 356 data structures which define content of the tables stored on disk (see below)\n* 346 data structures which define content of the instance tree data structure (see below)\n* 278 words contain x86 machine code\n* 235 16-Bit constants\n* 127 switch-case expressions\n* 105 words contain data structures to define the code overlays\n* the other words are of different type\n\nAnd that's actually all you need to know about the code structure.\nAs you can see this can be a space efficient encoding, but speedwise it is a catastrophe. Every few machine code instructions you have to jump to a different code block.\n\nThe equivalent of indirect threading in C would look like this.\n\n```C\nuint16_t instruction_pointer = start_of_program_pointer;\n \nvoid Call(uint16_t word_adress)\n{\n // the first two byte of the word's address contain \n // the address of the corresponding code, which must be executed for this word\n uint16_t code_address = Read16(word_address);\n\n switch(code_address)\n {\n .\n .\n .\n case 0x0f74: // word '+'\n Push16(Pop16() + Pop16());\n break;\n .\n .\n .\n }\n}\n\nvoid Run()\n{\n while(1)\n {\n uint16_t word_address = Read16(instruction_pointer);\n instruction_pointer += 2;\n Call(word_address);\n }\n}\n\n```\n\nThe code executed for a specific word has access to 5 major variables (16-Bit)\n\n * instruction pointer (register si): This points inside of a more complex function (\"word\") in Forth. It points to the address of the Forth \"word\" in memory which must be executed next. The instruction pointer can be altered by the word's code for branch and loop control.\n * stack pointer (register sp): This is a stack machine and therefore needs a stack pointer. Push will put an item on the stack. Pop retrieves an item from the top of the stack.\n * call stack pointer (register bp): contains the return addresses of the functions. Also used to temporarily store items.\n * word address (register bx): The first 2 byte contain the address to the x86 machine code of this word. Afterwards, there can be optional data such as constants, variables and arrays. In the above example for '+' it contains the machine code itself.\n * code address (register ip): The x86-machine code which must be executed\n\n## Translation ##\n\nThe disassember transpiles the FORTH code into C-style code.. Most of the transpiled code compiles. To understand what the program does take a look at the following table. It takes the \"bytecode\" (which are mainly 16-Bit pointers) as input and transforms it into C.\n\nForth code:\n```FORTH\n: .C ( -- )\n\\ Display context stack contents.\n CR CDEPTH IF CXSP @ 3 + END-CX\n DO I 1.5@ .DRJ -3 +LOOP\n ELSE .\" MT STK\"\n THEN CR ;\n EXIT\n```\n\nTransformation:\n\n| 16-Bit Pointers | FORTH | C |\n|-----------------|-------------|-------------------------------------------------------------------------|\n| | : .C ( -- ) | `void DrawC() { ` |\n| | | ` unsigned short int i, imax; ` |\n| 0x0642 | CR | ` Exec(\"CR\"); ` |\n| 0x75d5 | CDEPTH | ` CDEPTH(); ` |\n| 0x15fa 0x0020 | IF | ` if (Pop() != 0) { ` |\n| 0x54ae | CXSP | ` Push(Read16(pp_CXSP) + 3);` |\n| 0xbae | @ | |\n| 0x3b73 | 3 | |\n| 0x0f72 | + | |\n| 0x4ffd | END-CX | ` Push(Read16(cc_END_dash_CX));` |\n| 0x15b8 | DO | ` i = Pop();` |\n| | | ` imax = Pop();` |\n| | | ` do {` |\n| 0x50e0 | I | ` Push(i);` |\n| 0x4995 | 1.5@ | ` _1_dot_5_at_();` |\n| 0x81d5 | .DRJ | ` DrawDRJ();` |\n| 0x175d 0xfffd | -3 | ` Push(-3);` |\n| 0x155c 0xffff | +LOOP | ` int step = Pop();` |\n| | | ` i += step;` |\n| | | ` if (((step\u003e=0) \u0026\u0026 (i\u003e=imax)) \\|\\| ((step\u003c0) \u0026\u0026 (i\u003c=imax))) break;` |\n| | | ` } while(1);` |\n| 0x1660 0x000b | ELSE | ` } else {` |\n| 0x1bdc | \" MT STK\" | ` PRINT(\"MT STK\", 6);` |\n| 0x06 | | |\n| 0x4d | 'M' | |\n| 0x54 | 'T' | |\n| 0x20 | ' ' | |\n| 0x53 | 'S' | |\n| 0x54 | 'T' | |\n| 0x4b | 'K' | |\n| | THEN | ` }` |\n| 0x0642 | CR | ` Exec(\"CR\");` |\n| 0x1690 | EXIT | `}` |\n\n## Files ##\n\nThe game comes in 3 Files\n* STARA.COM and STARB.COM: Both contain the game data and the game executable stored in a its own directory structure.\n* STARFLT.COM: This file is a DOS executable and contains the initialitzation routines, general Forth routines and routines to read and write of the on-disk data structures in STARA.COM and STARB.COM. \n\n## Directory in STARA.COM and STARB.COM\n\nContent of STARA.com\n\n| entry | size | description |\n|-----------|--------|-------------------------------------------------|\n| DIRECTORY | 4096 | contains directory of STARA and STARB |\n| ELO-CPIC | 4816 | |\n| GAZ-CPIC | 3120 | |\n| MEC-CPIC | 2848 | |\n| MYS-CPIC | 6064 | |\n| NOM-CPIC | 1136 | |\n| SPE-CPIC | 1888 | |\n| THR-CPIC | 2480 | |\n| VEL-CPIC | 4672 | |\n| VPR-CPIC | 1248 | |\n| MIN-CPIC | 2096 | |\n| SPLASH | 16384 | Picture |\n| MED-PIC | 2048 | Picture |\n| PHAZES | 6144 | |\n| HUM-PIC | 480 | Picture |\n| VEL-PIC | 432 | Picture |\n| THR-PIC | 272 | Picture |\n| ELO-PIC | 608 | Picture |\n| AND-PIC | 640 | Picture |\n| SAVE | 124000 | |\n| MUSIC | 4960 | Code Overlay |\n| EARTH | 1152 | Map of the planet earth |\n| GALAXY | 6304 | |\n| CREDITS | 16384 | picture |\n| COP-CPIC | 2928 | |\n| FONTS | 768 | |\n| CGA | 3600 | Machine Code routines for the CGA graphics card |\n| EGA | 3600 | Machine Code routines for the EGA graphics card |\n\nContent of STARB.COM\n\n| entry | size | description |\n|--------------|--------|-----------------------------------------------------|\n| DIRECTORY | 4096 | contains directory of STARA and STARB |\n| INSTANCE | 150528 | Tree structure with most of the content of the game |\n| BOX | 1024 | Table |\n| BANK-TRANS | 144 | Table |\n| CREWMEMBER | 128 | Table |\n| VESSEL | 1936 | Table |\n| ELEMENT | 544 | Table |\n| ARTIFACT | 1584 | Table |\n| PLANET | 1360 | Table |\n| SPECIMEN | 448 | Table |\n| BIO-DATA | 448 | Table |\n| TPORT-PIC | 2416 | Picture |\n| BPORT-PIC | 3984 | Picture |\n| ANALYZE-TEXT | 3200 | Table |\n| BUTTONS | 944 | Table |\n| ICON1:1 | 912 | |\n| ICON1:2 | 912 | |\n| ICON1:4 | 912 | |\n| ICON-NAME | 736 | |\n| DPART-OV | 1552 | Code Overlay |\n| REGIONS | 176 | Table |\n| CREATURE | 17024 | Table |\n| CHKFLIGHT-OV | 960 | Code Overlay |\n| FRACT-OV | 4640 | Code Overlay |\n| ICONP-OV | 832 | Code Overlay |\n| SITE-OV | 1888 | Code Overlay |\n| HYPERMSG-OV | 4112 | Code Overlay |\n| GPOLY | 368 | |\n| FACET | 288 | |\n| VERTEX | 416 | |\n| BLT-OV | 864 | Code Overlay |\n| MISC-OV | 1440 | Code Overlay |\n| BANK-OV | 1520 | Code Overlay |\n| ASSCREW-OV | 2800 | Code Overlay |\n| PERSONNEL-OV | 4192 | Code Overlay |\n| SHIPGRPH-OV | 2112 | Code Overlay |\n| CONFIG-OV | 3072 | Code Overlay |\n| TDEPOT-OV | 4800 | Code Overlay |\n| PORTMENU-OV | 3120 | Code Overlay |\n| VITA-OV | 3552 | Code Overlay |\n| HP-OV | 4832 | Code Overlay |\n| LP-OV | 5280 | Code Overlay |\n| SENT-OV | 4784 | Code Overlay |\n| TV-OV | 3472 | Code Overlay |\n| COMM-OV | 7232 | Code Overlay |\n| COMMSPEC-OV | 2864 | Code Overlay |\n| SEED-OV | 2400 | Code Overlay |\n| LISTICONS | 720 | Code Overlay |\n| MOVE-OV | 3808 | Code Overlay |\n| ENGINEER | 2320 | Code Overlay |\n| DOCTOR | 1280 | Code Overlay |\n| ORBIT-OV | 6640 | Code Overlay |\n| CAPTAIN | 5952 | Code Overlay |\n| SCIENCE | 3952 | Code Overlay |\n| NAVIGATR | 880 | Code Overlay |\n| SHIPBUTTONS | 1984 | |\n| MAP-OV | 4160 | Code Overlay |\n| HYPER-OV | 7168 | Code Overlay |\n| ANALYZE-OV | 2560 | Code Overlay |\n| LAUNCH-OV | 1360 | Code Overlay |\n| FLUX-EFFECT | 464 | |\n| OP-OV | 4400 | Code Overlay |\n| ITEMS-OV | 6016 | Code Overlay |\n| LSYSICON | 752 | |\n| MSYSICON | 448 | |\n| SSYSICON | 176 | |\n| BEHAV-OV | 5360 | |\n| CMAP | 1008 | |\n| INSTALL | 800 | |\n| HEAL-OV | 1232 | Code Overlay |\n| REPAIR-OV | 1696 | Code Overlay |\n| GAME-OV | 5920 | Code Overlay |\n| PLSET-OV | 2400 | Code Overlay |\n| MAPS-OV | 2240 | Code Overlay |\n| VES-BLT | 4528 | |\n| STORM-OV | 1232 | Code Overlay |\n| COMPOUNDS | 176 | Table |\n| IT-OV | 1936 | Code Overlay |\n| COMBAT-OV | 6192 | Code Overlay |\n| DAMAGE-OV | 2752 | Code Overlay |\n| LAND-OV | 1088 | Code Overlay |\n| PSTATS | 64 | Table |\n| STP-OV | 1440 | Code Overlay |\n\n\n## Usage ##\n\nPut the files of the original Starflight game into the folders `starflt1-in` and `starflt2-in` and run `make`. You should get two executables (`disasOV1` and `disasOV2`), which produces the content in the folders `starflt1-out` and `starflt2-out`. The generated output is part of this repository.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs-macke%2Fstarflight-reverse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fs-macke%2Fstarflight-reverse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs-macke%2Fstarflight-reverse/lists"}