Lots of docstrings, and some code cleanup

effects/explosions/explosion.gd

@@ -1,5 +1,6 @@
 extends AnimatedSprite3D
 
+## An audio clip to play when this object enters the scene.
 @export var audio: AudioStreamPlayer3D
 
 func _ready() -> void:

effects/hyperspace/hyperspace_effect.gd

@@ -1,13 +1,25 @@
 extends MeshInstance3D
 
+## Performs the visual effect accompanying a hyperspace jump.
+##
+## Besides being visually interesting, this effect also serves to hide the scene transition, where otherwise nodes would pop in and out.
+
 @export var hyperspace_controller: HyperspaceController
+
+## An audio clip to play when a hyperspace jump begins.
 @export var jump_out_audio: AudioStreamPlayer
 
-const INITIAL_ROTATION = Vector3.ZERO
-const INITIAL_SCALE = Vector3.ZERO
-const JUMP_OUT_SCALE = Vector3.ONE * 2.7
+## The rotation the mesh should have at the start and end of a jump.
+@export var initial_rotation := Vector3.ZERO
+
+## The scale the mesh should have at the start and end of a jump.
+@export var initial_scale := Vector3.ZERO
+
+## The scale that the mesh should animate to at the peak of the jump.
+@export var jump_out_scale := Vector3.ONE * 2.7
 
-const JUMP_DURATION_SEC: float = 3
+## The total duration (in s) of the jump effect, including jumping out and jumping in.
+@export var total_jump_duration_sec := 3.0
 
 func _random_radians() -> float:
     return randf_range(0, 2 * PI)
@@ -20,29 +32,32 @@ func _random_rotation() -> Vector3:
     )
 
 func _on_jump_started(_destination: StarSystem) -> void:
-    self.rotation = INITIAL_ROTATION
-    self.scale = INITIAL_SCALE
+    self.rotation = self.initial_rotation
+    self.scale = self.initial_scale
     self.visible = true
 
+    # Jump out effect
     var tween := self.create_tween()
-    tween.tween_property(self, "rotation", _random_rotation(), JUMP_DURATION_SEC / 2)
-    tween.parallel().tween_property(self, "scale", JUMP_OUT_SCALE, JUMP_DURATION_SEC / 2)
-    tween.tween_callback(_jump_out_finished)
+    tween.tween_property(self, "rotation", _random_rotation(), self.total_jump_duration_sec / 2)
+    tween.parallel().tween_property(self, "scale", self.jump_out_scale, self.total_jump_duration_sec / 2)
 
     jump_out_audio.play()
 
-func _jump_out_finished() -> void:
+    await tween.finished
+
+    # Replace scene
     for node in self.get_tree().get_nodes_in_group("star_system"):
         node.visible = false
         node.process_mode = Node.PROCESS_MODE_DISABLED
 
     self.hyperspace_controller.load_jump_destination()
 
-    var tween := self.create_tween()
-    tween.tween_property(self, "rotation", INITIAL_ROTATION, JUMP_DURATION_SEC / 2)
-    tween.parallel().tween_property(self, "scale", INITIAL_SCALE, JUMP_DURATION_SEC / 2)
-    tween.tween_callback(_jump_in_finished)
+    # Jump in effect
+    tween = self.create_tween()
+    tween.tween_property(self, "rotation", self.initial_rotation, self.total_jump_duration_sec / 2)
+    tween.parallel().tween_property(self, "scale", self.initial_scale, self.total_jump_duration_sec / 2)
+
+    await tween.finished
 
-func _jump_in_finished() -> void:
     self.visible = false
     self.hyperspace_controller.finish_jump()

effects/main_camera.gd

@@ -1,8 +1,12 @@
 extends Camera3D
 
+## A node to automatically follow with the camera.
 @export var follow_target: Node3D
 
+## The material rendering the starfield below the game plane.
 @export var starfield_material: StandardMaterial3D
+
+## How much to dampen movement of the starfield below the game plane, while it moves in concert with the camera.
 @export var starfield_parallax_dampening: float = 50
 
 func _process(_delta: float) -> void:

galaxy/galaxy.gd

