Docking, and a ceiling that is no longer the old screen's edge

The station can be docked with: close enough, and slow enough RELATIVE TO
IT, or it is a wreck. Its speed is orbital speed, which is what the marks
on the drift bar point at, so the instrument for this was on the screen
before there was anything to dock with. A dock pays eighty units of fuel,
once and not once a frame, and holds the lander a tile under the station
until a thruster lets go - checked before the speeds are put back, or a
burn would be wiped on the frame it was made and the lander could never
leave.

---- And the ceiling went up, which is what made it work ----

Sixty four pixels was the whole of the sky a forty column screen had over
the world's origin. It was never a fact about the world, it was a fact
about the view, and the wide one starts twenty four rows higher: a lander
stopped at the old line was stopped a long way short of the top of its own
picture for no reason it could see. It is 192 pixels now, the top of the
wide view.

The station went from four rows up to twelve - about two thirds of the way
from the ground to the ceiling. At four it sat exactly where anything
climbing away from the surface had to pass, and being run down there is
not a hazard, it is a toll: ELEVEN of this suite's flights were being run
down as collateral, including the ceiling check, which has to climb past
it to reach the ceiling at all. Moving both fixed all eleven at once.

The height bar divides by sixty four rather than thirty two, because the
band it describes is 368 pixels now and half a pixel of bar to a pixel of
sky would stand 184 tall and run off the top of the forty column screen it
is drawn beside.

---- What is checked, and what is written down instead ----

The wreck is flown. The fixture is narrow - the window measured 496 to 514
frames of climb and it sits at 505 - and that is said in place, along with
the instruction to re-measure before believing the code is broken. It was
not always narrow: at the old altitude any climb from 135 to 300 frames
struck. Narrow is the right way round, because it means the station is
hard to blunder into.

The successful dock is NOT flown, and ninety six pad files failed to find
it. That is not the search's fault: climbing spends sideways speed, so a
lander cannot rise while matched. It is measured working instead - tank
100 to 180, message up, and the pair holding together one tile apart for
two hundred and forty frames.

Programs/CosmOS/Apps/Lander.asm

@@ -103,6 +103,7 @@ everyFrame:
   CALL moveStation
   CALL follow
   CALL touchdown
+  CALL dock
   CALL showLander
   CALL showStation
   CALL showDrift
@@ -750,7 +751,10 @@ fall:
   LDA.1
   SETD.1 FallTick
   STA.1
-  ; Gravity does not pull on a lander that is already sitting on the ground.
+  ; Gravity does not pull on a lander that is sitting on the ground or holding onto something.
+  SETD.0 Docked
+  LDA.0
+  BNA fallResting
   SETD.0 Landed
   LDA.0
   BNA fallResting
@@ -1124,6 +1128,13 @@ move:
   ; kept going came back through the bottom and hit the ground FROM ABOVE. Two thousand pixels
   ; of climb is a long way and entirely reachable with a full tank.
   ;
+  ; ---- And it is 192 pixels up, not 64, because the screen grew ----
+  ;
+  ; Sixty four was the whole of the sky a forty column screen had over the world's origin, so
+  ; it was never a fact about the world - it was a fact about the view. The wide one starts
+  ; twenty four rows higher, and a lander stopped at the old line was stopped a long way short
+  ; of the top of its own picture for no reason it could see.
+  ;
   ; Pinned rather than ended. Leaving upward is RECOVERABLE - gravity is always available and
   ; a lander with fuel can always come back - so stopping the run there would punish a state
   ; the player can fly out of. What kills you out here is running dry a long way from the
@@ -1139,10 +1150,10 @@ move:
   AND
   BRQ moveInside            ; The height is positive, so it is somewhere below the top.
   LDA.0                     ; DP0 is still DownHigh, from the sign test.
-  INIB 0xFD
+  INIB 0xF5
   CCF
   SUB
-  BRC moveAdrift            ; Borrowed: at 0xFC00 or above it, which is 64 pixels over the top.
+  BRC moveAdrift            ; Borrowed: at 0xF400 or above it, 192 pixels over the world's top.
 
 moveInside:
   ; Back under the ceiling, so the warning goes if there was one.
