===============================================================================

                                     ALIENS

                                 Hadley's Hope

               A first-person shooter for the Amstrad CPC 6128

                          2026 by Devil-System

===============================================================================


CONTENTS
--------
  1.  The Story
  2.  Requirements
  3.  Loading the Game
  4.  Controls
  5.  How to Play
  6.  The Levels
  7.  Enemies
  8.  Items and Objects
  9.  Health and Game Over
 10.  Hints and Tips
 11.  Technical Details
 12.  Files on the Disk


-------------------------------------------------------------------------------
1.  THE STORY
-------------------------------------------------------------------------------

LV-426, 2179. Fifty-seven years after the loss of the Nostromo, the
colony HADLEY'S HOPE has gone silent. Its seventy families, its
atmosphere processor and its operations block no longer answer any call.

You are ELLEN RIPLEY, warrant officer and sole survivor of the Nostromo.
You came back with a squad of Colonial Marines. Now the squad is gone, the
dropship is wreckage, and the only way out is down: through the colony,
into the hive that has grown around the atmosphere processor.

Somewhere down there a little girl named Newt is waiting for you. And
somewhere below her lies the chamber of the ALIEN QUEEN.

Armed with an M41A pulse rifle and whatever magazines you can scavenge,
you must fight your way through eight levels: the operations block, the
colony quarters, the atmosphere processor, the medical lab, the outskirts
of the hive, the colony records and the hive itself. On each level you have
to reach the cargo ELEVATOR to the next one. At the very bottom the Queen is
waiting.

Get away from her. Nuke it from orbit. It's the only way to be sure.


