Shuttle Mapping

Guide taken from Nebula's wiki originally by @afterthought2

---

This page covers how to set up shuttles for use with the overmap system, as well as covers the features currently available. If mapping legacy ferry-like shuttles or not using the overmap, much of this guide will not apply.

To establish terminology: a shuttle is a collection of areas which is capable of moving at runtime using the shuttle system. It is attached to a shuttle datum, described below. A ship is an overmap entity, representing the overmap position of some collection of areas; if that collection of areas is a shuttle, such a ship is called landable.

The physical shuttle

The physical shuttle is a collection of areas placed in physical, player-facing space. When mapping it, that is how it must be mapped: use one or more unique areas which cover the entirety of the shuttle and nothing else, and place it somewhere that players will have access to.

The shuttle should probably be walled off, have an airlock, atmospherics, and so on. For setting up docking for a shuttle, if relevant, see the next sections. A shuttle should almost certainly contain exactly one shuttle control computer: /obj/machinery/computer/shuttle; if it will be interacting with the overmap, the /obj/machinery/computer/shuttle_control/explore is the correct subtype for shuttles which interact with the overmap. You will also need to map obj/structure/fuel_port for shuttles which use fuel; this is usually mapped over a wall turf.

If you are mapping a shuttle attached to an overmap ship, then in addition you will need ship equipment: engine, helm, and sensor controllers, a sensors object (placed externally, but still within the shuttle area), and thrusters attached to a gas canister or other gas source.

No id-like variables need special setting on any of these objects; they will be located and hooked up to the relevant systems on the basis of them being located inside the shuttle's areas.

If a shuttle is mapped inside a larger, pressurized, location, it will work fine, but will decrease pressure when leaving. If there is a pipe network with members both inside and outside of the shuttle, it will not be properly rebuilt (as of the time of writing), so this is best avoided.

Shuttle datums

The next step is to create a shuttle datum. Here we assume you are creating overmap-using shuttles; if not, the procedure is similar but a different subtype needs to be used, like autodock/ferry.

/datum/shuttle/autodock/overmap/foo
	name = "foo"
	shuttle_area = list(/area/my_areas, ...)
	fuel_consumption = Z
	range = W
	warmup_time = X
	move_time = Y
	multiz = U

Fill in these variables. It is essential that the name is unique across all shuttles. The area var is either a single area path or list of paths, containing the areas you used when mapping it. Fuel consumption effects how much fuel it uses; set it to 0 if you did not map a fuel port. range is how many turfs away from its overmap location it can move (using shuttle movement); setting it to 0 means it can only move to landmarks on its current overmap turf. move_time is how long it spends at the transition waypoint; if you do not wish to map such a waypoint, set it to 0. Set multiz if your shuttle spans multiple z levels to (number of contiguous z levels occupied) - 1.

Shuttle waypoint landmarks

You will now need to map at least one, and possibly several, shuttle landmarks. First:

/datum/shuttle/autodock/overmap/foo
	current_location = "unique_tag_1"
	landmark_transition = "unique_tag_2"

/obj/effect/shuttle_landmark/bar
	name = "bar"
	landmark_tag = "unique_tag_1"
	base_area = preferred_area
	base_turf = preferred_turf