@@ -1161,7 +1172,7 @@ moveAdrift:
   ; is left alone, so gravity has somewhere to move it to.
   SETD.0 DownHigh
   LDA.0
-  INIB 0xFC
+  INIB 0xF4
   CCF
   SUB
   BNC moveAdriftSaid        ; No borrow, so it is at the ceiling and not past it.
@@ -1169,7 +1180,7 @@ moveAdrift:
   RSTA
   SETD.0 DownLow
   STA.0
-  INIA 0xFC
+  INIA 0xF4
   SETD.0 DownHigh
   STA.0
 
@@ -1775,6 +1786,210 @@ touchdownStop:
 touchdownDone:
   RET
 
+; ---- Docking, which is landing on something that is moving ----
+;
+; The same shape as touchdown and for the same reason: close enough, and slow enough, or it is
+; a wreck. What makes it a different skill is that "slow enough" is measured against the
+; STATION rather than against nothing. Its speed is orbital speed, which is the number the
+; marks on the drift bar point at - so the instrument for this was already on the screen
+; before there was anything to dock with.
+;
+; The tolerances are the ground's own, deliberately, so there is one number to argue with if
+; this turns out to be too kind.
+dock:
+  SETD.0 Docked
+  LDA.0
+  BNA dockRiding
+
+  ; ---- Close enough, going round ----
+  ;
+  ; Wrapped to fourteen bits like everything else on this moon, which measures the long way
+  ; round when the station is behind, so past the half way point is turned into a distance
+  ; backwards before its size is taken.
+  SETD.0 StationLow
+  LDA.0
+  SETD.1 AcrossLow
+  LDB.1
+  CCF
+  SUB
+  SETD.1 DockGapLow
+  STQ.1
+  SETD.0 StationHigh
+  LDA.0
+  SETD.1 AcrossHigh
+  LDB.1
+  SUB
+  MVQA
+  INIB 0x3F
+  AND
+  SETD.1 DockGapHigh
+  STQ.1
+  LDA.1
+  INIB 0x20
+  AND
+  BRQ dockGapNear
+  SETD.0 DockGapHigh
+  LDA.0
+  INIB 0x40
+  CCF
+  SUB
+  STQ.0
+dockGapNear:
+  SETD.0 DockGapLow
+  CALL magnitude
+  SETD.0 DriftHigh
+  LDA.0
+  BNA dockDone
+  SETD.0 DriftLow
+  LDA.0
+  INIB 0d128
+  CCF
+  SUB
+  BNC dockDone              ; A whole tile away or more, so there is nothing to touch.
+
+  ; ---- And close enough, up and down ----
+  SETD.0 StationDownLow
+  LDA.0
+  SETD.1 DownLow
+  LDB.1
+  CCF
+  SUB
+  SETD.1 DockRiseLow
+  STQ.1
+  SETD.0 StationDownHigh
+  LDA.0
+  SETD.1 DownHigh
+  LDB.1
+  SUB
+  SETD.1 DockRiseHigh
+  STQ.1
+  SETD.0 DockRiseLow
+  CALL magnitude
+  SETD.0 DriftHigh
+  LDA.0
+  BNA dockDone
+  SETD.0 DriftLow
+  LDA.0
+  INIB 0d128
+  CCF
+  SUB
+  BNC dockDone
+
+  ; ---- Touching. Now, how fast, and RELATIVE TO WHAT ----
+  ;
+  ; The station is going at orbital speed, so a lander going at orbital speed is standing still
+  ; beside it however fast the ground below says they are both travelling. That difference is
+  ; the whole of the manoeuvre.
+  SETD.0 SpeedAcross
+  LDA.0
+  INIB 0d64
+  CCF
+  SUB
+  SETD.1 DockVxLow
+  STQ.1
+  INCD.0
+  LDA.0
+  RSTB
+  SUB                       ; And the borrow, which is the other half of the difference.
+  SETD.1 DockVxHigh
+  STQ.1
+  SETD.0 DockVxLow
+  CALL magnitude
+  SETD.0 DriftHigh
+  LDA.0
+  BNA dockStruck
+  SETD.0 DriftLow
+  LDA.0
+  SETD.1 GentleAcross
+  LDB.1
+  CCF
+  SUB
+  BNC dockStruck
+
+  ; Downwards, where the station has no speed at all, so the difference is simply the fall.
+  SETD.0 SpeedDown
+  CALL magnitude
+  SETD.0 DriftHigh
+  LDA.0
+  BNA dockStruck
+  SETD.0 DriftLow
+  LDA.0
+  SETD.1 GentleDown
+  LDB.1
+  CCF
+  SUB
+  BNC dockStruck
+
+  ; ---- Aboard ----
+  INIA 0x01
+  SETD.0 Docked
+  STA.0
+  CALL payFuel
+  SETD.0 DockedText
+  CALL sayInWindow
+  CALL waitKey
+dockDone:
+  RET
+
+dockStruck:
+  SETD.0 StruckText
+  BRI touchdownStop         ; Which settles the view, says it, and ends the run.
+
+; ---- Riding, until something is leaned on ----
+;
+; Held to the station rather than merely paid by it, because that is what docking IS. The
+; speeds are the station's, so the pair drift round together, and the lander sits one tile
+; under it so both are still visible.
+;
+; ANY thruster lets go. It has to be checked before the speeds are put back, or a burn would
+; be wiped by the snap on the very frame it was made and the lander could never leave.
+dockRiding:
+  SETD.0 Held
+  LDA.0
+  INIB 0x0F
+  AND
+  BNQ dockLetGo
+
+  SETD.0 StationLow
+  LDA.0
+  SETD.1 AcrossLow
+  STA.1
+  SETD.0 StationHigh
+  LDA.0
+  SETD.1 AcrossHigh
+  STA.1
+  SETD.0 StationDownLow
+  LDA.0
+  INIB 0d128
+  CCF
+  ADD
+  SETD.1 DownLow
+  STQ.1
+  SETD.0 StationDownHigh
+  LDA.0
+  RSTB
+  ADD                       ; One tile below it, carry included.
+  SETD.1 DownHigh
+  STQ.1
+
+  INIA 0d64
+  SETD.0 SpeedAcross
+  STA.0
+  RSTA
+  INCD.0
+  STA.0                     ; Orbital speed exactly, which is what it is riding.
+  SETD.0 SpeedDown
+  STA.0
+  INCD.0
+  STA.0
+  RET
+
+dockLetGo:
+  RSTA
+  SETD.0 Docked
+  STA.0
+  RET
+
 ; ---- A key, or a button ----
 ;
 ; Somebody flying on a controller should not have to reach for the keyboard to say "yes, I
