D 2018-04-29T02:39:50.329
L Adventure
N text/x-markdown
P 90cb431e588f2c043ee6f1311ba5294ca1679480
U tangent
W 3581
# Introduction

The default OS/8 RK05 disk image shipped with our [binary OS images](/#bosi) has [Rick Murphy's version of Adventure][rma] installed and ready to run, so that unless you [go out of your way to disable Adventure][dopt], you do not need to follow [Rick Murphy's build instructions][rmdoc].

Since Rick's documentation is somewhat irrelevant to our configuration here and we wanted to make some additional points not covered in his documentation, we thought we should have some documentation of our own.

[dopt]: /doc/trunk/README.md#disable-os8
[rma]: http://www.rickmurphy.net/advent/
[rmdoc]: http://www.rickmurphy.net/advent/ADVENT.DC


# Starting the Game

There are two supported ways to start Adventure. Either:

    .R FRTS
    *ADVENT$          ⇠ $ = Escape keypress

or:

    .EXE ADVENT.LD


# How to Wreck Your Adventure Game
## ...And How to Fix it

The second command is obviously shorter, but it has a severe risk attached: if you forget to include the file name extension, it puts you at the mercy of OS/8's choice of `ADVENT.*` file to run:

    .EXE ADVENT

As currently distributed by the PiDP-8/I project, there are two choices available to the `EXE` command: `ADVENT.FT`, the main FORTRAN IV source code file for Adventure, and `ADVENT.LD`, the binary FORTRAN IV loadable executable file that we've pre-built for you.

If OS/8 happens to choose `ADVENT.FT`, it attempts to build the program from source code and run it, which will fail, because OS/8 Adventure requires a fairly complex [compilation][cbi] and [loading][lbi] sequence. Simply building `ADVENT.FT` will produce a broken `ADVENT.LD`, overwriting our version without any notice that this has happened.

Consequently, the above correct commands will begin to give an error:

    USER ERROR MAIN   0047

The fix is to restore `ADVENT.LD` from the binary tape we've provided. From within the simulator, press <kbd>Ctrl-E</kbd> to get out to the SIMH command prompt, then follow this script:

    sim> att dt0 /opt/pidp8i/share/media/os8/subsys/advent.tu56
    sim> cont
    .COPY DSK:<DTA0:ADVENT.LD

Now you should be able to start Adventure again using one of the above correct commands. We recommend that you use the `R FRTS` method exclusively to avoid getting into this broken state again by forgetting to include the `.LD` suffix in your OS/8 `EXE` command.

[cbi]: http://www.rickmurphy.net/advent/COMPIL.BI
[lbi]: http://www.rickmurphy.net/advent/LOAD.BI


# How *Not* to Start the Game

You may find pages elsewhere online that use commands like the following:

    .R ADVENT

or

    .RUN RKB0 ADVENT

These are relying on the existence of `ADVENT.SV`, a core memory image save file that OS/8 can just load up and begin executing directly, without directly involving the FORTRAN IV run-time system. The old `os8.rk05` disk image used in release v2017.04.04 and older — including the final v2015.12.15 release by Oscar Vermeulen — does provide this `ADVENT.SV` file, but we chose not to provide this in our distribution of Adventure, because that amounts to a duplicate copy of data already provided in `ADVENT.LD` and the OS/8 FORTRAN run-time system. We ran out of space on the OS/8 disk images multiple times during development, so we're reluctant to do anything that takes up space without a sufficiently good reason.


## License

Copyright © 2018 by Warren Young. This document is licensed under
the terms of [the SIMH license][sl].

[sl]:   https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md
Z 74564c03c892073a49de5e5852450f33