
           _  ---                   _  --- 
        ."    ,,   ~=_    ..   ."          ~=_
      .    . .OZZZO    ^g,      .    .~.      ^%   .s%ZO
          `  qZp'   `Z,         `        _.,  `gZ  :ZZ|
      _g%%oc,  ~ _.,  `  Z;         _.,©y%Z=-: .s%Z%L, `OZZYi%g_
     jOZZZZOL jOZZ,  `Zb  _.©y%ZZZZZZZZ%=: jZZZZZZZb `ZZZZZZZb
    ZZ?~ ~\ZZZ| |ZZZZO\ ?Z.%ZZZZZZ*^"`' /ZZ"~"ZZ\ T   ~!ZZ
     Z6f   ZZZO|ZZZ^ZZi ]Z1:-":ZZZ'      _. OZ/     \ZZL :    |6Z'
 .   `ZZ._ ~"^Z| ZZZ;\ZZ Z   ZZZ  _%ZZ l%! .oZo, ]ZZ  _ZZ'   .
  ,    ~^*^~.ZZZZl ZZZZ1  ZZZZ  ^!ZZ :=l dZZZb ZZ|  ~^"~
           g%ZZZZZZZ `ZZZ : ZZZZ:   lZZ| ; :ZZZF ZZ|         .'
    ~_    ZZZZ| ZZZZ  ZZ'   ?ZZZ!    :ZZ   ""  dZg      _~
       ~"^ :ZZZO|ZZZ!   `^'  '  `ZZZ    ZZ:       ./ZZf --`~
           OZZZ jZ~  `. _ _. .   ~^L, YZZZZOzz :=CO/
     -V!  j^~     .     ~--~    .     `^ʦZZF':%CG' . O R G
                     ~_    T    _~             ~'  '^"~
                        ~"=|="~
                                    p r e s e n t s
                            

      Composite CGA patch for COMMANDER KEEN IV: SECRET OF THE ORACLE
      ---------------------------------------------------------------

      1. WHAT'S THIS?                                        by VileR
      2. USAGE                                             2016-05-22
      3. SYSTEM REQUIREMENTS
      4. TECHNICAL PATCH INFO
      5. CREDITS & ACKNOWLEDGEMENTS
      6. CONTACT
      7. LEGAL STUFF



---------------
1. WHAT'S THIS?
===============

   A different type of Keen 'mod' - this one doesn't provide new maps,
   enemies, game logic or anything like that.  What this does is patch your
   copy of Commander Keen 4 (v1.4 CGA, Apogee release!) to take optimal
   advantage of composite displays.

   Basically, it exploits CGA's lesser-known capability of displaying solid
   artifact colors on NTSC-compatible composite monitors or TVs.  The
   technique is described in detail elsewhere, but in "normal" graphics
   modes, it expands the card's palette from 2/4 colors to 16.  These are
   not the same 16 RGBI colors normally supported by CGA/EGA, so all game
   graphics have been redrawn specifically for this mode.



--------
2. USAGE
========

   To install:

   - Copy all KEEN4 v1.4-CGA game files into a new directory (recommended).
   - Place the contents of the patch in the same directory:
         C16GRAPH.CK4
         C16HEAD.CK4
         CK4PATCH.EXE
         KEEN4C16.BAT
         KEEN4C16.PAT

   To run, simply launch KEEN4C16.BAT.