@@ -1850,22 +2065,26 @@ showHeight:
   AND
   BNQ showHeightNone        ; Negative: the feet are under the surface, so there is no sky.
   LDA.0                     ; The AND left A alone, so it still holds the high half.
-  INIB 0d16
+  INIB 0d32
   CCF
   SUB
-  BNC showHeightFull        ; 4,096 sixteenths or more, which is the whole bar and then some.
+  BNC showHeightFull        ; 8,192 sixteenths or more, which is the whole bar and then some.
 
   LDA.0                     ; DP0 still names the high half, and the compare did not touch A.
   SETD.0 HeightLow
   LDB.0
   SHL
-  SHL
+  SHL                       ; ---- Over sixty four, which comes out in A ----
-  SHL                       ; ---- Over thirty two, which comes out in A ----
                             ;
-                            ; A is the HIGH half of the shift register, so three turns LEFT of
+                            ; A is the HIGH half of the shift register, so two turns LEFT of
-                            ; the whole sixteen bits leaves bits five to twelve in A - which is
+                            ; the whole sixteen bits leaves bits six to thirteen in A - which
-                            ; the height over thirty two, in one instruction each and no
+                            ; is the height over sixty four, in one instruction each and no
                             ; division anywhere.
+                            ;
+                            ; Over sixty four rather than thirty two because the ceiling moved:
+                            ; the band is 368 pixels now, and half a pixel of bar to a pixel of
+                            ; sky would stand 184 tall and run off the top of the forty column
+                            ; screen it is drawn beside.
   BRI showHeightReady
 showHeightFull:
   INIA 0d127
@@ -2775,6 +2994,21 @@ Carrying:
   0x00
 Landed:
   0x00
