From 811ddaf8719aee17e30f3e6939e0299d32af40d9 Mon Sep 17 00:00:00 2001 From: Emill Date: Sat, 25 Jan 2025 20:38:27 -0500 Subject: [PATCH 1/6] =?UTF-8?q?=E2=9C=8F=EF=B8=8F=20docs(`GameTick.kt`):?= =?UTF-8?q?=20Add=20detailed=20documentation=20for=20game=20tick=20tasks?= =?UTF-8?q?=20and=20`AiTick`=20event=20handling.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../kotlin/world/gregs/voidps/GameTick.kt | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/game/src/main/kotlin/world/gregs/voidps/GameTick.kt b/game/src/main/kotlin/world/gregs/voidps/GameTick.kt index aefbc7ce2..4839ea1ca 100644 --- a/game/src/main/kotlin/world/gregs/voidps/GameTick.kt +++ b/game/src/main/kotlin/world/gregs/voidps/GameTick.kt @@ -34,6 +34,27 @@ import world.gregs.voidps.network.client.ConnectionQueue import world.gregs.voidps.network.login.protocol.npcVisualEncoders import world.gregs.voidps.network.login.protocol.playerVisualEncoders +/** + * Generates a list of tasks for processing game logic, including player and NPC resets, + * connections, updates, and other queued activities. The tasks generated are executed in the game's tick cycle. + * + * @param players The collection of players in the game. Default is obtained from the dependency injection framework. + * @param npcs The collection of NPCs in the game. Default is obtained from the dependency injection framework. + * @param items The collection of floor items in the game. Default is obtained from the dependency injection framework. + * @param floorItems The tracking system for floor items. Default is obtained from the dependency injection framework. + * @param objects The collection of game objects. Default is obtained from the dependency injection framework. + * @param queue The connection queue handling players' actions. Default is obtained from the dependency injection framework. + * @param accountSave The queue responsible for saving account states. Default is obtained from the dependency injection framework. + * @param batches Handles updates to game zones. Default is obtained from the dependency injection framework. + * @param itemDefinitions The definitions for all item types in the game. Default is obtained from the dependency injection framework. + * @param objectDefinitions The definitions for all object types in the game. Default is obtained from the dependency injection framework. + * @param npcDefinitions The definitions for all NPC types in the game. Default is obtained from the dependency injection framework. + * @param interfaceDefinitions Game interface definitions for UI handling. Default is obtained from the dependency injection framework. + * @param hunting The hunting task that handles hunting-related mechanics. Default is obtained from the dependency injection framework. + * @param handler The interface handler used to manage game interactions. Default is instantiated with dependencies from the framework. + * @param sequential A flag to determine whether the task execution should be sequential (true) or parallel (false). Default is the debugging mode value. + * @return A list of Runnable tasks to be executed in the game tick cycle. + */ fun getTickStages( players: Players = get(), npcs: NPCs = get(), @@ -81,6 +102,11 @@ fun getTickStages( ) } +/** + * Represents a task that emits the `AiTick` event to the world when executed. + * This class implements the `Runnable` interface and is designed to be run in a thread or scheduled task, + * triggering the `AiTick` event for handling AI-related updates in the game world. + */ private class AiTick : Runnable { override fun run() { World.emit(AiTick) From a05bc399dad3cb83126f91e94fe5429a44b0b5f6 Mon Sep 17 00:00:00 2001 From: Emill Date: Sat, 25 Jan 2025 20:39:42 -0500 Subject: [PATCH 2/6] =?UTF-8?q?=E2=9C=8F=EF=B8=8F=20docs(`Main.kt`):=20Add?= =?UTF-8?q?=20detailed=20KDocs=20to=20improve=20code=20documentation=20and?= =?UTF-8?q?=20readability.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../main/kotlin/world/gregs/voidps/Main.kt | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/game/src/main/kotlin/world/gregs/voidps/Main.kt b/game/src/main/kotlin/world/gregs/voidps/Main.kt index d898c245e..f4b79c162 100644 --- a/game/src/main/kotlin/world/gregs/voidps/Main.kt +++ b/game/src/main/kotlin/world/gregs/voidps/Main.kt @@ -26,13 +26,38 @@ import world.gregs.voidps.script.loadScripts import java.util.* /** + * Entry point for the application. + * + * The `Main` object initializes and starts various subsystems required for the application such as + * file server, content loader, login server, and game world. Additionally, it handles server shutdown + * and cleanup processes to ensure graceful termination of all resources. + * * @author GregHib * @since April 18, 2020 */ object Main { + /** + * A logger instance used for logging information, warnings, and errors throughout the application. + * This logger is based on inline logging, optimizing performance where logging evaluation can be skipped. + * + * Commonly utilized for crucial application events such as errors during application startup, + * processing game logic, or various system operations. + */ private val logger = InlineLogger() + /** + * Entry point of the application. + * This method initializes and starts various components required for the server, including: + * - Loading cache and settings + * - Configuring and starting the game server + * - Preloading content + * - Setting up the login server + * - Starting the game world and its loop + * - Handling server shutdown gracefully + * + * @param args Command-line arguments passed to the application. + */ @OptIn(ExperimentalUnsignedTypes::class) @JvmStatic fun main(args: Array) { @@ -74,12 +99,24 @@ object Main { } } + /** + * Loads and combines property settings from the specified property file and environment variables. + * The method execution time is logged for performance monitoring. + * + * @return A Properties object containing the combined configuration settings from the file and system environment variables. + */ private fun settings(): Properties = timed("properties") { val properties = Settings.load() properties.putAll(System.getenv()) return@timed properties } + /** + * Preloads the necessary modules, initializes the dependency injection container, + * and loads scripts for the application. + * + * @param cache The cache instance used to initialize various modules and definitions needed for the application. + */ private fun preload(cache: Cache) { val module = cache(cache) startKoin { @@ -89,6 +126,11 @@ object Main { loadScripts() } + /** + * Configures dependencies and initializes cache-related definitions and decoders. + * + * @param cache an instance of the Cache interface, representing the game cache being processed and used for loading various game definitions. + */ private fun cache(cache: Cache) = module { val members = Settings["world.members", false] single(createdAtStart = true) { MapDefinitions(CollisionDecoder(get()), get(), get(), cache).loadCache() } From 7f624b02c1ab5ce29dd182e7ee938c3ef51d35e8 Mon Sep 17 00:00:00 2001 From: Emill Date: Sat, 25 Jan 2025 20:47:45 -0500 Subject: [PATCH 3/6] =?UTF-8?q?=E2=9C=8F=EF=B8=8F=20docs(`definitions`):?= =?UTF-8?q?=20Add=20detailed=20KDocs=20for=20multiple=20definitions=20clas?= =?UTF-8?q?ses.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../data/definition/AccountDefinitions.kt | 53 +++++++- .../engine/data/definition/AmmoDefinitions.kt | 33 ++++- .../data/definition/AnimationDefinitions.kt | 24 ++++ .../engine/data/definition/AreaDefinition.kt | 34 +++++ .../engine/data/definition/AreaDefinitions.kt | 58 +++++++++ .../data/definition/CategoryDefinitions.kt | 29 ++++- .../definition/ClientScriptDefinitions.kt | 32 +++++ .../data/definition/DefinitionsDecoder.kt | 107 +++++++++++++++- .../data/definition/DiangoCodeDefinitions.kt | 64 ++++++++++ .../engine/data/definition/EnumDefinitions.kt | 58 ++++++++- .../engine/data/definition/FontDefinitions.kt | 27 ++++ .../engine/data/definition/GearDefinitions.kt | 45 +++++++ .../data/definition/GraphicDefinitions.kt | 34 +++++ .../data/definition/HuntModeDefinitions.kt | 35 +++++ .../data/definition/InterfaceDefinitions.kt | 120 ++++++++++++++++++ .../data/definition/InventoryDefinitions.kt | 49 +++++++ .../engine/data/definition/ItemDefinitions.kt | 88 +++++++++++++ .../data/definition/ItemOnItemDefinitions.kt | 76 +++++++++++ .../data/definition/JingleDefinitions.kt | 32 +++++ .../engine/data/definition/MapDefinitions.kt | 53 +++++++- .../engine/data/definition/MidiDefinitions.kt | 33 +++++ .../engine/data/definition/NPCDefinitions.kt | 51 ++++++++ .../data/definition/ObjectDefinitions.kt | 46 +++++++ .../data/definition/ParameterDefinitions.kt | 52 +++++++- .../data/definition/PatrolDefinitions.kt | 38 ++++++ .../data/definition/PrayerDefinitions.kt | 78 ++++++++++++ .../data/definition/QuestDefinitions.kt | 36 ++++++ .../definition/QuickChatPhraseDefinitions.kt | 23 ++++ .../data/definition/RenderEmoteDefinitions.kt | 33 +++++ .../data/definition/SoundDefinitions.kt | 30 +++++ .../data/definition/SpellDefinitions.kt | 34 +++++ .../data/definition/StructDefinitions.kt | 28 +++- .../data/definition/VariableDefinitions.kt | 58 ++++++++- .../definition/WeaponAnimationDefinitions.kt | 42 ++++++ .../data/definition/WeaponStyleDefinitions.kt | 35 +++++ .../kotlin/world/gregs/voidps/GameModules.kt | 27 ++++ 36 files changed, 1683 insertions(+), 12 deletions(-) diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AccountDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AccountDefinitions.kt index a5a088309..d9e985233 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AccountDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AccountDefinitions.kt @@ -12,7 +12,12 @@ import world.gregs.voidps.engine.get import world.gregs.voidps.engine.timedLoad /** - * Stores data about player accounts whether they're online or offline + * Manages account definitions, display names, and clans. + * Provides functionality to add, update, and retrieve account-related data. + * + * @property definitions A map storing account definitions keyed by display name. + * @property displayNames A map storing display names keyed by account name. + * @property clans A map storing clan data keyed by display name. */ class AccountDefinitions( private val definitions: MutableMap = Object2ObjectOpenHashMap(), @@ -20,6 +25,11 @@ class AccountDefinitions( private val clans: MutableMap = Object2ObjectOpenHashMap() ) { + /** + * Adds a player to the system by updating various collections including displayNames, definitions, and clans. + * + * @param player The player object containing account and clan information to be added. + */ fun add(player: Player) { displayNames[player.accountName.lowercase()] = player.name definitions[player.name.lowercase()] = AccountDefinition(player.accountName, player.name, player.previousName, player.passwordHash) @@ -37,6 +47,13 @@ class AccountDefinitions( ) } + /** + * Updates the display name of an account and its associated metadata. + * + * @param accountName The name of the account whose display name is being updated. + * @param newName The new display name to be associated with the account. + * @param previousDisplayName The previous display name associated with the account. + */ fun update(accountName: String, newName: String, previousDisplayName: String) { val definition = definitions.remove(previousDisplayName.lowercase()) ?: return definitions[newName.lowercase()] = definition @@ -45,16 +62,50 @@ class AccountDefinitions( displayNames[accountName.lowercase()] = newName } + /** + * Retrieves a clan by its display name. + * + * @param displayName The name of the clan to search for, case insensitive. + * @return The clan object corresponding to the provided display name, or null if not found. + */ fun clan(displayName: String) = clans[displayName.lowercase()] + /** + * Retrieves an account definition by the given account name. + * + * @param account The name of the account to retrieve. This parameter is case-insensitive. + * @return The account definition corresponding to the provided account name, or null if no match is found. + */ fun getByAccount(account: String): AccountDefinition? { return get(displayNames[account.lowercase()] ?: return null) } + /** + * Retrieves a value from the `definitions` map corresponding to the specified key. + * The key is case-insensitive and will be converted to lowercase before lookup. + * + * @param key The key used to look up a value in the `definitions` map. + * @return The value corresponding to the lowercase version of the key, or `null` if no matching entry is found. + */ fun get(key: String) = definitions[key.lowercase()] + /** + * Retrieves the value from the definitions map corresponding to the given key. + * The key is converted to lowercase before lookup to ensure case-insensitivity. + * + * @param key The key used to retrieve the corresponding value from the definitions map. + * @return The value associated with the lowercase version of the given key. + * @throws NoSuchElementException if the key is not present in the definitions map. + */ fun getValue(key: String) = definitions.getValue(key.lowercase()) + /** + * Loads account and clan definitions from the provided storage, processes them, and updates + * internal structures with the appropriate mappings for further usage. + * + * @param storage The account storage containing definitions and clan data. Defaults to an implementation of `AccountStorage` retrieved from a dependency injection mechanism. + * @return The updated account definitions after loading and processing. + */ fun load(storage: AccountStorage = get()): AccountDefinitions { timedLoad("account") { for ((name, definition) in storage.names()) { diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AmmoDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AmmoDefinitions.kt index 7e1e3ef98..fa88772dd 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AmmoDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AmmoDefinitions.kt @@ -9,14 +9,37 @@ import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml /** - * List of [AmmoDefinition.items] each weapons ammo_group can use ignoring - * skill requirements and whether inside dungeoneering. + * The `AmmoDefinitions` class is responsible for decoding and managing a collection of ammo definitions. + * It inherits from `DefinitionsDecoder` with a specific type of `AmmoDefinition`. */ class AmmoDefinitions : DefinitionsDecoder { + /** + * An overridden, late-initialized array holding instances of `AmmoDefinition`. + * This variable is expected to be initialized before its usage. + * Typically used to store and manage multiple ammunition definitions. + */ override lateinit var definitions: Array + /** + * A map of IDs where the key represents a string identifier and the value represents an integer ID. + * This property is overridden and expected to be initialized before accessing it. + * It can be used to store and retrieve mappings between string names and their corresponding integer IDs. + */ override lateinit var ids: Map + /** + * Loads the ammo definitions from the specified YAML file and path. + * + * This method decodes the YAML content at the given path to create and populate + * instances of `AmmoDefinition`. It provides a timed loading process for ammo definitions. + * + * @param yaml An instance of the `Yaml` class used to parse the YAML content. By default, + * it uses the instance returned from the `get()` method. + * @param path A string representing the path to the YAML content where ammo definitions are stored. + * By default, it is fetched from the `Settings` using the key `definitions.ammoGroups`. + * @return Returns the current object as an instance of `AmmoDefinitions` after successfully loading + * and decoding the YAML content. + */ @Suppress("UNCHECKED_CAST") fun load(yaml: Yaml = get(), path: String = Settings["definitions.ammoGroups"]): AmmoDefinitions { timedLoad("ammo definition") { @@ -32,6 +55,12 @@ class AmmoDefinitions : DefinitionsDecoder { return this } + /** + * Overrides the `empty` method to provide an implementation + * that returns an empty instance of `AmmoDefinition`. + * + * @return The `AmmoDefinition.EMPTY` instance representing an empty state. + */ override fun empty() = AmmoDefinition.EMPTY } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AnimationDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AnimationDefinitions.kt index 08a44c0ea..ba232c30a 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AnimationDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AnimationDefinitions.kt @@ -6,14 +6,38 @@ import world.gregs.voidps.engine.get import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml +/** + * A class responsible for managing and decoding animation definitions. + * It extends the [DefinitionsDecoder] interface, which provides mechanisms to decode and handle definitions. + * + * @property definitions An array of [AnimationDefinition] instances that represent animation configurations. + */ class AnimationDefinitions( override var definitions: Array ) : DefinitionsDecoder { + /** + * A map that stores identifier keys as strings and their corresponding integer values. + * This variable is overridden and will be initialized later with a proper value. + */ override lateinit var ids: Map + /** + * Indicates that the current animation definition is empty. + * This method is often used as a placeholder or default value + * when no specific animation definition is provided. + * + * @return An empty animation definition instance. + */ override fun empty() = AnimationDefinition.EMPTY + /** + * Loads animation definitions from the specified YAML file using the provided path. + * + * @param yaml The Yaml instance to use for decoding. Defaults to the result of the `get()` method. + * @param path The path to the definitions in the settings. Defaults to the value of `Settings["definitions.animations"]`. + * @return The loaded animation definitions. + */ fun load(yaml: Yaml = get(), path: String = Settings["definitions.animations"]): AnimationDefinitions { timedLoad("animation extra") { decode(yaml, path) diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AreaDefinition.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AreaDefinition.kt index 2ff4396b9..0e67f638e 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AreaDefinition.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AreaDefinition.kt @@ -4,6 +4,15 @@ import world.gregs.voidps.cache.definition.Extra import world.gregs.voidps.type.Area import world.gregs.voidps.type.area.Rectangle +/** + * Represents a named area of tiles with additional metadata. + * + * @property name The name of the area. + * @property area The shape and size of the area, represented as an implementation of [Area]. + * @property tags A set of associated tags for categorizing or describing the area. + * @property stringId A unique identifier for the area, defaulting to the area's name. + * @property extras A map of additional metadata or properties associated with the area. + */ data class AreaDefinition( val name: String, val area: Area, @@ -11,9 +20,34 @@ data class AreaDefinition( override var stringId: String = name, override var extras: Map? = null ) : Extra { + /** + * Companion object for `AreaDefinition` that provides predefined constants and utility methods + * to work with `AreaDefinition` instances. + */ companion object { + /** + * An empty instance of `AreaDefinition`. + * + * Represents a definition with no name, an empty rectangular area, and no tags. + * Used as a default or placeholder value when no specific area definition is provided. + */ val EMPTY = AreaDefinition("", Rectangle(0, 0, 0, 0), emptySet()) + /** + * Constructs an `AreaDefinition` from a provided name and a mutable map of attributes. + * + * The `map` parameter must include the following keys: + * - `"area"`: An instance of `Area`, which represents the spatial area of the definition. + * - `"tags"` (optional): A set of `String` tags associated with the area. If not provided, defaults to an empty set. + * + * Any remaining entries in the `map` will be stored as extras in the `AreaDefinition`. + * + * @param name The name of the area definition. + * @param map A mutable map containing the attributes required to create the `AreaDefinition`. + * The map must include an `"area"` key with an `Area` instance and optionally a `"tags"` key with a `Set`. + * Any remaining entries will be considered extras. + * @return An instance of `AreaDefinition` created using the provided name and attributes from the map. + */ @Suppress("UNCHECKED_CAST") fun fromMap(name: String, map: MutableMap): AreaDefinition { return AreaDefinition( diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AreaDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AreaDefinitions.kt index 20d65014d..18cec4782 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AreaDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/AreaDefinitions.kt @@ -11,32 +11,82 @@ import world.gregs.voidps.type.Zone import world.gregs.yaml.Yaml import world.gregs.yaml.read.YamlReaderConfiguration +/** + * Represents a collection of area definitions, which can be accessed based on various keys such as + * name, tags, or zones. This class centralizes the management and retrieval of area definitions, + * allowing for efficient queries and lookups. + * + * @property named A mapping of area names to their respective area definitions. + * @property tagged A mapping of tags to sets of area definitions that carry those tags. + * @property areas A mapping of zone IDs to sets of area definitions that belong to those zones. + */ class AreaDefinitions( private var named: Map = Object2ObjectOpenHashMap(), private var tagged: Map> = Object2ObjectOpenHashMap(), private var areas: Map> = Int2ObjectOpenHashMap() ) { + /** + * Retrieves the AreaDefinition associated with the given name, or returns null if no such entry exists. + * + * @param name The key used to look up the associated AreaDefinition. + * @return The AreaDefinition corresponding to the given name, or null if the name is not found. + */ fun getOrNull(name: String): AreaDefinition? { return named[name] } + /** + * Retrieves the area associated with the given name. + * + * @param name The name of the area to retrieve. + * @return The area corresponding to the provided name, or an empty area if the name is not found. + */ operator fun get(name: String): Area { return named[name]?.area ?: AreaDefinition.EMPTY.area } + /** + * Retrieves a set of area definitions associated with the given zone. + * + * @param zone the zone whose associated area definitions are to be retrieved + * @return a set of area definitions associated with the specified zone, + * or an empty set if no area definitions are found for the given zone + */ fun get(zone: Zone): Set { return areas[zone.id] ?: emptySet() } + /** + * Retrieves a set of `AreaDefinition` objects associated with the specified tag. + * + * @param tag The tag used to filter and retrieve the associated `AreaDefinition` objects. + * @return A set of `AreaDefinition` objects associated with the given tag. Returns an empty set if no associated objects are found. + */ fun getTagged(tag: String): Set { return tagged[tag] ?: emptySet() } + /** + * Loads area definitions from the provided YAML configuration file. + * + * @param yaml An instance of the `Yaml` parser used to load the configuration. Default is the instance returned by `get()`. + * @param path The file path to the YAML file containing the area definitions. Default is the value of `Settings["map.areas"]`. + * @return A populated `AreaDefinitions` object containing named, tagged, and zoned area definitions. + */ @Suppress("UNCHECKED_CAST") fun load(yaml: Yaml = get(), path: String = Settings["map.areas"]): AreaDefinitions { timedLoad("map area") { val config = object : YamlReaderConfiguration(2, 2) { + /** + * Sets a value in the provided map with considerations for specific keys and their associated types. + * + * @param map The mutable map where the key-value pair will be set. + * @param key The key to be added or updated in the map. + * @param value The value to be associated with the specified key. + * @param indent The indentation level influencing specific handling logic. + * @param parentMap The parent map's identifier, if applicable. + */ override fun set(map: MutableMap, key: String, value: Any, indent: Int, parentMap: String?) { if (key == "tags") { super.set(map, key, ObjectOpenHashSet(value as List), indent, parentMap) @@ -71,6 +121,14 @@ class AreaDefinitions( return this } + /** + * Retrieves a collection of all values stored in the `named` map. + * + * This method accesses the `values` property of the internal `named` map + * and returns a view of all the values contained within. + * + * @return A collection containing all values from the `named` map. + */ fun getAll() = named.values } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/CategoryDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/CategoryDefinitions.kt index f0713fdca..c75fa6590 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/CategoryDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/CategoryDefinitions.kt @@ -8,13 +8,32 @@ import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml /** - * Categories used in [ParameterDefinitions] + * CategoryDefinitions is responsible for handling the decoding and management + * of category definition data. It extends DefinitionsDecoder with a specific + * type of CategoryDefinition. */ class CategoryDefinitions : DefinitionsDecoder { + /** + * An overridden and late-initialized property that holds an array of `CategoryDefinition` objects. + * This property is intended to store definitions related to categories. + */ override lateinit var definitions: Array + /** + * A map representing a collection of string keys associated with integer values. + * This property is meant to be overridden and initialized later. + * Each key-value pair in the map signifies a unique identifier (key) + * and its corresponding numeric representation (value). + */ override lateinit var ids: Map + /** + * Loads category definitions from the provided YAML configuration and path. + * + * @param yaml The YAML configuration source to use. Defaults to the result of `get()`. + * @param path The file path or key in the configuration specifying the category definitions location. Defaults to `Settings["definitions.categories"]`. + * @return The loaded category definitions. + */ fun load(yaml: Yaml = get(), path: String = Settings["definitions.categories"]): CategoryDefinitions { timedLoad("category definition") { decode(yaml, path) { id, key, _ -> @@ -24,6 +43,14 @@ class CategoryDefinitions : DefinitionsDecoder { return this } + /** + * Returns an empty instance of `CategoryDefinition`. + * + * This method provides a default or placeholder value when no specific category definition is present. + * The returned instance is predefined as `CategoryDefinition.EMPTY`. + * + * @return An empty `CategoryDefinition` instance. + */ override fun empty() = CategoryDefinition.EMPTY } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ClientScriptDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ClientScriptDefinitions.kt index f482af061..ba49f4133 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ClientScriptDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ClientScriptDefinitions.kt @@ -7,11 +7,34 @@ import world.gregs.voidps.engine.get import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml +/** + * The `ClientScriptDefinitions` class is responsible for decoding and managing client script definitions. + * It extends `DefinitionsDecoder` to handle the specific type `ClientScriptDefinition`. + */ class ClientScriptDefinitions : DefinitionsDecoder { + /** + * An overridden, late-initialized array holding the definitions of + * client script objects. These objects represent client-side scripting + * configurations or instructions. + */ override lateinit var definitions: Array + /** + * A mapping of unique string identifiers to their corresponding numeric IDs. + * + * This map is utilized to maintain the relationship between human-readable + * string IDs and their internal numerical counterparts, which may be used + * for more efficient lookups or storage. + */ override lateinit var ids: Map + /** + * Loads and decodes client script definitions from the specified YAML configuration file and path. + * + * @param yaml the Yaml instance used for decoding; defaults to the result of `get()`. + * @param path the path to the client scripts definition file; defaults to the value of `Settings["definitions.clientScripts"]`. + * @return the loaded ClientScriptDefinitions instance. + */ fun load(yaml: Yaml = get(), path: String = Settings["definitions.clientScripts"]): ClientScriptDefinitions { timedLoad("client script definition") { decode(yaml, path) { id, key, _ -> @@ -21,6 +44,15 @@ class ClientScriptDefinitions : DefinitionsDecoder { return this } + /** + * Provides an empty default instance of `ClientScriptDefinition`. + * + * This method is used as a fallback or placeholder, returning a static + * `EMPTY` instance from `ClientScriptDefinition` when no specific + * instance is available or applicable. + * + * @return A predefined `ClientScriptDefinition` instance representing an empty or default state. + */ override fun empty() = ClientScriptDefinition.EMPTY } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/DefinitionsDecoder.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/DefinitionsDecoder.kt index 392c416ad..ae3f40e55 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/DefinitionsDecoder.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/DefinitionsDecoder.kt @@ -8,13 +8,36 @@ import world.gregs.voidps.engine.data.yaml.DefinitionConfig import world.gregs.yaml.Yaml /** - * Looks up [Definition]'s using Definitions unique string identifier - * Sets [Extra] values inside [Definition] + * Interface representing a decoder for a set of `Definition` objects. This decoder handles + * mappings between definitions, their IDs (both numerical and string-based), and provides + * utility methods for accessing and transforming these elements. It also supports loading + * definitions from external sources and applying additional metadata or operations to each definition. + * + * @param D The type of definition managed by the decoder, which must implement both `Definition` and `Extra`. */ interface DefinitionsDecoder where D : Definition, D : Extra { + /** + * Represents an array of definitions where each element is of type `D`. + * + * This variable can be utilized to store and manage a collection + * of definitions for further processing or retrieval. + */ var definitions: Array + /** + * A map containing identifiers as keys and their corresponding integer values. + * The key is a string representing a unique identifier, and the value is an integer + * associated with that identifier. + */ var ids: Map + /** + * Retrieves an element from the definitions list by its identifier, or returns null + * if the specified identifier is -1 or the element does not exist in the list. + * + * @param id The identifier of the element to retrieve. + * @return The element corresponding to the given identifier, or null if the identifier is -1 + * or the element is not found. + */ fun getOrNull(id: Int): D? { if (id == -1) { return null @@ -22,12 +45,29 @@ interface DefinitionsDecoder where D : Definition, D : Extra { return definitions.getOrNull(id) } + /** + * Creates and returns an empty instance of type D. + * + * @return An empty instance of type D. + */ fun empty(): D + /** + * Retrieves the entity associated with the specified identifier. + * + * @param id The identifier of the entity to retrieve. + * @return The entity of type D if found, or an empty default instance if not found. + */ fun get(id: Int): D { return getOrNull(id) ?: empty() } + /** + * Retrieves an object of type `D` corresponding to the provided identifier or returns null if not found. + * + * @param id The identifier as a string used to find the object. + * @return The object of type `D` if found, or null if the identifier is invalid or the object is not available. + */ fun getOrNull(id: String): D? { if (id.isBlank()) { return null @@ -39,14 +79,34 @@ interface DefinitionsDecoder where D : Definition, D : Extra { return getOrNull(ids[id] ?: return null) } + /** + * Retrieves an object of type D associated with the given identifier. + * If the object cannot be found, an empty object of type D is returned. + * + * @param id The unique identifier of the object to retrieve. + * @return The object of type D associated with the given identifier, or an empty object if not found. + */ fun get(id: String): D { return getOrNull(id) ?: empty() } + /** + * Checks whether an element with the specified ID exists within the collection. + * + * @param id The identifier of the element to be checked. + * @return `true` if an element with the specified ID exists, `false` otherwise. + */ fun contains(id: String): Boolean { return getOrNull(id) != null } + /** + * Decodes the given YAML file and processes it into an internal ID map. + * + * @param yaml The YAML parser instance used to load the data. + * @param path The file path to the YAML file to be decoded. + * @return The number of IDs processed and stored in the internal map. + */ fun decode(yaml: Yaml, path: String): Int { val ids = Object2IntOpenHashMap() val config = DefinitionConfig(ids, definitions) @@ -55,6 +115,13 @@ interface DefinitionsDecoder where D : Definition, D : Extra { return ids.size } + /** + * Applies the provided names and extras to definitions and executes an optional block of code for each definition. + * + * @param names A map where the key is an integer representing an index, and the value is a string representing the name. + * @param extras A nested map where the key is a string (name), and the value is another map containing additional properties. + * @param block An optional lambda function to be executed with each individual definition as its parameter. + */ fun apply(names: Map, extras: Map>, block: (D) -> Unit = {}) { for (i in definitions.indices) { val definition = definitions[i] @@ -66,14 +133,50 @@ interface DefinitionsDecoder where D : Definition, D : Extra { } } + /** + * A companion object for utility functions related to data conversion and string manipulation. + */ companion object { + /** + * A regular expression for matching and identifying HTML/XML-like tags within a given string. + * + * This regex pattern specifically matches substrings that start with a less-than sign (`<`), + * followed by any sequence of characters (including none), and ending with a greater-than sign (`>`). + * + * Useful for tasks such as parsing, extracting, or removing tags from strings. + */ private val tagRegex = "<.*?>".toRegex() + /** + * Removes all tags from the given text using a predefined regular expression. + * + * @param text The input string from which tags are to be removed. + * @return A string with all tags stripped out. + */ fun removeTags(text: String) = text.replace(tagRegex, "") + /** + * A regular expression pattern used to identify specific punctuation characters. + * + * This regex matches any of the following characters: `"` (double quote), `'` (single quote), + * `,` (comma), `(` (open parenthesis), `)` (close parenthesis), `?` (question mark), `.` (period), + * `!` (exclamation mark). + * Typically utilized for removing or processing these characters in text parsing or decoding operations. + */ private val chars = "[\"',()?.!]".toRegex() + /** + * Represents a predefined regular expression pattern used to match specific characters, + * such as spaces, slashes, or hyphens, often intended for usage in text normalization or parsing. + */ private val underscoreChars = "[ /-]".toRegex() + /** + * Converts a name into a standardized identifier by performing a series of transformations, + * including converting to lowercase, replacing specific characters, and removing tags. + * + * @param name The input string to be transformed into an identifier. + * @return A standardized string identifier derived from the input name. + */ fun toIdentifier(name: String) = removeTags(name.lowercase().replace(underscoreChars, "_")).replace(chars, "").replace("&", "and").replace("à", "a").replace("é", "e").replace("ï", "i").replace("'", "") } diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/DiangoCodeDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/DiangoCodeDefinitions.kt index d222fd6ee..b3a8504a2 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/DiangoCodeDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/DiangoCodeDefinitions.kt @@ -9,18 +9,58 @@ import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml import world.gregs.yaml.read.YamlReaderConfiguration +/** + * Represents a collection of Diango code definitions which are used + * to manage configurations for retrieving data related to Diango codes. + */ class DiangoCodeDefinitions { + /** + * A map containing all the DiangoCodeDefinitions keyed by their corresponding code strings. + * + * This variable is used within the DiangoCodeDefinitions class to store and manage + * the mapping of Django codes to their respective definitions. It is initialized + * later through the `load` method. + */ private lateinit var definitions: Map + /** + * Retrieves a definition based on the provided code. If no valid definition is found, + * a default empty definition is returned. + * + * @param code the code used to look up the corresponding definition + * @return the definition associated with the given code, or an empty definition if none is found + */ fun get(code: String) = getOrNull(code) ?: DiangoCodeDefinition.EMPTY + /** + * Retrieves the value associated with the provided code from the definitions map. + * If the code is not present in the map, returns null. + * + * @param code The key for which the corresponding value is to be retrieved from the definitions map. + * @return The value associated with the specified key or null if the key is not found. + */ fun getOrNull(code: String) = definitions[code] + /** + * Loads DiangoCodeDefinitions from the specified YAML configuration file. + * + * @param yaml An instance of the Yaml parser to read the configuration. If not provided, a default instance will be used. + * @param path A string representing the path to the YAML file. Defaults to the path defined in the Settings for Diango codes. + * @param itemDefinitions Optional parameter containing definitions of items. Used to validate item identifiers during loading. + * @return The loaded DiangoCodeDefinitions containing parsed configuration details. + */ @Suppress("UNCHECKED_CAST") fun load(yaml: Yaml = get(), path: String = Settings["definitions.diangoCodes"], itemDefinitions: ItemDefinitions? = null): DiangoCodeDefinitions { timedLoad("diango code definition") { val config = object : YamlReaderConfiguration(2, 2) { + /** + * Adds an item to the specified mutable list, converting the value to an Item object if necessary. + * + * @param list The mutable list to which the item will be added. + * @param value The value to be added to the list. If it is a map, it is transformed into an Item. + * @param parentMap Optional parent map identifier used for additional processing. + */ override fun add(list: MutableList, value: Any, parentMap: String?) { super.add(list, if (value is Map<*, *>) { val id = value["item"] as String @@ -32,6 +72,20 @@ class DiangoCodeDefinitions { Item(value as String, amount = 1) }, parentMap) } + /** + * Sets a value in the provided map according to the given key and handles specific conditions + * based on the key value and indentation level. + * + * If the key is "<<", the method merges the given value (expected to be a map) into the provided map. + * If the indentation level (`indent`) is 0, the value is wrapped as a `DiangoCodeDefinition` before being set. + * Otherwise, the value is set without modification. + * + * @param map The mutable map to be updated. + * @param key The key under which the value should be stored or merged. + * @param value The value to be set or merged into the map. + * @param indent The indentation level determining how the value should be processed. + * @param parentMap An optional parameter representing the parent map structure, may be null. + */ override fun set(map: MutableMap, key: String, value: Any, indent: Int, parentMap: String?) { if (key == "<<") { map.putAll(value as Map) @@ -51,7 +105,17 @@ class DiangoCodeDefinitions { return this } + /** + * Companion object for the `DiangoCodeDefinitions` class. + * + * Provides utility functions or shared behavior related to the scope of `DiangoCodeDefinitions`. + */ companion object { + /** + * Logger instance used for logging within the `DiangoCodeDefinitions` class. + * Provides a way to output debug or informational messages during the execution + * of the class's functions, such as loading or retrieving definitions. + */ private val logger = InlineLogger() } diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/EnumDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/EnumDefinitions.kt index e14777d01..5c1c54a0a 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/EnumDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/EnumDefinitions.kt @@ -7,33 +7,81 @@ import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml /** - * Also known as DataMap in cs2 + * A class responsible for decoding and managing EnumDefinitions. It provides functionality + * to work with EnumDefinitions tied to specific StructDefinitions. + * + * @property definitions Array of EnumDefinitions managed by this class. + * @property structs An instance of StructDefinitions used for structural data retrieval. */ class EnumDefinitions( override var definitions: Array, private val structs: StructDefinitions ) : DefinitionsDecoder { + /** + * A map where the keys are string identifiers and the values are integer IDs. + * + * This property is used to store a mapping of unique string keys, such as names or identifiers, + * to their corresponding integers. It functions as a lookup table, providing efficient access + * to integer IDs based on their string keys. + */ override lateinit var ids: Map + /** + * Retrieves a structured value of type [T] based on the provided parameters. + * + * @param id The identifier used to locate the associated enum definition. + * @param index The index used to retrieve a specific integer from the enum definition. + * @param param The key used to extract a specific value from the struct definition. + * @return The value of type [T] retrieved from the struct. + * + * @throws NoSuchElementException if the `id`, `index`, or `param` does not match an existing definition. + * @throws ClassCastException if the value associated with `param` cannot be cast to the type [T]. + */ fun getStruct(id: String, index: Int, param: String): T { val enum = get(id) val struct = enum.getInt(index) return structs.get(struct)[param] } + /** + * Retrieves a struct of type T from the provided identifier, index, and parameter, + * or null if the struct or parameter is not found. + * + * @param id The unique identifier used to locate the struct. + * @param index The index within the struct to retrieve. + * @param param The specific parameter within the struct to retrieve the value for. + * @return The value of type T associated with the specified id, index, and param, + * or null if the value does not exist. + */ fun getStructOrNull(id: String, index: Int, param: String): T? { val enum = get(id) val struct = enum.getInt(index) return structs.getOrNull(struct)?.getOrNull(param) } + /** + * Retrieves a structured value of a specified type associated with the given parameters. + * + * @param id The unique identifier for retrieving the enum definition. + * @param index The index to retrieve the specific integer value from the enum definition. + * @param param The key used to fetch the associated structured value from the struct definition. + * @param default The default value to return if the key does not exist or the value cannot be cast. + * @return The structured value of type T associated with the given parameters, or the default value if not found. + */ fun getStruct(id: String, index: Int, param: String, default: T): T { val enum = get(id) val struct = enum.getInt(index) return structs.get(struct)[param, default] } + /** + * Loads the EnumDefinitions from the specified YAML configuration. + * + * @param yaml The YAML instance to be used for loading. Defaults to the result of get(). + * @param path The path in the settings where the enum definitions are located. Defaults to Settings["definitions.enums"]. + * @return The loaded EnumDefinitions. + */ fun load(yaml: Yaml = get(), path: String = Settings["definitions.enums"]): EnumDefinitions { timedLoad("enum extra") { decode(yaml, path) @@ -41,6 +89,14 @@ class EnumDefinitions( return this } + /** + * Returns an empty instance of [EnumDefinition]. + * + * This method is used to provide a default or placeholder value + * when no specific enumeration definition is available. + * + * @return The constant `EnumDefinition.EMPTY`. + */ override fun empty() = EnumDefinition.EMPTY } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/FontDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/FontDefinitions.kt index 932557599..b44aa5018 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/FontDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/FontDefinitions.kt @@ -6,14 +6,41 @@ import world.gregs.voidps.engine.get import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml +/** + * Represents a collection of font definitions. This class extends the functionality for decoding + * and managing `FontDefinition` objects, allowing them to be loaded and associated with unique identifiers. + * + * @property definitions An array of `FontDefinition` objects that are managed by this class. + */ class FontDefinitions( override var definitions: Array ) : DefinitionsDecoder { + /** + * A map linking string identifiers to integer IDs. + * + * Used to store and manage mappings between unique string keys and their corresponding integer values + * for font definitions. Typically utilized to resolve or retrieve font details by their string identifiers. + */ override lateinit var ids: Map + /** + * Provides an empty or default instance of `FontDefinition`. + * + * This method is typically used to return a placeholder or default value + * when no specific font definition is available or required. + * + * @return The empty `FontDefinition` instance. + */ override fun empty() = FontDefinition.EMPTY + /** + * Loads font definitions from a YAML file and processes it into the internal structure. + * + * @param yaml An instance of the `Yaml` parser used to parse the input file. Defaults to a globally retrieved instance. + * @param path The file path to the YAML file containing font definitions. Defaults to the value of `Settings["definitions.fonts"]`. + * @return The updated `FontDefinitions` instance after loading and decoding the YAML data. + */ fun load(yaml: Yaml = get(), path: String = Settings["definitions.fonts"]): FontDefinitions { timedLoad("font extra") { decode(yaml, path) diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/GearDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/GearDefinitions.kt index adcb48518..5e3a8d125 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/GearDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/GearDefinitions.kt @@ -12,17 +12,53 @@ import world.gregs.voidps.network.login.protocol.visual.update.player.EquipSlot import world.gregs.yaml.Yaml import world.gregs.yaml.read.YamlReaderConfiguration +/** + * The `GearDefinitions` class is responsible for managing and loading gear definitions + * from a specified YAML configuration file. The gear definitions are stored as a mapping + * of gear styles to their respective lists of gear definitions. + */ class GearDefinitions { + /** + * A map that holds gear definitions categorized by a string key. + * + * Each key in the map represents a specific style or category, and the value + * is a mutable list of `GearDefinition` objects associated with that category. + * This structure allows the organization and retrieval of gear definitions + * based on their associated style. + */ private lateinit var definitions: Map> + /** + * Retrieves a list of GearDefinition objects associated with the specified style. + * + * @param style the style identifier used to fetch the corresponding gear definitions + * @return a list of GearDefinition objects matching the provided style; an empty list if none are found + */ fun get(style: String): List = definitions[style] ?: emptyList() + /** + * Loads gear definitions from the specified YAML file path using the provided YAML configuration. + * + * This method uses a custom `YamlReaderConfiguration` to process the YAML data into + * `GearDefinitions` by parsing equipment, inventory, and other definitions accordingly. + * + * @param yaml The YAML parser to use for loading the configuration. Defaults to the result of `get()`. + * @param path The file path to the YAML configuration file. Defaults to `Settings["definitions.gearSets"]`. + * @return The loaded `GearDefinitions` object containing the parsed gear data. + */ @Suppress("UNCHECKED_CAST") fun load(yaml: Yaml = get(), path: String = Settings["definitions.gearSets"]): GearDefinitions { timedLoad("gear definition") { var count = 0 val config = object : YamlReaderConfiguration() { + /** + * Adds a value to the specified list based on the type of value and the parent map context. + * + * @param list The mutable list to which the value will be added. + * @param value The value to be added to the list. The type of this value can vary and will be processed accordingly. + * @param parentMap A string identifier representing the context or type of parent map, used to determine how to process the value. + */ override fun add(list: MutableList, value: Any, parentMap: String?) { if (parentMap == "inventory") { value as Map @@ -54,6 +90,15 @@ class GearDefinitions { } } + /** + * Sets a key-value pair in the provided map with custom handling for specific keys. + * + * @param map The map where the key-value pair will be set. + * @param key The key to set in the map. + * @param value The value associated with the key. + * @param indent The current indentation level in the YAML structure. + * @param parentMap The name of the parent map, if applicable. + */ override fun set(map: MutableMap, key: String, value: Any, indent: Int, parentMap: String?) { super.set(map, key, when (key) { "levels" -> (value as String).toIntRange() diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/GraphicDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/GraphicDefinitions.kt index c4e8180d0..2e3f62bc2 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/GraphicDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/GraphicDefinitions.kt @@ -6,14 +6,48 @@ import world.gregs.voidps.engine.get import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml +/** + * A class responsible for managing and decoding graphic definitions. GraphicDefinitions provides functionalities + * to store, decode, and retrieve graphic-related data, including managing a collection of `GraphicDefinition` + * objects and their associated identifiers. + * + * This class extends the `DefinitionsDecoder` interface, allowing it to decode definitions from external sources + * and provides utility methods for working with graphic definitions. + * + * @property definitions An array of `GraphicDefinition` objects representing the graphic definitions managed by + * this class. + */ class GraphicDefinitions( override var definitions: Array ) : DefinitionsDecoder { + /** + * A mapping of string identifiers to their corresponding integer IDs for graphic definitions. + * + * This map serves as a lookup table where each string key represents a unique graphic identifier + * and the integer value corresponds to its associated graphical ID. + * It is typically used to decode and manage graphic definitions efficiently by linking string identifiers + * to their respective numerical representations. + */ override lateinit var ids: Map + /** + * Provides an empty default value for the `GraphicDefinition` type. + * + * This method is typically used to return a placeholder or default + * instance of `GraphicDefinition` when no valid data is available. + * + * @return The predefined empty instance of `GraphicDefinition`. + */ override fun empty() = GraphicDefinition.EMPTY + /** + * Loads and decodes the graphic definitions from the specified YAML file. + * + * @param yaml The YAML parser instance used to load the data. Defaults to the global YAML instance. + * @param path The file path to the YAML file to be decoded. Defaults to the path specified in the settings under "definitions.graphics". + * @return The instance of [GraphicDefinitions] with the loaded and decoded graphic definitions. + */ fun load(yaml: Yaml = get(), path: String = Settings["definitions.graphics"]): GraphicDefinitions { timedLoad("graphic extra") { decode(yaml, path) diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/HuntModeDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/HuntModeDefinitions.kt index d8d676ae1..09866625e 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/HuntModeDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/HuntModeDefinitions.kt @@ -7,18 +7,53 @@ import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml import world.gregs.yaml.read.YamlReaderConfiguration +/** + * A class that defines and manages hunt mode configurations. This class supports loading + * and retrieving different hunt modes by their names. + */ class HuntModeDefinitions { + /** + * A map containing hunt mode definitions, keyed by their respective names. + * + * Each entry represents a specific hunting mode defined by an instance of [HuntModeDefinition]. + * These definitions control various behavior parameters and checks for hunting targets in the system. + * + * The map is populated by loading definitions from external sources during initialization or runtime. + */ private lateinit var modes: Map + /** + * Retrieves the HuntModeDefinition associated with the specified name. + * + * @param name The name of the hunt mode to retrieve. + * @return The HuntModeDefinition corresponding to the given name. + */ fun get(name: String): HuntModeDefinition { return modes.getValue(name) } + /** + * Loads hunt mode definitions from the specified YAML configuration. + * + * @param yaml An optional Yaml instance to parse the configuration. Defaults to the result of `get()`. + * @param path The file path or configuration path to load the YAML definitions from. Defaults to `Settings["definitions.huntModes"]`. + * @return Returns an instance of `HuntModeDefinitions` with loaded and parsed hunt modes. + */ @Suppress("UNCHECKED_CAST") fun load(yaml: Yaml = get(), path: String = Settings["definitions.huntModes"]): HuntModeDefinitions { timedLoad("hunt mode") { val config = object : YamlReaderConfiguration(2, 2) { + /** + * Sets a key-value pair into the provided mutable map with additional handling for nested merge operations and + * specialized value processing based on the indent level. + * + * @param map The mutable map where the key-value pair or merged map will be set. + * @param key The key for the value to set or merge into the map. + * @param value The value to set or merge; can be a map or a processed object depending on the key or indent. + * @param indent The indentation level to determine how the value should be processed. If 0, the value is processed differently. + * @param parentMap The parent map context, if applicable, which might be used by the caller to determine behavior. + */ override fun set(map: MutableMap, key: String, value: Any, indent: Int, parentMap: String?) { if (key == "<<") { map.putAll(value as Map) diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/InterfaceDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/InterfaceDefinitions.kt index d1de0e800..b0dbc1725 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/InterfaceDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/InterfaceDefinitions.kt @@ -13,31 +13,122 @@ import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml import world.gregs.yaml.read.YamlReaderConfiguration +/** + * Represents the default type used to categorize or identify a primary screen or interface within + * the application. This value is utilized as the fallback or standard type in scenarios where + * no specific type is explicitly provided. + */ private const val DEFAULT_TYPE = "main_screen" +/** + * Indicates the default parent interface name for fixed game layouts. + * + * This constant is used as a reference point for the default game frame in scenarios + * where a fixed parent layout is required. It is tied to the game's specific user + * interface structure and ensures consistent rendering and handling across related + * UI components. + */ private const val DEFAULT_FIXED_PARENT = Interfaces.GAME_FRAME_NAME +/** + * A constant representing the default name for a game frame in resize mode. + * + * This value is indirectly linked to a predefined interface constant that specifies + * the name used for resizing the game frame in the UI system. It serves as a + * single source of truth for handling the default behavior related to resize operations. + */ private const val DEFAULT_RESIZE_PARENT = Interfaces.GAME_FRAME_RESIZE_NAME +/** + * Indicates whether an area or object is permanent by default. + * + * Used as a default value for settings or flags where permanence needs + * to be established unless explicitly overridden. + */ private const val DEFAULT_PERMANENT = true +/** + * Handles the decoding and management of interface definitions. + * + * This class provides methods to load, retrieve, and manipulate interface definitions and their components. + * It is used to decode interface data from a YAML configuration and manage associations between + * interfaces, their components, types, and other attributes. + * + * @constructor Initializes the definitions with an array of `InterfaceDefinition`. + */ @Suppress("UNCHECKED_CAST") class InterfaceDefinitions( override var definitions: Array ) : DefinitionsDecoder { + /** + * A map linking string identifiers to integer values. + * + * Typically used to store and retrieve IDs related to interface elements or components. + */ override lateinit var ids: Map + /** + * Maintains a mapping between component names and their identifiers. + * + * This variable serves as a centralized data structure that links string-based component names or keys + * to their corresponding integer IDs. It is useful for quick lookups and management of components, + * allowing for efficient access to their identifiers in various operations or definitions. + */ lateinit var componentIds: Map + /** + * Retrieves the ID of a specific component based on the provided ID and component name. + * + * @param id The identifier representing a specific entity or group. + * @param component The name of the component to retrieve the ID for. + * @return The ID of the component as stored in the `componentIds` map, or `null` if the component ID does not exist. + */ fun getComponentId(id: String, component: String) = componentIds["${id}_$component"] + /** + * Retrieves a specific component from an interface definition based on the given identifiers. + * + * @param id The unique string identifier of the interface. + * @param component The unique string identifier of the component within the interface. + * @return An instance of [InterfaceComponentDefinition] if the component is found, or `null` if not. + */ fun getComponent(id: String, component: String): InterfaceComponentDefinition? { return get(id).components?.get(getComponentId(id, component) ?: return null) } + /** + * Retrieves a component of an object based on its identifier and component index. + * + * @param id The unique identifier of the object from which the component is retrieved. + * @param component The index of the component to retrieve. + * @return The component at the specified index, or null if the object or component is not found. + */ fun getComponent(id: String, component: Int) = get(id).components?.get(component) + /** + * Retrieves a specific component of an entity based on its identifier and component index. + * + * @param id The identifier of the entity to retrieve. + * @param component The index of the component to retrieve from the entity. + * @return The component at the specified index, or null if not found. + */ fun getComponent(id: Int, component: Int) = get(id).components?.get(component) + /** + * Retrieves an empty instance of `InterfaceDefinition`. + * + * This method provides a default or placeholder value representing an empty interface definition. + * It is commonly used when there is no specific data to return or as a fallback. + * + * @return A constant representing an empty interface definition. + */ override fun empty() = InterfaceDefinition.EMPTY + /** + * Loads interface definitions from the specified YAML configuration. + * + * @param yaml the YAML utility instance used for parsing configuration. Defaults to the result of `get()`. + * @param path the path to the YAML file containing the interface definitions. Defaults to `Settings["definitions.interfaces"]`. + * @param typePath the path to the YAML file containing the type definitions. Defaults to `Settings["definitions.interfaces.types"]`. + * @return an instance of `InterfaceDefinitions` containing the loaded interface definitions and associated data. + */ fun load( yaml: Yaml = get(), path: String = Settings["definitions.interfaces"], @@ -49,6 +140,16 @@ class InterfaceDefinitions( val componentIds = Object2IntOpenHashMap() this.componentIds = componentIds val config = object : YamlReaderConfiguration(2, 2) { + /** + * Overrides the behavior for setting a key-value pair in a map during YAML parsing, with additional custom logic + * based on specific conditions such as `key`, `value` type, and `indent` level. + * + * @param map The map to which a key-value pair needs to be set. + * @param key The key to be associated with the value in the map. + * @param value The value to be set in the map. + * @param indent The current indentation level in the YAML data structure. + * @param parentMap The parent map key, if relevant to the context, used for hierarchical structures or null. + */ @Suppress("UNCHECKED_CAST") override fun set(map: MutableMap, key: String, value: Any, indent: Int, parentMap: String?) { if (key == "options" && value is Map<*, *> && indent == 3) { @@ -132,6 +233,14 @@ class InterfaceDefinitions( return this } + /** + * Retrieves an existing `InterfaceComponentDefinition` for the specified `id` and `index` or creates + * and stores a new one if it does not already exist. + * + * @param id The unique identifier for the interface definition. + * @param index The index of the component definition within the interface. + * @return The `InterfaceComponentDefinition` associated with the given `id` and `index`. + */ private fun getOrPut(id: Int, index: Int): InterfaceComponentDefinition { val definition = definitions[id] var components = definition.components @@ -142,6 +251,17 @@ class InterfaceDefinitions( return components.getOrPut(index) { InterfaceComponentDefinition(id = index + (id shl 16)) } } + /** + * Processes a nested map structure and returns a new map with transformed values. + * + * The method modifies the input map by generating new values based on specific keys (`index`, `parent`, `fixedParent`, `resizeParent`, + * `fixedIndex`, `resizeIndex`, and optionally `permanent`). If certain keys are not found, it uses predefined fallback defaults. + * + * @param data A map where the keys represent string identifiers and the values are nested maps containing key-value pairs + * used for generating the transformed map. + * @return A new map with the same structure as the input, but with transformed inner maps containing keys like `parent_fixed`, + * `parent_resize`, `index_fixed`, `index_resize`, and optionally `permanent`. + */ private fun loadTypes(data: Map>): Map> { return data.mapValues { (_, values) -> val index = values["index"] as? Int diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/InventoryDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/InventoryDefinitions.kt index 810a3c5e0..13c2ac98c 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/InventoryDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/InventoryDefinitions.kt @@ -8,19 +8,62 @@ import world.gregs.voidps.engine.get import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml +/** + * Represents the definitions for inventories in the system. This class handles the loading + * and decoding of inventory-related definitions from configuration files. + * + * @property definitions Array of `InventoryDefinition` objects that define the inventory details. + */ class InventoryDefinitions( override var definitions: Array ) : DefinitionsDecoder { + /** + * A map storing unique identifiers as keys and their associated integer values. + * The keys are of type `String`, and the corresponding values are of type `Int`. + * This variable is marked as `lateinit`, which means it will be initialized later. + * It is overridden from a base class or interface where it is declared. + */ override lateinit var ids: Map + /** + * Overrides the `empty` method to return a predefined constant representing + * an empty inventory definition. This method provides a standard way to + * access an empty or default state for the inventory definition. + * + * @return An instance of `InventoryDefinition.EMPTY` representing an empty inventory. + */ override fun empty() = InventoryDefinition.EMPTY + /** + * Loads inventory definitions from the provided YAML configuration file. + * + * @param yaml The YAML parser instance to use for loading the configurations. Defaults to the result of `get()` function. + * @param path The path to the YAML file containing the inventory definitions. Defaults to the value of `Settings["definitions.inventories"]`. + * @param itemDefs The item definitions used for resolving item IDs and data. Defaults to the result of `get()` function. + * @return The loaded inventory definitions. + */ @Suppress("UNCHECKED_CAST") fun load(yaml: Yaml = get(), path: String = Settings["definitions.inventories"], itemDefs: ItemDefinitions = get()): InventoryDefinitions { timedLoad("inventory extra") { val ids = Object2IntOpenHashMap() val config = object : DefinitionConfig(ids, definitions) { + /** + * Overrides the set method to modify the behavior when the key is "defaults" and + * the value is a list. Processes the list to update specific fields of a definition + * object if conditions are met, then delegates to the superclass method for other cases. + * + * @param map A mutable map containing string keys and arbitrary values. Represents a + * structure to be manipulated. + * @param key A string key used to identify the data to be processed or modified + * within the map. + * @param value The value associated with the key in the map, which may be manipulated + * if specific conditions are met. + * @param indent The current indentation level, which may be relevant for structured + * data processing. + * @param parentMap An optional string reference to the parent map, allowing access to + * higher-level context if needed. + */ override fun set(map: MutableMap, key: String, value: Any, indent: Int, parentMap: String?) { if (key == "defaults" && value is List<*>) { val id = map["id"] as Int @@ -44,6 +87,12 @@ class InventoryDefinitions( } } +/** + * Retrieves a list of string identifiers for items in the inventory. + * + * @return A list of string IDs representing the items in the inventory. + * If the inventory is null or empty, an empty list is returned. + */ fun InventoryDefinition.items(): List { val defs: ItemDefinitions = get() return ids?.map { defs.get(it).stringId } ?: emptyList() diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ItemDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ItemDefinitions.kt index 45978d705..6f9bbc65f 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ItemDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ItemDefinitions.kt @@ -17,16 +17,49 @@ import world.gregs.voidps.network.login.protocol.visual.update.player.EquipSlot import world.gregs.yaml.Yaml import world.gregs.yaml.read.YamlReader +/** + * A class representing definitions for items. It provides decoding capabilities + * for item definitions and operations to manage and load them. + * + * @property definitions An array of `ItemDefinition` objects representing item details. + * @property size The total number of item definitions available. + */ class ItemDefinitions( override var definitions: Array ) : DefinitionsDecoder { + /** + * Represents the size of a collection or dataset. + * Stores the total number of elements in the collection. + * The value is derived from the size of the `definitions` collection. + */ val size: Int = definitions.size + /** + * A map that associates string keys with integer values, representing unique identifiers. + * The variable is declared using `lateinit` to allow for deferred initialization and + * is marked as `override` to indicate it overrides a property in a supertype. + */ override lateinit var ids: Map + /** + * Indicates an overridden method that provides an empty state or representation + * of an `ItemDefinition`. + * + * This method returns a constant value representing an "empty" `ItemDefinition` + * as defined by `ItemDefinition.EMPTY`. + * + * @return An empty instance of `ItemDefinition`. + */ override fun empty() = ItemDefinition.EMPTY + /** + * Loads item definitions using the provided YAML configuration and path. + * + * @param yaml The YAML configuration to load. Defaults to the result of the `get()` function. + * @param path The path to the definitions file within the YAML configuration. Defaults to the value of `Settings["definitions.items"]`. + * @return The loaded item definitions as an `ItemDefinitions` object. + */ fun load(yaml: Yaml = get(), path: String = Settings["definitions.items"]): ItemDefinitions { timedLoad("item extra") { val equipment = IntArray(definitions.size) { -1 } @@ -45,12 +78,42 @@ class ItemDefinitions( return this } + /** + * CustomConfig is a specialized configuration class responsible for managing the + * properties and attributes of game items. It extends the DefinitionConfig class and + * provides implementations for handling custom logic specific to game mechanics. + * + * This class overrides methods for data parsing and transformation, offering support + * for a variety of game-related attributes and types such as equipment, crafting, + * and resource handling (e.g., pottery, smelting, fishing). + * + * The class also provides specific handling for nested map structures, range-based + * values, and object transformations based on the indentation levels and keys + * encountered during YAML processing. + * + * @property equipment Array of integers representing equipment configuration + * @property ids Mutable map linking string keys to integer indices + * @property definitions Array of ItemDefinition objects containing metadata + * for corresponding game items + */ @Suppress("UNCHECKED_CAST") private class CustomConfig( private val equipment: IntArray, ids: MutableMap, definitions: Array ) : DefinitionConfig(ids, definitions) { + /** + * Sets a value in the specified map based on the parameters provided and specific conditions, + * delegating to the superclass or handling custom logic for specific cases. + * + * @param reader The YamlReader instance used to parse and retrieve values. + * @param map The mutable map where the key-value pair will be set or modified. + * @param key The key in the map to associate the value with. + * @param indent The current indentation level of the YAML being read. + * @param indentOffset The offset to account for in the indentation level. + * @param withinMap Optional string indicating the context within a nested map, if applicable. + * @param parentMap Optional string indicating the parent map, if applicable. + */ override fun setMapValue(reader: YamlReader, map: MutableMap, key: String, indent: Int, indentOffset: Int, withinMap: String?, parentMap: String?) { if (indent > 1 && parentMap == "pottery") { val value = reader.value(indentOffset, withinMap) @@ -62,6 +125,14 @@ class ItemDefinitions( } } + /** + * Sets a value in the specified map with additional handling for specific keys and definitions. + * + * @param map The mutable map where the value will be set. + * @param key The key under which the value will be set. Special handling applies to keys ending with "_lent". + * @param id The definition ID used to determine the appropriate behavior and extras. + * @param extras An optional map of additional properties to include when setting the value. + */ override fun set(map: MutableMap, key: String, id: Int, extras: Map?) { if (key.endsWith("_lent") && id in definitions.indices) { val def = definitions[id] @@ -81,6 +152,17 @@ class ItemDefinitions( } } + /** + * Overrides the `set` method to provide custom behavior for handling specific key-value pairs + * within a mutable map. Processes and maps the provided key and value based on defined rules + * and further modifies the input map if needed. + * + * @param map The mutable map to be updated or modified. + * @param key The key corresponding to the value being processed or inserted into the map. + * @param value The value to be processed or inserted based on the key. + * @param indent The current level of indentation or depth in the processing logic. + * @param parentMap An optional string value indicating the parent map context or hierarchy. + */ override fun set(map: MutableMap, key: String, value: Any, indent: Int, parentMap: String?) { if (indent == 1) { super.set(map, key, when (key) { @@ -125,6 +207,12 @@ class ItemDefinitions( } } + /** + * Processes the given anchor object and removes the "aka" entry if the resulting value is a mutable map. + * + * @param anchor The input object to be processed and potentially modified. + * @return The processed object, with "aka" removed if it is a mutable map. + */ override fun anchor(anchor: Any): Any { val value = super.anchor(anchor) if (value is MutableMap<*, *>) { diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ItemOnItemDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ItemOnItemDefinitions.kt index e278320f5..261f91f48 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ItemOnItemDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ItemOnItemDefinitions.kt @@ -14,22 +14,72 @@ import world.gregs.voidps.engine.get import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml +/** + * Represents a collection of item-on-item interaction definitions. + * These definitions describe how two items interact with each other in a specific context. + */ class ItemOnItemDefinitions { + /** + * Stores a mapping between a string key and a list of `ItemOnItemDefinition` objects. + * This variable is initialized later using the `lateinit` modifier, meaning it must + * be assigned a value before its first use. It is private and cannot be accessed outside + * of its containing class. + */ private lateinit var definitions: Map> + /** + * Retrieves a list of results based on the provided items. If no results are found, + * it returns an empty list. + * + * @param one The first item to be used in the retrieval process. + * @param two The second item to be used in the retrieval process. + * @return A list of results corresponding to the provided items or an empty list if no results are found. + */ fun get(one: Item, two: Item) = getOrNull(one, two) ?: emptyList() + /** + * Retrieves a value from the `definitions` map based on the combined identifier + * of the given `one` and `two` items. If no value is found for the first identifier, + * it tries with the reversed identifier. + * + * @param one The first item used to construct the identifier. + * @param two The second item used to construct the identifier. + * @return The value associated with the identifier, or null if no value is found. + */ fun getOrNull(one: Item, two: Item) = definitions[id(one, two)] ?: definitions[id(two, one)] + /** + * Checks if the specified combination of two items exists in the definitions map. + * + * @param one the first item to check for containment. + * @param two the second item to check for containment. + * @return `true` if the combination of the two items is present in the definitions map, either as (one, two) or (two, one), `false` otherwise. + */ fun contains(one: Item, two: Item) = definitions.containsKey(id(one, two)) || definitions.containsKey(id(two, one)) + /** + * Loads and processes item-on-item definitions from a YAML configuration file. + * + * @param yaml An instance of the Yaml parser to use for loading the configuration. Defaults to the result of `get()`. + * @param path The file path of the YAML configuration file defining the item-on-item interactions. Defaults to the value specified in the `Settings["definitions.itemOnItem"] + * `. + * @param itemDefinitions The collection of item definitions to validate against when processing the YAML data. Defaults to the result of `get()`. + * @return The `ItemOnItemDefinitions` instance populated with the loaded definitions. + */ @Suppress("UNCHECKED_CAST") fun load(yaml: Yaml = get(), path: String = Settings["definitions.itemOnItem"], itemDefinitions: ItemDefinitions = get()): ItemOnItemDefinitions { timedLoad("item on item definition") { val definitions = Object2ObjectOpenHashMap>() var count = 0 val config = object : DefinitionIdsConfig() { + /** + * Adds an item to the provided list, converting input values into the appropriate representation. + * + * @param list The mutable list to which the item will be added. + * @param value The value to be added, which may be a Map or a String representing the item. + * @param parentMap An optional reference to a parent map, used for context during addition. + */ override fun add(list: MutableList, value: Any, parentMap: String?) { super.add(list, if (value is Map<*, *>) { val id = value["item"] as String @@ -42,6 +92,17 @@ class ItemOnItemDefinitions { }, parentMap) } + /** + * Overrides the parent set method to process and store item definitions or delegate to the super method depending on the indent level. + * At an indent level of 0, processes the map to create and add item-on-item definitions for various requirements. + * At different indent levels, forwards the data to the super set method with specific handling for certain keys. + * + * @param map The map being modified or updated. + * @param key The key in the map that corresponds to the value being set. + * @param value The new value being set in the map, which can vary in type depending on the key. + * @param indent The level of indentation for the current operation, determining the processing logic. + * @param parentMap An optional parent map name, typically used for contextual or hierarchical operations. + */ override fun set(map: MutableMap, key: String, value: Any, indent: Int, parentMap: String?) { if (indent == 0) { val definition = ItemOnItemDefinition(value as Map) @@ -77,8 +138,23 @@ class ItemOnItemDefinitions { return this } + /** + * Companion object for the outer class, providing additional utilities and helper methods. + */ companion object { + /** + * A logger instance used for logging messages within the scope of this class or file. + * This logger is an instance of `InlineLogger`, which allows for inline logging functionality. + * It is declared as a private property, restricting its visibility to the containing scope. + */ private val logger = InlineLogger() + /** + * Combines the IDs of two Item objects into a single string, separated by an ampersand. + * + * @param one The first Item object. + * @param two The second Item object. + * @return A string combining the IDs of the two Item objects separated by "&". + */ private fun id(one: Item, two: Item): String = "${one.id}&${two.id}" } diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/JingleDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/JingleDefinitions.kt index cfa8dc678..ce55dbf5b 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/JingleDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/JingleDefinitions.kt @@ -7,11 +7,34 @@ import world.gregs.voidps.engine.get import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml +/** + * JingleDefinitions is responsible for decoding and managing a collection of JingleDefinition objects + * from a specified configuration source. It provides functionality for loading definitions from a YAML file + * and managing their identifiers and mappings. + */ class JingleDefinitions : DefinitionsDecoder { + /** + * An array of `JingleDefinition` objects that holds specific definitions + * used within the context of a jingle or messaging component. + * This property must be initialized before use. + */ override lateinit var definitions: Array + /** + * A map that associates string keys to integer values. + * This overridden lateinit property allows lazy initialization + * and is intended to store a collection of IDs, with each ID represented + * as a key-value pair. + */ override lateinit var ids: Map + /** + * Loads jingle definitions from the specified YAML configuration. + * + * @param yaml The YAML configuration to use for loading. Defaults to the output of the `get()` function. + * @param path The path in the YAML configuration where the jingle definitions are stored. Defaults to the value of `Settings["definitions.jingles"]`. + * @return The loaded `JingleDefinitions` instance. + */ fun load(yaml: Yaml = get(), path: String = Settings["definitions.jingles"]): JingleDefinitions { timedLoad("jingle definition") { decode(yaml, path) { id, key, _ -> @@ -21,6 +44,15 @@ class JingleDefinitions : DefinitionsDecoder { return this } + /** + * Returns an empty representation of a JingleDefinition. + * + * This method provides a standard way to retrieve an empty or placeholder + * JingleDefinition object, which can be used when no meaningful data is available + * or no specific configuration is required. + * + * @return JingleDefinition.EMPTY, representing an empty JingleDefinition. + */ override fun empty() = JingleDefinition.EMPTY } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/MapDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/MapDefinitions.kt index de4f56561..49af421f4 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/MapDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/MapDefinitions.kt @@ -15,9 +15,14 @@ import world.gregs.voidps.type.Region import world.gregs.voidps.type.Zone /** - * Loads map collision and objects directly, quicker than [MapDecoder] + * The `MapDefinitions` class is responsible for managing game map data, + * including collision decoding, object decoding, and handling map caches. + * It supports loading map regions and zones with or without encryption keys (XTEAs), + * and integrates with multiple underlying decoders and game object handling systems. * - * Note: this is the only place we store the cache; for dynamic zone loading. + * @property collisions The collision decoder for handling blocked tiles and collision flags. + * @property objects The collection of game objects present in the map. + * @property cache The data cache used to store and retrieve map-related data. */ class MapDefinitions( private val collisions: CollisionDecoder, @@ -25,11 +30,38 @@ class MapDefinitions( private val objects: GameObjects, private val cache: Cache ) { + /** + * Logger instance for use within the MapDefinitions class to provide logging functionality + * for actions and events related to map data processing and handling. + */ private val logger = InlineLogger() + /** + * The `decoder` is an instance of `MapObjectsDecoder`. It is used to decode and manage + * map objects while associating them with their relevant definitions. The decoder handles: + * - Decoding map objects data from the cache. + * - Adding objects to the game world with their defined properties like shape, rotation, and level. + * - Managing collision data for tiles except for specific types like bridges. + * + * It encapsulates logic for parsing and setting objects into the game map, leveraging object + * data and definitions provided by `GameObjects` and `ObjectDefinitions`. + */ private val decoder = MapObjectsDecoder(objects, definitions) + /** + * Decoder used to transform and decode map objects from a specified zone into another zone with rotation applied. + * This instance utilizes the `MapObjectsRotatedDecoder` class to handle decoding logic and object transformations. + * It works with game object data (`objects`) and their definitions (`definitions`) for processing. + */ private val rotationDecoder = MapObjectsRotatedDecoder(objects, definitions) + /** + * Loads the map data and tiles cache for the current region. Decodes map tiles, + * collision data, and other related information, using optional XTEA keys. + * + * @param xteas Optional map of region IDs to XTEA key arrays for decryption. + * If null, regions are loaded without decryption. + * @return The current instance of [MapDefinitions]. + */ fun loadCache(xteas: Map? = null): MapDefinitions { val start = System.currentTimeMillis() var regions = 0 @@ -46,6 +78,14 @@ class MapDefinitions( return this } + /** + * Loads a zone from one region to another, decodes collision data, and processes rotation and optional XTEA keys. + * + * @param from The source zone to be loaded. + * @param to The destination zone where the data will be applied. + * @param rotation The rotation value to apply during decoding. + * @param xteas Optional mapping of XTEA keys used for decoding. + */ fun loadZone(from: Zone, to: Zone, rotation: Int, xteas: Map? = null) { val start = System.currentTimeMillis() val tiles = loadTiles(cache, from.region.x, from.region.y) ?: return @@ -58,6 +98,15 @@ class MapDefinitions( } } + /** + * Loads the tiles for a specified map region using the provided cache. + * + * @param cache The cache to look up the map data from. + * @param regionX The x-coordinate of the map region to load. + * @param regionY The y-coordinate of the map region to load. + * @return A LongArray containing the tile data for the specified region, or null if the archive is not found + * or the data cannot be loaded. + */ private fun loadTiles(cache: Cache, regionX: Int, regionY: Int): LongArray? { val archive = cache.archiveId(Index.MAPS, "m${regionX}_$regionY") if (archive == -1) { diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/MidiDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/MidiDefinitions.kt index b03826729..40a8c718d 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/MidiDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/MidiDefinitions.kt @@ -7,11 +7,37 @@ import world.gregs.voidps.engine.get import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml +/** + * Represents a specific implementation of `DefinitionsDecoder` for MIDI definitions. + * This class handles the loading, decoding, and management of `MidiDefinition` objects, + * including their mappings to both integer and string-based identifiers. + */ class MidiDefinitions : DefinitionsDecoder { + /** + * An overridden and late-initialized array of `MidiDefinition` objects. + * This variable is intended to store MIDI configuration or definitions + * and must be initialized before use. + */ override lateinit var definitions: Array + /** + * A mapping of string identifiers to their respective integer IDs for MIDI definitions. + * + * This map associates a unique string identifier with its corresponding numeric ID, + * which is used to reference specific MIDI definitions within the application. + * + * Key: The string identifier for a MIDI definition. + * Value: The numeric ID associated with the string identifier. + */ override lateinit var ids: Map + /** + * Loads MIDI definitions from the specified YAML configuration file. + * + * @param yaml An instance of the `Yaml` object for parsing the configuration file. Defaults to the result of `get()`. + * @param path The file path to the YAML configuration containing MIDI definitions. Defaults to the value of `Settings["definitions.midis"]`. + * @return The loaded `MidiDefinitions` object. + */ fun load(yaml: Yaml = get(), path: String = Settings["definitions.midis"]): MidiDefinitions { timedLoad("midi definition") { decode(yaml, path) { id, key, _ -> @@ -21,6 +47,13 @@ class MidiDefinitions : DefinitionsDecoder { return this } + /** + * Returns an empty instance of `MidiDefinition`. + * + * This method is used to provide a default or placeholder `MidiDefinition` when no specific definition is available. + * + * @return The empty instance of `MidiDefinition`, defined as `MidiDefinition.EMPTY`. + */ override fun empty() = MidiDefinition.EMPTY } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/NPCDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/NPCDefinitions.kt index 34731e1e5..16dc3c13f 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/NPCDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/NPCDefinitions.kt @@ -12,20 +12,61 @@ import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml import world.gregs.yaml.read.YamlReader +/** + * Represents a decoder for NPC (Non-Player Character) definitions. This class is responsible for + * reading and managing an array of `NPCDefinition` objects, and optionally loading them from + * a YAML configuration file. + * + * @property definitions An array of `NPCDefinition` instances representing the NPCs. + */ class NPCDefinitions( override var definitions: Array ) : DefinitionsDecoder { + /** + * A map containing identifiers for NPC definitions. + * + * The key represents a string identifier for the NPC, and the value is an integer + * corresponding to the NPC's unique internal ID. + */ override lateinit var ids: Map + /** + * Provides an empty NPC definition as a placeholder or default instance. + * + * Returns a predefined constant representing an NPC definition with no data or properties. + * Useful for scenarios where an NPC definition is required but no specific data is available. + */ override fun empty() = NPCDefinition.EMPTY + /** + * Loads NPC definitions from the specified YAML file at the given path. + * + * This method parses and configures NPC definitions using a custom DefinitionConfig class, + * adapting specific configurations based on the provided YAML data. + * + * @param yaml The YAML parser to use for loading data. Defaults to the global YAML instance. + * @param path The file path to the YAML data for the NPC definitions. Defaults to the path specified in application settings. + * @return The updated instance of NPCDefinitions containing the loaded data. + */ @Suppress("UNCHECKED_CAST") fun load(yaml: Yaml = get(), path: String = Settings["definitions.npcs"]): NPCDefinitions { timedLoad("npc extra") { val ids = Object2IntOpenHashMap() this.ids = ids val config = object : DefinitionConfig(ids, definitions) { + /** + * Sets a value in the provided map based on the key, indentation level, and other contextual parameters. + * Overrides the behavior for the key "chance" when the indentation level is 2, calling a specialized method to process the value. + * + * @param reader An instance of YamlReader used to parse and read the YAML content. + * @param map A mutable map where the key-value pair should be set or modified. + * @param key The key in the YAML map for which the value will be set. + * @param indent The current indentation level within the YAML structure, used to determine parsing logic. + * @param indentOffset The offset from the base indentation level, providing additional context for parsing. + * @param withinMap The identifier or name of the current nested map being processed, if applicable. + * @param parentMap The identifier or name of the immediate parent map within the YAML structure, if applicable. + */ override fun setMapValue(reader: YamlReader, map: MutableMap, key: String, indent: Int, indentOffset: Int, withinMap: String?, parentMap: String?) { if (indent == 2 && key == "chance") { set(map, key, reader.readIntRange(), indent, parentMap) @@ -34,6 +75,16 @@ class NPCDefinitions( } } + /** + * Sets a key-value pair in the provided map. Handles special cases for merging maps, + * creating custom objects, and delegating behavior based on the indent parameter. + * + * @param map The mutable map where the key-value pair will be set. + * @param key The key to set in the map. + * @param value The value associated with the key. + * @param indent The indentation level, used to determine specific behaviors. + * @param parentMap An optional string identifier for the parent map, if applicable. + */ override fun set(map: MutableMap, key: String, value: Any, indent: Int, parentMap: String?) { if (key == "<<") { map.putAll(value as Map) diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ObjectDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ObjectDefinitions.kt index 81f5d22a7..7fbe9fcc9 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ObjectDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ObjectDefinitions.kt @@ -12,24 +12,70 @@ import world.gregs.voidps.engine.get import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml +/** + * A container and manager for handling an array of `ObjectDefinition` objects. + * This class provides functionality to decode, retrieve, and load object definitions, + * allowing for configuration and customization of the objects using external YAML files. + * + * @property definitions An array of `ObjectDefinition` objects representing the core data structure. + */ class ObjectDefinitions( override var definitions: Array ) : DefinitionsDecoder { + /** + * A map linking unique string identifiers to integer IDs. + * + * This is used to store and retrieve mappings for object definitions, where each key is a string + * representing the name or identifier, and each value is an integer ID associated with it. + */ override lateinit var ids: Map + /** + * Retrieves the `ObjectDefinition` corresponding to the specified identifier. + * + * @param id The unique identifier of the `ObjectDefinition` to retrieve. + * @return The `ObjectDefinition` associated with the given identifier. + */ fun getValue(id: Int): ObjectDefinition { return definitions[id] } + /** + * Provides an empty instance of `ObjectDefinition`. + * + * This function returns a predefined constant `ObjectDefinition.EMPTY`, which represents + * a placeholder or default object definition with no specific data. It is typically used + * when no actual data is available or required for a given context. + * + * @return The empty instance of `ObjectDefinition`. + */ override fun empty() = ObjectDefinition.EMPTY + /** + * Loads object definitions from a YAML file and initializes object-specific configurations. + * + * @param yaml An instance of the Yaml class, used to parse the YAML file. Defaults to the result of the `get` function. + * @param path The file path to the YAML definitions. Defaults to the value from `Settings["definitions.objects"]`. + * @return The current instance of ObjectDefinitions, loaded with parsed data and mappings. + */ @Suppress("UNCHECKED_CAST") fun load(yaml: Yaml = get(), path: String = Settings["definitions.objects"]): ObjectDefinitions { timedLoad("object extra") { val ids = Object2IntOpenHashMap() this.ids = ids val config = object : DefinitionConfig(ids, definitions) { + /** + * Sets a key-value pair in the provided map based on the given parameters. Depending on the + * provided key, value, and indentation level, the method applies different transformations + * or types/mappings to the value before setting it into the map. + * + * @param map The mutable map where the key-value pair should be set. + * @param key The key to be used in the map. + * @param value The value to be associated with the key in the map. + * @param indent The indentation level that determines how the key-value pair is processed. + * @param parentMap An optional parent map reference for further processing, if required. + */ override fun set(map: MutableMap, key: String, value: Any, indent: Int, parentMap: String?) { if (key == "<<") { map.putAll(value as Map) diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ParameterDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ParameterDefinitions.kt index b18a44c57..e77316a9e 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ParameterDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/ParameterDefinitions.kt @@ -13,18 +13,51 @@ import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml /** - * Parameters mainly for [ItemDefinitions], [NPCDefinitions], [ObjectDefinitions] and [StructDefinitions] + * ParameterDefinitions is responsible for decoding and managing collections of parameter definitions. + * This class implements the `DefinitionsDecoder` interface with a specific type of `ParameterDefinition` and + * also provides functionality from the `Parameters` interface. + * + * It utilizes `CategoryDefinitions` and `AmmoDefinitions` to handle relationships between parameters + * and their respective categories or ammo groups. */ class ParameterDefinitions( private val categoryDefinitions: CategoryDefinitions, private val ammoDefinitions: AmmoDefinitions ) : DefinitionsDecoder, Parameters { + /** + * An overridden and late-initialized property of type Array containing elements of ParameterDefinition. + * This property is designed to hold parameter definitions, ensuring they can be accessed once initialized. + */ override lateinit var definitions: Array + /** + * A Map representing unique identifiers where the key is a String, + * and the value is an Integer. This map is initialized later and is used + * to store mappings between string identifiers and their corresponding integer values. + */ override lateinit var ids: Map + /** + * A map representing parameter definitions where the key is an integer identifier + * and the value is a string containing the associated parameter's definition or name. + * + * This property is expected to be initialized at runtime and provides access to + * parameter-related metadata within the containing class. + */ override lateinit var parameters: Map + /** + * Logger instance used for logging within the `ParameterDefinitions` class. + * Provides inline logging capabilities to track or debug the behavior of operations + * related to parameter definitions. + */ private val logger = InlineLogger() + /** + * Loads parameter definitions from a YAML configuration file. + * + * @param yaml The YAML configuration object to use for loading. Defaults to the result of `get()`. + * @param path The path to the parameter definitions in the YAML file. Defaults to `Settings["definitions.parameters"]`. + * @return A `ParameterDefinitions` instance containing the loaded parameter definitions. + */ fun load(yaml: Yaml = get(), path: String = Settings["definitions.parameters"]): ParameterDefinitions { timedLoad("parameter definition") { val size = decode(yaml, path) { id, key, _ -> @@ -36,6 +69,15 @@ class ParameterDefinitions( return this } + /** + * Sets the specified value in the `extras` map based on the provided `name` key. + * The behavior of this method varies depending on the prefix or suffix of the `name` key. + * Handles specific cases such as `equip_skill_`, `equip_level_`, `use_skill_`, `use_level_`, and more. + * + * @param extras A mutable map where the key-value pairs are stored. This is the target map for the operation. + * @param name The key used to determine the specific operation to perform or the value to set in the extras map. + * @param value The value to be added or processed in relation to the key and logic defined by the method. + */ @Suppress("UNCHECKED_CAST") override fun set(extras: MutableMap, name: String, value: Any) { when { @@ -81,6 +123,14 @@ class ParameterDefinitions( } } + /** + * Checks if the parameter definition is empty and returns an empty instance of `ParameterDefinition`. + * + * This method is overridden to provide a default empty state for parameter definitions, + * ensuring a consistent contract for handling empty or unset parameter definitions. + * + * @return An instance of `ParameterDefinition.EMPTY` representing an empty parameter definition. + */ override fun empty() = ParameterDefinition.EMPTY } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/PatrolDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/PatrolDefinitions.kt index 8f6cad74a..23913e369 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/PatrolDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/PatrolDefinitions.kt @@ -8,17 +8,55 @@ import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml import world.gregs.yaml.read.YamlReaderConfiguration +/** + * A class representing a collection of patrol definitions. + * This class provides functionality for loading patrol definitions + * from a YAML file and accessing specific definitions by their keys. + */ class PatrolDefinitions { + /** + * A map containing patrol definitions, associating a unique string identifier to each [PatrolDefinition]. + * + * Utilized for storing and managing the collection of patrol definitions loaded from external data sources. + */ private lateinit var definitions: Map + /** + * Retrieves the value associated with the given key from the definitions map. + * If the key is not found, returns a new instance of `PatrolDefinition`. + * + * @param key The key whose associated value is to be returned. + * @return The value associated with the specified key or a new `PatrolDefinition` if the key is not found. + */ fun get(key: String) = definitions[key] ?: PatrolDefinition() + /** + * Loads patrol definitions from a YAML configuration file and populates the `definitions` map. + * + * @param yaml The YAML parsing instance to be used for loading, with a default value obtained from `get()`. + * @param path The path to the YAML file that contains the patrol definitions, defaulting to the value in `Settings["definitions.patrols"]`. + * @return The updated `PatrolDefinitions` instance containing the loaded patrol definitions. + */ @Suppress("UNCHECKED_CAST") fun load(yaml: Yaml = get(), path: String = Settings["definitions.patrols"]): PatrolDefinitions { timedLoad("patrol definition") { val definitions = Object2ObjectOpenHashMap() val config = object : YamlReaderConfiguration() { + /** + * Configures the specified map by either adding or updating a key-value pair or merging another map, + * depending on the provided key and indentation level. + * + * @param map The mutable map to modify. + * @param key The key to set in the map. If the key equals "<<", the value is expected to be a map, + * which will be merged with the input map. + * @param value The value to associate with the specified key. If the `indent` is 0 and the value + * is a map, it will be used to create a `PatrolDefinition`. + * @param indent The indentation level, which determines whether the operation is handled directly + * or delegated to the parent class. + * @param parentMap The identifier of the parent map, which can be null. Used for maintaining + * structure in contexts involving nested maps. + */ override fun set(map: MutableMap, key: String, value: Any, indent: Int, parentMap: String?) { if (key == "<<") { map.putAll(value as Map) diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/PrayerDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/PrayerDefinitions.kt index 0fbfdd5b2..00e5a39a0 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/PrayerDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/PrayerDefinitions.kt @@ -10,23 +10,92 @@ import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml import world.gregs.yaml.read.YamlReaderConfiguration +/** + * Represents a collection of prayer definitions that include prayers, curses, and their associated metadata. + * Provides methods to load and access prayer definitions, and organizes them by groups for logical categorization. + */ class PrayerDefinitions { + /** + * A lazily initialized map that holds prayer definitions, where the key is a string identifier + * and the value is an instance of `PrayerDefinition`. + */ private lateinit var definitions: Map + /** + * A variable holding an array of PrayerDefinition objects. + * This variable is initialized later in the program and intended to store + * the definitions or details of different prayers. + * It is defined as `lateinit` to allow deferred initialization. + */ private lateinit var prayers: Array + /** + * A private, late-initialized variable that holds an array of `PrayerDefinition` objects. + * This variable is intended to store a collection of prayer definitions + * and must be initialized before usage to avoid runtime exceptions. + */ private lateinit var curses: Array + /** + * Represents categorized groups of related strings identified by an integer key. + * + * The map associates each integer key with a set of strings, where: + * - The integer key serves as the identifier for a specific group. + * - The set of strings contains related or grouped values. + * + * This property is used to manage or reference predefined groups of strings within a data structure + * or process, such as categorizing items, settings, or elements. + */ private lateinit var groups: Map> + /** + * Retrieves a value associated with the given key. If the key does not exist, returns an empty `PrayerDefinition`. + * + * @param key the key for which the value is to be retrieved + * @return the value associated with the key or an empty `PrayerDefinition` if the key does not exist + */ fun get(key: String) = getOrNull(key) ?: PrayerDefinition.EMPTY + /** + * Retrieves the value associated with the given key from the definitions map, + * or returns null if the key does not exist in the map. + * + * @param key The key whose associated value is to be returned. + * @return The value associated with the specified key, or null if the key is not present in the map. + */ fun getOrNull(key: String) = definitions[key] + /** + * Retrieves a prayer from the list of prayers based on the provided index. + * + * @param index The position in the prayers list to retrieve. + * @return The prayer at the specified index. + * @throws IndexOutOfBoundsException If the index is out of range of the prayers list. + */ fun getPrayer(index: Int) = prayers[index] + /** + * Retrieves a curse definition at the specified index. + * + * @param index The index of the curse to retrieve. + * @return The curse located at the given index. + * @throws IndexOutOfBoundsException if the index is out of bounds. + */ fun getCurse(index: Int) = curses[index] + /** + * Retrieves a group from the `groups` collection using the provided index. + * + * @param group The index of the group to retrieve. + * @return The group corresponding to the provided index. + */ fun getGroup(group: Int) = groups[group] + /** + * Loads prayer definitions from a YAML file and processes the data into structured definitions. + * + * @param yaml The YAML parser instance to use for loading data. Defaults to a newly created instance if not provided. + * @param path The file path or key in the settings where the YAML data is stored. Defaults to the configured path for prayer definitions. + * @return The processed prayer definitions structured into various categories (e.g., prayers, curses, groups). + */ @Suppress("UNCHECKED_CAST") fun load(yaml: Yaml = get(), path: String = Settings["definitions.prayers"]): PrayerDefinitions { timedLoad("prayer definition") { @@ -34,6 +103,15 @@ class PrayerDefinitions { val prayers = Int2ObjectArrayMap() val curses = Int2ObjectArrayMap() val config = object : YamlReaderConfiguration() { + /** + * Overrides the set method to process and store prayer or curse definitions based on the provided key and value. + * + * @param map The mutable map in which the provided key-value pair is to be processed and stored. + * @param key The key used to identify a prayer or curse, which may include specific suffixes like "_curse" or "_prayer". + * @param value The value associated with the key, which can be a Map or any other data type. + * @param indent The depth level used to determine the hierarchy of processing; special processing occurs when indent is 0. + * @param parentMap The parent map associated with the operation, which may be null. + */ override fun set(map: MutableMap, key: String, value: Any, indent: Int, parentMap: String?) { if (indent == 0) { val id = key.removeSuffix("_curse").removeSuffix("_prayer") diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/QuestDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/QuestDefinitions.kt index e28c65142..fc70ec264 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/QuestDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/QuestDefinitions.kt @@ -7,11 +7,38 @@ import world.gregs.voidps.engine.get import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml +/** + * Represents a decoder for quest definitions. This class is responsible for loading, storing, + * and processing definitions related to quests in the application. + * + * The `QuestDefinitions` class decodes YAML-based quest definition files and provides access + * to the parsed definitions as well as their corresponding IDs. + */ class QuestDefinitions : DefinitionsDecoder { + /** + * This property holds an array of `QuestDefinition` objects. + * It is overridden and marked as `lateinit`, which means it will be initialized at a later point + * before it is accessed. + */ override lateinit var definitions: Array + /** + * A map containing string keys and integer values, used to store and retrieve + * identification values associated with specific keys. + * + * This property is defined as a lateinit variable and must be initialized + * before it is accessed. The override modifier indicates that this variable + * overrides a similar property in a superclass or interface. + */ override lateinit var ids: Map + /** + * Loads quest definitions from the specified YAML configuration file and path. + * + * @param yaml The YAML parser to use for decoding the quest definitions. Defaults to the result of `get()`. + * @param path The path to the YAML file containing the quest definitions. Defaults to the value of `Settings["definitions.quests"]`. + * @return A `QuestDefinitions` object populated with the decoded quest definitions. + */ fun load(yaml: Yaml = get(), path: String = Settings["definitions.quests"]): QuestDefinitions { timedLoad("quest definition") { decode(yaml, path) { id, key, extras -> @@ -21,6 +48,15 @@ class QuestDefinitions : DefinitionsDecoder { return this } + /** + * Provides an implementation of the `empty` method, returning an empty or default instance of `QuestDefinition`. + * + * This method is designed to supply a standardized empty state for `QuestDefinition` objects. + * It is particularly useful in situations where an empty or placeholder quest definition is required, + * ensuring consistency and preventing null references. + * + * @return The predefined empty instance of `QuestDefinition`, represented by `QuestDefinition.EMPTY`. + */ override fun empty() = QuestDefinition.EMPTY } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/QuickChatPhraseDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/QuickChatPhraseDefinitions.kt index eeed30244..9592e9fc9 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/QuickChatPhraseDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/QuickChatPhraseDefinitions.kt @@ -2,14 +2,37 @@ package world.gregs.voidps.engine.data.definition import world.gregs.voidps.cache.definition.data.QuickChatPhraseDefinition +/** + * Represents a collection of quick chat phrase definitions. + * This class is responsible for decoding and managing quick chat phrase definitions. + * + * @property definitions The array of quick chat phrase definitions. + */ class QuickChatPhraseDefinitions( override var definitions: Array ) : DefinitionsDecoder { + /** + * A map that stores key-value pairs where the key is a String and the value is an Integer. + * This property is initialized lazily and can be overridden in subclasses. + */ override lateinit var ids: Map + /** + * Returns an empty instance of `QuickChatPhraseDefinition`. + * + * This method provides a predefined placeholder or default value, which is an instance + * of `QuickChatPhraseDefinition` that represents an empty or uninitialized state. + * + * @return The empty instance of `QuickChatPhraseDefinition`. + */ override fun empty() = QuickChatPhraseDefinition.EMPTY + /** + * Loads the quick chat phrase definitions and returns them as a QuickChatPhraseDefinitions instance. + * + * @return the loaded QuickChatPhraseDefinitions instance. + */ fun load(): QuickChatPhraseDefinitions { return this } diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/RenderEmoteDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/RenderEmoteDefinitions.kt index d672806ed..afa840705 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/RenderEmoteDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/RenderEmoteDefinitions.kt @@ -7,11 +7,35 @@ import world.gregs.voidps.engine.get import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml +/** + * Handles the decoding and management of `RenderEmoteDefinition` instances. + * Inherits from the `DefinitionsDecoder` interface and provides specific implementations + * for loading, managing, and retrieving render emote definitions. + */ class RenderEmoteDefinitions : DefinitionsDecoder { + /** + * An overridden, late-initialized property that holds an array of `RenderEmoteDefinition` objects. + * These definitions are likely used to configure or control the rendering of emotes within the application. + */ override lateinit var definitions: Array + /** + * A map where the keys are string identifiers and the values are integer IDs for render emote definitions. + * + * This map serves as a lookup table to associate string identifiers with their corresponding + * integer IDs. It is typically populated during the decoding of render emote definitions and + * used for quick access or reference by the string-based keys. + */ override lateinit var ids: Map + /** + * Loads render emote definitions from the specified YAML source and path, and initializes + * them using the provided decoding logic. + * + * @param yaml The YAML configuration object to load the definitions from. Defaults to the result of `get()`. + * @param path The path within the settings to locate the definitions. Defaults to the value of `Settings["definitions.renderEmotes"]`. + * @return A [RenderEmoteDefinitions] object containing the loaded render emote definitions. + */ fun load(yaml: Yaml = get(), path: String = Settings["definitions.renderEmotes"]): RenderEmoteDefinitions { timedLoad("render emote definition") { decode(yaml, path) { id, key, _ -> @@ -21,5 +45,14 @@ class RenderEmoteDefinitions : DefinitionsDecoder { return this } + /** + * Provides an empty or default instance of `RenderEmoteDefinition`. + * + * This method is used to return a placeholder or default value when no specific + * `RenderEmoteDefinition` instance is available. Typically used in scenarios where + * an absence of data needs to be representable with a neutral or predefined placeholder. + * + * @return A predefined empty instance of `RenderEmoteDefinition`. + */ override fun empty() = RenderEmoteDefinition.EMPTY } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/SoundDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/SoundDefinitions.kt index 17607a988..44edeadcd 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/SoundDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/SoundDefinitions.kt @@ -7,11 +7,33 @@ import world.gregs.voidps.engine.get import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml +/** + * Handles the decoding and management of sound definitions. It provides functionality to load, + * process, and manage sound definition objects, represented by the `SoundDefinition` class. + */ class SoundDefinitions : DefinitionsDecoder { + /** + * This property holds an array of `SoundDefinition` objects. It is defined as `lateinit`, meaning + * it should be initialized before accessing. The property is declared as `override`, suggesting + * that it is inherited and implements or overrides a member from a superclass or interface. + */ override lateinit var definitions: Array + /** + * A map associating string identifiers to their corresponding integer IDs for sound definitions. + * + * This variable is intended to provide quick access to sound definition IDs + * through their unique string identifiers. + */ override lateinit var ids: Map + /** + * Loads sound definitions from the provided YAML configuration. + * + * @param yaml The YAML configuration object to decode. Defaults to the result of `get()`. + * @param path The path within the settings to retrieve sound definitions. Defaults to `Settings["definitions.sounds"]`. + * @return SoundDefinitions instance populated with the loaded sound definitions. + */ fun load(yaml: Yaml = get(), path: String = Settings["definitions.sounds"]): SoundDefinitions { timedLoad("sound definition") { decode(yaml, path) { id, key, _ -> @@ -21,5 +43,13 @@ class SoundDefinitions : DefinitionsDecoder { return this } + /** + * Provides an empty or default instance of [SoundDefinition]. + * + * This method returns a predefined `EMPTY` instance of [SoundDefinition], which serves as a placeholder + * or default value when no specific sound definition is available. + * + * @return The `EMPTY` instance of [SoundDefinition]. + */ override fun empty() = SoundDefinition.EMPTY } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/SpellDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/SpellDefinitions.kt index 3285126ba..eb3a24834 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/SpellDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/SpellDefinitions.kt @@ -8,17 +8,51 @@ import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml import world.gregs.yaml.read.YamlReaderConfiguration +/** + * The `SpellDefinitions` class is responsible for managing a collection of spell definitions. + * It provides methods to retrieve and load spell definitions from a configuration source. + */ class SpellDefinitions { + /** + * A map that holds spell definitions, where the key is a unique identifier (String) + * and the value is an instance of [SpellDefinition]. + * + * This property is initialized through a loading mechanism and contains all available spell definitions. + * It is expected to be used for retrieving specific spell configurations within the system. + */ private lateinit var definitions: Map + /** + * Retrieves a `SpellDefinition` from the `definitions` map using the provided key. + * If the key does not exist in the map, a default `SpellDefinition` is returned. + * + * @param key The key used to locate the desired `SpellDefinition` in the map. + * @return The `SpellDefinition` corresponding to the key, or a default instance if the key is not found. + */ fun get(key: String) = definitions[key] ?: SpellDefinition() + /** + * Loads spell definitions from a YAML configuration file. + * + * @param yaml The YAML parser used for loading the file. Defaults to a provided instance. + * @param path The path to the YAML file containing the spell definitions. Defaults to a specified configuration path. + * @return An instance of [SpellDefinitions] containing the loaded spell definitions. + */ @Suppress("UNCHECKED_CAST") fun load(yaml: Yaml = get(), path: String = Settings["definitions.spells"]): SpellDefinitions { timedLoad("spell definition") { val definitions = Object2ObjectOpenHashMap() val config = object : YamlReaderConfiguration() { + /** + * Overrides the behavior for setting values in a map, with custom logic for handling certain keys and conditions. + * + * @param map The map in which the key-value pair will be set. + * @param key The key to be set in the map. + * @param value The value to be associated with the key in the map. + * @param indent The level of indentation, which determines how the key and value should be processed. + * @param parentMap The containing map's key, if applicable, to provide contextual information during processing. + */ override fun set(map: MutableMap, key: String, value: Any, indent: Int, parentMap: String?) { if (key == "<<") { map.putAll(value as Map) diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/StructDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/StructDefinitions.kt index fed69b16c..d395b3c7c 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/StructDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/StructDefinitions.kt @@ -7,16 +7,42 @@ import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml /** - * Also known as AttributeMaps in cs2 + * Represents a collection of `StructDefinition` objects, allowing for decoding, + * management, and manipulation of structured data definitions. This class extends + * the functionality of `DefinitionsDecoder` and provides additional methods to + * facilitate the loading and handling of structured definitions. + * + * @property definitions The array of `StructDefinition` instances managed by this class. */ class StructDefinitions( override var definitions: Array ) : DefinitionsDecoder { + /** + * A map associating string identifiers with their corresponding integer IDs. + * + * Typically used to map unique names or keys to numerical IDs for efficient lookup or storage. + * The keys in the map represent the unique string identifiers, while the values represent their associated integer IDs. + */ override lateinit var ids: Map + /** + * Returns an empty `StructDefinition` instance. + * + * This method provides a default or placeholder value representing + * an absence of meaningful data within the context of `StructDefinitions`. + * + * @return The static `EMPTY` instance of `StructDefinition`. + */ override fun empty() = StructDefinition.EMPTY + /** + * Loads structural definitions from the specified YAML configuration and path. + * + * @param yaml The YAML configuration to use. Defaults to the result of `get()`. + * @param path The path within the settings where the structural definitions are located. Defaults to the value of `Settings["definitions.structs"]`. + * @return The loaded structural definitions as an instance of `StructDefinitions`. + */ fun load(yaml: Yaml = get(), path: String = Settings["definitions.structs"]): StructDefinitions { timedLoad("struct extra") { decode(yaml, path) diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/VariableDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/VariableDefinitions.kt index 40fba7b62..36206d3ab 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/VariableDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/VariableDefinitions.kt @@ -11,18 +11,65 @@ import world.gregs.yaml.Yaml import java.io.File import kotlin.collections.set +/** + * A class responsible for managing and storing variable definitions, as well as providing access to those definitions. + * This includes mappings for variable definitions, varbit IDs, and varp IDs. + */ class VariableDefinitions { + /** + * A map containing variable definitions where the key is a string representing + * the variable's name and the value is an instance of `VariableDefinition`. + * This map initializes as empty by default. + */ private var definitions: Map = emptyMap() + /** + * A map that associates unique Varbit IDs with their corresponding names. + * + * These Varbit IDs are often used to reference specific configurable variables + * within the system, defined by their unique integer keys and their associated string identifiers. + * The map is initialized as empty by default. + */ private var varbitIds: Map = emptyMap() + /** + * A map representing variable parameter (varp) identifiers and their associated names. + * + * The map's keys are the identifiers (integers), and the associated values are their string representations. + * This serves as a lookup table for varp definitions within the context of variable definitions. + */ private var varpIds: Map = emptyMap() + /** + * Retrieves a value from the `definitions` map corresponding to the specified key. + * + * @param key The key used to lookup the value in the `definitions` map. + * @return The value associated with the provided key, or null if the key is not present. + */ fun get(key: String) = definitions[key] + /** + * Retrieves a varbit value by its unique identifier. + * + * @param id The unique identifier of the varbit to retrieve. + * @return The varbit value associated with the given identifier. + */ fun getVarbit(id: Int) = varbitIds[id] + /** + * Retrieves the variable parameter value associated with the specified ID. + * + * @param id The identifier of the variable parameter to retrieve. + * @return The value of the variable parameter corresponding to the given ID. + */ fun getVarp(id: Int) = varpIds[id] + /** + * Loads variable definitions from YAML files located at the specified path. + * + * @param yaml the `Yaml` instance used for loading the definitions, defaults to a singleton instance. + * @param path the directory path where the YAML files are located, defaults to the "definitions.path" setting. + * @return the instance of `VariableDefinitions` that contains the loaded definitions. + */ @Suppress("UNCHECKED_CAST") fun load(yaml: Yaml = get(), path: String = Settings["definitions.path"]): VariableDefinitions { timedLoad("variable definition") { @@ -50,7 +97,16 @@ class VariableDefinitions { } } val config = object : DefinitionIdsConfig() { - override fun set(map: MutableMap, key: String, value: Any, indent: Int, parentMap: String?) { + /** + * Overrides the `set` method to handle specific logic for updating a map with a key-value pair. + * + * @param map The mutable map in which the key-value pair will be updated or stored. + * @param key The key with which the specified value will be associated. + * @param value The value to be associated with the specified key in the map. + * @param indent The indentation level determining the behavior of this method. + * @param parentMap Optional parameter representing the parent map if applicable. + */ + override fun set(map: MutableMap, key: String, value: Any, indent: Int, parentMap: String?) { if (indent == 0) { val definition = factory.invoke(if (value is Int) { mapOf("id" to value) diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/WeaponAnimationDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/WeaponAnimationDefinitions.kt index fb48a7bed..cca736ed5 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/WeaponAnimationDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/WeaponAnimationDefinitions.kt @@ -8,18 +8,60 @@ import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml import world.gregs.yaml.read.YamlReaderConfiguration +/** + * This class is responsible for managing weapon animation definitions. + * It provides functionality to load, retrieve, and query animation definitions + * for weapons from a configuration source, typically in YAML format. + */ class WeaponAnimationDefinitions { + /** + * A map containing weapon animation definitions, where the key is a unique string identifier, + * and the value is the corresponding weapon animation definition. + * + * This map is populated during the loading process from an external configuration + * (e.g., YAML file) and provides quick access to the weapon animation definitions + * by their identifiers. + */ private lateinit var definitions: Map + /** + * Retrieves the value associated with the specified key or returns a default value if the key is not found. + * + * @param key the key whose associated value is to be returned. + * @return the value corresponding to the given key, or `WeaponAnimationDefinition.EMPTY` if no value is found. + */ fun get(key: String) = getOrNull(key) ?: WeaponAnimationDefinition.EMPTY + /** + * Retrieves the value associated with the provided key from the definitions map. + * If the key does not exist in the map, this function returns null. + * + * @param key The key whose associated value is to be retrieved. + * @return The value associated with the key, or null if the key is not found. + */ fun getOrNull(key: String) = definitions[key] + /** + * Loads weapon animation definitions from the specified YAML configuration file. + * + * @param yaml The YAML reader instance to load data. Defaults to an instance returned by `get()`. + * @param path The path to the configuration file containing weapon animation definitions. Defaults to the value of `Settings["definitions.weapons.animations"]`. + * @return The loaded `WeaponAnimationDefinitions` containing the parsed weapon animation data. + */ fun load(yaml: Yaml = get(), path: String = Settings["definitions.weapons.animations"]): WeaponAnimationDefinitions { timedLoad("weapon animation definition") { val definitions = Object2ObjectOpenHashMap() val config = object : YamlReaderConfiguration() { + /** + * Sets a value in the provided map or processes it based on the given parameters. + * + * @param map The mutable map where the key-value pair may be set. + * @param key The key associated with the value to be set. + * @param value The value to be set in the map or processed. + * @param indent Indicates the level of indentation or processing required. + * @param parentMap An optional parameter representing the parent map, if applicable. + */ override fun set(map: MutableMap, key: String, value: Any, indent: Int, parentMap: String?) { if (indent == 0) { definitions[key] = if (value is Map<*, *>) { diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/WeaponStyleDefinitions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/WeaponStyleDefinitions.kt index 53994bdfd..5c7819eba 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/WeaponStyleDefinitions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/WeaponStyleDefinitions.kt @@ -7,11 +7,36 @@ import world.gregs.voidps.engine.get import world.gregs.voidps.engine.timedLoad import world.gregs.yaml.Yaml +/** + * WeaponStyleDefinitions is a decoder class responsible for managing weapon style definitions. + * It extends DefinitionsDecoder to provide functionalities for loading, decoding, and storing weapon style data. + */ class WeaponStyleDefinitions : DefinitionsDecoder { + /** + * An array of WeaponStyleDefinition objects. + * This variable is overridden and initialized at a later stage. + * It is used to store definitions of various weapon styles. + */ override lateinit var definitions: Array + /** + * A map representing unique identifiers. + * + * The key is a string representing the identifier name, + * and the value is an integer associated with that identifier. + * + * This property is meant to be overridden and initialized + * with the desired mapping in subclasses or implementations. + */ override lateinit var ids: Map + /** + * Loads weapon style definitions from the specified YAML file and path. + * + * @param yaml the YAML object to use for loading, defaults to the result of `get()` + * @param path the path to the definitions within the YAML file, defaults to `Settings["definitions.weapons.styles"]` + * @return the loaded WeaponStyleDefinitions object + */ fun load(yaml: Yaml = get(), path: String = Settings["definitions.weapons.styles"]): WeaponStyleDefinitions { timedLoad("weapon style definition") { decode(yaml, path) { id, key, extras -> @@ -21,5 +46,15 @@ class WeaponStyleDefinitions : DefinitionsDecoder { return this } + /** + * This method overrides the `empty` function and provides an implementation + * that returns the default empty value for `WeaponStyleDefinition`. + * + * It is designed to provide a pre-defined empty or null-like instance + * of `WeaponStyleDefinition` that can be used as a placeholder or default value + * to signify the lack of a specific weapon style definition. + * + * @return The default EMPTY instance of `WeaponStyleDefinition`. + */ override fun empty() = WeaponStyleDefinition.EMPTY } \ No newline at end of file diff --git a/game/src/main/kotlin/world/gregs/voidps/GameModules.kt b/game/src/main/kotlin/world/gregs/voidps/GameModules.kt index 841fb04d2..62db35f4f 100644 --- a/game/src/main/kotlin/world/gregs/voidps/GameModules.kt +++ b/game/src/main/kotlin/world/gregs/voidps/GameModules.kt @@ -11,6 +11,25 @@ import world.gregs.voidps.world.interact.entity.obj.Teleports import world.gregs.voidps.world.interact.entity.player.music.MusicTracks import world.gregs.voidps.world.interact.world.spawn.ItemSpawns +/** + * Defines a Koin module for initializing game-related components and services. + * The `gameModule` includes the setup and configuration of various game components + * that are essential for game logic execution such as item spawning, task management, + * navigation graph construction, and data loading. + * + * Components included in this module: + * - `ItemSpawns`: Manages the spawning and clearing of items in zones. + * - `TaskManager`: Handles task queuing and task assignment for game entities. + * - `Dijkstra`: A graph traversal algorithm implementation with a pool of frontiers, + * initialized based on the navigation graph's size. + * - `NavigationGraph`: Sets up the adjacency list for nodes, edges, and areas in the game world. + * - `Books`: Loads book definitions used in the game. + * - `MusicTracks`: Manages and loads music track data. + * - `Teleports`: Loads teleportation data for game shortcuts. + * + * This module ensures that specific components like the navigation graph, books, music tracks, + * and teleports are preloaded and available at the start of the application. + */ val gameModule = module { single { ItemSpawns() } single { TaskManager() } @@ -19,6 +38,14 @@ val gameModule = module { Dijkstra( get(), object : DefaultPool(10) { + /** + * Produces a new instance of `DijkstraFrontier` with the provided size. + * + * This method is responsible for creating and returning a new instance of the `DijkstraFrontier` class, + * which manages the nodes visited or to be visited by the Dijkstra algorithm. + * + * @return A new `DijkstraFrontier` instance initialized with the specified size. + */ override fun produceInstance() = DijkstraFrontier(size) } ) From b9f1875c2311572d7d5b797ee082333f3ff0a983 Mon Sep 17 00:00:00 2001 From: Emill Date: Sat, 25 Jan 2025 20:55:42 -0500 Subject: [PATCH 4/6] =?UTF-8?q?=E2=9C=8F=EF=B8=8F=20docs(`data/definitions?= =?UTF-8?q?`):=20Enhance=20and=20restructure=20class=20documentation/annot?= =?UTF-8?q?ations=20for=20clarity?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../engine/data/definition/data/Catch.kt | 24 +++++++++ .../engine/data/definition/data/Cleaning.kt | 24 ++++++++- .../engine/data/definition/data/Fire.kt | 30 +++++++++-- .../data/definition/data/FletchBolts.kt | 22 +++++++- .../data/definition/data/FletchDarts.kt | 22 +++++++- .../engine/data/definition/data/Fletching.kt | 33 ++++++++++-- .../engine/data/definition/data/Jewellery.kt | 22 ++++++++ .../data/definition/data/LightSources.kt | 26 +++++++-- .../voidps/engine/data/definition/data/Ore.kt | 22 +++++++- .../engine/data/definition/data/Pickable.kt | 25 +++++++-- .../engine/data/definition/data/Pocket.kt | 37 ++++++++++--- .../engine/data/definition/data/Pottery.kt | 36 +++++++++++++ .../engine/data/definition/data/Rock.kt | 28 ++++++++-- .../engine/data/definition/data/Rune.kt | 44 +++++++++++++-- .../engine/data/definition/data/Silver.kt | 31 +++++++++-- .../engine/data/definition/data/Smelting.kt | 30 +++++++++-- .../engine/data/definition/data/Smithing.kt | 21 +++++++- .../engine/data/definition/data/Spinning.kt | 24 +++++++++ .../engine/data/definition/data/Spot.kt | 22 ++++++++ .../engine/data/definition/data/Tanning.kt | 15 ++++++ .../engine/data/definition/data/Tree.kt | 41 ++++++++++---- .../engine/data/definition/data/Uncooked.kt | 54 +++++++++++++++---- .../engine/data/definition/data/Weaving.kt | 27 ++++++++++ 23 files changed, 592 insertions(+), 68 deletions(-) diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Catch.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Catch.kt index 2c6e24724..e0faa6140 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Catch.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Catch.kt @@ -1,18 +1,42 @@ package world.gregs.voidps.engine.data.definition.data +/** + * Data class representing a Catch entity that contains attributes related to its level, experience points (xp), + * and a chance range. + * + * @property level The level associated with the Catch instance. Defaults to 1. + * @property xp The experience points associated with the Catch instance. Defaults to 0.0. + * @property chance The range of chance associated with the Catch instance. Defaults to 1..1. + */ data class Catch( val level: Int = 1, val xp: Double = 0.0, val chance: IntRange = 1..1 ) { + /** + * Companion object for the `Catch` class. + * Provides utility methods and properties for handling instances of the `Catch` class. + */ companion object { + /** + * Converts a map of values to a Catch object by extracting the relevant properties. + * + * @param map A map containing key-value pairs. Expected keys are: + * - "level" (Int?): The level value to be extracted. Defaults to `EMPTY.level` if not present or invalid. + * - "xp" (Double?): The experience points value to be extracted. Defaults to `EMPTY.xp` if not present or invalid. + * - "chance" (IntRange?): The range defining the chance value. Defaults to `EMPTY.chance` if not present or invalid. + */ operator fun invoke(map: Map) = Catch( level = map["level"] as? Int ?: EMPTY.level, xp = map["xp"] as? Double ?: EMPTY.xp, chance = map["chance"] as? IntRange ?: EMPTY.chance ) + /** + * Represents an empty state or default instance of the `Catch` class. + * It is typically used as a placeholder or to signify the absence of a specific value. + */ val EMPTY = Catch() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Cleaning.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Cleaning.kt index b6d86e8aa..ac9e57aac 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Cleaning.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Cleaning.kt @@ -1,20 +1,40 @@ package world.gregs.voidps.engine.data.definition.data /** - * @param level required to clean - * @param xp experience from cleaning a grimy herb + * Represents a cleaning activity with associated level and experience. + * The `Cleaning` class provides functionality for instantiating objects + * with default values or mapping values from a given data structure. + * + * @param level The level required or associated with cleaning. + * @param xp The experience gained or associated with cleaning. */ data class Cleaning( val level: Int = 1, val xp: Double = 0.0 ) { + /** + * Companion object for the Cleaning data class. Provides utility functions and constants + * for working with Cleaning instances. + */ companion object { + /** + * Creates a new instance of the `Cleaning` class from the given map, using default values for missing or invalid keys. + * + * @param map A map containing key-value pairs where: + * - "level" is the cleaning level as an `Int`. + * - "clean_xp" is the cleaning experience points as a `Double`. + * If a key is missing or its value cannot be cast to the required type, a default value will be used. + */ operator fun invoke(map: Map) = Cleaning( level = map["level"] as? Int ?: EMPTY.level, xp = map["clean_xp"] as? Double ?: EMPTY.xp, ) + /** + * Represents an empty or default instance of the `Cleaning` data class. + * Used as a baseline for creating or referencing uninitialized `Cleaning` objects. + */ val EMPTY = Cleaning() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Fire.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Fire.kt index d656ddcdf..565ff1a44 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Fire.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Fire.kt @@ -1,10 +1,13 @@ package world.gregs.voidps.engine.data.definition.data /** - * @param level required to attempt to light - * @param xp experience from successfully lighting a fire - * @param chance Chance of creating a fire at level 1 and 99 - * @param life duration in ticks that the fire object will last for + * Represents the properties of fire, typically associated with its usage mechanics such as color, duration, and chance of occurrence. + * + * @param level The required level to interact with the fire feature. + * @param xp The experience rewarded for interacting with the fire. + * @param chance The range of chance influencing interactions or outcomes involving the fire. + * @param life The duration in ticks that the fire will remain active. + * @param colour The visual representation of the fire, given as a color. */ data class Fire( val level: Int = 1, @@ -13,8 +16,23 @@ data class Fire( val life: Int = 0, val colour: String = "orange" ) { + /** + * Companion object for the Fire class. + * Provides utility methods and constants for creating and managing Fire instances. + */ companion object { + /** + * Creates a Fire instance based on the provided map of values. + * Fallbacks to default `EMPTY` values for missing or invalid entries in the map. + * + * @param map A map containing keys and corresponding values for `level`, `xp`, `chance`, `life`, and `colour`. + * - `level`: Int (required level, default is `EMPTY.level`) + * - `xp`: Double (experience value, default is `EMPTY.xp`) + * - `chance`: IntRange (chance range, default is `EMPTY.chance`) + * - `life`: Int (duration in ticks, default is `EMPTY.life`) + * - `colour`: String (colour representation, default is `EMPTY.colour`) + */ operator fun invoke(map: Map) = Fire( level = map["level"] as? Int ?: EMPTY.level, xp = map["xp"] as? Double ?: EMPTY.xp, @@ -23,6 +41,10 @@ data class Fire( colour = map["colour"] as? String ?: EMPTY.colour ) + /** + * A predefined constant representing an instance of the Fire class with default values. + * Used as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = Fire() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/FletchBolts.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/FletchBolts.kt index 54d2f0863..08655500b 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/FletchBolts.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/FletchBolts.kt @@ -1,20 +1,38 @@ package world.gregs.voidps.engine.data.definition.data /** - * @param level required to make bolt - * @param xp experience per bolt made + * Represents the properties associated with fletching bolts in a game or simulation. + * + * @param level The player's level required to fletch the bolts. + * @param xp The amount of experience awarded for successfully fletching the bolts. */ data class FletchBolts( val level: Int = 1, val xp: Double = 0.0 ) { + /** + * Companion object for the FletchBolts class. + * Provides utility methods and constants for creating and managing FletchBolts instances. + */ companion object { + /** + * Creates a new FletchBolts instance based on the provided map of values. + * Missing or invalid values in the map default to the `EMPTY` instance properties. + * + * @param map A map containing keys and corresponding values for `level` and `xp`. + * - `level`: Int (the required level, default is `EMPTY.level`) + * - `xp`: Double (experience value, default is `EMPTY.xp`) + */ operator fun invoke(map: Map) = FletchBolts( level = map["level"] as? Int ?: EMPTY.level, xp = map["xp"] as? Double ?: EMPTY.xp, ) + /** + * Represents a predefined constant of a `FletchBolts` instance with default values. + * Used as a placeholder or default value to ensure safe initialization and prevent null references. + */ val EMPTY = FletchBolts() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/FletchDarts.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/FletchDarts.kt index 7afb99010..4feeac98f 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/FletchDarts.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/FletchDarts.kt @@ -1,20 +1,38 @@ package world.gregs.voidps.engine.data.definition.data /** - * @param level required to make dart - * @param xp experience per dart made + * Represents the properties for fletching darts in the game. + * + * @param level The required level to fletch darts. + * @param xp The experience awarded for successfully fletching darts. */ data class FletchDarts( val level: Int = 1, val xp: Double = 0.0 ) { + /** + * Companion object for the FletchDarts class. + * Provides utility methods and constants for creating and managing FletchDarts instances. + */ companion object { + /** + * Creates a FletchDarts instance based on the given map. + * If the map contains missing or invalid values, the default values from `EMPTY` are used. + * + * @param map A map containing the following optional keys: + * - `level`: Int (required level, defaults to `EMPTY.level`) + * - `xp`: Double (experience value, defaults to `EMPTY.xp`) + */ operator fun invoke(map: Map) = FletchDarts( level = map["level"] as? Int ?: EMPTY.level, xp = map["xp"] as? Double ?: EMPTY.xp, ) + /** + * A predefined constant representing an instance of the FletchDarts class with default values. + * Used as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = FletchDarts() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Fletching.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Fletching.kt index 1ca9a8d64..a0957f1e7 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Fletching.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Fletching.kt @@ -1,11 +1,14 @@ package world.gregs.voidps.engine.data.definition.data /** - * @param level required to make item - * @param xp experience per item - * @param animation the animation the player will perform will fletching item - * @param makeAmount the amount of items fletched from a log - * @param tick the amount of ticks for fletching an item + * Represents the properties and actions related to fletching, including level requirements, experience gained, + * animations used, production amount, and associated ticks for the activity. + * + * @param level The level required to perform the fletching action. + * @param xp The experience points gained upon a successful fletching action. + * @param animation The animation played during the fletching process. + * @param makeAmount The number of items produced per fletching action. + * @param tick The number of ticks required to complete the action; default is -1. */ data class Fletching( val level: Int = 1, @@ -14,8 +17,24 @@ data class Fletching( val makeAmount: Int = 1, val tick: Int = -1 ) { + /** + * Companion object for the Fletching class. + * Provides utility methods and constants for creating and managing Fletching instances. + */ companion object { + /** + * Creates an instance of Fletching based on the provided map of values. + * Each key in the map corresponds to a property of the Fletching object. + * If a key is absent or its value cannot be cast to the expected type, a default value is used. + * + * @param map A map containing the property keys and values: + * - `level`: Int (the required level, default is `EMPTY.level`) + * - `xp`: Double (experience points, default is `EMPTY.xp`) + * - `animation`: String (animation name, default is `EMPTY.animation`) + * - `make_amount`: Int (quantity to make, default is `EMPTY.makeAmount`) + * - `tick`: Int (time in ticks, default is `EMPTY.tick`) + */ operator fun invoke(map: Map) = Fletching( level = map["level"] as? Int ?: EMPTY.level, xp = map["xp"] as? Double ?: EMPTY.xp, @@ -24,6 +43,10 @@ data class Fletching( tick = map["tick"] as? Int ?: EMPTY.tick, ) + /** + * A predefined constant representing an instance of the Fletching class with default values. + * Used as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = Fletching() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Jewellery.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Jewellery.kt index a39b35640..028239989 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Jewellery.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Jewellery.kt @@ -1,16 +1,38 @@ package world.gregs.voidps.engine.data.definition.data +/** + * Represents the skills and experience associated with jewellery crafting or usage. + * + * @param level The level required for crafting or interacting with the jewellery. + * @param xp The experience gained from crafting or interacting with the jewellery. + */ data class Jewellery( val level: Int = 1, val xp: Double = 0.0 ) { + /** + * Companion object for the Jewellery class. + * Provides utility methods and constants for creating and managing Jewellery instances. + */ companion object { + /** + * Creates an instance of the Jewellery class based on the provided map. + * If a property is missing or is of a different type, default values are used. + * + * @param map A map containing key-value pairs where: + * - `level`: Int, the level of the jewellery (default is `Spinning.EMPTY.level`). + * - `xp`: Double, the experience value of the jewellery (default is `Spinning.EMPTY.xp`). + */ operator fun invoke(map: Map) = Jewellery( level = map["level"] as? Int ?: Spinning.EMPTY.level, xp = map["xp"] as? Double ?: Spinning.EMPTY.xp, ) + /** + * A predefined constant representing an instance of the Jewellery class with default values. + * This instance serves as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = Jewellery() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/LightSources.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/LightSources.kt index 52b1293a7..85c13e96c 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/LightSources.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/LightSources.kt @@ -1,23 +1,43 @@ package world.gregs.voidps.engine.data.definition.data /** - * @param onceLit the item that is given once the player lights a light source - * @param onceExtinguish the item that is given once the player extinguishes the light source - * @param level the firemaking level required to light the light source + * Represents the properties of light sources, encompassing details about their states + * when lit or extinguished, as well as an associated lighting level. + * + * @param onceLit A string representing the state or identifier of the light source when lit. + * @param onceExtinguish A string representing the state or identifier of the light source when extinguished. + * @param level An integer representing the level or intensity of the light source. */ data class LightSources( val onceLit: String = "", val onceExtinguish: String = "", val level: Int = -1 ) { + /** + * Companion object for the LightSources class. + * Provides utility methods and constants for creating and managing LightSources instances. + */ companion object { + /** + * Creates a `LightSources` instance based on the provided map of values. + * Defaults to `EMPTY` values for any missing or invalid map entries. + * + * @param map A map containing keys and corresponding values for `onceLit`, `onceExtinguish`, and `level`: + * - `onceLit`: String (value for once lit, defaults to `EMPTY.onceLit`) + * - `onceExtinguish`: String (value for once extinguished, defaults to `EMPTY.onceExtinguish`) + * - `level`: Int (value for level, defaults to `EMPTY.level`) + */ operator fun invoke(map: Map) = LightSources( onceLit = map["once_lit"] as? String ?: EMPTY.onceLit, onceExtinguish = map["once_extinguish"] as? String ?: EMPTY.onceExtinguish, level = map["level"] as? Int ?: EMPTY.level, ) + /** + * A predefined constant representing an instance of the LightSources class with default values. + * Used as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = LightSources() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Ore.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Ore.kt index 2585e1af6..f5f1e0446 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Ore.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Ore.kt @@ -1,20 +1,38 @@ package world.gregs.voidps.engine.data.definition.data /** - * @param xp experience for successful mining - * @param chance of mining per cycle + * Represents an ore with properties influencing its mechanics, such as the experience rewarded and the chance of occurrence. + * + * @param xp The experience rewarded for successfully interacting with the ore. + * @param chance The range of chance influencing the occurrence or success of mining the ore. */ data class Ore( val xp: Double = 0.0, val chance: IntRange = 0..0 ) { + /** + * Companion object for the Ore class. + * Provides utility methods and constants for managing Ore instances. + */ companion object { + /** + * Creates an instance of the Ore class using values from the provided map. + * Fallbacks to default `EMPTY` values for missing or invalid entries in the map. + * + * @param map A map containing keys and values to initialize the Ore instance. + * - `xp`: Double representing experience points, default is `EMPTY.xp`. + * - `chance`: IntRange representing the range of chance, default is `EMPTY.chance`. + */ operator fun invoke(map: Map) = Ore( xp = map["xp"] as? Double ?: EMPTY.xp, chance = map["chance"] as? IntRange ?: EMPTY.chance ) + /** + * A predefined constant representing an instance of the Ore class with default values. + * Used as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = Ore() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Pickable.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Pickable.kt index 75230554d..8ee271a2a 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Pickable.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Pickable.kt @@ -1,23 +1,42 @@ package world.gregs.voidps.engine.data.definition.data /** - * @param item id of the item given - * @param respawnDelay seconds until object is respawned - * @param message message to send when picked + * Represents an item that can be picked up, with customizable properties for respawn delay and messaging. + * + * @param item The identifier or name of the item that can be picked up. + * @param respawnDelay The time in ticks before the item reappears after being picked up. + * @param message A custom message displayed when the item is interacted with. */ data class Pickable( val item: String = "", val respawnDelay: Int = -1, val message: String = "" ) { + /** + * Companion object for the Pickable class. + * Provides utility methods and constants for creating and managing Pickable instances. + */ companion object { + /** + * Creates an instance of the Pickable class using the values from the provided map. + * Missing or invalid values default to the `EMPTY` instance's properties. + * + * @param map A map containing key-value pairs to initialize the Pickable instance: + * - `item`: A String representing the item name. Defaults to `EMPTY.item` if not provided or invalid. + * - `delay`: An Int representing the respawn delay in ticks. Defaults to `EMPTY.respawnDelay` if not provided or invalid. + * - `message`: A String representing a message associated with the item. Defaults to `EMPTY.message` if not provided or invalid. + */ operator fun invoke(map: Map) = Pickable( item = (map["item"] as? String) ?: EMPTY.item, respawnDelay = map["delay"] as? Int ?: EMPTY.respawnDelay, message = map["message"] as? String ?: EMPTY.message, ) + /** + * A predefined constant representing an instance of the Pickable class with default values. + * Serves as a default or placeholder value to avoid null references or for initialization purposes. + */ val EMPTY = Pickable() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Pocket.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Pocket.kt index 42b5057aa..2435aa787 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Pocket.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Pocket.kt @@ -1,12 +1,17 @@ package world.gregs.voidps.engine.data.definition.data /** - * @param level required to pickpocket - * @param xp experience per pickpocket - * @param stunHit the amount of damage when caught - * @param stunTicks the amount of ticks to stun for - * @param chance the chance of being successful - * @param caughtMessage npc message when caught + * Represents the properties of a pocket configuration, detailing various attributes + * and their corresponding effects. The pocket can define its level, the experience + * gained from interactions, stun properties, success chance, and a custom message + * for caught scenarios. + * + * @property level The level associated with the pocket. Default is 1. + * @property xp The experience points rewarded for relevant interactions. Default is 0.0. + * @property stunHit The number of hits required to stun. Default is 0. + * @property stunTicks The duration in ticks during which the pocket is stunned. Default is 1. + * @property chance The range of chance influencing success or failure rates. Default is 1..1. + * @property caughtMessage The message displayed upon being caught. Default is "What do you think you're doing?". */ data class Pocket( val level: Int = 1, @@ -16,8 +21,24 @@ data class Pocket( val chance: IntRange = 1..1, val caughtMessage: String = "What do you think you're doing?" ) { + /** + * Companion object for the Pocket class. + * Provides utility methods and constants for creating and managing Pocket instances. + */ companion object { + /** + * Creates a Pocket instance based on the provided map of values. + * If the map doesn't contain expected keys or the values are of an invalid type, default values from `EMPTY` are used. + * + * @param map A map containing keys and corresponding values for the Pocket properties. + * - `level`: Int representing the level, or defaults to `EMPTY.level`. + * - `xp`: Double representing the experience points, or defaults to `EMPTY.xp`. + * - `stun_hit`: Int representing stun hits, or defaults to `EMPTY.stunHit`. + * - `stun_ticks`: Int representing stun duration in ticks, or defaults to `EMPTY.stunTicks`. + * - `chance`: IntRange representing a range of chances, or defaults to `EMPTY.chance`. + * - `caught`: String representing the caught message, or defaults to `EMPTY.caughtMessage`. + */ operator fun invoke(map: Map) = Pocket( level = map["level"] as? Int ?: EMPTY.level, xp = map["xp"] as? Double ?: EMPTY.xp, @@ -27,6 +48,10 @@ data class Pocket( caughtMessage = map["caught"] as? String ?: EMPTY.caughtMessage, ) + /** + * A predefined constant representing an instance of the Pocket class with default values. + * Used as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = Pocket() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Pottery.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Pottery.kt index f8a952e58..2cc1e670b 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Pottery.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Pottery.kt @@ -1,24 +1,60 @@ package world.gregs.voidps.engine.data.definition.data +/** + * Represents a collection of pottery data, composed of various ceramics and their associated properties. + * + * @param map A mapping of ceramic names to their respective `Ceramic` instances. + * Defaults to an empty map if no data is provided. + */ data class Pottery( val map: Map = emptyMap() ) { + /** + * Represents a Ceramic object with level and experience points (xp). + * + * @param level The current level of the ceramic object. Defaults to 1. + * @param xp The experience points associated with the ceramic object. Defaults to 0.0. + */ data class Ceramic( val level: Int = 1, val xp: Double = 0.0 ) { + /** + * Companion object for the Ceramic class. + * Provides utility methods and constants for creating and managing Ceramic instances. + */ companion object { + /** + * Creates an instance of the Ceramic class using the provided map. + * Missing or invalid values will default to the equivalent values from `EMPTY`. + * + * @param map A map containing key-value pairs to initialize the Ceramic instance. + * - `level`: Int representing the level required, defaults to `EMPTY.level`. + * - `xp`: Double representing the experience points, defaults to `EMPTY.xp`. + */ operator fun invoke(map: Map) = Ceramic( level = map["level"] as? Int ?: EMPTY.level, xp = map["xp"] as? Double ?: EMPTY.xp, ) + /** + * A predefined constant representing an instance of the `Ceramic` class with default values. + * Used as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = Ceramic() } } + /** + * Companion object for the Pottery class. + * Provides utility constants for managing Pottery instances. + */ companion object { + /** + * A predefined constant representing an instance of the Pottery class with default values. + * Used as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = Pottery() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Rock.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Rock.kt index a6283cdb4..af52b0878 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Rock.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Rock.kt @@ -1,10 +1,12 @@ package world.gregs.voidps.engine.data.definition.data /** - * @param level required to attempt to mine - * @param ores List of materials that can be mined - * @param life duration in ticks that the fire object will last for - * @param gems if rock has chance of dropping random gems + * Represents a rock that can contain ores and potentially gems. + * + * @param level The hardness or toughness level of the rock. Higher levels may require more effort to mine. + * @param ores A list of ore types available in the rock. + * @param life The remaining durability or life of the rock. A value of -1 indicates infinite durability. + * @param gems Indicates if the rock contains gems. */ data class Rock( val level: Int = 1, @@ -12,8 +14,22 @@ data class Rock( val life: Int = -1, val gems: Boolean = false ) { + /** + * Companion object for the Rock class. + * Provides utility methods and constants for creating and managing Rock instances. + */ companion object { + /** + * Creates an instance of the Rock class using values from the provided map. + * Fallbacks to default `EMPTY` values for missing or invalid entries in the map. + * + * @param map A map containing keys and values for initializing the Rock instance: + * - `level`: Int representing the level, default is `EMPTY.level`. + * - `ores`: List representing ore types, default is `EMPTY.ores`. + * - `life`: Int representing life or durability, default is `EMPTY.life`. + * - `gems`: Boolean indicating if gems are present, default is `EMPTY.gems`. + */ @Suppress("UNCHECKED_CAST") operator fun invoke(map: Map) = Rock( level = map["level"] as? Int ?: EMPTY.level, @@ -22,6 +38,10 @@ data class Rock( gems = map["gems"] as? Boolean ?: EMPTY.gems, ) + /** + * A predefined constant representing an instance of the Rock class with default values. + * Used as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = Rock() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Rune.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Rune.kt index 93d30b881..3a0e4c936 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Rune.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Rune.kt @@ -4,10 +4,13 @@ import world.gregs.voidps.engine.entity.character.player.Player import world.gregs.voidps.engine.entity.character.player.skill.Skill /** - * @param xp experience from successfully crafting a rune - * @param pure whether pure essence is required - * @param levels level required for each amount of runes created - * @param doubleChance of getting double at ourania altar with medium ardougne diary + * Represents a Rune entity containing data relevant to runecrafting. + * + * @property xp The experience gained from crafting this rune. Default is 0.0. + * @property pure A flag indicating whether this is a pure rune or not. Default is false. + * @property levels The required runecrafting levels for crafting this rune, represented as an array of integers. + * @property combinations A map of combination runes and their respective components. + * @property doubleChance The chance of crafting double runes. Default is 0.0. */ data class Rune( val xp: Double = 0.0, @@ -16,6 +19,12 @@ data class Rune( val combinations: Map> = emptyMap(), val doubleChance: Double = 0.0 ) { + /** + * Determines the multiplier based on the player's Runecrafting skill level. + * + * @param player The player whose levels are being evaluated. + * @return The calculated multiplier based on the player's Runecrafting level. + */ fun multiplier(player: Player): Int { var multiplier = 1 for (index in levels.indices.reversed()) { @@ -27,6 +36,12 @@ data class Rune( return multiplier } + /** + * Checks whether the specified object is equal to this instance. + * + * @param other the object to be compared for equality with this instance. + * @return true if the specified object is equal to this instance; false otherwise. + */ override fun equals(other: Any?): Boolean { if (this === other) return true if (javaClass != other?.javaClass) return false @@ -38,6 +53,11 @@ data class Rune( return levels.contentEquals(other.levels) } + /** + * Computes the hash code for this object based on its properties. + * + * @return The hash code value as an integer, computed using the properties `xp`, `pure`, and `levels`. + */ override fun hashCode(): Int { var result = xp.hashCode() result = 31 * result + pure.hashCode() @@ -45,8 +65,20 @@ data class Rune( return result } + /** + * Companion object for the Rune class. Provides utilities such as the `invoke` operator + * for creating a Rune instance from a map and a default EMPTY instance. + */ companion object { + /** + * Converts a map of values into a `Rune` object by extracting and casting + * the required properties. If a particular key is not found in the map or + * if the value is of an incorrect type, a default value from `EMPTY` is used instead. + * + * @param map A map where the keys represent property names and the values + * are the corresponding data used to create a `Rune`. + */ @Suppress("UNCHECKED_CAST") operator fun invoke(map: Map) = Rune( xp = map["xp"] as? Double ?: EMPTY.xp, @@ -56,6 +88,10 @@ data class Rune( doubleChance = (map["ourania_chance"] as? Double) ?: EMPTY.doubleChance, ) + /** + * A constant representing an empty or default rune. This value can be used + * as a placeholder or to signify the absence of a meaningful rune. + */ val EMPTY = Rune() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Silver.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Silver.kt index 18c8cef8b..507ac5f35 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Silver.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Silver.kt @@ -1,11 +1,13 @@ package world.gregs.voidps.engine.data.definition.data /** - * @param name interface override - * @param item the silver item to craft - * @param level required to attempt to craft - * @param xp experience from successfully crafting - * @param quest quest required to display this item + * Represents a Silver entity with properties such as name, item, experience points (XP), level, and quest. + * + * @param name The name associated with the Silver entity, default is null. + * @param item The item represented by the Silver entity, default is an empty string. + * @param xp The experience points of the Silver entity, default is 0.0. + * @param level The level value associated with the Silver entity, default is 1. + * @param quest The quest linked to the Silver entity, if applicable, default is null. */ data class Silver( val name: String? = null, @@ -14,8 +16,23 @@ data class Silver( val level: Int = 1, val quest: String? = null ) { + /** + * Companion object for the Silver class. + * Provides utility methods and constants for creating and managing Silver instances. + */ companion object { + /** + * Creates an instance of the Silver class using values from the provided map. + * Default values from `EMPTY` are used for missing or invalid map entries. + * + * @param map A map containing keys and values for initializing the Silver instance: + * - `name`: String representing the name, default is `EMPTY.name`. + * - `item`: String representing the item, default is `EMPTY.item`. + * - `xp`: Double representing the experience points, default is `EMPTY.xp`. + * - `level`: Int representing the level, default is `EMPTY.level`. + * - `quest`: String representing the quest, default is `EMPTY.quest`. + */ operator fun invoke(map: Map) = Silver( name = map["name"] as? String ?: EMPTY.name, item = map["item"] as? String ?: EMPTY.item, @@ -24,6 +41,10 @@ data class Silver( quest = map["quest"] as? String ?: EMPTY.quest, ) + /** + * A predefined constant representing an instance of the Silver class initialized with default values. + * Serves as a placeholder or default value to prevent null references or for initialization purposes. + */ val EMPTY = Silver() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Smelting.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Smelting.kt index f009d85c8..ec3bb40c0 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Smelting.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Smelting.kt @@ -3,10 +3,13 @@ package world.gregs.voidps.engine.data.definition.data import world.gregs.voidps.engine.entity.item.Item /** - * @param level mining level required to smelt - * @param xp experience for successful smelting - * @param chance of success out of 255 - * @param items required items to smelt + * Represents the smelting mechanics, including requirements, rewards, and success chances. + * + * @param level The required level to perform smelting. + * @param xp The experience rewarded upon a successful smelting action. + * @param chance The success chance for smelting, where 255 indicates 100% success by default. + * @param items The list of items resulting from the smelting process. + * @param message The associated message or feedback displayed during smelting. */ data class Smelting( val level: Int = 0, @@ -15,7 +18,22 @@ data class Smelting( val items: List = emptyList(), val message: String = "" ) { + /** + * Companion object for the Smelting class. + * Provides utility methods and constants for creating and managing Smelting instances. + */ companion object { + /** + * Creates an instance of the `Smelting` class using a map of values. + * Fallbacks to default `EMPTY` values for missing or invalid entries in the map. + * + * @param map A map containing keys and values to initialize the Smelting instance: + * - `level`: Int representing the required level for smelting, default is `EMPTY.level`. + * - `xp`: Double representing the experience points gained from smelting, default is `EMPTY.xp`. + * - `chance`: IntRange or its highest value representing the probability of successful smelting, default is `EMPTY.chance`. + * - `items`: List> containing item maps with fields `item` (String) and `amount` (Int, default 1), default is `EMPTY.items`. + * - `message`: String representing the message associated with smelting, default is `EMPTY.message`. + */ @Suppress("UNCHECKED_CAST") operator fun invoke(map: Map) = Smelting( level = map["level"] as Int, @@ -25,6 +43,10 @@ data class Smelting( message = map["message"] as String ) + /** + * A predefined constant representing an instance of the Smelting class with default values. + * Used as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = Smelting() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Smithing.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Smithing.kt index 335ea9455..252d11d57 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Smithing.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Smithing.kt @@ -1,18 +1,35 @@ package world.gregs.voidps.engine.data.definition.data /** - * @param level smithing level required to smith - * @param xp experience for smithing + * Represents a Smithing activity with properties defining the level required and experience points. + * + * @param level The level of Smithing. Default is 0. + * @param xp The experience points accumulated in Smithing. Default is 0.0. */ data class Smithing( val level: Int = 0, val xp: Double = 0.0 ) { + /** + * Companion object for the Smithing class. + * Provides utility methods and constants for creating and managing Smithing instances. + */ companion object { + /** + * Creates an instance of the Smithing class using values from the provided map. + * + * @param map A map containing keys and values to initialize the Smithing instance: + * - `level`: Int representing the level, required and must be a valid integer. + * - `xp`: Double representing experience points, required and must be a valid double. + */ operator fun invoke(map: Map) = Smithing( level = map["level"] as Int, xp = map["xp"] as Double ) + /** + * A predefined constant representing an instance of the Smithing class with default values. + * Used as a placeholder or default value for initialization or to avoid null references. + */ val EMPTY = Smithing() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Spinning.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Spinning.kt index f00164e66..36c8b33b2 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Spinning.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Spinning.kt @@ -1,19 +1,43 @@ package world.gregs.voidps.engine.data.definition.data +/** + * Represents the spinning mechanic in the context of processing items or resources. + * + * @param to The resulting item or state after spinning. + * @param level The minimum level required to perform the spinning action. + * @param xp The experience awarded for successfully completing the spinning process. + */ data class Spinning( val to: String = "", val level: Int = 1, val xp: Double = 0.0 ) { + /** + * Companion object for the Spinning class. + * Provides utility methods and constants for creating and managing Spinning instances. + */ companion object { + /** + * Creates a Spinning instance using values from the given map, with fallback to default values + * if map entries are missing or invalid. + * + * @param map A map containing keys and corresponding values for initializing the Spinning instance: + * - `to`: String, default is an empty string. + * - `level`: Int, default is `EMPTY.level`. + * - `xp`: Double, default is `EMPTY.xp`. + */ operator fun invoke(map: Map) = Spinning( to = map["to"] as? String ?: "", level = map["level"] as? Int ?: EMPTY.level, xp = map["xp"] as? Double ?: EMPTY.xp, ) + /** + * A predefined constant representing an instance of the `Spinning` class with default values. + * Used as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = Spinning() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Spot.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Spot.kt index ae57a5da8..1fa266e07 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Spot.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Spot.kt @@ -1,11 +1,29 @@ package world.gregs.voidps.engine.data.definition.data +/** + * Represents a fishing spot with the properties defining available tackle and bait options. + * + * @param tackle A list of strings representing the tackle items available for use in the fishing spot. + * @param bait A map of bait types (string keys) paired with lists of corresponding bait options. + */ data class Spot( val tackle: List = emptyList(), val bait: Map> = emptyMap() ) { + /** + * Companion object for the Spot class. + * Provides utility methods and constants for creating and managing Spot instances. + */ companion object { + /** + * Creates an instance of the Spot class using values from the provided map. + * + * @param map A map containing keys and corresponding values for initializing the Spot instance: + * - `items`: List representing the tackle items. + * - `bait`: Map> representing the bait configuration. + * @return A Spot instance initialized with the specified map values. + */ @Suppress("UNCHECKED_CAST") operator fun invoke(map: Map): Spot { return Spot( @@ -14,6 +32,10 @@ data class Spot( ) } + /** + * A predefined constant representing an instance of the Spot class with default values. + * Used as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = Spot() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Tanning.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Tanning.kt index 45025ee14..79e56eff9 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Tanning.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Tanning.kt @@ -1,9 +1,24 @@ package world.gregs.voidps.engine.data.definition.data +/** + * Represents the pricing structure for a tanning process, consisting of a nested list + * of prices and their associated values or conditions. + * + * @param prices A nested list where each sublist represents specific pricing information. + * Each sublist can contain varying types of data, such as price values and any related attributes. + */ data class Tanning( val prices: List> = emptyList() ) { + /** + * Companion object for the Tanning class. + * Provides utility constants for creating and managing Tanning instances. + */ companion object { + /** + * A predefined constant representing an instance of the Tanning class with default values. + * Used as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = Tanning() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Tree.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Tree.kt index c7997453f..fd585de80 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Tree.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Tree.kt @@ -1,15 +1,16 @@ package world.gregs.voidps.engine.data.definition.data /** - * Note: all regular tree data is accurate to wiki/skilling chances spreadsheet - * @param log The log given on success - * @param level The woodcutting level required to cut - * @param xp The woodcutting experience given on success - * @param depleteRate The chance on success of a tree falling - * @param chance The chance out of 256 of success at level 1 and 99 - * @param hatchetLowDifference The min and max difference increase in chance per hatchet at level 1 - * @param hatchetHighDifference The min and max difference increase in chance per hatchet at level 99 - * @param respawnDelay The delay in ticks before regrowing at 2000 and 0 players online (Taken from https://www.runehq.com/skill/woodcutting#respawntimes and unknown ones balanced around those values) + * Represents a tree with properties to define its behavior in a game or simulation. + * + * @param log The type of log associated with the tree. + * @param level The required level to interact with the tree. + * @param xp The experience rewarded for processes involving the tree. + * @param depleteRate The rate at which the tree depletes during interactions. + * @param chance The range of chance influencing the success of interactions with the tree. + * @param hatchetLowDifference The range of effectiveness difference for low-quality hatchets. + * @param hatchetHighDifference The range of effectiveness difference for high-quality hatchets. + * @param respawnDelay The range of delay in ticks before the tree respawns after being depleted. */ data class Tree( val log: String = "", @@ -21,7 +22,25 @@ data class Tree( val hatchetHighDifference: IntRange = 0..0, val respawnDelay: IntRange = 0..0 ) { + /** + * Companion object for the Tree class. + * Provides utility methods and constants for creating and managing Tree instances. + */ companion object { + /** + * Creates a Tree instance using values from the provided map. + * Defaults to `EMPTY` values for missing or invalid entries in the map. + * + * @param map A map containing key-value pairs for initializing the Tree instance: + * - `log`: String representing the log type, default is `EMPTY.log`. + * - `level`: Int representing the level requirement, default is `EMPTY.level`. + * - `xp`: Double representing the experience points, default is `EMPTY.xp`. + * - `deplete_rate`: Double representing the rate of resource depletion, default is `EMPTY.depleteRate`. + * - `chance`: IntRange representing the range of chance, default is `EMPTY.chance`. + * - `hatchet_low_dif`: IntRange representing the lower difference for hatchet levels, default is `EMPTY.hatchetLowDifference`. + * - `hatchet_high_dif`: IntRange representing the higher difference for hatchet levels, default is `EMPTY.hatchetHighDifference`. + * - `respawn`: IntRange representing the respawn delay interval, default is `EMPTY.respawnDelay`. + */ operator fun invoke(map: Map) = Tree( log = map["log"] as? String ?: EMPTY.log, level = map["level"] as? Int ?: EMPTY.level, @@ -32,6 +51,10 @@ data class Tree( hatchetHighDifference = map["hatchet_high_dif"] as? IntRange ?: EMPTY.hatchetHighDifference, respawnDelay = map["respawn"] as? IntRange ?: EMPTY.respawnDelay ) + /** + * A predefined constant representing a Tree instance with default values for all properties. + * Used as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = Tree() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Uncooked.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Uncooked.kt index eb3babe22..25874b10d 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Uncooked.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Uncooked.kt @@ -1,17 +1,24 @@ package world.gregs.voidps.engine.data.definition.data /** - * @param level required to attempt cooking - * @param xp experience for successfully cooking - * @param chance of burning on a fire - * @param rangeChance of burning on a stove - * @param cooksRangeChance of burning on the lumbridge range - * @param gauntletChance of burning with cooking_gauntlets - * @param cooked cooked item name if not `"raw_item".replace("raw", "cooked")` - * @param burnt burnt item name if not `"raw_item".replace("raw", "burnt")` - * @param leftover any by-products from cooking - * @param start tick delay - * @param ticks till the end of the process + * Represents an uncooked item with properties related to its cooking process, such as experience gained, chances of success, and related messaging. + * + * @param level The required level to cook the item. + * @param xp The experience rewarded for successfully cooking the item. + * @param burntXp The experience rewarded if the item is burnt during cooking. + * @param chance The range of chance influencing the cooking outcome when using fire. + * @param rangeChance The range of chance influencing the cooking outcome when using a range. + * @param cooksRangeChance The range of chance when using a range with cook-specific bonuses. + * @param gauntletChance The range of chance when using cooking gauntlets. + * @param cooked The identifier for the successfully cooked item. + * @param cookedMessage The message displayed upon successfully cooking the item. + * @param burnt The identifier for the burnt variant of the item. + * @param burntMessage The message displayed upon burning the item. + * @param leftover The identifier for any leftover item produced during cooking. + * @param start The starting level of cooking ticks. + * @param ticks The total number of ticks required for cooking the item. + * @param type Specifies the type of cooking process (e.g., cook, bake, etc.). + * @param rangeOnly A flag indicating if the item can only be cooked on a range. */ data class Uncooked( val level: Int = 1, @@ -32,8 +39,29 @@ data class Uncooked( val rangeOnly: Boolean = false ) { + /** + * Companion object for the Uncooked class. + * Provides utility methods and constants for creating and managing Uncooked instances. + */ companion object { + /** + * Creates an instance of the Uncooked class using values provided in the map. + * If certain keys are missing or their values are invalid, default values from `EMPTY` are used. + * + * @param map A map containing keys and corresponding values to initialize an instance of Uncooked: + * - `chances`: Map (optional) representing various chances such as fire, range, cooks_range, or gauntlet. + * - `level`: Int (optional) indicating the level, default is `EMPTY.level`. + * - `xp`: Double (optional) indicating the experience points, default is `EMPTY.xp`. + * - `cooked`: String (optional) indicating the cooked item, default is `EMPTY.cooked`. + * - `cooked_message`: String (optional) representing a message related to the cooked item, default is `EMPTY.cookedMessage`. + * - `burnt`: String (optional) representing the burnt item, default is `EMPTY.burnt`. + * - `burnt_message`: String (optional) representing a message related to the burnt item, default is `EMPTY.burntMessage`. + * - `leftover`: String (optional) representing the leftover item, default is `EMPTY.leftover`. + * - `type`: String (optional) indicating the type, default is `EMPTY.type`. + * + * @return An instance of the Uncooked class initialized with the values provided in the map. + */ @Suppress("UNCHECKED_CAST") operator fun invoke(map: Map): Uncooked { val chances = map["chances"] as? Map ?: emptyMap() @@ -58,6 +86,10 @@ data class Uncooked( ) } + /** + * A predefined constant representing an instance of the `Uncooked` class with default values. + * Used as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = Uncooked() } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Weaving.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Weaving.kt index a8682bb8a..ae19c0d35 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Weaving.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/data/definition/data/Weaving.kt @@ -1,5 +1,14 @@ package world.gregs.voidps.engine.data.definition.data +/** + * Represents the mechanics of weaving, including the amount of materials, the final product, + * the level requirement, and the experience gained. + * + * @param amount The quantity of materials needed for the weaving process. + * @param to The resulting product of the weaving process. + * @param level The required skill level to perform the weaving action. + * @param xp The experience points rewarded for successfully completing the weaving. + */ data class Weaving( val amount: Int = 1, val to: String = "", @@ -7,8 +16,22 @@ data class Weaving( val xp: Double = 0.0 ) { + /** + * Companion object for the Weaving class. + * Provides utility methods and constants for creating and managing Weaving instances. + */ companion object { + /** + * Creates an instance of the Weaving class using values from the provided map. + * Defaults to `EMPTY` values for missing or invalid entries in the map. + * + * @param map A map containing keys and values for initializing the Weaving instance: + * - `amount`: Int representing the quantity, default is `EMPTY.amount`. + * - `to`: String representing the destination or target, default is an empty string. + * - `level`: Int representing the level requirement, default is `EMPTY.level`. + * - `xp`: Double representing experience points, default is `EMPTY.xp`. + */ operator fun invoke(map: Map) = Weaving( amount = map["amount"] as? Int ?: EMPTY.amount, to = map["to"] as? String ?: "", @@ -16,6 +39,10 @@ data class Weaving( xp = map["xp"] as? Double ?: EMPTY.xp, ) + /** + * A predefined constant representing an instance of the Weaving class with default values. + * Used as a placeholder or default value to avoid null references or for initialization purposes. + */ val EMPTY = Weaving() } } \ No newline at end of file From 768e91af796f46df02affdadbd969f5680de2cb5 Mon Sep 17 00:00:00 2001 From: Emill Date: Sat, 25 Jan 2025 20:57:17 -0500 Subject: [PATCH 5/6] =?UTF-8?q?=E2=9C=8F=EF=B8=8F=20docs(`PlayerAccountLoa?= =?UTF-8?q?der.kt`,=20`EncodeExtensions.kt`):=20Enhance=20code=20documenta?= =?UTF-8?q?tion=20for=20better=20clarity=20and=20detail.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../voidps/engine/client/EncodeExtensions.kt | 182 +++++++++++++++--- .../engine/client/PlayerAccountLoader.kt | 46 ++++- 2 files changed, 196 insertions(+), 32 deletions(-) diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/client/EncodeExtensions.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/client/EncodeExtensions.kt index 6e62e901e..e9d83099a 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/client/EncodeExtensions.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/client/EncodeExtensions.kt @@ -17,11 +17,12 @@ import java.util.* */ /** - * A chat box message to display - * @param type The message type - * @param tile The tile the message was sent from - * @param name Optional display name? - * @param text The chat message text + * Sends a message to the client with specific chat settings and formatting. + * + * @param text The content of the message that will be sent. + * @param type The type of chat message to display, default is ChatType.Game. + * @param tile The tile ID associated with the message, default is 0. + * @param name Optional name associated with the message, default is null. */ fun Character.message( text: String, @@ -39,7 +40,21 @@ fun Character.message( } } +/** + * A fixed-size queue that only retains the most recent elements added, up to a specified capacity. + * This class extends LinkedList and automatically removes the oldest element when the capacity is reached. + * + * @param E The type of elements held in this queue. + * @param capacity The maximum number of elements the queue can hold. + */ private class FixedSizeQueue(private val capacity: Int) : LinkedList() { + /** + * Adds the specified element to the collection. If the collection has reached its maximum capacity, + * the first element in the collection is removed before adding the new element. + * + * @param element the element to be added to the collection + * @return `true` if the collection was modified as a result of the call, `false` otherwise + */ override fun add(element: E): Boolean { if (size >= capacity) { removeFirst() @@ -49,11 +64,12 @@ private class FixedSizeQueue(private val capacity: Int) : LinkedList() { } /** - * Sends a list of items to display on an interface item group component - * @param inventory The id of the inventory - * @param size The capacity of items in the inventory - * @param items List of the item ids to display - * @param primary Optional to send to the primary or secondary inventory + * Sends inventory items to the client for display or processing. + * + * @param inventory The ID of the inventory to which the items belong. + * @param size The number of slots in the inventory. + * @param items An array containing the item IDs in the inventory. + * @param primary A flag indicating if this inventory is the primary one. */ fun Player.sendInventoryItems( inventory: Int, @@ -63,10 +79,11 @@ fun Player.sendInventoryItems( ) = client?.sendInventoryItems(inventory, size, items, primary) ?: Unit /** - * Sends a list of items to display on an interface item group component - * @param key The id of the interface item group - * @param updates List of the indices, item ids and amounts to update - * @param secondary Optional to send to the primary or secondary inventory + * Sends an update for an interface item. + * + * @param key The identifier for the interface to update. + * @param updates A list of triples, where each triple contains the item ID, amount, and slot. + * @param secondary A boolean value indicating whether this is a secondary update or not. */ fun Player.sendInterfaceItemUpdate( key: Int, @@ -75,12 +92,13 @@ fun Player.sendInterfaceItemUpdate( ) = client?.sendInterfaceItemUpdate(key, updates, secondary) ?: Unit /** - * Sends settings to an interface's component(s) - * @param id The id of the parent window - * @param component The index of the component - * @param fromSlot The start slot index - * @param toSlot The end slot index - * @param settings The settings hash + * Sends interface settings to the client for a specific interface component. + * + * @param id The ID of the interface. + * @param component The ID of the component within the interface. + * @param fromSlot The starting slot of the range for which the settings apply. + * @param toSlot The ending slot of the range for which the settings apply. + * @param settings The settings to apply to the specified interface component and slot range. */ fun Player.sendInterfaceSettings( id: Int, @@ -97,10 +115,11 @@ fun Player.sendInterfaceSettings( ) ?: Unit /** - * Sends vertical height to an interfaces' component - * @param id The id of the parent window - * @param component The index of the component - * @param settings The settings hash + * Sends an interface scroll event to the client associated with the player. + * + * @param id The unique identifier of the interface. + * @param component The specific component within the interface. + * @param settings Additional settings related to the interface scroll. */ fun Player.sendInterfaceScroll( id: Int, @@ -109,15 +128,17 @@ fun Player.sendInterfaceScroll( ) = client?.sendInterfaceScroll(id, component, settings) ?: Unit /** - * Sends run energy - * @param energy The current energy value + * Sends the player's current run energy to the client. + * + * @param energy The current run energy value to be sent to the client. */ fun Player.sendRunEnergy(energy: Int) = client?.sendRunEnergy(energy) ?: Unit /** - * Sends a client script to run - * @param id The client script id - * @param params Additional parameters to run the script with (strings & integers only) + * Sends a client script to the player with the specified script ID and parameters. + * + * @param id The unique identifier of the client script to send. + * @param params The parameters to be passed to the client script. */ fun Player.sendScript( id: String, @@ -127,17 +148,38 @@ fun Player.sendScript( sendScript(definition.id, params.toList()) } +/** + * Sends a script to the player using the specified script ID and parameters. + * + * @param id The unique identifier of the script to be sent. + * @param params A list of parameters to be passed to the script. Nullable values are allowed. + */ fun Player.sendScript( id: Int, params: List ) = client?.sendScript(id, params) ?: Unit +/** + * Plays a music track using the Player's audio system. + * + * @param music The identifier of the music track to be played. + * @param delay The delay in milliseconds before the music track starts playing. Default is 100. + * @param volume The volume level of the music track, where 255 is the maximum volume. Default is 255. + */ fun Player.playMusicTrack( music: Int, delay: Int = 100, volume: Int = 255 ) = client?.playMusicTrack(music, delay, volume) ?: Unit +/** + * Updates the private status of the player based on the given parameter. + * + * @param private A string representing the private status. Possible values are: + * - "friends" to set the private status to friends-only. + * - "off" to turn the private status off. + * - Any other value sets the private status to default. + */ fun Player.privateStatus( private: String ) { @@ -148,6 +190,14 @@ fun Player.privateStatus( }) } +/** + * Updates the public and trade status of the player. + * + * @param public The public status of the player. Expected values are: + * "friends", "off", "hide", or other values default to 0. + * @param trade The trade status of the player. Expected values are: + * "friends", "off", or other values default to 0. + */ fun Player.publicStatus( public: String, trade: String @@ -164,8 +214,21 @@ fun Player.publicStatus( }) } +/** + * Updates the friend's information in the friends list of the player. + * + * @param friend The Friend instance containing the updated data to be sent to the friends list. + */ fun Player.updateFriend(friend: Friend) = client?.sendFriendsList(listOf(friend)) ?: Unit +/** + * Moves the camera to a specified position with defined parameters. + * + * @param tile The target tile position to move the camera to. + * @param height The height level for the camera. + * @param constantSpeed The constant speed at which the camera moves. Default is 232. + * @param variableSpeed The variable speed at which the camera moves. Default is 232. + */ fun Player.moveCamera( tile: Tile, height: Int, @@ -178,6 +241,14 @@ fun Player.moveCamera( return client?.moveCamera(local.x, local.y, height, constantSpeed, variableSpeed) ?: Unit } +/** + * Turns the player's camera to a specific tile position with adjustable speed settings. + * + * @param tile The target tile to which the camera should be turned. + * @param height The vertical height of the camera focus in relation to the target tile. + * @param constantSpeed The constant speed at which the camera moves (default is 232). + * @param variableSpeed The variable speed for camera movement calculation (default is 232). + */ fun Player.turnCamera( tile: Tile, height: Int, @@ -190,6 +261,15 @@ fun Player.turnCamera( return client?.turnCamera(local.x, local.y, height, constantSpeed, variableSpeed) ?: Unit } +/** + * Applies a camera shake effect for the player. + * + * @param intensity The intensity of the camera shake. + * @param type The type of shake applied to the camera. + * @param cycle The duration or cycle of the camera shake effect. + * @param movement The movement amount or amplitude of the shake. + * @param speed The speed of the camera shake effect. + */ fun Player.shakeCamera( intensity: Int, type: Int, @@ -198,16 +278,60 @@ fun Player.shakeCamera( speed: Int, ) = client?.shakeCamera(intensity, type, cycle, movement, speed) ?: Unit +/** + * Clears the camera settings for the player. + * + * This method resets the camera state for the player, if a client is associated + * with the player. If no client is present, the method performs no operation. + */ fun Player.clearCamera() = client?.clearCamera() ?: Unit +/** + * Enum class that represents the different states or modes of a minimap. + * + * @property index Represents the unique integer value associated with each minimap state. + */ enum class Minimap(val index: Int) { + /** + * Represents an enumeration value that signifies an unclickable state. + * This could be utilized in settings or scenarios where a clickable functionality needs + * to be intentionally disabled or marked as inactive. + */ Unclickable(1), + /** + * This is a class that represents a map with hidden elements or functionality. + * + * The primary purpose of the HideMap class is to define and manage a + * map with specific hidden or obfuscated features. + * + * @constructor Creates a HideMap object with the given parameters. + */ HideMap(2), + /** + * Enumeration constant used to represent the visibility state of a compass indicator. + * + * @constructor Creates an instance of the `HideCompass` enum with the specified value for managing the compass visibility state. + * @param value An integer value representing a specific state for hiding or showing the compass. + */ HideCompass(3), } +/** + * Updates the minimap state for the player by combining the provided states and sending the result + * to the player's client. + * + * @param states Vararg parameter representing the states to be applied to the minimap. Each state is + * represented by a Minimap instance, whose index will be used for bitwise operations. + */ fun Player.minimap(vararg states: Minimap) { client?.sendMinimapState(states.fold(0) { acc, state -> acc or state.index }) } +/** + * Clears the minimap display for the player by resetting its state. + * + * This method sends a reset instruction to the player's client, causing + * the minimap to be cleared or reverted to its default state. If the + * player's client is unavailable, the operation safely performs no action. + */ fun Player.clearMinimap() = client?.sendMinimapState(0) ?: Unit \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/client/PlayerAccountLoader.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/client/PlayerAccountLoader.kt index a53549923..6b5049c3a 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/client/PlayerAccountLoader.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/client/PlayerAccountLoader.kt @@ -20,8 +20,19 @@ import world.gregs.voidps.network.login.AccountLoader import world.gregs.voidps.network.login.protocol.encode.login /** - * Checks password is valid for a player account before logging in - * Keeps track of the players online, prevents duplicate login attempts + * Handles the loading of player accounts from storage, validation of login credentials, + * and managing of player login processes. + * + * This class integrates with various system components such as the connection queue, + * account storage, account manager, save queue, and account definitions to facilitate + * account-related operations. + * + * @property queue The connection queue used to manage player login and logout operations. + * @property storage The account storage system used to persist and retrieve player accounts. + * @property accounts The account manager responsible for creating, setting up, and spawning player accounts. + * @property saveQueue The save queue that handles saving of player accounts asynchronously. + * @property accountDefinitions Definitions of player accounts, including metadata such as password hashes. + * @property gameContext The coroutine dispatcher used for running game-related tasks. */ class PlayerAccountLoader( private val queue: ConnectionQueue, @@ -31,18 +42,40 @@ class PlayerAccountLoader( private val accountDefinitions: AccountDefinitions, private val gameContext: CoroutineDispatcher ) : AccountLoader { + /** + * Logger instance utilized for logging messages and events within the PlayerAccountLoader class. + * It provides a streamlined mechanism for tracking the execution flow and debugging processes. + */ private val logger = InlineLogger() + /** + * Determines whether an account with the given username exists in the storage. + * + * @param username The username of the account to check for existence. + * @return True if the account exists, false otherwise. + */ override fun exists(username: String): Boolean { return storage.exists(username) } + /** + * Retrieves the password hash associated with the given username. + * + * @param username The username for which the password hash is being requested. + * @return The password hash of the specified username, or null if no entry exists for the username. + */ override fun password(username: String): String? { return accountDefinitions.get(username)?.passwordHash } /** - * @return flow of instructions for the player to be controlled with + * Loads a player's account and connects them to the game. + * + * @param client The client instance representing the connection to the player. + * @param username The username of the account to be loaded. + * @param passwordHash The hashed password of the account for verification. + * @param displayMode The display mode selected by the client (e.g., fullscreen or windowed). + * @return A SendChannel of instructions for the loaded player, or null if the operation fails. */ override suspend fun load(client: Client, username: String, passwordHash: String, displayMode: Int): SendChannel? { try { @@ -62,6 +95,13 @@ class PlayerAccountLoader( } } + /** + * Connects a player to the game server. + * + * @param player The player to be connected. Represents a client-controlled or bot-controlled player. + * @param client The client associated with the player. Can be null if the player is a bot. + * @param displayMode The display mode to use when connecting the player. + */ suspend fun connect(player: Player, client: Client? = null, displayMode: Int = 0) { if (!accounts.setup(player)) { logger.warn { "Error setting up account" } From 97dfe03836b036f8a02f345a3d478306436da97d Mon Sep 17 00:00:00 2001 From: Emill Date: Sat, 25 Jan 2025 20:58:48 -0500 Subject: [PATCH 6/6] =?UTF-8?q?=E2=9C=8F=EF=B8=8F=20docs(`instruction-hand?= =?UTF-8?q?lers`):=20Add=20comprehensive=20KDoc=20comments=20for=20improve?= =?UTF-8?q?d=20code=20understanding=20and=20maintainability.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../client/instruction/InstructionHandler.kt | 13 +- .../client/instruction/InstructionHandlers.kt | 233 ++++++++++++++++++ .../client/instruction/InstructionTask.kt | 58 +++++ .../client/instruction/InterfaceHandler.kt | 93 +++++++ 4 files changed, 396 insertions(+), 1 deletion(-) diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/client/instruction/InstructionHandler.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/client/instruction/InstructionHandler.kt index 43f613f3e..575e6abaa 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/client/instruction/InstructionHandler.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/client/instruction/InstructionHandler.kt @@ -3,10 +3,21 @@ package world.gregs.voidps.engine.client.instruction import world.gregs.voidps.engine.entity.character.player.Player import world.gregs.voidps.network.client.Instruction +/** + * An abstract handler for processing and validating instructions specific to a player. + * This class requires implementation for handling validation logic. + * + * @param T The type of instruction being handled, constrained to implementations of the [Instruction] interface. + */ abstract class InstructionHandler { /** - * Validates the [instruction] information is correct and emits a [Player] event with the relevant data + * Validates the given instruction for the specified player. + * Implementations should ensure the provided instruction can be safely and correctly executed + * based on the player's current state and other conditions. + * + * @param player The player for whom the instruction is being validated. + * @param instruction The instruction to validate. */ abstract fun validate(player: Player, instruction: T) diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/client/instruction/InstructionHandlers.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/client/instruction/InstructionHandlers.kt index 6d8a27d42..51f15dc90 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/client/instruction/InstructionHandlers.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/client/instruction/InstructionHandlers.kt @@ -14,6 +14,26 @@ import world.gregs.voidps.engine.event.Event import world.gregs.voidps.network.client.Instruction import world.gregs.voidps.network.client.instruction.* +/** + * Manages and processes a variety of instruction handlers for the game world interactions. + * + * This class handles various types of player interactions and game instructions by delegating + * them to the appropriate handlers. Each type of instruction is managed by its corresponding + * handler, providing a modular and maintainable structure for handling in-game actions and events. + * + * @constructor Creates a new instance of InstructionHandlers with several game-related components + * required for initializing instruction handlers. + * + * @param players The collection of active players in the game world. + * @param npcs The collection of non-player characters (NPCs) in the game world. + * @param items The collection of floor items available in the game world. + * @param objects The collection of objects in the game world. + * @param itemDefinitions Definitions and metadata describing all game items. + * @param objectDefinitions Definitions and metadata describing all game objects. + * @param npcDefinitions Definitions and metadata describing all NPCs. + * @param interfaceDefinitions Definitions for user interfaces within the game. + * @param handler Interface handler for user interaction with game interface elements. + */ class InstructionHandlers( players: Players, npcs: NPCs, @@ -25,42 +45,255 @@ class InstructionHandlers( interfaceDefinitions: InterfaceDefinitions, handler: InterfaceHandler ) { + /** + * Represents a handler for managing interactions with floor items in the game. + * The variable encapsulates a FloorItemOptionHandler which provides functionality + * to handle specific options or actions related to items located on the ground. + * It operates on a list of items that can be interacted with directly from the game floor. + */ private val interactFloorItem = FloorItemOptionHandler(items) + /** + * A private instance of DialogueContinueHandler used to manage and control the continuation of dialogue interactions. + * It leverages interfaceDefinitions to handle specific interaction rules or configurations. + */ private val interactDialogue = DialogueContinueHandler(interfaceDefinitions) + /** + * This variable represents an instance of InterfaceClosedHandler + * that is used to handle the closure of an interface. It encapsulates + * logic or actions to be performed when the interface is closed. + */ private val closeInterface = InterfaceClosedHandler() + /** + * A private variable used to handle interface interactions. + * interactInterface is instantiated with an instance of InterfaceOptionHandler. + * It provides an abstraction layer to manage specific options or operations + * related to the interface interaction in the application logic. + */ private val interactInterface = InterfaceOptionHandler(handler) + /** + * Handles the movement of an inventory item within the system. + * This variable is assigned an instance of InterfaceSwitchHandler, + * which provides the functionality to manage the switching behavior + * for handling inventory item relocation. + */ private val moveInventoryItem = InterfaceSwitchHandler(handler) + /** + * Handles interactions with NPCs, utilizing the provided NPCs and NPCDefinitions to manage + * and validate NPC interaction instructions. This field is an instance of `NPCOptionHandler`, + * responsible for determining the appropriate game logic based on the interaction details + * such as the NPC index, selected option, and player state. + */ private val interactNPC = NPCOptionHandler(npcs, npcDefinitions) + /** + * Handles interaction events with in-game objects, processing and validating instructions + * for interacting with specific game objects based on their definitions and interaction options. + * + * This variable is responsible for: + * - Determining the targeted game object using a combination of tile and object ID. + * - Validating the interaction by checking the existence of the target object and its + * interaction options. + * - Assigning the corresponding interaction mode to the player if the interaction is valid. + * + * Part of the instruction handling system within the game, utilized to process player actions + * involving objects in the game world. + */ private val interactObject = ObjectOptionHandler(objects, objectDefinitions) + /** + * Holds an instance of `PlayerOptionHandler`, initialized with the provided `players` parameter. + * This variable is used for managing player interactions and handling player-specific options + * within the associated functionality. + * + * It encapsulates the logic related to player interaction events and operations, ensuring + * appropriate behavior during these processes. + */ private val interactPlayer = PlayerOptionHandler(players) + /** + * A private variable responsible for handling item examination functionality. + * Manages the retrieval of item details by utilizing an ItemExamineHandler instance. + * The handler processes item definitions provided via the `itemDefinitions` parameter. + */ private val examineItem = ItemExamineHandler(itemDefinitions) + /** + * Handler for examining Non-Player Characters (NPCs) in the game. + * This variable is initialized with a reference to the `NPCExamineHandler`, + * which utilizes the provided `npcDefinitions` to retrieve metadata or + * descriptions related to specific NPC entities. + */ private val examineNPC = NPCExamineHandler(npcDefinitions) + /** + * A handler instance responsible for examining objects using a predefined set of object definitions. + * + * This variable is used to process and analyze objects based on the logic encapsulated in the + * ObjectExamineHandler. It leverages `objectDefinitions` for defining the characteristics or + * criteria required for examination. + * + * @property examineObject The handler instance for object examination logic. + */ private val examineObject = ObjectExamineHandler(objectDefinitions) + /** + * Represents a handler responsible for managing and toggling the display mode of the screen. + * This variable is intended to be used to facilitate changes in screen presentation states. + */ private val changeDisplayMode = ScreenChangeHandler() + /** + * Defines a handler for interacting with an NPC through a specific interface. + * This variable assigns an instance of `InterfaceOnNPCOptionHandler` to handle + * player interactions with NPCs when a particular interface option is activated. + * + * @property npcs The list of NPCs that can be interacted with via this handler. + * @property handler The specific interaction logic to process interactions between + * the interface and the associated NPCs. + */ private val interactInterfaceNPC = InterfaceOnNPCOptionHandler(npcs, handler) + /** + * A private variable that initializes an instance of `InterfaceOnObjectOptionHandler`. + * It manages interactions with objects by utilizing the provided `objects` and `handler`. + * This variable is used to handle interface-related functionalities for object options. + */ private val interactInterfaceObject = InterfaceOnObjectOptionHandler(objects, handler) + /** + * A handler for managing interactions between the user interface and player-specific options. + * + * The `interactInterfacePlayer` variable is used to assign functionality for handling + * events when an interface element interacts with a player. This typically involves + * executing specific logic provided by the handler whenever such interactions occur. + * + * @property players Represents the group of players targeted for this interaction. + * @property handler Defines the logic to be executed upon interaction between the + * user interface and a player. + */ private val interactInterfacePlayer = InterfaceOnPlayerOptionHandler(players, handler) + /** + * A private variable that holds an instance of InterfaceOnInterfaceOptionHandler. + * This is used to manage interactions between interfaces by handling specific events or actions. + */ private val interactInterfaceItem = InterfaceOnInterfaceOptionHandler(handler) + /** + * A private variable representing the interface interaction handler for floor item options. + * This handler manages the interactions triggered when performing actions on items placed on the floor. + * It is initialized with a specified set of items and a corresponding handler that performs the required logic. + */ private val interactInterfaceFloorItem = InterfaceOnFloorItemOptionHandler(items, handler) + /** + * Represents an instance of the `WalkHandler` that manages or handles functionality + * related to walking behavior within the application. + * + * This variable is declared as private and is not accessible outside the scope + * of its containing class. It is typically used internally for processing walk-related + * operations or logic. + */ private val walk = WalkHandler() + /** + * A private variable that handles click actions on the world map. + * This variable is an instance of WorldMapClickHandler, which is used to manage + * and process user interactions with the world map, such as detecting and responding + * to clicks on specific map regions or elements. + */ private val worldMapClick = WorldMapClickHandler() + /** + * A handler responsible for managing the completion of a region load operation. + * This variable is used to trigger or manage actions that need to occur + * after a specific region load process is finalized. + */ private val finishRegionLoad = FinishRegionLoadHandler() + /** + * A private variable that holds an instance of the ExecuteCommandHandler. + * Used to handle the execution of specific commands within the application. + */ private val executeCommand = ExecuteCommandHandler() + /** + * A private variable that holds an instance of EnterStringHandler. + * The purpose of this handler is to manage and process string input + * within the application. It provides functionality to handle user-entered + * string data appropriately. + */ private val enterString = EnterStringHandler() + /** + * A private instance of the `EnterIntHandler` responsible for handling integer input operations. + * Encapsulates the logic related to managing or processing integer input in the system. + */ private val enterInt = EnterIntHandler() + /** + * Handler for processing friend addition events. + * This variable is responsible for managing the logic + * required when a new friend is added within the application. + */ private val friendAddHandler = FriendAddHandler() + /** + * A private instance of FriendDeleteHandler used to manage the deletion of friends. + * It encapsulates the logic and operations required to handle friend removal processes. + */ private val friendDeleteHandler = FriendDeleteHandler() + /** + * A private variable used to manage the state or instance of an IgnoreAddHandler. + * The handler may be responsible for selectively ignoring or managing the addition + * of certain elements or operations, depending on its implementation. + * + * It is likely used internally within the context of the class or component + * to enforce specific rules or behaviors related to addition processes. + */ private val ignoreAddHandler = IgnoreAddHandler() + /** + * A private instance of the `IgnoreDeleteHandler` class. + * + * This variable is utilized to manage and handle scenarios where + * delete operations should be ignored. Typically used to prevent + * specific objects or records from being processed for deletion + * based on predefined logic determined by the handler implementation. + */ private val ignoreDeleteHandler = IgnoreDeleteHandler() + /** + * Instance of ChatPublicHandler used to manage and handle public chat-related operations. + */ private val chatPublicHandler = ChatPublicHandler() + /** + * An instance of `ChatPrivateHandler` used to manage private chat-related functionalities. + * This encapsulates logic specific to handling private message interactions and operations. + */ private val chatPrivateHandler = ChatPrivateHandler() + /** + * A private instance of `QuickChatPublicHandler` used to manage or handle public chat-related operations. + * This handler is responsible for executing tasks specific to the quick chat functionality within a public context. + */ private val quickChatPublicHandler = QuickChatPublicHandler() + /** + * Handler responsible for managing private quick chat interactions. + * It facilitates operations related to private communication in a quick chat context. + */ private val quickChatPrivateHandler = QuickChatPrivateHandler() + /** + * Represents a handler responsible for managing actions when a player + * joins a clan chat. This object facilitates the execution of specific + * logic or triggers to ensure appropriate behavior upon a clan chat join event. + */ private val clanChatJoinHandler = ClanChatJoinHandler() + /** + * Handles changes related to the chat type in the application. + * This variable is responsible for managing and executing the logic required + * when the type of chat is altered, ensuring the application responds + * appropriately to such changes. + */ private val chatTypeChangeHandler = ChatTypeChangeHandler() + /** + * A private variable that handles the functionality related to kicking a member + * from the clan chat. It encapsulates the logic required to manage and enforce + * kick actions within the context of clan chats. + */ private val clanChatKickHandler = ClanChatKickHandler() + /** + * An instance of ClanChatRankHandler used to manage and handle + * functionalities related to clan chat ranking within the application. + */ private val clanChatRankHandler = ClanChatRankHandler() + /** + * Handles the given instruction for the specified player. The function processes different types of + * instructions and delegates their handling to the appropriate handlers or operations based on the + * instruction type. + * + * @param player The player for whom the instruction is being handled. + * @param instruction The instruction to handle, determining the specific logic to execute. + */ fun handle(player: Player, instruction: Instruction) { when (instruction) { is Event -> player.emit(instruction) diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/client/instruction/InstructionTask.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/client/instruction/InstructionTask.kt index 658389ead..fd75ec392 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/client/instruction/InstructionTask.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/client/instruction/InstructionTask.kt @@ -10,6 +10,21 @@ import world.gregs.voidps.engine.entity.character.player.Players import world.gregs.voidps.engine.entity.item.floor.FloorItems import world.gregs.voidps.engine.entity.obj.GameObjects +/** + * Represents a task responsible for handling instructions for players. + * This class processes and executes a maximum number of instructions per player + * during each run cycle, utilizing defined instruction handlers. + * + * @property players The collection of players to process instructions for. + * @property npcs The collection of non-player characters available in the game world. + * @property items The collection of floor items available in the game world. + * @property objects The collection of interactive game objects within the game world. + * @property itemDefinitions The definitions and configurations for various item types. + * @property objectDefinitions The definitions and configurations for various game object types. + * @property npcDefinitions The definitions and configurations for available NPC types. + * @property interfaceDefinitions The definitions related to graphical interfaces used in the game. + * @property handler An interface handler responsible for managing interface interactions. + */ class InstructionTask( private val players: Players, npcs: NPCs, @@ -22,7 +37,26 @@ class InstructionTask( handler: InterfaceHandler ) : Runnable { + /** + * Logger used for recording debug and error messages related to the processing + * of player instructions in the `InstructionTask` class. Provides inline logging + * capabilities for better performance and structured output. + */ private val logger = InlineLogger() + /** + * A collection of instruction handlers utilized to process various game-related entities and definitions. + * This includes processing for players, NPCs, floor items, game objects, and interface-related interactions. + * + * @property players Reference to manage and process player-related instructions. + * @property npcs Reference to handle NPC-related instructions. + * @property items Reference to manage floor item-related instructions. + * @property objects Reference to process game object-related instructions. + * @property itemDefinitions Definitions required for item-related handling. + * @property objectDefinitions Definitions required for game object-related instructions. + * @property npcDefinitions Definitions used for NPC-related processes. + * @property interfaceDefinitions Definitions related to interface interaction handling. + * @property handler Responsible for managing the interface interactions. + */ private val handlers = InstructionHandlers( players, npcs, @@ -35,6 +69,20 @@ class InstructionTask( handler ) + /** + * Executes the main processing logic for handling player instructions. + * + * This method iterates over all players in the game and processes a set number of instructions + * (defined by `MAX_INSTRUCTIONS`) for each player. Instructions are received from the player's + * instruction queue. If a player has debug mode enabled (retrieved via `player["debug", false]`), + * a debug log is generated for each instruction processed. Any errors encountered during the + * handling of an instruction are logged. + * + * Each instruction is passed to the `handlers.handle` method for further processing, + * which delegates the instruction to the appropriate handler based on its type. + * + * If no instruction is found in the player's queue, processing breaks early for that player. + */ override fun run() { for (player in players) { for (i in 0 until MAX_INSTRUCTIONS) { @@ -51,7 +99,17 @@ class InstructionTask( } } + /** + * Companion object for the InstructionTask class. + * Provides static constants or utility functions specific to the class. + */ companion object { + /** + * The maximum number of instructions that can be processed for a player in a single run cycle. + * + * This constant is used to limit the number of instructions a player can execute to avoid + * excessive processing and ensure fair turn-based execution among all active players. + */ const val MAX_INSTRUCTIONS = 20 } } \ No newline at end of file diff --git a/engine/src/main/kotlin/world/gregs/voidps/engine/client/instruction/InterfaceHandler.kt b/engine/src/main/kotlin/world/gregs/voidps/engine/client/instruction/InterfaceHandler.kt index 3106f5f5a..50887853b 100644 --- a/engine/src/main/kotlin/world/gregs/voidps/engine/client/instruction/InterfaceHandler.kt +++ b/engine/src/main/kotlin/world/gregs/voidps/engine/client/instruction/InterfaceHandler.kt @@ -9,13 +9,46 @@ import world.gregs.voidps.engine.entity.character.player.Player import world.gregs.voidps.engine.entity.item.Item import world.gregs.voidps.engine.inv.equipment +/** + * Handles operations related to game interfaces, including retrieving interface items, + * managing component definitions, and verifying inventory items for a specified player. + * + * This class provides functionalities to retrieve items displayed on game interfaces, + * validating components and their mappings to ensure proper interactions, and tracking + * inventory items for specific interfaces. + * + * @property itemDefinitions Definitions and metadata of game items, providing access + * to string identifiers and other item attributes. + * @property interfaceDefinitions Definitions for game interfaces, including the + * organization and metadata of components within an interface. + * @property inventoryDefinitions Definitions for player inventories, managing inventory + * configurations, sizes, and related behaviors. + */ class InterfaceHandler( private val itemDefinitions: ItemDefinitions, private val interfaceDefinitions: InterfaceDefinitions, private val inventoryDefinitions: InventoryDefinitions ) { + /** + * Logger instance used for logging messages throughout the application. + * This logger is initialized using the InlineLogger class. + */ private val logger = InlineLogger() + /** + * Retrieves information about a specific item within an interface for the given player. + * + * This method checks whether a player has a specific interface open, verifies the component's existence, + * and retrieves additional details, including the associated inventory and item data if applicable. + * + * @param player The player for whom the interface item is being retrieved. + * @param interfaceId The unique identifier of the interface being checked. + * @param componentId The identifier of the specific component within the interface. + * @param itemId The identifier of the item being queried, or -1 if not applicable. + * @param itemSlot The slot within the inventory where the item is located, or -1 if not applicable. + * @return An instance of [InterfaceData] containing the details of the interface and the target item, + * or `null` if the specified item, component, or interface conditions are not met. + */ fun getInterfaceItem(player: Player, interfaceId: Int, componentId: Int, itemId: Int, itemSlot: Int): InterfaceData? { val id = getOpenInterface(player, interfaceId) ?: return null val componentDefinition = getComponentDefinition(player, interfaceId, componentId) ?: return null @@ -29,6 +62,13 @@ class InterfaceHandler( return InterfaceData(id, component, item, inventory, componentDefinition.options) } + /** + * Retrieves the open interface identifier for a given player and interface. + * + * @param player The player whose open interface is being queried. + * @param interfaceId The ID of the interface to check. + * @return The string identifier of the open interface if the interface is open for the player, or null if it is not open. + */ private fun getOpenInterface(player: Player, interfaceId: Int): String? { val id = interfaceDefinitions.get(interfaceId).stringId if (!player.interfaces.contains(id)) { @@ -38,6 +78,14 @@ class InterfaceHandler( return id } + /** + * Retrieves the definition of a specific component within an interface. + * + * @param player The player requesting the component definition. + * @param id The identifier of the interface containing the component. + * @param componentId The identifier of the component within the interface. + * @return The definition of the specified component, or null if the component does not exist. + */ private fun getComponentDefinition(player: Player, id: Int, componentId: Int): InterfaceComponentDefinition? { val interfaceDefinition = interfaceDefinitions.get(id) val componentDefinition = interfaceDefinition.components?.get(componentId) @@ -48,6 +96,15 @@ class InterfaceHandler( return componentDefinition } + /** + * Retrieves the inventory identifier associated with a specific player and interface component. + * + * @param player The player for whom the inventory is being retrieved. + * @param id The identifier of the interface this component belongs to. + * @param component The specific component name or identifier within the interface. + * @param componentDefinition The interface component definition containing metadata for the component. + * @return The inventory identifier as a string if found and valid, otherwise null. + */ private fun getInventory(player: Player, id: String, component: String, componentDefinition: InterfaceComponentDefinition): String? { if (component.isEmpty()) { logger.info { "No inventory component found [$player, interface=$id, inventory=$component]" } @@ -61,6 +118,17 @@ class InterfaceHandler( return inventory } + /** + * Retrieves an `Item` from a player's inventory based on specified parameters. + * + * @param player The `Player` whose inventory is being accessed. + * @param id The identifier for the interface or context being used. + * @param componentDefinition The `InterfaceComponentDefinition` providing details about the interface component. + * @param inventoryId The identifier for the inventory type (e.g., "worn_equipment", "inventory"). + * @param item The item ID to be matched, or -1 if no specific item ID is provided. + * @param itemSlot The slot index of the item, or -1 if the slot needs to be determined dynamically. + * @return The `Item` located at the specified slot in the inventory, or `null` if the item is not found or the parameters are invalid. + */ private fun getInventoryItem(player: Player, id: String, componentDefinition: InterfaceComponentDefinition, inventoryId: String, item: Int, itemSlot: Int): Item? { val itemId = if (item == -1 || item > itemDefinitions.size) "" else itemDefinitions.get(item).stringId val slot = when { @@ -87,6 +155,16 @@ class InterfaceHandler( } } +/** + * A data class representing interface data with properties for ID, component name, item + * details, inventory name, and optional array of string options. + * + * @property id A unique identifier for the interface data. + * @property component The name of the associated component. + * @property item The item associated with the interface data. + * @property inventory The name of the inventory related to the interface data. + * @property options An optional array of string representations of additional options, which may be null. + */ data class InterfaceData( val id: String, val component: String, @@ -94,6 +172,12 @@ data class InterfaceData( val inventory: String, val options: Array? ) { + /** + * Checks if the current object is equal to another object. + * + * @param other The object to compare with the current instance. + * @return `true` if the objects are equal, `false` otherwise. + */ override fun equals(other: Any?): Boolean { if (this === other) return true if (javaClass != other?.javaClass) return false @@ -112,6 +196,15 @@ data class InterfaceData( return true } + /** + * Computes the hash code for the object based on its properties. + * + * The hash code is calculated using the `id`, `component`, `item`, `inventory`, + * and `options` properties. The calculation ensures that objects with the same + * property values produce the same hash code, satisfying the contract of `hashCode`. + * + * @return The hash code value of the object. + */ override fun hashCode(): Int { var result = id.hashCode() result = 31 * result + component.hashCode()