-------------------------------------------------------------------------------
2.  REQUIREMENTS
-------------------------------------------------------------------------------

  - Amstrad CPC 6128 (or a CPC 464/664 with 64 KB memory expansion), or an
    emulator set up as a CPC 6128 (e.g. WinAPE, CPCEC, Caprice, Arnold,
    RetroVirtualMachine)
  - Disk drive (3" drive, Gotek/HxC or disk image in the emulator)
  - Keyboard; a joystick is optional

  The game needs the extra 64 KB RAM of the 6128: parts of the 3D engine are
  loaded into the additional memory banks. It will not run on an unexpanded
  CPC 464 or 664.


-------------------------------------------------------------------------------
3.  LOADING THE GAME
-------------------------------------------------------------------------------

  Insert the disk (or attach ALIENS.DSK in your emulator) and type:

      RUN"ALIENS"

  and press RETURN (or ENTER).

  The loader first shows the title picture, then loads the game code and the
  three engine files into memory. After a few seconds the title screen
  appears.

  Please note: do NOT start the game with RUN"ALIENS.BIN". Always use the
  BASIC loader, otherwise the engine files cannot be loaded.


-------------------------------------------------------------------------------
4.  CONTROLS
-------------------------------------------------------------------------------

  Keyboard and joystick can be used at the same time. There is nothing to
  select or configure.

    Action                      Keyboard                Joystick
    --------------------------  ----------------------  -------------------
    Walk forward                Cursor Up    or  W      Up
    Walk backward               Cursor Down  or  S      Down
    Turn left                   Cursor Left  or  A      Left
    Turn right                  Cursor Right or  D      Right
    Strafe (step sideways)      Q (left) / E (right)    -
    Fire                        CTRL                    Fire
    Open a door                 SPACE, F, RETURN, ENTER 2nd fire
    Use the elevator            SPACE, F, RETURN, ENTER 2nd fire
    Open a secret wall          SPACE, F, RETURN, ENTER 2nd fire
    Automap (pauses the game)   M                       -
    Start game (title)          SPACE / RETURN          Fire
    (With a one-button joystick the button fires and SPACE opens doors.)
    Continue (between levels)  any key                 Fire
    Choose view size (title)    1 / 2 / 3               -
    Enter a password (title)    P, letters, RETURN      -
    Back to the title menu      ESC

  PASSWORD ENTRY
    On the title screen, press P. "Password:" appears with six dots.
    Type the password, correct mishots with DEL and confirm with RETURN
    (ESC cancels). The result is shown in the same line:
      "Start: LEVEL n"  the game will start on that level
      "Wrong password"   the game will start on level 1
    You can enter a new password at any time by pressing P again.

  VIEW SIZE
    On the title screen, press 1, 2 or 3 to choose the size of the 3D
    window. The current choice is shown as "View: ...".

      Key  View   Window size (pixels)   Speed (approx.)
      ---  -----  ---------------------  ------------------------
       1   FULL   160 x 200 (full screen)  5 - 6 frames per second
       2   2/3    108 x 136                 8 frames per second
       3   1/2     80 x 104                11 frames per second

    The field of view is the same in all sizes. The smaller the window, the
    smoother the game runs. The default is 2/3; the setting is kept until
    you change it.
    In the smaller sizes the rest of the screen is filled with a terminal wall
    pattern, with a black frame around the 3D window.

  Shooting and using are separate: CTRL / Fire always fires the pulse rifle,
  USE (SPACE, F, RETURN, ENTER or 2nd fire) opens doors and secret walls and
  lets you take the elevator when you stand right in front of them. Elsewhere
  USE does nothing, so no ammunition is wasted.


-------------------------------------------------------------------------------
5.  HOW TO PLAY
-------------------------------------------------------------------------------

  Levels 1 to 7:
    Find the cargo ELEVATOR and use it. It is easy to spot: a cage door
    framed with yellow-and-black stripes. Walk up close (about one tile), face it and
    press USE (SPACE, F, RETURN, ENTER or 2nd fire).
    You are taken to the next level.

  Level 8 (Queen's Chamber):
    There is no elevator here. Your goal is to KILL THE QUEEN.
    When she falls, you have won the game.

  You do NOT have to kill every alien. Speed and survival matter more than
  a body count, but aliens will chase you once you get close, so it is often
  safer to deal with them than to run.

  Before each level a short screen shows the level number and your goal:
    "LEVEL n  -  Find the elevator"   (levels 1-7)
    "LEVEL 8  -  Kill the Queen!"     (level 8)
  It also shows your score, your ammunition and - from level 2 on - the
  PASSWORD of this level. Write it down: entering it on the title screen
  (press P) lets you start directly on that level next time (with a score
  of zero).

  AUTOMAP
    Press M at any time to see a map of the level inside a cyan frame.
    It shows the area around every place you have walked (one tile in
    each direction); secret walls look like normal walls. The level is
    shown as a dark blue area, walls in their own colour (panels grey,
    cocoons and hive walls in their own colours, terminals green, pipes,
    elevator, doors yellow, vents white). Your position is
    a yellow arrow pointing in the direction you are facing. Below the map: level number, ammunition and score. The
    game is paused while the map is shown. Press M, ESC or Fire to go
    back.


-------------------------------------------------------------------------------
6.  THE LEVELS
-------------------------------------------------------------------------------

  Every level is a 16 x 16 tile maze.

    Level  Name                   Layout                        Aliens
    -----  ---------------------  ----------------------------  -----------
      1    Operations Block       Offices around a corridor       6
      2    Colony Quarters        Streets and family flats        6
      3    Atmosphere Processor   Pipe shafts, switchbacks        6
      4    Medical Lab            Lab with stasis tubes           6
      5    Hive Outskirts         Organic caves, cocoons          7
      6    Colony Records         Archive rows, offices           6
      7    The Hive               Twisting hive tunnels           6
      8    Queen's Chamber        Egg-filled cavern               6 + QUEEN

  Every level also holds medipacks, ammunition and treasure. Some of it is
  hidden behind secret walls.

  Goal on levels 1-7: reach the elevator.
  Goal on level 8:    kill the Queen.

  Your health is fully restored at the start of every level.


-------------------------------------------------------------------------------
7.  ENEMIES
-------------------------------------------------------------------------------

  ALIEN WARRIOR
    Black, glossy and fast, with an elongated skull, silver teeth and a
    long tail. Nobody knows how many of them there are.
    - Takes 3 hits to go down.
    - Notices you when you come within about 8 tiles and comes for you.
    - Spits acid whenever it has a clear line of sight - even from far
      away. The closer it is, the more likely it hits. Walls and closed
      doors block the acid.
    - Slashes with claws and tail in close combat (less than one tile).
    - Every hit takes one unit of your health.
    - When hit, it flashes acid green and stops for a moment.
    - It dissolves into a puddle of acid after about 2.5 seconds and
      leaves a pulse rifle magazine behind (the marines left plenty).

  THE ALIEN QUEEN
    Huge, with a wide crested head, extra arms and very bad manners.
    - Takes 12 hits to go down.
    - Chases, spits and slashes just like her warriors.
    - Glows green when hit.
    - When she falls, she sinks into a pool of her own acid.
      About 2.5 seconds later the victory screen appears.

  Aliens cannot pass through closed blast doors. Once you open a door, it
  stays open, and aliens can follow you through it.


-------------------------------------------------------------------------------
8.  ITEMS AND OBJECTS
-------------------------------------------------------------------------------

  MEDIPACK
    A white box with a red cross.
    - Walk over it to use it.
    - Restores 4 units of health (half of the maximum), up to the maximum
      of 8.
    - It is only used if you are injured. At full health it stays where
      it is, so you can come back for it later.

  PULSE RIFLE MAGAZINE
    An olive green M41A magazine.
    - Walk over it to pick it up: +8 shots (maximum 40).
    - It is only picked up if your rifle is not fully loaded.
    - Every alien you kill leaves one behind.

  TREASURE (CASEY)
    The head of Newt's doll Casey. Newt will want it back.
    - Walk over it to pick it up: +500 points.

  BLAST DOORS
    Grey doors with yellow-and-black hazard stripes and a red light.
    - Face the door from close range (about 1.5 tiles) and press USE
      (SPACE, F, RETURN, ENTER or 2nd fire).
    - The door slides open sideways in a little under a second and stays
      open.

  CARGO ELEVATOR
    A metal cage door framed with yellow-and-black stripes.
    - Face it from close range (about one tile) and press USE.
    - Takes you down to the next level.

  SECRET WALLS
    Some walls look exactly like normal wall panels but can be moved: face
    the wall from close range and press USE. It slides aside like
    a door and reveals a hidden room. Where they are is up to you to find
    out.

  WALL TYPES
    - Ribbed colony wall panels with a hazard stripe
    - Hive wall with a cocooned colonist (don't ask)
    - Computer terminal with green screen and blinking lights
    - Pipes and red valves
    - Hive wall: biomechanical ribs
    - Ventilation grille with a fan (solid)


-------------------------------------------------------------------------------
9.  HEALTH AND GAME OVER
-------------------------------------------------------------------------------

  Your health is shown as a red bar in the top left corner of the screen.
  The maximum is 8 units. Below it, the yellow bar shows your ammunition
  (maximum 40 shots, one small block = 2 shots). You start the game with
  16 shots; ammunition is kept from level to level. With an empty rifle
  you only hear a dry click.

  SCORE
    Alien            100 points
    Treasure         500 points
    Level completed 1000 points
    Alien Queen     5000 points
  Your score is shown between levels, on the automap and at the end of the
  game. The best score (HI-SCORE) is shown on the title screen.

  HALL OF FAME
    The eight best players are kept in the HALL OF FAME. If your score is
    good enough at the end of a game (Game Over or victory), "Name:"
    appears: type up to 8 letters (DEL corrects, RETURN confirms). The list
    is then saved to the disk as HISCORE.DAT and loaded again the next
    time you start the game. Leave the disk in the drive and do not
    write-protect it if you want your scores to be saved; if saving is not
    possible, the list is simply kept until the computer is reset.

    To reset the Hall of Fame to its original entries, type
        RUN"RESHIGH"
    (disk must not be write-protected). Then start the game again with
    RUN"ALIENS".

  - Each alien hit (acid or claws) takes 1 unit. The screen border
    flashes red when you are hit.
  - Medipacks restore 4 units.
  - Health is refilled to 8 at the start of every level.

  Press ESC at any time during the game to abandon it and return to the
  title menu (for example to change the view size). To leave the game
  completely, reset the computer.

  When your health reaches zero, "GAME OVER" appears together with your
  score (and "NEW HI-SCORE!" if you beat the record; see HALL OF FAME for
  entering your name). Press any key or Fire to return to the title screen
  and try again from level 1 - or enter a password to continue on a later
  level.

  TITLE SEQUENCE AND DEMO MODE
  If no key is pressed, the title screen changes every 5 seconds:
    title menu - Hall of Fame - title menu - Hall of Fame - title menu -
    demo.
  Any key brings back the title menu and starts the sequence again. The
  demo is an autopilot that plays through level 1 (opens the door, shoots
  the aliens on its way and takes the elevator). The title music plays in a
  loop while the title screen is shown. Press any key, Fire or move the
  joystick to return to the title screen at once. The demo also
  ends by itself at the elevator. The selected view size is used.

  After killing the Queen you get the victory screen:
    "VICTORY!  The Queen is dead!  Nuke it from orbit"
  Press any key or Fire to return to the title screen.


-------------------------------------------------------------------------------
10. HINTS AND TIPS
-------------------------------------------------------------------------------

  - Keep your distance. Aliens spit acid, but they hit much less
    often from far away. Use corners and doors as cover.
  - Your shot hits whatever is in the middle of the screen. Line up the
    enemy with the centre before firing.
  - An alien that is hit stops for a moment. Keep firing and it will not
    reach you.
  - Save medipacks for later: they are not used while you are at full health.
  - Watch your shots. Collect the magazines the aliens leave behind.
  - Use Q / E to step sideways out of an alien's reach while keeping it in
    your sights.
  - Lost? Press M for the automap.
  - A dead end in a straight corridor or an odd single wall block can hide a
    secret wall. Try USE (SPACE / F / RETURN / 2nd fire).
  - Open doors carefully. Aliens may be waiting in the room behind.
  - On level 8, clear out the warriors before you open the doors to the
    chamber. The Queen needs 12 hits, so you want a full health bar
    for that fight.


-------------------------------------------------------------------------------
11. TECHNICAL DETAILS
-------------------------------------------------------------------------------

  Engine
    - Raycasting engine written entirely in Z80 assembly language.
    - Full-screen 3D view: 160 x 200 pixels in MODE 0 (16 colours).
      80 rays are cast per frame, each ray drawn as 2 pixels wide.
    - Texture-mapped walls: 16 x 16 texel textures, 9 wall types, each with
      a light and a dark variant for the two wall orientations (simple
      lighting).
    - Compiled scalers: for each possible wall height there is a
      specialised, unrolled drawing routine. These routines take about
      61 KB (including the clipped scalers for the smaller view sizes) and
      are stored in the extra 64 KB RAM banks of the CPC 6128.
      They are paged in at &4000-&7FFF while the walls are drawn.
    - Sprites (aliens, the Queen, remains, medipacks, ammunition, treasure)
      are scaled with the distance and clipped against the walls per
      column (depth buffer).
    - Only changed parts of the ceiling and floor are redrawn, which saves
      a lot of time.
    - Sliding doors are handled inside the raycaster: rays pass through the
      part of the door that is already open.
    - Movement and animation are timed with the 50 Hz interrupt, so the
      game runs at the same speed whatever the frame rate.
    - Frame rate on a standard 4 MHz CPC, depending on the scene:
        full view (80 rays)   about 5 - 6 frames per second
        2/3 view  (54 rays)   about 8 frames per second
        1/2 view  (40 rays)   about 11 frames per second
    - Selectable view size: the smaller windows are vertically centred so
      that the normal scalers can be reused unchanged (a wall in a small
      window looks exactly like a more distant wall in the full window).
      Only walls that are taller than the small window use extra, clipped
      scalers (43 for 2/3, 43 for 1/2). Separate ray angle and fish-eye
      correction tables keep the field of view identical.

  Sound
    - Own sound player for the AY-3-8912 sound chip, driven by the
      firmware's 50 Hz interrupt (frame flyback event).
    - Sound effects: rifle shot, acid spit, empty rifle, enemy hit, enemy death,
      player hurt, door, medipack, ammunition and treasure pickup, short
      melodies between levels, on victory and on defeat.
    - Title music: a small three-channel tracker plays an original
      military march in D minor at 125 BPM - lead melody on channel B
      (centre), octave bass on channel C and marching drums (kick, snare rolls,
      hi-hat made from tone and noise) on channel A. Other melodies play on channel B,
      sound effects use all three channels.

  Graphics
    - Custom 16-colour palette (firmware colours):
      0,0,1,26,3,6,12,15,24,1,11,18,16,13,10,20
    - Custom bold character set (96 characters) in classic shooter style, with small capitals for lower case
      letters.
    - The title logo is drawn at runtime from the character set: twice
      as wide, three times as high, with a colour gradient and a drop
      shadow.
    - Title picture (TITLE.SCR) shown by the loader while the game loads.

  Game data
    - 8 levels of 16 x 16 tiles, stored in memory bank 7 behind the last
      block of scalers and copied to a buffer when a level starts
    - Up to 16 objects per level (aliens, medipacks, ammunition, treasure,
      the Queen)
    - Player health: 8 units; alien: 3 hits; the Queen: 12 hits
    - Medipack: +4 health; magazine: +8 shots (max. 40)
    - Score kept as BCD (in hundreds); Hall of Fame (8 names) saved to
      and loaded from HISCORE.DAT (80 bytes)
    - Automap: whenever you enter a new tile, the 3x3 tiles around you
      are marked as explored (256-byte table); no cost for the raycaster

  Memory map (main RAM)
    &0170 - &02FF   BASIC loader (MEMORY &2FF)
    &0300 - &7FFF   Game code, tables, textures, sprites
    &8000 - &8FFF   Sound player, view size module, automap, title and
                    password logic, character set data, title logo routine
    &9000 - &97FF   AMSDOS file buffer (while loading the banks and
                    HISCORE.DAT at start-up)
    &9000 - &96FF   Character matrix table used by the firmware
                    (set up after loading)
    &9700 - &97FF   Enemy AI (line of sight, acid spitting), copied
                    from bank 7 when a game starts
    &9800 - &9BFF   Quarter-square multiplication tables (built at start-up)
    &9C00 - &9CFF   Automap: explored tiles
    &9D00 - &9EFF   Buffer for the current level
    &9800 - &9FFF   AMSDOS file buffer when saving HISCORE.DAT
                    (tables are rebuilt afterwards)
    &C000 - &FFFF   Screen memory
    Banks 4-7       Compiled scalers (SC0.BIN - SC3.BIN); bank 7 also
                    holds the 8 levels

  Development
    - Assembled with RASM.
    - Textures, sprites, levels, font and scaler code are generated by
      Python scripts, then assembled and written to the disk image.


-------------------------------------------------------------------------------
12. FILES ON THE DISK
-------------------------------------------------------------------------------

    ALIENS.BAS     BASIC loader (start with RUN"ALIENS")
    TITLE.SCR      Title picture (loaded to &C000, palette routine at &C7D0)
    ALIENS.BIN     Main program (loaded to &0300, about 35 KB)
    SC0.BIN        Compiled wall scalers, part 1 (memory bank 4)
    SC1.BIN        Compiled wall scalers, part 2 (memory bank 5)
    SC2.BIN        Compiled wall scalers, part 3 (memory bank 6)
    SC3.BIN        Compiled wall scalers, part 4, and the 8 levels
                   (memory bank 7)
    HISCORE.DAT    Hall of Fame (8 names and scores, 80 bytes)
    RESHIGH.BAS    Resets the Hall of Fame (start with RUN"RESHIGH")
    RESHIGH.BIN    Reset program (loaded to &4000 by RESHIGH.BAS)


===============================================================================
                  Aliens  -  Hadley's Hope  -  2026 by Devil-System
===============================================================================
