VAXDoom
=======

 _   _  ___  __   _______                      
| | | |/ _ \ \ \ / /  _  \                     
| | | / /_\ \ \ V /| | | |___   ___  _ __ ___  
| | | |  _  | /   \| | | / _ \ / _ \| '_ ` _ \ 
\ \_/ / | | |/ /^\ \ |/ / (_) | (_) | | | | | |
 \___/\_| |_/\/   \/___/ \___/ \___/|_| |_| |_|
                                               
Astr0Claude 2026


A port of id Software's linuxdoom-1.10 to OpenVMS VAX. The game runs
on a SIMH-emulated MicroVAX 3900 with X11 display forwarded to a
macOS host via Xephyr. No audio. All gameplay works: movement,
shooting, doors, switches, lifts, level transitions.


Platform
--------

Emulator:   SIMH VAX, emulating a MicroVAX 3900
OS:         OpenVMS 7.3 VAX with DECwindows Motif
Compiler:   DEC C (Compaq C V6.4-005), C89 standard
Assembler:  VAX MACRO
Host:       macOS (Apple Silicon) running Xephyr for X11 display
Network:    TCP/IP Services for OpenVMS, bridged networking in SIMH
WAD:        DOOM1.WAD v1.9 (shareware, 4,196,020 bytes)


SIMH Configuration
------------------

The emulated VAX used for development and testing:

  CPU:        MicroVAX 3900 (KA655 processor)
  Memory:     512 MB
  Boot disk:  RA92 on RQ0 (disk.dd, ~594 MB)
  Data disk:  RA92 on RQ1 (disk2.dd, ~1.4 GB)
  Network:    DELQA (XQ) Ethernet, MAC 00-01-2A-2B-2C-73
  Console:    KA655X.BIN firmware
  Idle:       VMS idle detection enabled (set cpu idle=vms)
  Boot:       Autoboot from DUA0

  Disabled devices: RL, TS, TQ, DZ, LPT

The network adapter is attached to a bridged interface on the host,
giving the VAX its own IP address (10.0.40.73) on the local network.
This is used for FTP file transfers, X11 display forwarding, and
Telnet access.

SIMH startup file (vms.ini):

  set cpu 512M
  set cpu idle=vms
  set rq0 ra92
  set rq3 cdrom
  attach RQ0 disk.dd
  attach RQ1 disk2.dd
  set rl disable
  set ts disable
  set tq disable
  set dz disable
  set lpt disable
  set xq enable
  set xq mac=00-01-2A-2B-2C-73
  attach xq feth5003
  set cpu autoboot
  set cpu boot=DUA0
  boot cpu


Porting Challenges
------------------

No 64-bit integers.

  The biggest issue. DEC C on VAX has no "long long" type. DOOM's
  fixed-point math depends on 64-bit intermediates for FixedMul
  (multiply two 32-bit values, return the middle 32 bits) and
  FixedDiv (shift left 16, then divide). The solution is a VAX MACRO
  assembly module, FIXEDMUL.MAR, using the VAX EMUL instruction
  (extended multiply, producing a signed 64-bit result in a register
  pair) and EDIV (extended divide, taking a 64-bit dividend). The
  critical detail is sign extension: when constructing the 64-bit
  quadword for EDIV, the high longword must be sign-extended from the
  low longword, not zeroed. Getting this wrong produces garbage for
  any negative operand, which silently breaks line-of-sight checks,
  ray intercept calculations, and door activation.

Symbol name collision.

  DEC C defaults to uppercasing all external symbols to match VMS
  linker conventions. The DOOM source defines a global variable called
  "lines" (the array of map linedefs). VAXCRTL also exports a symbol
  called LINES (from curses). The linker silently resolved DOOM's
  "lines" to the curses variable, causing an access violation in
  P_SpawnSpecials on level load. Fixed with a /DEFINE renaming
  lines=doom_lines on the compiler command line.

No shared memory X11.

  Linux DOOM uses XShm (shared memory pixmaps) for fast blitting.
  This is not available over a TCP/IP X11 connection. The port uses
  XPutImage exclusively, converting the 8-bit paletted framebuffer
  to 24-bit TrueColor via a 256-entry lookup table that is rebuilt
  whenever the palette changes (damage flash, item pickup, etc.).

X11 display setup.

  The VAX has no physical display. X11 is forwarded over TCP/IP to
  Xephyr running on the macOS host. Xephyr is started with
  "-listen tcp -ac" for unauthenticated access, and the VMS side
  uses SET DISPLAY/CREATE/NODE=.../TRANSPORT=TCPIP/SERVER=1 to
  point at it. The game window is 640x400, scaled 2x, in a
  1200x700 Xephyr window.

