ck1-amiga 0.9

Commander Keen 1 RTG

Short:        Commander Keen 1 RTG
Author:       raoul.schroeter@gmx.de
Uploader:     raoul schroeter gmx de
Type:         game/actio
Version:      0.9
Requires:     Picasso96 or CyberGraphX, an RTG graphics card (or an RTG-capable emulator), and your own legitimate Commander Keen 1 v1.31 data files (not included)
Architecture: m68k-amigaos >= 2.0

Commander Keen 1 -- Amiga RTG port
===================================
Unofficial, non-commercial fan-made port of "Commander Keen in Invasion of
the Vorticons -- Episode 1: Marooned on Mars" (v1.31) to the Commodore
Amiga, rendered through RTG (Picasso96 / CyberGraphX, via cybergraphics.library)
in 8-bit chunky-pixel mode instead of the original's EGA/VGA output.

This is a *port*, not an emulator: it is a native m68k AmigaOS program, built
from a line-by-line reconstruction of the original DOS source, that reads
the original game's own data files directly and reimplements the game logic,
rendering, audio and timing natively against Amiga APIs (Picasso96/cgx,
AudioDevice, timer.device, Intuition). No DOS emulation or x86 code of any
kind is involved.

Status: pre-release / work in progress. The core game is fully playable
start to finish (see "Known issues" below for the open corners). Tested on
real Amiga hardware as well as WinUAE/FS-UAE with Picasso96 configured.


LEGAL / COPYRIGHT
-----------------
Commander Keen is (C) id Software / Apogee Software (now part of
ZeniMax/Bethesda). This archive is NOT affiliated with, endorsed by, or
sponsored by id Software, Apogee, Bethesda, ZeniMax, or any of their
successors. "Commander Keen" and related names are their trademarks.

This archive contains ONLY code written for this Amiga port. It does NOT
contain, and will never contain:
  - any of the original game's data files (graphics, levels, sounds, text --
    the *.CK1 files, or the DOS KEEN1.EXE), or
  - the GPLv2-licensed "Reconstructed Commander Keen 1-3 Source Code" project
    by K1n9_Duk3, which was used purely as a reference during development to
    verify this port's behaviour against the original -- none of its code is
    copied into this port's own sources.

To use this port you must already own a legitimate copy of Commander Keen 1
v1.31 (e.g. from id Software's own 1991 shareware/registered release, or a
legally purchased re-release) and supply its data files yourself. See
SETUP below.


WHAT'S IN THIS ARCHIVE
-----------------------
  README.txt           -- this file
  LICENSE              -- license for this port's own source code (GPLv2)
  DECISIONS.md          -- full development log: every architectural
                           decision, fidelity check against the original,
                           and bug investigation made while building this
                           port. Essential reading for anyone continuing
                           this project.
  amiga/README.md       -- short build quick-reference
  amiga/Makefile         -- cross-compiles amiga/src with vbcc
  amiga/build-adf.sh     -- assembles a bootable keen1.adf from amiga/disk/
  amiga/src/             -- full source code of this port (C, m68k AmigaOS)
  amiga/tools/           -- helper scripts (see below)
  amiga/disk/KEEN1       -- precompiled binary (68000, no FPU required)
  amiga/disk/S/Startup-Sequence
                        -- the boot script that launches KEEN1


SETUP -- adding your own copy of the game data
------------------------------------------------
1. Get your own legitimate copy of Commander Keen 1 v1.31 and locate these
   original files (from the DOS install):
     EGAHEAD.CK1  EGALATCH.CK1  EGASPRIT.CK1  FINALE.CK1  HELPTEXT.CK1
     LEVEL01.CK1 .. LEVEL16.CK1  LEVEL80.CK1  LEVEL81.CK1  LEVEL90.CK1
     PREVIEW2.CK1  PREVIEW3.CK1  PREVIEWS.CK1  STORYTXT.CK1  SOUNDS.CK1
     KEEN1.EXE

2. Create a folder named "CKeen1" *next to* the "amiga" folder from this
   archive (i.e. CKeen1/ and amiga/ are siblings), and copy all the files
   above into it.

3. Easiest path (no cross-compiler needed, binary is already built):
     - On a real Amiga or emulator with Picasso96/CyberGraphX installed,
       copy everything from amiga/disk/ plus all the files from CKeen1/
       into one directory (e.g. a hard-drive partition, or an emulated
       directory), then run KEEN1 from there.
     - TILEINFO.BIN and SOUNDS.BIN (two small files this port derives from
       KEEN1.EXE and SOUNDS.CK1) are NOT included in CKeen1/'s original
       file list above -- generate them with:
         python3 amiga/tools/extract_tileinfo.py CKeen1/KEEN1.EXE TILEINFO.BIN
         python3 amiga/tools/extract_sounds.py CKeen1/SOUNDS.CK1 SOUNDS.BIN
       and place both next to the other data files.