+; Holding onto the station, which is the same kind of rest as sitting on the ground.
+Docked:
+  0x00
+DockGapLow:
+  0x00
+DockGapHigh:
+  0x00
+DockRiseLow:
+  0x00
+DockRiseHigh:
+  0x00
+DockVxLow:
+  0x00
+DockVxHigh:
+  0x00
 
 ; Whether the lander is pinned against the ceiling, so the warning is said once rather than
 ; sixty times a second and taken away when it comes back down.
@@ -2796,6 +3030,10 @@ EmptyText:
   0x00
 CrashedText:
 "Crashed."
+DockedText:
+"Docked. Eighty units of fuel."
+StruckText:
+"Wrecked against the station."
 
 ; ---- The station, which is a body and not a special case ----
 ;
@@ -2817,7 +3055,14 @@ StationHigh:
 StationDownLow:
   0x00
 StationDownHigh:
-  0xFE                      ; Minus 512 sixteenths, which is four rows up.
+  0xFA                      ; ---- Minus 1,536 sixteenths, which is twelve rows up ----
+                            ;
+                            ; About two thirds of the way from the ground to the ceiling. It
+                            ; was four rows up when four rows was most of the sky there was,
+                            ; which put it exactly where anything climbing away from the
+                            ; surface had to pass - and being run down there is not a hazard,
+                            ; it is a toll. Twelve rows up is clear of work near the ground and
+                            ; still a dozen rows under the ceiling.
 StationSpeed:
   0x40 0x00                 ; Orbital speed, and the whole of its behaviour.
 

Tests/expected/cosmosCrossDisk.out

@@ -25,7 +25,7 @@ Mode.sbx                48
 Flip.sbx                173
 Sprite.sbx              442
 Depth.sbx               672
-Lander.sbx              5823
+Lander.sbx              6290
 Pad.sbx                 264
 Crash.sbx               632
 vars.script             50

Tests/expected/cosmosDrives.out

@@ -15,7 +15,7 @@ Mode.sbx                48
 Flip.sbx                173
 Sprite.sbx              442
 Depth.sbx               672
-Lander.sbx              5823
+Lander.sbx              6290
 Pad.sbx                 264
 Crash.sbx               632
 vars.script             50

Tests/expected/cosmosFault.out

@@ -32,7 +32,7 @@ Mode.sbx                48
 Flip.sbx                173
 Sprite.sbx              442
 Depth.sbx               672
-Lander.sbx              5823
+Lander.sbx              6290
 Pad.sbx                 264
 Crash.sbx               632
 vars.script             50

Tests/expected/cosmosFlip.out

@@ -22,7 +22,7 @@ Mode.sbx                48
 Flip.sbx                173
 Sprite.sbx              442
 Depth.sbx               672
-Lander.sbx              5823
+Lander.sbx              6290
 Pad.sbx                 264
 Crash.sbx               632
 vars.script             50

Tests/expected/cosmosGrid.out

@@ -22,7 +22,7 @@ Mode.sbx                48
 Flip.sbx                173
 Sprite.sbx              442
 Depth.sbx               672
-Lander.sbx              5823
+Lander.sbx              6290
 Pad.sbx                 264
 Crash.sbx               632
 vars.script             50

Tests/expected/cosmosMonitor.out

@@ -108,7 +108,7 @@ Mode.sbx                48
 Flip.sbx                173
 Sprite.sbx              442
 Depth.sbx               672
-Lander.sbx              5823
+Lander.sbx              6290
 Pad.sbx                 264
 Crash.sbx               632
 vars.script             50

Tests/expected/cosmosMonitorRun.out

@@ -27,7 +27,7 @@ Mode.sbx                48
 Flip.sbx                173
 Sprite.sbx              442
 Depth.sbx               672
-Lander.sbx              5823
+Lander.sbx              6290
 Pad.sbx                 264
 Crash.sbx               632
 vars.script             50

Tests/expected/cosmosRun.out

@@ -15,7 +15,7 @@ Mode.sbx                48
 Flip.sbx                173
 Sprite.sbx              442
 Depth.sbx               672
-Lander.sbx              5823
+Lander.sbx              6290
 Pad.sbx                 264
 Crash.sbx               632
 vars.script             50