Then position this landmark somewhere on the map. The location matters: as the shuttle moves, its location relative to its initial current_location landmark will be preserved (relative to the landmark it's at). Usually that means you can place it somewhere inside or outside the shuttle, ideally on its main external airlock or next to it so the shuttle can better take advantage of already mapped in docking ports. In delicate docking setups you may need to carefully place several landmarks in precise positions.

The base_turf and base_area variables are the turf and area types you wish to have spawn there when your shuttle leaves. On other landmarks you can arrange for them to be autoset, but for this first one you should specify them explicitly. The name is player-facing.

Next, if you wish a shuttle to be able to move to this landmark, you must place it into a list of landmarks that the sector containing it possesses. There are two ways to do this, but let us only look at the manual one here:

• First, figure out which overmap entity should control the landmark. This will usually be the overmap entity corresponding to the station, base, ship, or whatever that your shuttle will be docked at. It is a subtype of /obj/effect/overmap/visitable.
• Next, decide if you want this landmark to be usable only for your shuttle, or for any shuttle.
• If for any shuttle, add it to the list

/obj/effect/overmap/visitable/baz
	initial_generic_waypoints = list(
		"unique_tag_1",
		...
		)

• If for only your shuttle, instead add it like this:

/obj/effect/overmap/visitable/baz
	initial_restricted_waypoints= list(
		"shuttle_name" = list("unique_tag_1", ...),
		...
		)

Next, decide if you wish your shuttle to spend time in transit. If you do, you must map a transit landmark as well, similar to the this first one. It should be mapped on a z level containing space and little else (players will go there), does not need base_area/base_turf set, and should not be added to any lists.

Finally, if you want some more landmarks that only your shuttle can go to, create them, map them, and add them to initial_restricted_waypoints as above. Otherwise, it will only use generic landmarks.

Some more comments: if your landmark is next to an airlock and you want the shuttle to dock (as in, open airlocks on both sides and merge atmospheres), use the docking_controller var to supply the id_tag of the docking controller for the airlock. You will also need to use dock_target on the shuttle to supply the id_tag of the docking controller on the shuttle. For setups with multiple airlocks, use special_dock_targets. There are several flags which can be applied to landmarks, using the flags var, of which the AUTOSET one is most relevant: it will set the base turf and area to be whatever is beneath the landmark when you map it.

You may use the subtype /obj/effect/shuttle_landmark/automatic instead, which will handle being added to sectors for you automatically, and also will name itself and set base turf/area. Set the shuttle_restricted var to your shuttle's name to have it be available only to your shuttle. You cannot use them for the current_location initial landmark.

Shuttles within shuttles

If you wish for a shuttle to be contained within a larger shuttle, and for them to move together when the larger one moves, this is supported, though the smaller shuttle may only have one larger shuttle to which it can be attached like that. On the smaller shuttle datum, set mothershuttle = "big_shuttle_name". There are now two cases:

• If you map the smaller shuttle inside the bigger one initially, have shuttle_area on the bigger one contain all the areas in both the smaller and bigger one. No other setup is needed.
• If you map the smaller shuttle outside the bigger one, do not put the smaller one's areas inside the bigger one's shuttle_area; instead, set motherdock on the smaller one to be the landmark tag for the landmark corresponding to being inside the bigger one.

In either case, the landmark used for moving together should be added to the larger shuttle's ship/landable waypoint lists if the larger shuttle has a corresponding ship/landable.

Shuttles can be nested arbitrarily like this, but circular mothership relations will not work properly. Equipment mapped inside of a shuttle (like the shuttle or helm computers, etc.) will be attached to the innermost (smallest) shuttle in whose areas it's contained.

Landable ships

To attach a shuttle to an overmap ship, you must set up a landable ship effect:

/obj/effect/overmap/visitable/ship/landable/foo
	name = "foo"
	desc = "bar"
	shuttle = "shuttle_name"
	fore_dir = NORTH
	multiz = 0
	vessel_size = SHIP_SIZE_SMALL
	vessel_mass = 10000
	max_speed = 1 / (10 SECONDS)
	burn_delay = 1 SECOND

The name and desc are player-facing. The shuttle var must be exactly the name of your shuttle datum. The fore_dir var effects the direction of the skybox scrolling as the ship moves on the overmap. The other vars influence how fast it moves and how it handles. multiz should be the same as the shuttle's.

Once you have done this, place it anywhere (location doesn't matter). You are done, just make sure that you have also mapped the appropriate computers to have the ship be fully operational.

Shuttles on runtime-loaded maps

If you are mapping a shuttle on a compiled map (.dmm ticked in DreamMaker), you should omit the following.

On your shuttle datum, set

/datum/shuttle/autodock/overmap/foo
	defer_initialisation = TRUE

Then on the map template datum associated to your map, add the shuttle datum's type path to the shuttles_to_initialise list.

Note that loading multiple maps at runtime which contain the same shuttle will cause errors and is not supported.