PLAYING.txt

Cosmo's Cosmic Adventure
========================

A native port of the 1992 Apogee game. No DOS emulator.


Starting it
-----------

macOS      Double-click Cosmo. macOS will refuse the first time, because this
           is not signed by a paid Apple developer account -- there is no way
           to avoid that without one.

           To allow it: open System Settings, go to Privacy & Security, scroll
           down to Security, and click "Open Anyway" next to the message about
           Cosmo. Confirm, and it opens normally from then on.

           On macOS 15 and later that panel is the only route. Right-clicking
           and choosing Open used to work and no longer does.

           From a terminal, this does the same thing in one step:

               xattr -dr com.apple.quarantine /path/to/Cosmo.app

Windows    Run cosmo.exe.

Linux      Run ./cosmo. If your desktop will not start it from a file manager,
           run it from a terminal.

Episode 1 is included, so it plays straight away.


Controls
--------

Arrow keys    move
Space         jump
Alt           bomb
F1            help, in game
Q then Y      quit, saving your settings and high scores

All six can be rebound from the game's own menu: press G at the main menu for
Game Redefine, then K for Keyboard redefine.

The original used ctrl to jump. Space is this port's one deliberate change,
because ctrl with an arrow key is a window manager shortcut on most systems
today. On macOS, Command jumps as well.

Quit through the game rather than closing the window. The configuration file
is written on the way out, exactly as it was on DOS, where killing the program
lost it the same way.


The window
----------

It opens at the largest whole multiple of the original 640x400 that fits your
screen, so the title bar always stays reachable. To choose the size yourself:

    COSMO_SCALE=2 ./cosmo        (1 is the original size, 3 is large)

Resizing is fine. The picture is letterboxed rather than stretched, so it never
distorts.


What is in this folder
----------------------

    cosmo          the launcher, and the only thing you need to run
    episodes/      the episodes: one program each, and their data

The episodes are separate programs rather than one with a switch. They differ
by preprocessor conditionals that include or exclude whole actor
implementations, so each compiles to genuinely different code -- Apogee shipped
three executables for the same reason. Each one sits beside the COSMO*.STN and
COSMO*.VOL files it reads, in a subdirectory, so there is one obvious thing to
run at the top.

On macOS all of that is inside Cosmo.app, where none of it needs looking at.


Episodes 2 and 3
----------------

Only Episode 1 was shareware. Episodes 2 and 3 were the paid ones and are still
sold by Apogee, so they cannot be included here.

If you already own them, choose the episode in the launcher and it will ask you
to find your copy. Point it at COSMO2.STN or COSMO3.STN and both files are
installed for you; they will be there next time.


Where your saves go
-------------------

If the folder this was unpacked into can be written to, the game keeps
everything in episodes/, beside the data it saves against, so a copy on a USB
stick carries its own saves.

The macOS application cannot write inside itself, so it uses
~/Library/Application Support/digows/Cosmo instead, and copies the game data
there the first time it runs.


Credits
-------

Cosmo's Cosmic Adventure, its artwork and its music are Copyright (c) 1992
Apogee Software, Ltd. Episode 1 is included as the freely distributable
shareware release.

This port is built on Cosmore, Scott Smitelli's reconstruction of the original
source, and uses ymfm by Aaron Giles to synthesise the AdLib. Its own code is
MIT licensed. Full credits are in ATTRIBUTION.md.

Source, and the story of what it took:  https://github.com/digows/cosmo