
           _  ---                   _  --- 
        ."    ,,   ~=_    ..   ."          ~=_
      .    . .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 V: THE ARMAGEDDON MACHINE
      ----------------------------------------------------------------

      1. WHAT'S THIS?                                        by VileR
      2. USAGE                                             2016-07-15
      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 5 (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 KEEN5 v1.4-CGA game files into a new directory (recommended).
   - Place the contents of the patch in the same directory:
         C16GRAPH.CK5
         C16HEAD.CK5
         CK5PATCH.EXE
         KEEN5C16.BAT
         KEEN5C16.PAT

   To run, simply launch KEEN5C16.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 V: The Armageddon Machine, v1.4-CGA (Apogee
     release).  The executable should have this size and date stamp:
     KEEN5C.EXE     98,880    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
=======================

   CK5PATCH 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).

   As for the modified code itself, it is quite similar to my equivalent
   patch for Keen 4, so you're welcome to browse the relevant blog post for
   the dirty details:
   
   < goo.gl/b6UCyT >

   The one new thing for Keen 5 was the 'game over' screen with the animated
   galaxy.  The EGA version pulls this off by modifying palette registers,
   while the vanilla CGA version settles for a plain boring static picture.
   With composite CGA in mode 6, flipping the bits for the foreground color
   lets us achieve "palette" effects (just like with the fades), so I've
   added a new routine to do this here.  Hope it doesn't break your shit. :)



-----------------------------
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