4. Bootable-floppy path (produces a ready-to-boot keen1.adf):
     - Requires amitools (`pip3 install amitools`) for its xdftool, on
       whatever machine you run the script on (does not need to be the
       Amiga itself).
     - From amiga/, with CKeen1/ in place as in step 2, run:
         ./build-adf.sh
       This auto-generates TILEINFO.BIN/SOUNDS.BIN, auto-copies the raw
       *.CK1 files from ../CKeen1/, and writes amiga/keen1.adf -- boot that
       on real hardware or in WinUAE/FS-UAE with Picasso96/CyberGraphX
       configured.

5. To rebuild the binary itself from source instead of using the one
   included, see amiga/README.md and amiga/tools/setup-toolchain.sh (needs
   vbcc targeting m68k-amigaos).


CONTROLS
--------
  Arrow keys  -- move
  Ctrl        -- jump
  Alt         -- fire / enter a level from the world map (stand on an
                 entrance and press Alt/Fire)
  Enter/Space -- confirm in menus
  Esc         -- quit (brings up a confirmation box)
  F1          -- help
  F5          -- save game (world map only, matching the original)


REQUIREMENTS
------------
  - Amiga with Picasso96 or CyberGraphX and a supported RTG graphics card
    (or an emulator such as WinUAE/FS-UAE configured with one)
  - 68000 or better, no FPU required
  - Your own legitimate Commander Keen 1 v1.31 data files (see SETUP)


KNOWN ISSUES / NOT YET IMPLEMENTED
------------------------------------
This is a from-scratch native port verified screen-by-screen and mechanic-
by-mechanic against the original DOS source, but a few corners are
deliberately incomplete. Listed here so whoever picks this project up next
doesn't have to rediscover them:

  * Joystick support is not implemented. Input is keyboard-only
    (input_cgx.c, via Intuition RAWKEY). Would need gameport/CIA potgo
    register reads (or lowlevel.library/gameport.device) feeding the same
    control structure keyboard input already populates. Scoped as a small,
    independent task; not attempted yet.

  * F2 (sound on/off) and F3/F4 (keyboard/joystick calibration) are not
    bound to anything. Only F1 (Help) and F5 (Save) are wired up. F3/F4
    only make sense once joystick support (above) exists.

  * The ENDTEXT.CK1 end-credits crawl is not shown after the finale's
    "TO BE CONTINUED....". A KEENSCRN.C-style scrolling text reader
    already exists in this port (textwin.c) and is used elsewhere (Story,
    F1-Help, Previews) -- wiring ENDTEXT.CK1 through it after DoFinale()
    should be straightforward, just not done yet.

  * "Ordering Info" in the main menu shows a short placeholder message
    instead of a reconstruction of the original 1990 Apogee mail-order
    form. Deliberate: that content has no functional value today.

  * "Restart Demo" in the main menu is a no-op (returns to the attract
    cycle). This port has no recorded-input demo-playback subsystem at
    all, so there's nothing to restart.

  * The High Scores screen (reached from the attract-mode title cycle)
    shows a plain black background instead of the LEVEL90 map backdrop
    every other menu screen uses. Minor visual inconsistency, not fixed.

  * World-map avatar movement speed is intentionally code-faithful: it's
    ported literally from the original's own ControlMapKeen(), unscaled
    by elapsed time. Combined with this port's fixed 60Hz pacing, the map
    avatar can feel faster than in-level Keen. This has been raised and
    deliberately deferred twice during development without a decision on
    whether "faithful to the original" should mean code-faithful (current
    behaviour) or feel-faithful (scaled to match perceived speed) --
    needs an explicit decision before anyone changes this, not a silent
    "fix".

  * Title-picture centering was reported as possibly slightly off on one
    real-hardware test. The relevant RTG screen-centering logic
    (video_cgx.c, BestCModeIDTags/s_destx/s_desty) was reviewed and found
    structurally correct; no concrete bug was found. Flagged as
    unresolved -- needs a side-by-side screenshot comparison or another
    real-hardware data point to make further progress.

None of the above affect core gameplay: all three episode-1 "worlds",
all 16 regular levels plus the secret levels, saving/loading, the full
menu system (title, attract-mode cycle, main menu, Story/About
ID/High Scores/Previews/F1-Help text screens), and the finale sequence
are implemented and have been verified on real Amiga hardware.


CONTINUING THIS PROJECT
------------------------
Read DECISIONS.md first. It is a complete, chronological log of every
design decision and bug investigation made while building this port,
including things that were tried and rejected -- it will save you from
re-deriving work already done or re-breaking things already fixed for a
good reason (several entries specifically document "looks like a bug but
isn't" cases and "fixed once, regressed, fixed again, here's why" cases).


CREDITS
-------
This port's fidelity to the original was checked throughout development
against the "Reconstructed Commander Keen 1-3 Source Code" project by
K1n9_Duk3 (GPLv2, (C) 2021-2026), used strictly as a reference -- no code
from it is included in or copied into this archive. If you have access to
that project separately, DECISIONS.md cites it by original filename
(KEENSCRN.C, KEENACTS.C, IDLIBC.C, etc.) throughout.

Commander Keen (C) id Software / Apogee Software.


LICENSE
-------
This port's own source code (everything under amiga/) is licensed under
the GNU General Public License v2 or later -- see LICENSE. This does not
and cannot grant any rights to the original Commander Keen game or its
assets, which remain the property of their respective copyright holders.