{"id":51891497,"url":"https://github.com/digows/cosmo","last_synced_at":"2026-07-26T04:30:41.450Z","repository":{"id":372807688,"uuid":"1308441631","full_name":"digows/cosmo","owner":"digows","description":"Native source port of Cosmo's Cosmic Adventure: Forbidden Planet (Apogee, 1992) for macOS, Linux and Windows. Built from the original game's code, with an emulated EGA, PIT, PC speaker and AdLib — no DOSBox.","archived":false,"fork":false,"pushed_at":"2026-07-23T13:38:48.000Z","size":874,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-23T15:11:55.325Z","etag":null,"topics":["1992","adlib","apogee","c","cosmo-cosmic-adventure","dos-games","ega","game-porting","ms-dos","opl2","platformer","retrogaming","reverse-engineering","sdl3","source-port"],"latest_commit_sha":null,"homepage":"https://github.com/digows/cosmos#readme","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/digows.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-22T06:00:26.000Z","updated_at":"2026-07-23T13:39:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/digows/cosmo","commit_stats":null,"previous_names":["digows/cosmo"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/digows/cosmo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digows%2Fcosmo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digows%2Fcosmo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digows%2Fcosmo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digows%2Fcosmo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digows","download_url":"https://codeload.github.com/digows/cosmo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digows%2Fcosmo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35901460,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-26T02:00:06.503Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["1992","adlib","apogee","c","cosmo-cosmic-adventure","dos-games","ega","game-porting","ms-dos","opl2","platformer","retrogaming","reverse-engineering","sdl3","source-port"],"created_at":"2026-07-26T04:30:40.977Z","updated_at":"2026-07-26T04:30:41.445Z","avatar_url":"https://github.com/digows.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cosmo's Cosmic Adventure — native port for macOS, Linux and Windows\n\nA source port of **Cosmo's Cosmic Adventure: Forbidden Planet** (Apogee\nSoftware, 1992) that runs natively on modern machines. No DOSBox, no emulator,\nno virtual machine — the original game's own code, compiled for your computer.\n\n[![CI](https://github.com/digows/cosmo/actions/workflows/ci.yml/badge.svg)](https://github.com/digows/cosmo/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n![Platforms: macOS, Linux, Windows](https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)\n![Language: C](https://img.shields.io/badge/language-C11-orange)\n\n|  |  |\n|:-:|:-:|\n| ![Cosmo's Cosmic Adventure title screen, Forbidden Planet](docs/screenshots/title1.png) | ![The game's credits screen](docs/screenshots/credit.png) |\n| ![Cosmo running through a jungle level](docs/screenshots/gameplay-jungle.png) | ![Episode selection launcher drawn in the game's own font](docs/screenshots/launcher.png) |\n\nEvery screenshot is produced by this port, on macOS, from the original 1992 data\nfiles — not captured from an emulator.\n\n## Download and play\n\n**[Get the latest release](https://github.com/digows/cosmo/releases/latest)** —\nmacOS, Windows and Linux. Each download includes the shareware Episode 1 and\nplays as soon as it is unpacked; nothing to install. If you own Episodes 2 and\n3, the launcher will ask you to point it at your copy.\n\nmacOS refuses to open this the first time, because it is not signed by a paid\nApple developer account. To allow it, open **System Settings → Privacy \u0026\nSecurity**, scroll to Security, and click **Open Anyway** next to the message\nabout Cosmo. On macOS 15 and later that panel is the only route — right-clicking\nand choosing Open no longer works. From a terminal,\n`xattr -dr com.apple.quarantine /path/to/Cosmo.app` does the same in one step.\n\n## What this is\n\nThe starting point is the game's own code rather than a reimplementation. This\nproject builds on [Cosmore](https://github.com/smitelli/cosmore), Scott\nSmitelli's reconstruction of the v1.20 source recovered by disassembling the\n1992 executables and accurate to 96.3% of their bytes, and replaces only the\nlayer that talked to PC hardware.\n\nEverything above that layer is the game as Todd Replogle wrote it: the physics,\nthe actors, the collision handling, the bugs. What was written from scratch is\nthe machine underneath — an emulated EGA adapter, the programmable interval\ntimer, the keyboard controller, the PC speaker, and an AdLib.\n\nIf you want the story of what broke along the way, that is in\n**[docs/porting-notes.md](docs/porting-notes.md)**.\n\n## Status\n\n| Subsystem | State |\n|---|---|\n| All three episodes, behind an in-game-style launcher | ✅ |\n| Application bundle with an icon, and downloads that just run | ✅ |\n| Emulated EGA — write modes, latches, bit mask, map mask, set/reset | ✅ unit tested |\n| Planar decode, palette, SDL3 presentation | ✅ unit tested |\n| Interrupt and timing layer — int 8 / int 9, PIT, PIC | ✅ 140 Hz, measured |\n| Map loading, scrolling, actors, the attract-mode demo | ✅ |\n| Keyboard, including jump while moving | ✅ verified by script |\n| Saving and restoring a game | ✅ |\n| PC speaker sound effects | ✅ verified against the game's own sound data |\n| AdLib (OPL2) music, via [ymfm](https://github.com/aaronsgiles/ymfm) | ✅ |\n| macOS, Linux and Windows builds | ✅ green in CI |\n| Joystick | ⬜ not implemented |\n| Frame-by-frame comparison against DOSBox | ⬜ the largest remaining gap |\n\nThe game runs end to end: `cosmo` starts the original `InnerMain()` on its own\nthread, the main thread plays the part of the PC hardware, and it goes through\nits title screen, credits and playable attract-mode demo at the 10.8 frames per\nsecond the original was paced for.\n\n## Building\n\nRequires CMake 3.21+, a C11 and C++17 compiler, and SDL3. If SDL3 is not\ninstalled, CMake downloads and builds it. The only C++ in the project is the\nwrapper around ymfm, which synthesises the AdLib's YM3812.\n\n```bash\ngit clone --recurse-submodules https://github.com/digows/cosmo.git\ncd cosmo\ncmake --preset default\ncmake --build --preset default\nctest --preset default\n```\n\n**macOS** — `brew install cmake sdl3`. This is where the port is developed and\nplayed.\n\n**Linux** — SDL3 from your distribution, or let CMake fetch it. The build\ndependencies are listed in [the CI workflow](.github/workflows/ci.yml).\n\n**Windows** — MinGW, either natively through MSYS2 or cross-compiled with\n[the toolchain file](cmake/toolchain-mingw64.cmake). MSVC is not yet exercised.\n\nA universal macOS binary, which builds SDL from source for both slices since the\nHomebrew package is single-architecture:\n\n```bash\ncmake --preset macos-universal \u0026\u0026 cmake --build --preset macos-universal\n```\n\n`-DCOSMO_BUNDLE=ON` builds what the releases ship rather than a terminal\nprogram: `Cosmo.app` with an icon on macOS, and on Windows an icon, no console\nwindow, and the MinGW runtime linked in rather than left to three DLLs that\nhave to travel alongside.\n\n### Checking other platforms without spending CI\n\nTwo container recipes reproduce the Linux and Windows jobs on any machine with\nDocker, which is faster and cheaper than finding out from a red pipeline:\n\n```bash\ndocker build -f tools/checks/linux.Dockerfile .\ndocker build -f tools/checks/windows-mingw.Dockerfile .\n```\n\nThe first uses the same distribution and package list as the CI job. The second\ncross-compiles with MinGW-w64, the same compiler family the Windows job uses.\nBoth have caught real defects before they reached a runner.\n\n## Game data\n\nThe assets belong to Apogee Software and are **not** in this repository. The\nrelease downloads include Episode 1, which Apogee distributed freely; a build\nfrom source needs it putting in place.\n\n`COSMO1.STN` and `COSMO1.VOL` are looked for beside the program, inside the\napplication bundle on macOS, and in the directory the game was started from, in\nthat order. Whichever is found first is used, and if it can be written to the\nsaves go there too — so an unpacked folder carries its own. See\n[gamedata/README.md](gamedata/README.md) for where to get the data, with\nchecksums.\n\nIf a `COSMOn.CFG` is already present it wins over this port's defaults,\nincluding the jump key — the original distributions shipped one with ctrl.\nDelete it to get the defaults, or rebind in game.\n\n## Running\n\n```bash\n./build/default/cosmo\n```\n\nLeave it alone for a minute and it plays its attract-mode demo.\n\n`cosmo` is a launcher: it lists the episodes, marks the ones whose data is\nmissing, and offers a file picker for those — and it does the listing in the\ngame's own font on the game's own title art, drawn through the same emulated\nEGA. Name an episode to skip the menu:\n\n```bash\n./build/default/cosmo 2\n```\n\nThe three episodes are separate programs — `cosmo1`, `cosmo2`, `cosmo3` — which\nis not a packaging choice. They differ by preprocessor conditionals that include\nor exclude whole actor implementations, so they compile to genuinely different\ncode. Apogee shipped three executables for the same reason.\n\n`imgview` is a harness for the video layer alone, useful for inspecting the\nfullscreen images without starting the game:\n\n```bash\n./build/default/imgview                                  # browse them\n./build/default/imgview gamedata TITLE1.MNI shot.png 2   # headless screenshot\n```\n\n## Controls\n\nArrow keys move, **Space** jumps, **Alt** throws a bomb.\n\nThe original shipped ctrl for jump, which was ordinary in 1992; space has been\nthe platformer convention for a long time since, and it is the binding no window\nmanager fights over. That is the one deliberate change this port makes to the\ngame's behaviour — see [patches/0007](patches/). Bomb is unchanged.\n\nAll six can be rebound from the game's own menu: **G** for Game Redefine at the\nmain menu, then **K** for Keyboard redefine. The choice is written to\n`COSMOn.CFG` alongside the sound settings and high scores, so it survives\nbetween runs — but only on a clean exit. Quit through the game (**Q**, then\n**Y**) rather than closing the window, exactly as on DOS, where killing the\nprogram lost the file the same way.\n\nOn macOS, Command reports as Control. That matters if you rebind jump back to\nctrl: macOS binds Control with every arrow key to Mission Control, so ctrl and a\ndirection never reaches the application at all. Command is not claimed, and\nfills that gap.\n\n## How it works\n\nThe main thread plays the part of the PC hardware and a second thread plays the\npart of the CPU. Cosmo's main loop never yields: it busy-waits on a counter its\nown timer interrupt increments, and reads keyboard state its own keyboard\ninterrupt fills in. On real hardware those handlers fired underneath the running\nprogram, so here the main thread fires them at whatever rate the game programmed\ninto the PIT — 140 Hz, or 560 with music — while the game runs alongside.\n\nThe original programs the EGA through I/O ports and writes into video memory at\nsegment 0xA000. Rather than rewriting the drawing code, this port emulates the\nadapter: four 64 KiB planes in ordinary memory, with the write modes, latches,\nbit mask and set/reset logic the game depends on.\n\nThat fidelity matters. `DrawSolidTile` blits scenery from video memory to video\nmemory using `*dst = *src` under write mode 1, where the CPU data is discarded\nand what reaches the screen is the latch content the read loaded. An EGA that\nlooks correct but skips the latches renders garbage.\n\nAssembly is avoided entirely. Upstream publishes a pure C implementation of\nevery drawing routine in `C-DRAWING.md`, written as a curiosity because it is\ntoo slow for a 286. On a modern CPU that cost is irrelevant, and using it removes\nthe dependency on Turbo Assembler, which Borland never released for free.\n\n## Debugging and automated checks\n\n`COSMO_SCRIPT` points at a file of timed key events, which drives the game\nwithout anyone at the keyboard. Each line is\n`\u003cmilliseconds\u003e \u003cdown|up|tap\u003e \u003ckey\u003e`; see [tests/scripts](tests/scripts/).\n\n| Variable | Effect |\n|---|---|\n| `COSMO_DEBUG=1` | Timer rate, interrupt delivery, and the game's own key and command state, once a second |\n| `COSMO_SHOT_PATH=p COSMO_SHOT_MS=500,3000` | Screenshots at fixed moments after startup. `F12` takes one at any time |\n| `COSMO_AUDIO_WAV=out.wav` | Records everything the sound hardware produces. The header stays valid even if the game is killed rather than quit |\n| `COSMO_OPL_LOG=1` | Traces every write to the AdLib's registers |\n| `COSMO_SCRIPT=file` | Replays timed key events |\n\nBetween them these are how the sound effects were checked against the game's own\ndata, and how a keyboard bug was traced to the window system rather than to the\nemulation.\n\n## Layout\n\n```\nvendor/cosmore/    upstream submodule, pinned and never modified\nvendor/ymfm/       YM3812 synthesiser, pinned and never modified\ncmake/             source preparation, run at configure time\npatches/           changes to upstream, one numbered patch each\ninclude/cosmo/     platform layer headers\nsrc/platform/      emulated EGA, video, audio, DOS runtime, hardware\nsrc/launcher.c     episode picker, drawn in the game's own font\ntools/             validation harnesses and container checks\ntests/             unit tests and input scripts\ndocs/              porting notes and screenshots\n```\n\nSource preparation applies three mechanical transformations to upstream: it\ndrops the `#include` lines for Borland headers with no modern equivalent,\ncomments out the 16-bit inline assembly, and pins the base types to their\noriginal widths — `unsigned int` was 16 bits on DOS and the game leans on the\nwraparound. Anything those cannot express is a numbered patch under\n[`patches/`](patches/), each explaining the defect and why the change is correct.\n\nIt all runs in CMake rather than a shell script, so it behaves the same on every\nplatform, and each patch is fingerprinted before and after: a patch that reports\nsuccess while changing nothing fails the configure step rather than silently\ndoing nothing. That is not hypothetical — it happened, and\n[the notes](docs/porting-notes.md) describe it.\n\n## License and attribution\n\nCode in this repository: MIT, see [LICENSE](LICENSE).\n\n*Cosmo's Cosmic Adventure*, its assets and trademarks are © 1992 Apogee\nSoftware, Ltd. and are not redistributed here. Cosmore is MIT, © Scott Smitelli\nand contributors; ymfm is BSD 3-Clause, © Aaron Giles. Full credits, including\nthe game's original authors, are in [ATTRIBUTION.md](ATTRIBUTION.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigows%2Fcosmo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigows%2Fcosmo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigows%2Fcosmo/lists"}