Key event timing.

  Over a network X11 connection, KeyPress and KeyRelease events for
  a single keypress can arrive in the same game tic. DOOM's original
  input handling clears the key state on release, so a quick press
  registers as "not held" when the tic is processed. Fixed by adding
  a keypressed[] latch array that persists for one tic, ensuring
  momentary actions like BT_USE (open door) and BT_ATTACK survive
  the press-release race.

Binary file I/O.

  VMS files have record attributes (fixed, variable, stream, etc.).
  WAD files transferred via FTP in binary mode get VMS record
  attributes that break sequential byte reads. The fix is opening
  files with the "ctx=stm" option in the fopen/open calls, which
  forces byte-stream access regardless of file attributes.


Source Files
------------

62 C source files, 1 VAX MACRO assembly file (FIXEDMUL.MAR), and
1 linker options file (DOOM.OPT). The source is a lightly modified
linuxdoom-1.10. Changes are limited to what is needed for VMS; the
game logic is unmodified.


Build Instructions
------------------

Prerequisites on VMS:
  - DEC C compiler (CC)
  - VAX MACRO assembler (MACRO)
  - DECwindows X11 development headers (DECW$INCLUDE)
  - TCP/IP Services for OpenVMS (for X11 display over network)

Steps:

  1. Create a directory on VMS for the source and WAD file:

       $ CREATE/DIRECTORY disk:[directory.DOOM]

     Transfer all .C, .H, .COM, .OPT, and .MAR files to VMS in
     ASCII mode. Transfer DOOM1.WAD in BINARY mode.

  2. On VMS, set default to the source directory and build:

       $ SET DEFAULT disk:[directory.DOOM]
       $ @BUILD_DOOM

     This compiles all C files, assembles FIXEDMUL.MAR, builds an
     object library, and links VAXDOOM.EXE.

  3. To run, start Xephyr on the host machine:

       /opt/X11/bin/Xephyr -listen tcp -ac -br :1.0 -screen 1200x700

  4. On VMS, point X11 at the host and run:

       $ SET DISPLAY/CREATE/NODE=x.x.x.x/TRANSPORT=TCPIP/SERVER=1
       $ DEFINE DOOM_WAD disk:[directory.DOOM]DOOM1.WAD
       $ DOOM :== $disk:[directory.DOOM]VAXDOOM.EXE
       $ DOOM

     The default window is 320x200. Use -2 for double size (640x400)
     or -3 for triple size (960x600):

       $ DOOM -2

     Arrow keys move, Ctrl fires, Space opens doors and activates
     switches, Escape opens the menu.


Compiler Flags
--------------

  /NODEBUG /NOWARNING
  /INCLUDE=([],DECW$INCLUDE)
  /DEFINE=("NORMALUNIX=1","__VMS=1","lines=doom_lines")

The NORMALUNIX define selects the Unix I/O and X11 code paths in
the original source. The __VMS define gates VMS-specific changes.
The lines=doom_lines define avoids the VAXCRTL symbol collision.


Linker Options (DOOM.OPT)
-------------------------

  sys$library:decw$xlibshr/share     X11 client library
  sys$library:decw$xextlibshr/share  X11 extensions
  sys$library:vaxcrtl/share          C runtime
  sys$share:librtl/share             VMS runtime library
  sys$library:pthread$rtl/share      POSIX threads


Running on Other VAX Systems
-----------------------------

The executable is portable across VAX hardware. VAXDOOM.EXE is
compiled with standard VAX instructions, linked /NODEBUG with no
install-specific paths, and uses only dynamic shared libraries.
It will run on any VAX meeting these requirements:

  OpenVMS 7.0 or later.

    The POSIX threads library (PTHREAD$RTL) shipped starting with
    OpenVMS 7.0. Any 7.x system should work. The executable was
    built on OpenVMS 7.3.

  DECwindows Motif (X11).

    The game links against DECW$XLIBSHR and DECW$XEXTLIBSHR.
    The target system must have DECwindows Motif installed and
    an X11 display available, either local or forwarded over
    TCP/IP. Headless or minimal OpenVMS installs without
    DECwindows will not work.

  WAD file accessible.

    DOOM looks for WAD files using the DOOMWADDIR or DOOM_WAD
    logical names. If neither is defined, it searches the current
    default directory. To run on another system, either:

      $ DEFINE DOOM_WAD disk:[directory]
      $ RUN VAXDOOM.EXE

    or SET DEFAULT to the directory containing the WAD file:

      $ SET DEFAULT disk:[directory.DOOM]
      $ RUN VAXDOOM.EXE

  No special installation required.

    The executable needs no INSTALL privileges or system logical
    names. Copy VAXDOOM.EXE and a WAD file to the target system,
    define the display, and run.


Credits
-------

Original game by id Software (1993). linuxdoom-1.10 source release
(1997). FIXEDMUL.MAR technique inspired by Tim E. Sneddon's
Wolf3D VAX port. Port to OpenVMS 7.3 VAX, November 2026.