@@ -1,8 +1,14 @@
 extends Resource
 class_name Galaxy
 
+## Represents a galaxy of star systems.
+##
+## Only one galaxy is playable at any given time, but testing or add-on content may want to swap out the default galaxy.
+
+## A list of all systems in the galaxy.
 @export var systems: Array[StarSystem]
 
+## Looks up a system by name.
 func get_system(name: StringName) -> StarSystem:
     for system in systems:
         if system.name == name:

galaxy/hyperspace_controller.gd

@@ -1,20 +1,41 @@
 extends Node
 class_name HyperspaceController
 
+## Coordinates the player's hyperspace jumps and loading new scenes.
+
+## The playable galaxy, used to determine system connections.
 @export var galaxy: Galaxy
+
+## The current star system.
 @export var current_system: StarSystem
 
-signal jump_started(destination: StarSystem)
+## Fires when the player changes the jump destination, or it resets because of a performed jump.
 signal jump_destination_changed(new_destination: StarSystem)
+
+## Fires when the player initiates a hyperspace jump, before any changes have occurred.
+signal jump_started(destination: StarSystem)
+
+## Fires when the hyperspace destination has been loaded and added to the current scene, but before the full visual effect has finished.
 signal jump_destination_loaded(new_system: StarSystem)
+
+## Fires when the hyperspace jump has been completed, and the visual effect has finished.
 signal jump_finished(new_system: StarSystem)
 
+## Whether a jump is currently being performed.
+##
+## This property should not be written to outside the class!
 var jumping = false
+
+## The hyperspace destination that the player currently has selected.
+##
+## This property should not be written to outside the class!
 var jump_destination: StarSystem
-var loaded_system_nodes = {}
+
+## Used to keep systems around in memory, so their state is remembered.
+var _loaded_system_nodes = {}
 
 func _ready() -> void:
-    self.loaded_system_nodes[self.current_system.name] = get_tree().get_first_node_in_group("star_system")
+    self._loaded_system_nodes[self.current_system.name] = get_tree().get_first_node_in_group("star_system")
 
 func set_jump_destination(destination: StarSystem) -> void:
     assert(current_system != destination, "Current system should not be the same as the jump destination")
@@ -29,7 +50,7 @@ func start_jump() -> void:
     assert(jump_destination != null, "Jump destination not set")
     assert(current_system != jump_destination, "Current system should not be the same as the jump destination")
 
-    if not self.loaded_system_nodes.has(jump_destination.name):
+    if not self._loaded_system_nodes.has(jump_destination.name):
         ResourceLoader.load_threaded_request(jump_destination.scene_path())
 
     jumping = true
@@ -39,13 +60,13 @@ func load_jump_destination() -> void:
     assert(jump_destination != null, "Jump destination not set")
     assert(current_system != jump_destination, "Current system should not be the same as the jump destination")
 
-    var node: Node = self.loaded_system_nodes.get(jump_destination.name)
+    var node: Node = self._loaded_system_nodes.get(jump_destination.name)
     if node == null:
         print("Instantiating node for system ", jump_destination.name)
         var new_scene := ResourceLoader.load_threaded_get(jump_destination.scene_path()) as PackedScene
         node = new_scene.instantiate()
 
-        self.loaded_system_nodes[jump_destination.name] = node
+        self._loaded_system_nodes[jump_destination.name] = node
         get_parent().add_child(node)
     else:
         print("Restoring node for system ", jump_destination.name)

galaxy/star_systems/star_system.gd

@@ -1,8 +1,16 @@
 extends Resource
 class_name StarSystem
 
+## Describes the non-visual characteristics of a single star system.
+##
+## Visual characteristics, pre-existing nodes, etc., should all be saved into a scene that matches the [method scene_path].
+
+## The human-readable name of this star system.
 @export var name: StringName
+
+## All hyperspace connections that this system has to other systems.
 @export var connections: Array[StringName] = []
 
+## The resource path to this star system's scene.
 func scene_path() -> String:
     return "res://galaxy/star_systems/%s.tscn" % self.name.to_snake_case()

game.tscn