Tests/expected/cosmosSlowDisk.out

@@ -13,7 +13,7 @@ Mode.sbx                48
 Flip.sbx                173
 Sprite.sbx              442
 Depth.sbx               672
-Lander.sbx              5823
+Lander.sbx              6290
 Pad.sbx                 264
 Crash.sbx               632
 vars.script             50

Tests/expected/cosmosSprite.out

@@ -22,7 +22,7 @@ Mode.sbx                48
 Flip.sbx                173
 Sprite.sbx              442
 Depth.sbx               672
-Lander.sbx              5823
+Lander.sbx              6290
 Pad.sbx                 264
 Crash.sbx               632
 vars.script             50

Tests/video.sh

@@ -2347,6 +2347,53 @@ MOVED=$(( X3 - X2 ))
     && result ok "and round the back of the moon and out again" "gone, then back at $X7" \
     || result no "and round the back of the moon and out again" "$X5 at five million, $X7 at seven"
 
+# ---- Docking, and the half of it that can be flown to ----
+#
+# The same shape as touchdown: close enough, and slow enough, or it is a wreck. What makes it
+# a different skill is that "slow enough" is measured against the STATION, which is doing
+# orbital speed - the number the marks on the drift bar already point at.
+#
+# ---- A NARROW FIXTURE, and it is written down rather than hidden ----
+#
+# The climb here has to arrive at the station's altitude just as the station arrives at the
+# lander, and the window measured 496 to 514 frames - about nineteen. 505 sits in the middle
+# of it. That is thinner than this suite likes and it is the same shape as the orbit check
+# that had to be deleted for measuring the boot time, so: IF THIS EVER FAILS, re-measure the
+# window before believing the code is broken.
+#
+# It was not always narrow. The station used to orbit four rows up, where anything climbing
+# away from the surface had to pass, and a strike could be had with any climb between 135 and
+# 300 frames - eleven of this suite's other flights were being run down as collateral. Moving
+# it to twelve rows and the ceiling to twenty four fixed all eleven at once, and made the
+# station properly hard to blunder into. The narrow window is the price of that, and it is the
+# right way round.
+python3 -c "open('$BUILD/struck.pad','wb').write(b'\x08' * 505 + b'\x00' * 60000)"
+timeout 60 "$EMU" --fast --cycles 40000000 --keyboard "$BUILD/fly.keys" \
+    --pad "$BUILD/struck.pad" --disk "$ROOT/Tests/build/disks/cosmos.img" \
+    --ram-disk 2048 "$BUILD/cosmos.bin" > "$BUILD/struck.out" 2>&1 || true
+grep -q "Wrecked against the station" "$BUILD/struck.out" \
+    && result ok "the station runs down a lander in its lane" "at 64 sixteenths of relative speed" \
+    || result no "the station runs down a lander in its lane" "no wreck in the transcript"
+
+# ---- And the half that is not checked here ----
+#
+# THE SUCCESSFUL DOCK IS NOT FLOWN. It was measured working, from a build that PLACED the
+# lander alongside the station and matched: the tank went from 100 to 180, once and not once a
+# frame, the message went up, and the pair then held together - lander at 316,168 and station
+# at 320,160, one tile apart and unmoving for two hundred and forty frames, which is what
+# riding looks like. A thrust in any direction let go of it.
+#
+# What could not be found was a pad file that flies there. Ninety six were tried and every one
+# either hit the moon or was run down on the way UP, which turns out not to be the search's
+# fault: climbing SPENDS sideways speed, by the exchange that makes the orbit work at all, so
+# a lander cannot rise while matched - it arrives slower than orbital every time. Docking needs
+# two burns, one to raise the far side of the orbit and one to circularise at the top, and no
+# straight line of button presses stumbles into that.
+#
+# So it wants either a hand flown recording or, better, a way to PLACE the lander at a chosen
+# position and velocity before the loop starts - which is now wanted by this, by the orbit
+# above, by the ride, and by the narrow window three paragraphs up.
+
 # ---- Clearing puts the cursor back at the top ----
 #
 # A screen with nothing on it and a cursor half way down it is not a cleared screen. This