----------------------
3. SYSTEM REQUIREMENTS
======================

   The patch is geared towards running on real CGA-equipped machines, but
   it'll work just fine in DOSBox's CGA mode as well (a recent SVN build is
   highly recommended - composite support in DOSBox is still being
   improved!).

   What you will need:

   - A copy of Commander Keen IV: Secret of the Oracle, v1.4-CGA (Apogee
     release).  The executable should have this size and date stamp:
     KEEN4C.EXE     98,007    01-Feb-92

   - DOS 3.3+

   - 8088 or higher (runs fine at 4.77MHz, but rather slow)

   - ~540 KB of free RAM

   - A true IBM CGA card driving a composite monitor or TV

   The latter isn't strictly a requirement, but if your CGA card is not a
   true IBM, it is highly unlikely that you'll get correct colors.  IBM never
   bothered to document the artifact color technique, so clone makers didn't
   have a standard to adhere to.  Of course, you can also run this on an RGB
   monitor if you choose, or on EGA/VGA; however, that'd only get you a
   serrated, stripy monochrome picture (and likely an ocular migraine).

   To complicate matters further, IBM CGA cards fall into two basic designs
   ("early" and "late" style), which differ *ONLY* in their composite output.
   This patch will look best on an "early"-type CGA.  "Late"-type cards tend
   to produce over-saturated colors in this mode, but you might get
   acceptable output if you dial down your display's saturation by 40%-50%.

   Again, the exact differences between these two CGA flavors are explained
   elsewhere, but if you don't know which one you have, simply get Trixter's
   latest CGA Compatibility Tester and run its "CGA card determination" test:

   < http://www.oldskool.org/pc/cgacomp >



-----------------------
4. TECHNICAL PATCH INFO
=======================

   CK4PATCH is used to modify the game in memory (at runtime).  Conveniently
   (for me!), this means that I don't have to distribute a modified EXE --
   something that certain legal entities may consider "not cool".

   This version of CKPATCH (v0.11.2) is the unofficial update available at
   http://ny.duke4.net/files.html, with the difference that UPX compression
   has been removed (to support 8088 CPUs).

   Seasoned and observant Keen modders may note that the patch file is messy
   and uncommented.  This is because I first created the patch as a direct
   modification of the original EXE.  I hadn't even heard of CKPATCH until
   it was pointed out to me (thanks NY00123), so only when I was done did I
   port my changes to this format.

   I may do a more detailed writeup in the future, and/or if there's
   interest, but this is the general idea of what's going on:


   - Video mode 3 is replaced with mode 2, for more readable 80x25 text
     screens on composite
   - Video mode 4 is replaced with a jump to new code to set mode 6 and
     enable NTSC color burst on the CGA
   - Fade-in/out routines (no-op stubs in the CGA version) now jump to new
     CGA fade code - write to the CRTC, set/clear the "screenfaded" status
     byte (the keyboard-handling code checks this), and call the game's
     existing wait-for-vblank routine for timing
   - All graphics code for drawing non-sprite/tile stuff (text, rectangles,
     lines) now uses expanded color lookup tables instead of the old 4-color
     ones; various color values throughout the code are replaced accordingly
   - Naturally, all sprite/tile data is completely replaced (C16GRAPH.CK4,
     C16HEAD.CK4)

   Patch space for new code was hijacked from an unused routine (leftover
   from Keen Dreams?).  For new data, the unused color tables for EGA fades
   (still present in the CGA executable!) were stomped over.



-----------------------------
5. CREDITS & ACKNOWLEDGEMENTS
=============================

   - VileR
        code and graphics modification

 THANKS TO:

   - reenigne, Scali, Trixter
        real hardware testing + general CGA/8088 co-conspiration

   - NY00123
        ModId & CKPATCH support

   - ripsaw8080
        low-level strategic consultancy

   - John Carmack
        providing this tweet as inspiration:
        https://twitter.com/ID_AA_Carmack/status/714415047695425537

 TOOLS USED:

   - IDA Pro (free version)

   - DOSBox's internal debugger

   - ModId v0.1 for asset importing: < https://github.com/owenmpierce/modId >

   - CKPATCH v0.11.2 (unofficial): < http://ny.duke4.net/files.html >

   - reenigne's cga2ntsc, for quick proofing:
     < http://www.reenigne.org/misc/cga2ntsc.zip >

   - Adobe Photoshop (yeah, I know)



----------
6. CONTACT
==========

   I can be reached at:   email - viler -AT- int10h -DOT- org
                            www - http://int10h.org
                           blog - http://8088mph.blogspot.com

   Spam and/or excessive dumbness will be ignored, deleted, spindled and
   mutilated.



--------------
7. LEGAL STUFF
==============

   Commander Keen is (c) id Software.

   CKPATCH is free software released under GNU GPL-v2.  No changes were made to
   this copy other than unpacking the EXE, so feel free to consult the URL (in
   section 5) for sources/docs.


   Enjoy,

      VileR