@@ -147,6 +147,7 @@ can_sleep = false
 script = ExtResource("7_6citj")
 hyperspace_controller = NodePath("../HyperspaceController")
 ship_def = ExtResource("8_s4vsk")
+free_when_destroyed = false
 
 [node name="AudioListener3D" type="AudioListener3D" parent="Player"]
 transform = Transform3D(1, -1.21652e-31, 0, -1.21652e-31, 1, 0, 0, 0, 1, 0, 0, 0)

gui/player_vitals.gd

@@ -4,10 +4,10 @@ extends GridContainer
 @export var shield_bar: ProgressBar
 
 func _on_player_ship_hull_changed(ship: Ship) -> void:
-    assert(ship.ship_def.hull >= ShipDef.MIN_HULL_VALUE, "Ship definition should not have 0 hull")
+    assert(ship.ship_def.hull > 0.0, "Ship definition should not have 0 hull")
     self.hull_bar.max_value = ship.ship_def.hull
     self.hull_bar.value = ship.hull
 
 func _on_player_ship_shield_changed(ship: Ship) -> void:
-    self.shield_bar.max_value = ship.ship_def.shield if ship.ship_def.shield >= ShipDef.MIN_SHIELD_VALUE else 1.0
+    self.shield_bar.max_value = 1.0 if is_zero_approx(ship.ship_def.shield) else ship.ship_def.shield
     self.shield_bar.value = ship.shield

gui/target_info.gd

@@ -1,22 +1,24 @@
 extends VBoxContainer
 
+## Displays information and vitals about the ship that the player is targeting, if any.
+
 @export var target_label: Label
 @export var vitals_container: Container
 @export var hull_bar: ProgressBar
 @export var shield_bar: ProgressBar
 @export var pick_sound: AudioStreamPlayer
 
-var target: Ship = null
+var _target: Ship = null
 
 func _on_player_ship_target_changed(_player_ship: Ship, targeted_ship: Ship) -> void:
-    if targeted_ship == self.target:
+    if targeted_ship == self._target:
         return
 
-    if self.target != null:
-        self.target.ship_hull_changed.disconnect(_on_target_ship_hull_changed)
-        self.target.ship_shield_changed.disconnect(_on_target_ship_shield_changed)
+    if self._target != null:
+        self._target.ship_hull_changed.disconnect(_on_target_ship_hull_changed)
+        self._target.ship_shield_changed.disconnect(_on_target_ship_shield_changed)
 
-    self.target = targeted_ship
+    self._target = targeted_ship
 
     if targeted_ship == null:
         self.target_label.text = "No target"
@@ -32,18 +34,18 @@ func _on_player_ship_target_changed(_player_ship: Ship, targeted_ship: Ship) ->
         self._update_shield()
 
 func _on_target_ship_hull_changed(ship: Ship) -> void:
-    assert(ship == self.target, "Should only be notified about changes to the target")
+    assert(ship == self._target, "Should only be notified about changes to the target")
     self._update_hull()
 
 func _on_target_ship_shield_changed(ship: Ship) -> void:
-    assert(ship == self.target, "Should only be notified about changes to the target")
+    assert(ship == self._target, "Should only be notified about changes to the target")
     self._update_shield()
 
 func _update_hull() -> void:
-    assert(self.target.ship_def.hull >= ShipDef.MIN_HULL_VALUE, "Ship definition should not have 0 hull")
-    self.hull_bar.max_value = self.target.ship_def.hull
-    self.hull_bar.value = self.target.hull
+    assert(self._target.ship_def.hull > 0.0, "Ship definition should not have 0 hull")
+    self.hull_bar.max_value = self._target.ship_def.hull
+    self.hull_bar.value = self._target.hull
 
 func _update_shield() -> void:
-    self.shield_bar.max_value = self.target.ship_def.shield if self.target.ship_def.shield >= ShipDef.MIN_SHIELD_VALUE else 1.0
-    self.shield_bar.value = self.target.shield
+    self.shield_bar.max_value = 1.0 if is_zero_approx(self._target.ship_def.shield) else self._target.ship_def.shield
+    self.shield_bar.value = self._target.shield