From 571eb920829b0423e4626ec97f433661f38746b3 Mon Sep 17 00:00:00 2001 From: Octol1ttle Date: Wed, 12 Feb 2025 14:25:05 +0500 Subject: [PATCH] chore: add missing API documentation where useful --- .../octol1ttle/flightassistant/api/SystemView.kt | 1 - .../octol1ttle/flightassistant/api/alert/Alert.kt | 15 +++++++++++++++ .../flightassistant/api/alert/AlertCategory.kt | 5 ++++- .../flightassistant/api/alert/CenteredAlert.kt | 3 +++ .../flightassistant/api/alert/ECAMAlert.kt | 2 ++ .../api/autoflight/ControlInput.kt | 10 ++++++++++ .../flightassistant/api/computer/Computer.kt | 11 +++++++++++ .../api/util/ChangeTrackingArrayList.kt | 4 ++++ .../flightassistant/api/util/FATickCounter.kt | 6 +++--- .../api/util/extensions/CollectionExtensions.kt | 12 +++++++++++- .../api/util/extensions/DrawContextExtensions.kt | 5 +++++ .../impl/computer/AirDataComputer.kt | 6 +++--- 12 files changed, 71 insertions(+), 9 deletions(-) diff --git a/src/main/kotlin/ru/octol1ttle/flightassistant/api/SystemView.kt b/src/main/kotlin/ru/octol1ttle/flightassistant/api/SystemView.kt index 97102af..5100117 100644 --- a/src/main/kotlin/ru/octol1ttle/flightassistant/api/SystemView.kt +++ b/src/main/kotlin/ru/octol1ttle/flightassistant/api/SystemView.kt @@ -1,5 +1,4 @@ package ru.octol1ttle.flightassistant.api -// TODO: documentation for the whole package import net.minecraft.util.Identifier diff --git a/src/main/kotlin/ru/octol1ttle/flightassistant/api/alert/Alert.kt b/src/main/kotlin/ru/octol1ttle/flightassistant/api/alert/Alert.kt index dbdd018..de74e9e 100644 --- a/src/main/kotlin/ru/octol1ttle/flightassistant/api/alert/Alert.kt +++ b/src/main/kotlin/ru/octol1ttle/flightassistant/api/alert/Alert.kt @@ -2,11 +2,26 @@ package ru.octol1ttle.flightassistant.api.alert import ru.octol1ttle.flightassistant.api.computer.ComputerView +/** + * A class that represents an alert. Only a single instance of this class is present for each actual alert + */ abstract class Alert(val computers: ComputerView) { + /** + * The data that this alert uses. Impacts the priority of this alert, its sound and category color + */ abstract val data: AlertData + + /** + * An offset for the priority of this alert, relative to the priority defined by the [data]. + * A negative offset means this alert will be more important than others in its category + */ open val priorityOffset: Int = 0 + val priority: Int get() = data.priority + priorityOffset + /** + * @return whether or not this alert should be active (displaying on a screen and/or playing a sound) + */ abstract fun shouldActivate(): Boolean } diff --git a/src/main/kotlin/ru/octol1ttle/flightassistant/api/alert/AlertCategory.kt b/src/main/kotlin/ru/octol1ttle/flightassistant/api/alert/AlertCategory.kt index 797308e..5a771c0 100644 --- a/src/main/kotlin/ru/octol1ttle/flightassistant/api/alert/AlertCategory.kt +++ b/src/main/kotlin/ru/octol1ttle/flightassistant/api/alert/AlertCategory.kt @@ -4,7 +4,10 @@ import net.minecraft.text.Text import ru.octol1ttle.flightassistant.FlightAssistant import ru.octol1ttle.flightassistant.api.computer.ComputerView -class AlertCategory(val categoryText: Text) { +/** + * A class that represents a category of alerts. + */ +sealed class AlertCategory(val categoryText: Text) { private val registeredAlerts: MutableList = ArrayList() val activeAlerts: MutableList = ArrayList() val ignoredAlerts: MutableList = ArrayList() diff --git a/src/main/kotlin/ru/octol1ttle/flightassistant/api/alert/CenteredAlert.kt b/src/main/kotlin/ru/octol1ttle/flightassistant/api/alert/CenteredAlert.kt index 5e961b7..2521276 100644 --- a/src/main/kotlin/ru/octol1ttle/flightassistant/api/alert/CenteredAlert.kt +++ b/src/main/kotlin/ru/octol1ttle/flightassistant/api/alert/CenteredAlert.kt @@ -3,5 +3,8 @@ package ru.octol1ttle.flightassistant.api.alert import net.minecraft.client.gui.DrawContext interface CenteredAlert { + /** + * @return whether or not this alert has rendered and occupied the center of the screen + */ fun render(drawContext: DrawContext, y: Int): Boolean } diff --git a/src/main/kotlin/ru/octol1ttle/flightassistant/api/alert/ECAMAlert.kt b/src/main/kotlin/ru/octol1ttle/flightassistant/api/alert/ECAMAlert.kt index 9c9cc83..d6cb21c 100644 --- a/src/main/kotlin/ru/octol1ttle/flightassistant/api/alert/ECAMAlert.kt +++ b/src/main/kotlin/ru/octol1ttle/flightassistant/api/alert/ECAMAlert.kt @@ -6,6 +6,8 @@ interface ECAMAlert { /** * Renders the text of this alert * + * @param firstLineX The X coordinate value that should be used only for the first line. + * @param otherLinesX The X coordinate value that should be used for the second line and onwards. * @return the amount of lines rendered */ fun render(drawContext: DrawContext, firstLineX: Int, otherLinesX: Int, firstLineY: Int): Int diff --git a/src/main/kotlin/ru/octol1ttle/flightassistant/api/autoflight/ControlInput.kt b/src/main/kotlin/ru/octol1ttle/flightassistant/api/autoflight/ControlInput.kt index 422fb33..114116c 100644 --- a/src/main/kotlin/ru/octol1ttle/flightassistant/api/autoflight/ControlInput.kt +++ b/src/main/kotlin/ru/octol1ttle/flightassistant/api/autoflight/ControlInput.kt @@ -3,6 +3,16 @@ package ru.octol1ttle.flightassistant.api.autoflight import net.minecraft.text.Text import net.minecraft.util.Identifier +/** + * Represents an input that computers may provide to other computers. + * + * @param target The target value of this input (e.g. the target thrust) + * @param priority The priority of this input + * @param text The text that will be shown on the [ru.octol1ttle.flightassistant.impl.display.AutomationModesDisplay] when this input is being satisfied + * @param deltaTimeMultiplier The multiplier for the delta time, used to determine how fast an input will be satisfied + * @param active If the input is active, it will be satisfied. Otherwise, this input serves as a notification + * @param identifier The identifier of this input + */ data class ControlInput(val target: Float, val priority: Priority, val text: Text? = null, val deltaTimeMultiplier: Float = 1.0f, val active: Boolean = true, val identifier: Identifier? = null) { enum class Priority(val value: Int) { HIGHEST(0), diff --git a/src/main/kotlin/ru/octol1ttle/flightassistant/api/computer/Computer.kt b/src/main/kotlin/ru/octol1ttle/flightassistant/api/computer/Computer.kt index b99a1c4..0f10e11 100644 --- a/src/main/kotlin/ru/octol1ttle/flightassistant/api/computer/Computer.kt +++ b/src/main/kotlin/ru/octol1ttle/flightassistant/api/computer/Computer.kt @@ -4,8 +4,19 @@ package ru.octol1ttle.flightassistant.api.computer * A class responsible for computing data and providing it to [ru.octol1ttle.flightassistant.api.display.Display]s and [ru.octol1ttle.flightassistant.api.alert.Alert]s */ abstract class Computer(val computers: ComputerView) { + /** + * Whether or not this computer is enabled. Disabled computers do not tick. + */ var enabled: Boolean = true + + /** + * Whether or not this computer has faulted. This value is set to false whenever the computer is reset. + */ var faulted: Boolean = false + + /** + * The amount of times this computer has faulted. + */ var faultCount: Int = 0 fun disabledOrFaulted(): Boolean { diff --git a/src/main/kotlin/ru/octol1ttle/flightassistant/api/util/ChangeTrackingArrayList.kt b/src/main/kotlin/ru/octol1ttle/flightassistant/api/util/ChangeTrackingArrayList.kt index 6a51476..673cf5e 100644 --- a/src/main/kotlin/ru/octol1ttle/flightassistant/api/util/ChangeTrackingArrayList.kt +++ b/src/main/kotlin/ru/octol1ttle/flightassistant/api/util/ChangeTrackingArrayList.kt @@ -1,5 +1,9 @@ package ru.octol1ttle.flightassistant.api.util +/** + * A class which can track changes to a list. Useful when a list is fully reconstructed each time it is updated. + * To use, call [startTracking], which will clear this list. Call [hasNewElements] to check if the list has changed after adding elements to it + */ class ChangeTrackingArrayList { private var backingList: ArrayList = ArrayList() private var staleList: ArrayList = ArrayList() diff --git a/src/main/kotlin/ru/octol1ttle/flightassistant/api/util/FATickCounter.kt b/src/main/kotlin/ru/octol1ttle/flightassistant/api/util/FATickCounter.kt index b196d07..1d5d875 100644 --- a/src/main/kotlin/ru/octol1ttle/flightassistant/api/util/FATickCounter.kt +++ b/src/main/kotlin/ru/octol1ttle/flightassistant/api/util/FATickCounter.kt @@ -15,10 +15,10 @@ object FATickCounter { private set var timePassed: Float = 0.0f private set - var tickDelta: Float = 0.0f + var tickProgress: Float = 0.0f private set - fun tick(player: ClientPlayerEntity, tickDelta: Float, paused: Boolean) { + fun tick(player: ClientPlayerEntity, tickProgress: Float, paused: Boolean) { if (!paused) { if (player.age < lastPlayerAge) { ticksSinceWorldLoad = player.age @@ -27,7 +27,7 @@ object FATickCounter { lastPlayerAge = player.age totalTicks += ticksPassed ticksSinceWorldLoad += ticksPassed - this.tickDelta = tickDelta + this.tickProgress = tickProgress } val millis: Long = Util.getMeasuringTimeMs() diff --git a/src/main/kotlin/ru/octol1ttle/flightassistant/api/util/extensions/CollectionExtensions.kt b/src/main/kotlin/ru/octol1ttle/flightassistant/api/util/extensions/CollectionExtensions.kt index 616f355..1a51a01 100644 --- a/src/main/kotlin/ru/octol1ttle/flightassistant/api/util/extensions/CollectionExtensions.kt +++ b/src/main/kotlin/ru/octol1ttle/flightassistant/api/util/extensions/CollectionExtensions.kt @@ -1,9 +1,13 @@ package ru.octol1ttle.flightassistant.api.util.extensions import ru.octol1ttle.flightassistant.api.alert.AlertData -import ru.octol1ttle.flightassistant.api.computer.Computer import ru.octol1ttle.flightassistant.api.autoflight.ControlInput +import ru.octol1ttle.flightassistant.api.computer.Computer +/** + * Filters the current list to try and get an active input with the highest priority in the list. + * If there are no such inputs, the returned list contains all inputs with the highest priority in the list. + */ fun List.getActiveHighestPriority(): List { val activeInput: List = this.filter { it.active && it.priority.value == this[0].priority.value } if (activeInput.any()) { @@ -13,10 +17,16 @@ fun List.getActiveHighestPriority(): List { return this.filter { it.priority.value == this[0].priority.value } } +/** + * Filters the current list to get alert datas that have the highest priority in the list. + */ fun List.getHighestPriority(): List { return this.filter { it.priority == this[0].priority } } +/** + * Filters the current list to exclude faulted computers. If a list contains an object that is not a computer, that object remains in the returned list. + */ fun List.filterNonFaulted(): List { return this.filter { it !is Computer || !it.faulted} } diff --git a/src/main/kotlin/ru/octol1ttle/flightassistant/api/util/extensions/DrawContextExtensions.kt b/src/main/kotlin/ru/octol1ttle/flightassistant/api/util/extensions/DrawContextExtensions.kt index b7313d7..c3acb4d 100644 --- a/src/main/kotlin/ru/octol1ttle/flightassistant/api/util/extensions/DrawContextExtensions.kt +++ b/src/main/kotlin/ru/octol1ttle/flightassistant/api/util/extensions/DrawContextExtensions.kt @@ -40,6 +40,11 @@ val cautionColor: Int val warningColor: Int get() = FAConfig.display.warningColor.rgb +/** + * Scales this draw context's matrix and returns the adjusted coordinates. + * + * @return a pair of adjusted coordinates. + */ fun DrawContext.scaleMatrix(scale: Float, trueX: Int, trueY: Int): Pair { matrices.scale(scale, scale, 1.0f) diff --git a/src/main/kotlin/ru/octol1ttle/flightassistant/impl/computer/AirDataComputer.kt b/src/main/kotlin/ru/octol1ttle/flightassistant/impl/computer/AirDataComputer.kt index 6481c65..4ec9ebc 100644 --- a/src/main/kotlin/ru/octol1ttle/flightassistant/impl/computer/AirDataComputer.kt +++ b/src/main/kotlin/ru/octol1ttle/flightassistant/impl/computer/AirDataComputer.kt @@ -18,7 +18,7 @@ import net.minecraft.world.RaycastContext import ru.octol1ttle.flightassistant.FlightAssistant import ru.octol1ttle.flightassistant.api.computer.Computer import ru.octol1ttle.flightassistant.api.computer.ComputerView -import ru.octol1ttle.flightassistant.api.util.FATickCounter.tickDelta +import ru.octol1ttle.flightassistant.api.util.FATickCounter.tickProgress import ru.octol1ttle.flightassistant.api.util.RenderMatrices import ru.octol1ttle.flightassistant.api.util.degrees import ru.octol1ttle.flightassistant.api.util.extensions.fallFlying @@ -70,9 +70,9 @@ class AirDataComputer(computers: ComputerView, private val mc: MinecraftClient) get() = world.chunkManager.isChunkLoaded(player.chunkPos.x, player.chunkPos.z) override fun tick() { - position = player.getLerpedPos(tickDelta) + position = player.getLerpedPos(tickProgress) groundLevel = computeGroundLevel() - velocity = player.lerpVelocity(tickDelta) + velocity = player.lerpVelocity(tickProgress) forwardVelocity = computeForwardVelocity() roll = degrees(atan2(-RenderMatrices.worldSpaceMatrix.m10(), RenderMatrices.worldSpaceMatrix.m11())) }