{"id":16564163,"url":"https://github.com/laanwj/sundog","last_synced_at":"2025-04-10T03:52:24.388Z","repository":{"id":136252642,"uuid":"80211124","full_name":"laanwj/sundog","owner":"laanwj","description":"A port of the Atari ST game SunDog: Frozen Legacy (1984) by FTL software ","archived":false,"fork":false,"pushed_at":"2024-09-23T14:34:36.000Z","size":2724,"stargazers_count":81,"open_issues_count":7,"forks_count":14,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-04-10T03:52:01.540Z","etag":null,"topics":["atari-st","game","port","sdl2"],"latest_commit_sha":null,"homepage":"","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/laanwj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","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}},"created_at":"2017-01-27T13:50:17.000Z","updated_at":"2025-03-27T21:37:03.000Z","dependencies_parsed_at":"2023-12-26T20:29:01.392Z","dependency_job_id":"389f75e7-d705-405f-98ac-1cf44fcc2783","html_url":"https://github.com/laanwj/sundog","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laanwj%2Fsundog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laanwj%2Fsundog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laanwj%2Fsundog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laanwj%2Fsundog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/laanwj","download_url":"https://codeload.github.com/laanwj/sundog/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248154998,"owners_count":21056542,"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":["atari-st","game","port","sdl2"],"created_at":"2024-10-11T20:43:35.504Z","updated_at":"2025-04-10T03:52:24.357Z","avatar_url":"https://github.com/laanwj.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"![CI status](https://github.com/laanwj/sundog/actions/workflows/ci_meson.yml/badge.svg?branch=main)\n\nSundog: Frozen Legacy\n========================\n\n\u003cimg alt=\"Sundog box logo\" src=\"screenshots/sundog_logo.jpg\"\u003e\n\nThis is a port of the Atari ST game SunDog: Frozen Legacy (1985) by\nFTL software to modern platforms, using SDL2 for input and OpenGL ES 2+ for\ngraphics. A good overview of the gameplay can be found on [wikipedia](https://en.wikipedia.org/wiki/SunDog:_Frozen_Legacy).\n\nThe game was originally written in Pascal, developed using the well-known UCSD\nPascal compiler. This compiler compiles to bytecode called \"p-code\" for an\nabstract architecture called the p-system. This project implements a p-system\ninterpreter (also called \"P-Machine Emulator\" or PME) in C, which is able to\nrun the game.\n\nThis makes it possible to run the game without emulating the Atari ST or even\n68000 processor. There are a few assembly-language functions for (primarily)\ngraphics rendering, which have been re-implemented separately.\n\nThe goal of this port is to keep the gameplay and graphics close to the Atari\nST version, although small hacks or improvements would be welcome. See the\n[Sundog Resurrection](http://sundogresurrectionproject.com) project for a complete re-imagining of the game.\n\nScreenshots\n-------------\n\n\u003cimg alt=\"Title screen\" src=\"screenshots/title_screen.png\" width=\"40%\"\u003e \u003cimg alt=\"Planet surface\" src=\"screenshots/surface.png\" width=\"40%\"\u003e\n\u003cimg alt=\"Drahew city\" src=\"screenshots/city.png\" width=\"40%\"\u003e \u003cimg alt=\"Drahew exchange\" src=\"screenshots/drahew_ech.png\" width=\"40%\"\u003e\n\u003cimg alt=\"Ship interior\" src=\"screenshots/moveonship.png\" width=\"40%\"\u003e \u003cimg alt=\"Inside pod\" src=\"screenshots/pod.png\" width=\"40%\"\u003e\n\u003cimg alt=\"Pilotage\" src=\"screenshots/ship_cockpit.png\" width=\"40%\"\u003e \u003cimg alt=\"Ship maintenance\" src=\"screenshots/ship_parts.png\" width=\"40%\"\u003e\n\u003cimg alt=\"Space fight\" src=\"screenshots/ship_fight.png\" width=\"40%\"\u003e\n\nDisk image\n-------------\n\nFor copyright reasons this game does not come with the resources nor game code.\nIt requires the user to provide a 360K `.st` raw disk image of the game to run.\nThis can be imaged from an original copy or found on a dozen abandonware sites.\nBe sure to use an image of the original disk: the re-packed version will not\nwork as the layout of the disk will be different.\n\nUnlike the original game which writes to disk on every start, this\nimplementation never writes to the disk image.\n\nBuilding from source\n----------------------\n\n### Linux\n\nTo build from source make sure the SDL2 development package for your\ndistribution is installed, as well as GNU readline (only necessary for the\ndebugger). On Debian and Ubuntu this is:\n\n```bash\napt-get install libreadline-dev libsdl2-dev meson ninja-build\n```\n\nThen:\n\n```bash\nmeson setup --buildtype release build\nninja -C build\n```\n\n### Mac OS X\n\n1. Install build- and run-time dependencies:\n   ```\n   brew install mesa meson ninja sdl2\n   brew install --cask chromium\n   ```\n2. Clone this repository\n3. Create a `game` subdirectory below the repository, and install [your copy](https://github.com/laanwj/sundog/issues/2#issuecomment-478829859) of the game as `game/sundog.st`\n4. Build from source:\n   ```\n   meson setup --buildtype release build -Dbuiltin_image=true\n   ninja -C build\n   ```\n5. Install the built binary somewhere *not* in the `PATH` (see below), e.g.\n   ```\n   mkdir /usr/local/lib/sundog\n   cp build/src/sundog /usr/local/lib/sundog/\n   ```\n6. Create a shell script `/usr/local/bin/sundog` that reads\n   ```\n   export SDL_VIDEO_EGL_DRIVER=\"/Applications/Chromium.app/Contents/Frameworks/Chromium Framework.framework/Versions/Current/Libraries/libEGL.dylib\"\n   exec /usr/local/lib/sundog/sundog \"$@\"\n   ```\n7. Run Chromium by hand once, so as to validate the “unknown developer” warning — If you don't, the next step will complain (because the copies of `libEGL.dylib` and `libGLESv2.dylib` that `sundog` attempts to dynamically load, must be whitelisted by the OS before running)\n8. Run `sundog` from the command line.\n\n### Build settings\n\nThe following settings can be set with `-Doption=value` on the meson command line, or through `meson configure`:\n```\n  Project options                                Default Value                                    Possible Values                                  Description\n  -----------------                              -------------                                    ---------------                                  -----------\n  builtin_image                                  false                                            [true, false]                                    Use built-in disk image (must be in game/sundog.st)\n  debug_ui                                       false                                            [true, false]                                    Enable debug user interface\n  game_cheats                                    false                                            [true, false]                                    Enable cheats\n  psys_debugger                                  false                                            [true, false]                                    Enable P-system command line debugger\n```\n\n### Other platforms\n\nPeople have built this software for other platforms. It should be pretty\nstraightforward, as we've tried hard to make the source and build system as\ncompatible as possible. Also, SDL2 and support for OpenGL ES 2.0+ (especially\nwhen coupled with [ANGLE](https://github.com/google/angle)) is widely\navailable.\n\nThe CI checks run on Linux (gcc), MacOS (clang) and Windows (MSVC). However, no\ninstructions have been contributed for manual builds on these platforms.\n\nInvocation\n------------\n\nThe game can be started using the command line:\n\n```\nbuild/src/sundog[.exe] [\u003cimage.st\u003e]\n```\n\nWhere `\u003cimage.st\u003e` is the Sundog disk image to use. If none is provided, it\nwill look for `sundog.st` in the same directory as the program. If it isn't\nfound there, the game will fail to start.\n\nOther options can be provided:\n\n- `--fullscreen`: Make window initially fullscreen.\n- `--right-click-emulation`: Dedicate the top right corner of the screen\n   to right-click emulation (e.g. for tablets)\n- `--no-right-click-emulation`: Disable right-click emulation in the top right\n  corner\n- `--renderer \u003crenderer\u003e`: Set renderer to use:\n  - `basic` is the default, which applies straightforward nearest pixel filtering\n    to scale the image.\n  - `hq4x` is a higher quality pixel art scaler that takes neighbour pixels\n    into account. This is a more expensive algorithm that requires a GPU\n    capable of OpenGL ES 3.0.\n  - `hqish` is another higher quality pixel art scaler. It's different than\n    `hq4x` in that it doesn't hardcode a scale factor but computes everything\n    on the fly. This may look better for larger resolutions. YMMV.\n- `--help`: Display a help message and exit.\n\nPlaying\n---------\n\nAfter starting the program the game will immediately start. \n\nLots of hints for playing the game, as well as the original manual can be found\non the excellent [Sundog information page](http://www.lukin.com/sundog/).\n\n### Key shortcuts\n\nThe game is controlled with the mouse only. There are however some key\nshortcuts for the interpreter:\n\n- ` ` Pause/unpause game\n- `s` Save state to `sundog.sav` in current directory.\n- `l` Load state from `sundog.sav` in current directory.\n\nSome other shortcuts are debugging related, see [debugging.md](doc/debugging.md).\n\nStatus\n---------\n\n### What works?\n\n- Loading screen graphics, palette effects.\n- Starting a new game.\n- Right-click popup in-game.\n- Walking around the ship and in buildings.\n- Liftoff / Landing.\n- Sublight flight.\n- Warp (with fancy effects).\n- Loading / reading save states (`l` and `s` respectively).\n- Ground combat.\n- Space combat.\n- Sound effects.\n- Touch screen support: a small area in the top-right of the screen has been\n  designated as \"cancel area\" and will emulate a right-mouse click when touched.\n  This can be disabled by passing `--no-right-click-emulation` on the command\n  line.\n\nIs it fully playable? Yes, I played it for quite a bit. All the critical things\nhave been implemented, Though I cannot guarantee that there aren't any bugs\nleft. If so, please report them through the issue tracker, along with a saved\nstate if possible.\n\nP-system\n-----------\n\nSundog uses version `IV.2.1 R3.4` of the p-system. This is a version of the\np-system developed commercially by Softech. I looked at using [ucsd-psystem-vm](http://ucsd-psystem-vm.sourceforge.net/),\nhowever this implements version `II.0` which is significantly different. As\nfar as I know this is the only open source, publicly available p-system\nIV implementation. It is fairly independent of the game, so if it is useful\nfor anything else it could be factored out to a library. Code for the p-system\ninterpreter is in [src/psys](src/psys).\n\nThe p-system has a custom disk layout (this is why on the Atari ST the disk\nlooks like it has only a small `.prg` and the rest of the disk is empty). This\nlayout is very basic: it supports only contiguous files, and there is only\nthe top-level directory.\n\nP-code is stored in code files, which in turn are organized into segments.\nSegments are self-contained and can be compared to \"units\" in later Pascal\nvariants. These in turn contain one or multiple procedures.\n\nAt bootstrap time the interpreter seeks into a code archive `SYSTEM.PASCAL`, loads\nthe segment `USERPROG`, and starts interpreting at procedure 1 of that segment.\nFrom there the p-system takes care of the rest of initialization, eventually\nexecuting `SYSTEM.STARTUP`. This is the game, in this case.\n\nIn modern terms the P-system is comparable to the Java Runtime Environment, but\nmore low-level. Some \"advanced\" features (for the time) that are supported:\n\n- OS, architecture, endian-independent bytecode.\n\n- Tasks (multi-tasking), synchronized using semaphores.\n\n- External events (user input, timer interrupts) can signal semaphores.\n\n- Paging (\"swapping\") of code. Segments are loaded when accessed, causing a\n  segment fault to occur. When there is memory pressure, least recently used\n  code segments are discarded, and will be reloaded when used again.\n\n- Run-time error handling.\n\n- Dynamic memory management (the heap).\n\nIt most notably does NOT do:\n\n- Security and sandboxing. Everything can read and write everywhere.\n\n- Address more than 64KiB (or 128KiB on word-addressed architectures) of data\n  memory. It does however use \"code pools\" to be able to store more code and\n  string constants.\n\nThe game includes a rudimentary debugger (use *d* key to start it) which can be\nused to poke around in the internals of the p-machine.\n\nThe best overview of the internals of the p-system version IV is the\n\"p-System Software Reference Library: Internal Architecture\", which can be\nfound [on bitsavers](http://bitsavers.informatik.uni-stuttgart.de/pdf/sage/sageandstride/Internal_Architecture-1.140.41.A.pdf).\n\n## Retrospect\n\nIn retrospect we could have gotten away with emulating way less of the actual\np-system, if we'd emulated at the run-time level instead of the OS level. The\ngame doesn't use any of the OS functionality, besides one background task. The\npaging was not required even with the 1MB of memory of an Atari ST. Most game\ndata is static, it hardly uses dynamic memory management.\n\nSo we could do away with SofTech's `SYSTEM.PASCAL` runtime and replace it with\na minimal stub in C. Run the game itself only.\n\nThat said, I didn't have enough knowledge about the whole thing when I started\nthis, and besides, it's kind of cool how this project is as much of a toy\noperating system as a game. Unless the PASCAL source code of the original game\nhappens to become open source (:smile:) there's little reason to do otherwise.\n\nDebug UI\n---------\n\n\u003cimg alt=\"Debug UI\" src=\"screenshots/debugui.png\"\u003e\n\nA debug UI can be compiled in to aid with debugging and reverse engineering. For more information, see [debugging.md](doc/debugging.md).\n\nCredits\n--------\n\nAuthors:\n\n- Wladimir J. van der Laan\n\nContributions in the form of github pull requests are very welcome.\n\nSpecial thanks to:\n\n- [Bitsavers](http://bitsavers.trailing-edge.com)\n- The former UCSD pascal group on Yahoo\n- [ocornut](https://github.com/ocornut) for the \"dear imgui\" GUI system used for debug GUI\n- Mitsutaka Okazaki for emu2149\n- Of course late FTL software: Bruce Webster, Doug Bell, Wayne Holder, Mike Newton, Andy Jaros for making SunDog in the first place.\n\nLicense\n---------\n\nThis software is provided under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaanwj%2Fsundog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaanwj%2Fsundog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaanwj%2Fsundog/lists"}