feat: mods and missions choose which ships the player can land on

docs/engine/camera.md

@@ -195,8 +195,8 @@ launch tube the ship lands in, which the landing keeps, turned as the carrier is
 The display names view `0x23`, but not `0x26`. **Improvement:** from within the tube, the sound is
 heard as in a hangar ([Sound](../port/sound.md)).
 
-**Improvement:** a landing in a hangar bay ([Landing](orders.md#landing)) picks one of the same
-two views, which stand by the bay instead, in the frame of the launch point of the gate the ship
+**Improvement:** a landing in a hangar bay or in the Badanov's bay ([Landing](orders.md#landing))
+picks one of the same two views, which stand by the bay instead, in the frame of the place the ship
 lands at. They go by the ship and the bay rather than by fixed distances, so that they frame a
 landing on any carrier. View `0x23` stands in the bay off the launch point, by the landing ship's
 radius: one radius to the right, a third of one above and one and three quarters out towards the

docs/engine/launch.md

@@ -129,8 +129,9 @@ fire](orders.md#friendly-fire)) go by it.
 
 **Improvement:** the game records the player's carrier only in the Reliant's and the Yamato's
 launches, the only ones the original's missions give the player. OpenReliant records it as any
-launch of the player's ship starts (`launch.init`), so that PERMISSION TO LAND and the bridge's
-lines work from any carrier a mission launches the player from, such as a mod's.
+launch of the player's ship starts (`launch.init`), so that the bridge's lines work from any
+carrier a mission launches the player from, such as a mod's. PERMISSION TO LAND lands the ship
+only where that carrier offers a landing ([Landing](orders.md#landing)).
 
 The hangar (`reliant_hang.shp`, type `0xD6`) is made in the cutaway slot, colliding with nothing,
 its hull and its two doors reached by no light of the backdrop's but the first ambient (light mask
@@ -315,6 +316,10 @@ From step 2 (`launch_badanov_run`, `0x0041A100`):
 **Fix:** if the model lacks the bay or its level, OpenReliant leaves the ship in place,
 riding the carrier's root. The original dereferences the missing part.
 
+A landing in the bay, where a mod or a mission's script lets the player land on the Badanov or the
+Krasny, comes to rest where a ship waits at the gate, through doors 1 and 2
+([Landing](orders.md#landing)).
+
 ## The escape pods
 
 Both escape pods use `launch_point_init` (`0x0041A4B0`) to wait at the launch point selected

docs/engine/orders.md

@@ -758,14 +758,30 @@ of a door closing (`0x36`, `doorclos`).
 PERMISSION TO LAND does nothing where the player's ship launched from no carrier, where the game
 reads through a null pointer.
 
-**Improvement:** the player's ship lands in a hangar bay of any other carrier that ships launch
-from as one ([Hangar bays](launch.md#hangar-bays)), the Victorious or a mod's carrier among them,
-so that PERMISSION TO LAND ends a mod's mission on the carrier the mission launched the player
-from. The landing aims at a gate: the component of its order's target, which a mission's `SetAI`
+**Improvement:** the game lands only on the Reliant and the Yamato, by their types. OpenReliant
+lands on a ship that offers a landing (`ailand.Style`): `reliant`, `yamato`, `bay` or `badanov`.
+Each ship type's record says which one it offers (`ShipTypeRecord.landing`). The Reliant and the
+Yamato offer theirs, as in the game, and no other type offers one. A mod's ship type can give its
+own ([Ship types](../guide/modding.md#ship-types)), and a mission's script can change it for a
+single ship ([Landing on another carrier](../guide/missions.md#landing-on-another-carrier)).
+This holds for every Land order, whether PERMISSION TO LAND, a mission's `SetAI` or the friendly
+fire's sending home gives it. A Land order aimed at a ship that offers none ends at once, and so
+does one aimed at a ship whose model lacks what its landing needs: the Reliant's first launch tube,
+a bay's launch point for the gate, or the Badanov's bay. PERMISSION TO LAND asks nothing where the
+player's carrier offers none, and the friendly fire's sending home lets the ship fly on, as where
+there is no carrier. A script can make another ship the player's carrier
+(`world.set_player_carrier`), and answer PERMISSION TO LAND its own way (the `permission_to_land`
+hook). The game's missions launch the player only from the Reliant and the Yamato, so they land as
+they do in the game.
+
+**Improvement:** a ship that offers a bay's landing (`bay`) takes the player's ship into a hangar
+bay that ships launch from ([Hangar bays](launch.md#hangar-bays)), such as the Victorious or a
+mod's carrier, so that PERMISSION TO LAND can end a mod's mission there. The landing aims at a
+gate: the component of its order's target, which a mission's `SetAI`
 names with `component(carrier, gate)`, or gate 0 when the order aims at the carrier as a whole, as
 the player's request does. Aimed at the whole carrier, the landing is due 700 ticks on, as the
 Reliant's is; aimed at a gate, it begins at once, so that a mission's script lands the ship at its
-own moment. A carrier whose model has no launch point for the gate is one that nothing lands on.
+own moment.
 A ship other than the player's lets the landing go at once, as on the Yamato.
 
 The cutaway is the Reliant's: one of its two views, picked at random, standing by the bay
@@ -779,6 +795,11 @@ point, upright, its throttle 0.0001 for each unit it has to go, at most the thro
 at the Yamato's bay speed of 100, and stops within 200 of the point, sounding its landing. The
 doors close behind it, and 270 ticks later the mission is over.
 
+**Improvement:** the Badanov's landing (`badanov`) is the same in the Badanov's or the Krasny's bay
+([The Badanov and the Krasny](launch.md#the-badanov-and-the-krasny)). The ship comes to rest where
+the launch sets a ship at the gate, and the bay's doors, parts 1 and 2, open and close as a hangar
+bay's do.
+
 The Yamato's style lands the ship in the Yamato's landing bay, ship type `0xD5` (Jap Yam Landing
 Bay, `yamhanger.shp`), whose part 6 is the hangar and part 1 the pad. Its init
 (`land_yamato_init`, `0x0040EB60`) sets the first step, due in 700 ticks, and for the player's ship
@@ -809,7 +830,7 @@ leaves the ship turned as it was.
 
 **Improvement:** the angles come from `std.math.atan2` rather than the engine's table (`sr_atan2`).
 OpenReliant has no parent frames, so the ship on the pad is put back on it each frame
-(`ailand.hold`), as the launches hold their ships ([Launches](launch.md)).
+(`ailand.yamato.hold`), as the launches hold their ships ([Launches](launch.md)).
 
 ### Friendly fire
 

docs/engine/radio.md

@@ -177,6 +177,11 @@ answer 300 ticks on:
   from `_lnd_017` to `_lnd_024` for any other; refusing it, from `_lnd_den_01` to `_lnd_den_04`.
   It also writes "DEBUG: Mission is flagged as a" and the rating's name into a line nothing shows.
 
+**Improvement:** outside training, OpenReliant asks only where the player's carrier offers a
+landing, and asks nothing otherwise ([Landing](orders.md#landing)). A ship type can't name a bridge
+officer of its own yet, so any carrier other than a Yamato answers with the Reliant's officer, a
+mod's carrier too ([#1340](https://github.com/OpenReliant/openreliant/issues/1340)).
+
 ## The wingmen's commands
 
 ATTACK MY TARGET (`0x00454C20`), BACK OFF (`0x00454FA0`) and HELP ME (`0x00455330`) go to the

docs/guide/missions.md

@@ -413,9 +413,36 @@ The objectives' names come from the game's table, which has a row for each of th
 - `TerminateMission()` ends it too. In the missions numbered below 28, the game then counts the
   player's ship as destroyed.
 - `game.landing_cleared = 1` lets the player land on the carrier with PERMISSION TO LAND, which ends
-  the mission.
+  the mission. The carrier is the ship the player launched from, and it has to offer a landing: the
+  Reliant and the Yamato do, as in the game, and any other ship only where a mod or a script gives
+  it one ([Landing on another carrier](#landing-on-another-carrier)).
 - The mission also ends once the player's ship is destroyed.
 
+### Landing on another carrier
+
+A mission that launches the player from another carrier, such as the Victorious or the Badanov, can
+let the player land there with a script of its own. A mod lists it under `[Missions]` beside the
+mission ([Scripting](scripting.md)), and the script gives the carrier a landing as it joins the
+mission:
+
+```lua
+return {
+    engine_handlers = {
+        on_object_added = function(object)
+            if object.type == "victorious" then object.landing = "bay" end
+        end,
+    },
+}
+```
+
+- `landing` takes the values of a ship type's `Landing` ([Ship types](modding.md#ship-types)), such
+  as `bay` for a hangar bay. Nil keeps the player from landing on the ship, even on the Reliant.
+- `world.set_player_carrier(ship)` makes another ship the one PERMISSION TO LAND asks, such as a
+  carrier that jumps in later. Until then, it is the ship the player launched from, if any.
+- A mod's own carrier type gives its landing in its section ([Ship types](modding.md#ship-types)),
+  and a load script can give every ship of one of the game's types a landing:
+  `records.ship_types.victorious.landing = "bay"`.
+
 ## Checking a mission
 
 `openreliant missions` lists the missions, the mods' among them, and checks that each loads:

docs/guide/modding.md

@@ -965,12 +965,31 @@ its own launches them as a hangar bay: each ship waits at the launch point of it
 `launch_point` object of the model ([Models from OBJ](#models-from-obj)), and flies out once its
 launch starts.
 
-PERMISSION TO LAND brings the player's ship back into such a carrier the same way, once the
-mission's script has cleared it to land (`game.landing_cleared = 1`): the carrier's bridge answers,
-and the ship flies in at the doors of gate 0 and down to its launch point, which ends the mission.
-A mission can land the ship at another gate, and at a moment of its own, with
+The player's ship lands only on a ship that offers a landing. A type's `Landing` says how the
+player's ship lands on it:
+
+- `bay`: the ship flies in at the doors of a gate and down to its launch point, as into a hangar
+  bay. The model needs `launch_point` objects ([Models from OBJ](#models-from-obj)).
+- `reliant`: the Reliant's landing, down its first launch tube, which needs the Reliant's model.
+- `yamato`: the Yamato's landing, onto a pad of the Yamato's landing bay.
+- `badanov`: the Badanov's landing, into the bay of the Badanov's or the Krasny's model.
+- `none`: no landing.
+
+Where the model lacks what its landing needs, nothing lands on it, and the log says so.
+
+Without the key, a type that keeps its base's model offers its base's landing, so a type based on
+the Reliant lands the player as the Reliant does. A type with a model of its own offers none.
+
+Where the player's carrier offers a landing, PERMISSION TO LAND brings the player's ship back into
+it once the mission's script has cleared it to land (`game.landing_cleared = 1`): the carrier's
+bridge answers, and the ship lands, which ends the mission. The Yamato's bridge officer answers for
+a Yamato and the Reliant's for any other carrier, a mod's too
+([#1340](https://github.com/OpenReliant/openreliant/issues/1340)). In a bay, the ship flies in at
+gate 0. A mission can land the ship at another gate, and at a moment of its own, with
 `SetAI(player, "land", 1, component(carrier, gate))`
-([Landing](../engine/orders.md#landing)).
+([Landing](../engine/orders.md#landing)). A mission can also let the player land on a ship that
+offers no landing, such as the Victorious, or keep the player off one that does
+([Landing on another carrier](missions.md#landing-on-another-carrier)).
 
 #### Ship types without a base