From 64c5f59a5eb0430add0aec16de02d78f1c1f31a7 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Mon, 6 Oct 2025 14:24:59 +0000 Subject: [PATCH] feat: Add comprehensive Docusaurus documentation This commit introduces a complete set of documentation for the Dungeons Guide mod, structured for Docusaurus. The documentation is written in a descriptive, paragraphed style to be more comprehensive and readable. The documentation is organized into the following sections: - **Introduction:** A landing page that provides a brief overview of the mod. - **Features:** A detailed breakdown of all the mod's features, organized into categories such as Solvers, Boss, QOL, Statistics, Cosmetics, and Discord. Each feature has its own page with a description and configuration options. - **Developer:** A section for developers that includes a high-level overview of the mod's code structure and a more in-depth explanation of how the core components work together, including dungeon state management, the Secret Finder's TSP/ActionDAG system, and the Waterboard solver's simulated annealing algorithm. This new documentation will make it much easier for users to learn how to use the mod and for new developers to understand the codebase. --- docs/developer/_category_.json | 4 ++ docs/developer/advanced-solvers.md | 29 ++++++++ docs/developer/code-structure.md | 57 +++++++++++++++ docs/developer/core-systems/_category_.json | 4 ++ docs/developer/core-systems/action-dag.md | 31 ++++++++ .../coordinates-and-room-detection.md | 25 +++++++ docs/developer/core-systems/data-model.md | 29 ++++++++ .../developer/core-systems/pre-calculation.md | 70 ++++++++++++++++++ .../core-systems/smart-route-example.md | 72 +++++++++++++++++++ docs/developer/core-systems/tsp-solver.md | 39 ++++++++++ .../core-systems/waterboard-solver.md | 23 ++++++ docs/developer/dungeon-state-management.md | 50 +++++++++++++ docs/features/_category_.json | 4 ++ docs/features/boss/_category_.json | 4 ++ docs/features/boss/auto-reparty.md | 12 ++++ docs/features/boss/boss-health-display.md | 20 ++++++ docs/features/boss/box-real-livid.md | 12 ++++ docs/features/boss/current-phase-display.md | 11 +++ docs/features/boss/f7-terminal-waypoints.md | 26 +++++++ docs/features/boss/hide-animals.md | 17 +++++ docs/features/boss/score-warning-on-portal.md | 11 +++ docs/features/boss/spirit-bear-percentage.md | 11 +++ docs/features/boss/spirit-bow-timer.md | 11 +++ docs/features/boss/terracotta-timer.md | 11 +++ docs/features/cosmetics/_category_.json | 4 ++ docs/features/cosmetics/nickname-color.md | 11 +++ docs/features/cosmetics/nickname-prefix.md | 11 +++ docs/features/cosmetics/player-model.md | 11 +++ docs/features/discord/_category_.json | 4 ++ .../features/discord/discord-rich-presence.md | 11 +++ .../discord/friend-online-notification.md | 11 +++ docs/features/qol/_category_.json | 4 ++ docs/features/qol/ability-cooldown.md | 11 +++ docs/features/qol/blood-room-warning.md | 11 +++ docs/features/qol/box-secret-bats.md | 15 ++++ docs/features/qol/box-skeleton-masters.md | 17 +++++ docs/features/qol/custom-party-finder-gui.md | 11 +++ docs/features/qol/disable-ability-messages.md | 11 +++ docs/features/qol/dungeon-map.md | 11 +++ docs/features/qol/highlight-starred-mobs.md | 17 +++++ docs/features/qol/low-health-warning.md | 11 +++ docs/features/qol/reparty-command.md | 11 +++ docs/features/qol/secrets-chest-close.md | 11 +++ docs/features/qol/spirit-boots-fixer.md | 11 +++ docs/features/solvers/_category_.json | 4 ++ docs/features/solvers/blaze-solver.md | 23 ++++++ docs/features/solvers/bomb-defuse-solver.md | 12 ++++ docs/features/solvers/ice-fill-solver.md | 17 +++++ docs/features/solvers/riddle-solver.md | 12 ++++ docs/features/solvers/silverfish-solver.md | 17 +++++ docs/features/solvers/teleport-solver.md | 17 +++++ docs/features/solvers/tic-tac-toe-solver.md | 17 +++++ docs/features/solvers/waterboard-solver.md | 30 ++++++++ docs/features/statistics/_category_.json | 4 ++ .../statistics/broken-crypts-indicator.md | 11 +++ .../statistics/current-milestone-indicator.md | 11 +++ .../statistics/dungeon-cooldown-indicator.md | 11 +++ .../statistics/dungeon-death-indicator.md | 11 +++ .../statistics/dungeon-items-stats.md | 11 +++ .../dungeon-score-pre-calculator.md | 11 +++ .../statistics/in-game-time-indicator.md | 11 +++ .../statistics/obtained-secret-indicator.md | 11 +++ .../statistics/party-profile-viewer.md | 11 +++ docs/features/statistics/price-viewer.md | 11 +++ docs/features/statistics/profit-calculator.md | 11 +++ .../statistics/real-time-indicator.md | 11 +++ docs/features/statistics/view-room-name.md | 11 +++ docs/index.md | 13 ++++ 68 files changed, 1107 insertions(+) create mode 100644 docs/developer/_category_.json create mode 100644 docs/developer/advanced-solvers.md create mode 100644 docs/developer/code-structure.md create mode 100644 docs/developer/core-systems/_category_.json create mode 100644 docs/developer/core-systems/action-dag.md create mode 100644 docs/developer/core-systems/coordinates-and-room-detection.md create mode 100644 docs/developer/core-systems/data-model.md create mode 100644 docs/developer/core-systems/pre-calculation.md create mode 100644 docs/developer/core-systems/smart-route-example.md create mode 100644 docs/developer/core-systems/tsp-solver.md create mode 100644 docs/developer/core-systems/waterboard-solver.md create mode 100644 docs/developer/dungeon-state-management.md create mode 100644 docs/features/_category_.json create mode 100644 docs/features/boss/_category_.json create mode 100644 docs/features/boss/auto-reparty.md create mode 100644 docs/features/boss/boss-health-display.md create mode 100644 docs/features/boss/box-real-livid.md create mode 100644 docs/features/boss/current-phase-display.md create mode 100644 docs/features/boss/f7-terminal-waypoints.md create mode 100644 docs/features/boss/hide-animals.md create mode 100644 docs/features/boss/score-warning-on-portal.md create mode 100644 docs/features/boss/spirit-bear-percentage.md create mode 100644 docs/features/boss/spirit-bow-timer.md create mode 100644 docs/features/boss/terracotta-timer.md create mode 100644 docs/features/cosmetics/_category_.json create mode 100644 docs/features/cosmetics/nickname-color.md create mode 100644 docs/features/cosmetics/nickname-prefix.md create mode 100644 docs/features/cosmetics/player-model.md create mode 100644 docs/features/discord/_category_.json create mode 100644 docs/features/discord/discord-rich-presence.md create mode 100644 docs/features/discord/friend-online-notification.md create mode 100644 docs/features/qol/_category_.json create mode 100644 docs/features/qol/ability-cooldown.md create mode 100644 docs/features/qol/blood-room-warning.md create mode 100644 docs/features/qol/box-secret-bats.md create mode 100644 docs/features/qol/box-skeleton-masters.md create mode 100644 docs/features/qol/custom-party-finder-gui.md create mode 100644 docs/features/qol/disable-ability-messages.md create mode 100644 docs/features/qol/dungeon-map.md create mode 100644 docs/features/qol/highlight-starred-mobs.md create mode 100644 docs/features/qol/low-health-warning.md create mode 100644 docs/features/qol/reparty-command.md create mode 100644 docs/features/qol/secrets-chest-close.md create mode 100644 docs/features/qol/spirit-boots-fixer.md create mode 100644 docs/features/solvers/_category_.json create mode 100644 docs/features/solvers/blaze-solver.md create mode 100644 docs/features/solvers/bomb-defuse-solver.md create mode 100644 docs/features/solvers/ice-fill-solver.md create mode 100644 docs/features/solvers/riddle-solver.md create mode 100644 docs/features/solvers/silverfish-solver.md create mode 100644 docs/features/solvers/teleport-solver.md create mode 100644 docs/features/solvers/tic-tac-toe-solver.md create mode 100644 docs/features/solvers/waterboard-solver.md create mode 100644 docs/features/statistics/_category_.json create mode 100644 docs/features/statistics/broken-crypts-indicator.md create mode 100644 docs/features/statistics/current-milestone-indicator.md create mode 100644 docs/features/statistics/dungeon-cooldown-indicator.md create mode 100644 docs/features/statistics/dungeon-death-indicator.md create mode 100644 docs/features/statistics/dungeon-items-stats.md create mode 100644 docs/features/statistics/dungeon-score-pre-calculator.md create mode 100644 docs/features/statistics/in-game-time-indicator.md create mode 100644 docs/features/statistics/obtained-secret-indicator.md create mode 100644 docs/features/statistics/party-profile-viewer.md create mode 100644 docs/features/statistics/price-viewer.md create mode 100644 docs/features/statistics/profit-calculator.md create mode 100644 docs/features/statistics/real-time-indicator.md create mode 100644 docs/features/statistics/view-room-name.md create mode 100644 docs/index.md diff --git a/docs/developer/_category_.json b/docs/developer/_category_.json new file mode 100644 index 0000000..b48cbd5 --- /dev/null +++ b/docs/developer/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Developer", + "position": 3 +} \ No newline at end of file diff --git a/docs/developer/advanced-solvers.md b/docs/developer/advanced-solvers.md new file mode 100644 index 0000000..71a3e99 --- /dev/null +++ b/docs/developer/advanced-solvers.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 3 +--- + +# Advanced Solver Architectures + +Dungeons Guide employs several sophisticated algorithms to solve the most complex puzzles and optimization problems in dungeons. This document provides a high-level overview of the two main advanced solver architectures. For a deeper, more technical dive into each component, please see the detailed pages in the **[Core Systems](./core-systems/waterboard-solver.md)** section. + +## 1. Waterboard Puzzle Solver + +The Waterboard puzzle is a complex state-space search problem. The mod solves this by using a **simulated annealing** algorithm, which is implemented in native C++ for maximum performance. This probabilistic technique allows the solver to efficiently search the vast space of possible lever flips and timings to find a high-quality solution. + +- **[Read the detailed Waterboard Solver documentation...](./core-systems/waterboard-solver.md)** + +## 2. Secret Route Pathfinder + +The "Secret Finder" feature is a powerful route optimization engine that calculates the most efficient path to collect all secrets and complete all necessary tasks within a room. This system is built on several interconnected components. + +- **The ActionDAG:** The entire problem of clearing a room is first modeled as a **D**irected **A**cyclic **G**raph of all necessary actions and their dependencies. This allows the system to understand complex prerequisites, such as needing to flip a lever to unlock a secret. + - **[Read the detailed ActionDAG documentation...](./core-systems/action-dag.md)** + +- **The TSP Solver:** Finding the best path through the ActionDAG is a **T**raveling **S**alesperson **P**roblem. The mod uses a multi-stage solver, with its core logic implemented in native C++ for performance, to find the most efficient route. + - **[Read the detailed TSP Solver documentation...](./core-systems/tsp-solver.md)** + +- **Pre-calculation and Caching:** To ensure the TSP solver can run in real-time without causing lag, all pathfinding costs are calculated offline by developers and consolidated into a single cache file for each room. At runtime, the solver reads from this in-memory cache for instant results. + - **[Read the detailed Pre-calculation and Caching documentation...](./core-systems/pre-calculation.md)** + +- **Code Example:** To see how these systems are tied together by a trigger feature, refer to the Smart Route example. + - **[Read the Smart Route Example...](./core-systems/smart-route-example.md)** \ No newline at end of file diff --git a/docs/developer/code-structure.md b/docs/developer/code-structure.md new file mode 100644 index 0000000..8996d92 --- /dev/null +++ b/docs/developer/code-structure.md @@ -0,0 +1,57 @@ +--- +sidebar_position: 1 +--- + +# Code Structure and Architecture + +This document provides a high-level overview of the Dungeons Guide mod's architecture. For a more detailed look at the core systems, please see the following pages: + +- **[Core Data Model: Blueprints and Instances](./core-systems/data-model.md)** +- **[Coordinates and Room Detection](./core-systems/coordinates-and-room-detection.md)** +- **[Dungeon State Management](./dungeon-state-management.md)** +- **[Advanced Solver Architectures](./advanced-solvers.md)** + +## High-Level Data Flow + +The mod's architecture is designed around a one-way data flow, ensuring that the state remains consistent and predictable. + +1. **Raw Game Events:** The process begins with raw events from Minecraft, such as chat messages, map data updates, entity spawns, and world ticks. +2. **Listeners (`DungeonListener`, etc.):** These classes are registered with the Minecraft Forge event bus. Their sole purpose is to capture these raw game events. +3. **`DungeonContext` Update:** The listeners take the raw event data and translate it into meaningful state changes within the central `DungeonContext`. For example, a chat message about a puzzle failure updates a flag in the context. +4. **`RoomProcessor` Logic:** The various `RoomProcessor` instances (for puzzles, boss fights, etc.) continuously monitor the `DungeonContext`. Based on the state in the context, they run their own logic to determine the current state of the puzzle or room (e.g., which blaze to shoot next). The results of this logic are also stored back into the `DungeonContext` or within the processor itself. +5. **Feature Logic (`AbstractFeature`):** The individual features that the user sees (like HUD elements or solvers) are the final step. They read the processed state from the `DungeonContext` and the `RoomProcessors`. They do not modify the state themselves; they are purely for presentation. +6. **User Display:** The feature then uses this information to render waypoints, display HUD text, or highlight entities, providing the final output to the user. + +This unidirectional flow prevents circular dependencies and makes the system easier to debug and reason about. Data flows from the game, is processed into a central state, and then displayed by features. + +## Package Overview + +- **`kr.syeyoung.dungeonsguide.mod`**: The root package for the mod. It contains the main mod class, `DungeonsGuide.java`, which is the entry point for the mod and handles initialization and event registration. + +- **`kr.syeyoung.dungeonsguide.mod.chat`**: This package contains classes for processing and sending chat messages. + +- **`kr.syeyoung.dungeonsguide.mod.commands`**: This package contains the implementation for all of the mod's chat commands (e.g., `/dg`, `/reparty`). + +- **`kr.syeyoung.dungeonsguide.mod.config`**: This package handles loading and saving the mod's configuration. The `Config.java` class is responsible for serializing and deserializing the configuration to and from a JSON file. Individual features define their own configuration parameters. + +- **`kr.syeyoung.dungeonsguide.mod.cosmetics`**: This package contains features related to player cosmetics, such as custom nickname colors, prefixes, and player models. + +- **`kr.syeyoung.dungeonsguide.mod.discord`**: This package contains all the code for Discord Rich Presence integration, including handling party invites and displaying friend activity. + +- **`kr.syeyoung.dungeonsguide.mod.dungeon`**: This is a core package that contains the logic for tracking the player's state within a dungeon. This includes parsing the dungeon layout, tracking room completion, and managing boss fight mechanics. + +- **`kr.syeyoung.dungeonsguide.mod.events`**: This package defines a custom event system that is used throughout the mod to communicate between different components. + +- **`kr.syeyoung.dungeonsguide.mod.features`**: This package contains the base classes and registry for all of the mod's features. Each feature is a subclass of `AbstractFeature` and is registered with the `FeatureRegistry`. This allows for a modular and extensible system for adding new features. + +- **`kr.syeyoung.dungeonsguide.mod.gui`**: This package contains the graphical user interface (GUI) components for the mod, including the main configuration GUI and various HUD elements. + +- **`kr.syeyoung.dungeonsguide.mod.overlay`**: This package contains the system for rendering HUD overlays on the screen. + +- **`kr.syeyoung.dungeonsguide.mod.party`**: This package contains the logic for managing the player's party, including repartying and handling party invites. + +- **`kr.syeyoung.dungeonsguide.mod.pathfinding`**: This package contains pathfinding algorithms used by some of the solvers, such as the ice fill and silverfish solvers. + +- **`kr.syeyoung.dungeonsguide.mod.player`**: This package is responsible for tracking player data and statistics. + +- **`kr.syeyoung.dungeonsguide.mod.utils`**: This package contains various utility classes that are used throughout the mod. \ No newline at end of file diff --git a/docs/developer/core-systems/_category_.json b/docs/developer/core-systems/_category_.json new file mode 100644 index 0000000..c1b9c20 --- /dev/null +++ b/docs/developer/core-systems/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Core Systems", + "position": 4 +} \ No newline at end of file diff --git a/docs/developer/core-systems/action-dag.md b/docs/developer/core-systems/action-dag.md new file mode 100644 index 0000000..d942b78 --- /dev/null +++ b/docs/developer/core-systems/action-dag.md @@ -0,0 +1,31 @@ +--- +sidebar_position: 3 +--- + +# The ActionDAG: Modeling Complex Tasks + +The core of the Secret Finder and other complex route-planning features is the **ActionDAG**, a **D**irected **A**cyclic **G**raph of actions. This data structure provides a powerful and flexible way to represent all the possible tasks and their dependencies required to clear a dungeon room. Instead of a simple list of locations, the ActionDAG models the entire problem as a graph, which can then be solved to find the most efficient solution. + +## A Recursive Construction Process + +The power of the system lies in how the `ActionDAG` is constructed. The logic is not centralized in a single, monolithic class; it is **distributed throughout the `AbstractAction` subclasses themselves** in an elegant, recursive process. + +The process begins when a feature requests a path to achieve a high-level goal, such as getting a specific secret. This creates an `ActionRoute`, which in turn instantiates an `ActionDAGBuilder` and calls its `requires()` method with a high-level action, for example: `requires(new ActionChangeState("secret_chest_1", "found"))`. + +This is where the recursion starts. The builder adds this top-level `ActionChangeState` node to the graph and then calls the `buildActionDAG()` method on the node it just added. The `ActionChangeState` class's implementation of this method knows what it means to "find" a chest: you must first move to it, and then click on it. It then uses the builder it was passed to add its own, lower-level dependencies, such as `builder.requires(new ActionMove(...))` and `builder.requires(new ActionClick(...))`. This process continues, with each action being responsible for defining its own prerequisites, until it reaches "atomic" actions like `ActionMove`, whose `buildActionDAG()` methods are empty, which terminates that branch of the recursion. + +## Modeling Choices: The Three Connection Types + +The `ActionDAGBuilder` supports three distinct ways to define the relationship between a parent node and its prerequisites, giving it incredible flexibility. + +The most common connection is made with the **`requires()`** method, which creates a standard "AND" dependency. This is a list of nodes that must all be completed before the current node can be executed. + +To model choices, the builder uses the **`or()`** method. This creates a list of nodes where **exactly one** of them must be completed. This is perfect for situations where a goal can be achieved in multiple ways, such as opening a door by either flipping a lever or using a superboom. The solver can then evaluate both options and choose the most efficient one. + +Finally, the **`optional()`** method is used for conditional dependencies. This creates a list of nodes that may or may not be required. This is useful for modeling shortcuts or alternative strategies. For example, a path to a secret might be faster if an optional lever is flipped first, but the secret is still obtainable without it. The solver can then decide if the time saved by taking the shortcut is worth the time spent on the optional action. + +## Resolving Possibilities: The `dagId` + +These `or` and `optional` connections mean that a single ActionDAG can represent thousands, or even millions, of possible valid routes. To manage this complexity, the system uses a `dagId`—a single integer that acts as a compact, **bit-masked representation of a specific path** through the graph. + +The `ActionDAGNode` class contains methods that use bitwise arithmetic on the `dagId` to resolve all the choices in the graph. Different bits in the `dagId` determine which path to take at each `or` connection and which of the `optional` dependencies to include. By iterating through all possible `dagId` values, the **[TSP Solver](./tsp-solver.md)** can effectively evaluate every single unique, valid path through the graph to find the one with the lowest total cost. This elegant solution allows the mod to model incredibly complex, non-linear tasks and then systematically find the single most efficient solution. \ No newline at end of file diff --git a/docs/developer/core-systems/coordinates-and-room-detection.md b/docs/developer/core-systems/coordinates-and-room-detection.md new file mode 100644 index 0000000..15a0d26 --- /dev/null +++ b/docs/developer/core-systems/coordinates-and-room-detection.md @@ -0,0 +1,25 @@ +--- +sidebar_position: 2 +--- + +# Coordinates and Room Detection + +Before the mod can solve puzzles or find secrets, it must first solve two fundamental problems: where things are located within a room, and what room it's currently in. Dungeons Guide uses a clever combination of a relative coordinate system and a unique room "fingerprinting" method to handle this with precision and efficiency. + +## 1. The Relative Coordinate System (`OffsetPoint` & `OffsetVec3`) + +A dungeon room can spawn at any location in the world and can be rotated in one of four directions. Hard-coding the absolute coordinates of every secret and lever would be impossible. To solve this, the mod uses a relative coordinate system based on the `OffsetPoint` and `OffsetVec3` classes. + +The purpose of an `OffsetPoint` is to store a coordinate (`x`, `y`, `z`) that is **relative to the corner of a room's schematic**, assuming zero rotation. This allows developers to define the location of a mechanic (like a chest at `(5, 10, 15)`) in a way that is completely independent of where the room spawns or how it's rotated. This is a fundamental concept that allows all `DungeonRoomInfo` blueprints to be defined in a consistent, reusable way. + +At runtime, the `OffsetPoint` class provides the crucial mathematical transformations (`toRotatedRelBlockPos`, `setPosInWorld`) to convert between these abstract, schematic-relative coordinates and the actual, absolute coordinates in the Minecraft world. When a feature needs to know the real-world location of a mechanic, it provides the `OffsetPoint` from the static `DungeonMechanicData` and the current room's rotation. The class then handles the complex matrix transformations to return the correct `BlockPos`, ensuring that waypoints and solvers always have accurate information. + +## 2. Room Detection and the `shape` Bitmask + +When a player enters a new, unexplored area of the dungeon, the mod needs to identify what room it is so it can load the correct `DungeonRoomInfo` blueprint. This is accomplished through a room "fingerprinting" process managed by the `DungeonRoomScaffoldParser`. + +When a new, unidentified room appears on the dungeon map, the `buildRoom` method is called. It performs a **flood-fill** algorithm on the map data, starting from a single point and expanding outwards to find all the connected "unit points" (the 16x16 segments on the map) that constitute a single, contiguous room. + +Once the algorithm has the complete set of points belonging to the room, it generates a unique fingerprint for the room's footprint: the `shape` ID. It does this by normalizing the set of points to a 4x4 grid and then constructing a `short` (a 16-bit integer). The formula `shape |= 1 << (localY * 4 + localX)` sets a specific bit for each cell in the 4x4 grid that is part of the room. This creates a compact and unique bitmask that represents the exact shape of the room's footprint. For example, a simple 1x1 room would have a `shape` of `1` (binary `...0001`), while a 2x2 room in the top-left corner would have a shape of `51` (binary `...00110011`). + +This unique `shape` ID, along with the room's color on the map, is then passed to the `RoomMatcher`. The `RoomMatcher` compares this fingerprint against its library of known `DungeonRoomInfo` blueprints to find the one that has the same shape and color, allowing it to definitively identify the room. Once a match is found, the system knows the room's rotation and can load all of its mechanics and pre-calculated data, enabling all of the mod's advanced features. \ No newline at end of file diff --git a/docs/developer/core-systems/data-model.md b/docs/developer/core-systems/data-model.md new file mode 100644 index 0000000..5111364 --- /dev/null +++ b/docs/developer/core-systems/data-model.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 1 +--- + +# Core Data Model: Blueprints and Instances + +To understand how Dungeons Guide works, it is essential to grasp its core data model. The system is built on a clear and powerful separation between **static, pre-defined blueprints** and **dynamic, runtime instances**. This architecture allows the mod to use a rich, pre-calculated set of data for every known room in the game, while still being able to track the unique, changing state of every individual dungeon run. + +## The Static Blueprints: `Info` & `Data` + +The static half of the data model represents the unchanging, "textbook" definition of a dungeon room and all of its components. These objects are loaded from the mod's asset files (`.roomdata.cbor`) once when the game starts and are never modified during gameplay. + +A `DungeonRoomInfo` object serves as the master blueprint for a specific dungeon room, such as the "1x1 Crusher Room". It contains all the static information about that room, including its physical schematic (the block data), its shape and color as they appear on the map, and a map of all its interactive elements. + +This map of interactive elements is the key to the blueprint system. It contains `DungeonMechanicData` objects, which are the blueprints for individual mechanics like secrets, levers, or traps. A `DungeonSecretChestData` object, for example, knows the static location of a secret chest within the room's schematic. It defines *what* the mechanic is and its inherent properties, but knows nothing about its current state in a live game. Think of these as the raw schematics and parts lists for a room; they know everything about how a room *should* be, but nothing about what's happening in it *right now*. + +## The Runtime Instances: `Room` & `State` + +The runtime half of the data model represents the live, dynamic state of a room during an active dungeon run. These objects are created when a player enters a room and are destroyed when the run ends, holding all the information specific to that single instance of the room. + +The `DungeonRoom` class is the runtime instance of a room. When the `DungeonRoomScaffoldParser` detects that the player has entered a new area, it creates a `DungeonRoom` object. This object holds a reference back to its `DungeonRoomInfo` blueprint, giving it access to all the static data. Most importantly, it manages a collection of `DungeonMechanicState` objects. + +The `DungeonMechanicState` is the dynamic counterpart to `DungeonMechanicData` and the heart of the runtime state tracking. A new `DungeonMechanicState` object is instantiated for every mechanic in the room's blueprint when the `DungeonRoom` is created. This object holds the *current, mutable state* of that specific mechanic for the current run. For example, a `DungeonLeverState` object would have a property like `isFlipped`, which starts as `false` and is updated to `true` only when the player interacts with that specific lever in that specific run. + +## The `RoomProcessor`: The Logic Engine + +The `RoomProcessor` is the bridge that connects the static world of blueprints to the dynamic world of the live dungeon. When a `DungeonRoom` is created, it uses a `ProcessorFactory` to instantiate the correct type of `RoomProcessor` based on an ID string from the `DungeonRoomInfo` blueprint. This allows for specialized logic for different room types, such as a `RoomProcessorWaterPuzzle` or a `RoomProcessorBlazeSolver`. + +The `RoomProcessor` acts as the "brain" of the room. It observes game events like chat messages, block updates, and entity deaths. It then interprets these events within the context of the room and updates the state of the `DungeonRoom` and its collection of `DungeonMechanicState` objects accordingly. This clean separation of data (the `State` objects) and logic (the `Processor`) is fundamental to the mod's ability to manage the complexity of Hypixel Dungeons. \ No newline at end of file diff --git a/docs/developer/core-systems/pre-calculation.md b/docs/developer/core-systems/pre-calculation.md new file mode 100644 index 0000000..9c368a6 --- /dev/null +++ b/docs/developer/core-systems/pre-calculation.md @@ -0,0 +1,70 @@ +--- +sidebar_position: 5 +--- + +# Pre-calculation and Caching Pipeline + +The advanced pathfinding and TSP solving capabilities of Dungeons Guide are only possible because of an aggressive, multi-layered pre-calculation and caching pipeline. The system is designed to solve two major problems: the performance cost of real-time pathfinding, and the memory cost of loading huge amounts of pathfinding data. + +This entire process happens **offline**, during development. The results are bundled with the mod release. + +## The Overall Architecture + +The system can be broken down into two distinct phases: + +1. **Offline Data Generation:** A developer-run process that calculates all the necessary data ahead of time and bundles it with the mod. +2. **Runtime Cache Generation & Usage:** A just-in-time process that consolidates the pre-calculated data into an efficient in-memory cache for the solver to use. + +--- + +## 1. Offline Data Generation + +This phase happens entirely during development. It has two parts: calculating *where* a player needs to go, and calculating the *cost* to get there. + +### A. Target Coordinate Calculation + +Before a path can be calculated, the system needs to know the exact destination coordinates. This is handled by pre-calculating all valid target spots for an action based on the room's state. + +- **`PrecalculatedStonk`:** Calculates all valid standing locations for interacting with a specific block (e.g., clicking a lever), accounting for line-of-sight and potential blockers. +- **`PrecalculatedMoveNearest`:** Calculates all valid standing locations near an entity or point (e.g., for killing a bat). + +This data is generated by developers using the `calculatestonks` and `calculatenearests` debug commands and is stored within the main room data files. + +### B. Path Cost Calculation (`PathfindPrecalculation`) + +Once all possible targets are known, the expensive process of calculating the path costs between them begins. + +- **`PathfindPrecalculation`:** This object represents the raw, pre-calculated path cost data. Each `PathfindPrecalculation` corresponds to a single `.pfres2` file on disk and contains a lookup table of the costs to get from *every point* in a room to a *single target point*. +- **The `PathfindRequest` System:** This is the system used by developers to generate new `.pfres2` files. A `PathfindPrecalculationRequestSet` bundles many pathfinding tasks into a zip file, which is uploaded to a remote server for heavy-duty processing, which then returns the generated `.pfres2` files. + +--- + +## 2. Runtime Cache Generation & Usage + +Loading hundreds of individual `.pfres2` files from disk at runtime would be slow and inefficient. To solve this, the system uses a just-in-time caching mechanism to consolidate this data. + +### The `TSPCache` - A Just-in-Time Cache + +The `TSPCache` is a critical performance component that is **built at runtime**. It is **not** an offline-built asset. Its purpose is to consolidate all the path cost data needed for a specific room configuration into a single, optimized, in-memory object. + +### The `TSPCacheRegistry` and the Generation Process + +1. **Trigger:** The process is managed by the `TSPCacheRegistry`. The generation of a `TSPCache` is triggered whenever a `PathfindPreset` is loaded or a `RoomPreset` is modified by the user. + +2. **Scheduling:** When triggered, the registry schedules a `TSPCacheCalculationTask` to run on a background thread. This prevents the cache generation from causing any lag. + +3. **The Task:** The `TSPCacheCalculationTask` performs the following steps: + - It identifies the specific `RoomPreset` that needs its cache built. + - It reads the manifest of that `RoomPreset` to get the list of all required `PathfindPrecalculation` file IDs. + - It then reads all of these individual `.pfres2` files **from the disk**. + - It extracts the path cost data from each file and consolidates it all into a single, new `TSPCache` object. + - Finally, it serializes this new, complete `TSPCache` object and saves it to a single `.cache` file on disk for future sessions, and also stores it in an in-memory map for the current session. + +### The Final Runtime Data Flow + +1. **Dungeon Start:** The `TSPCacheRegistry` is initialized. When a `PathfindPreset` is loaded, the registry checks if a `.cache` file for each room configuration already exists. If not, or if the configuration has changed, it schedules a background task to generate it. +2. **Route Request:** The `ActionRoute` is created, which triggers the **[TSP Solver](./tsp-solver.md)**. +3. **TSP Solve:** The TSP solver needs the cost between two actions. It asks the `RoomPresetPathPlanner`. +4. **Instant Lookup:** The planner retrieves the fully populated `TSPCache` for the room from the `TSPCacheRegistry`. Since the cache is already consolidated and in-memory, it performs an instant lookup and returns the cost. + +This architecture ensures that all expensive calculations (target-finding, pathfinding, and data consolidation) happen offline. At runtime, path costs are retrieved from a pre-built, in-memory cache, providing maximum performance with no disk I/O. \ No newline at end of file diff --git a/docs/developer/core-systems/smart-route-example.md b/docs/developer/core-systems/smart-route-example.md new file mode 100644 index 0000000..8711a6e --- /dev/null +++ b/docs/developer/core-systems/smart-route-example.md @@ -0,0 +1,72 @@ +--- +sidebar_position: 6 +--- + +# Example: The Smart Route Trigger + +To see how the core systems work together, let's examine the `FeatureSmartRoute` trigger. This feature is responsible for creating a single, optimized route that visits all unfound secrets and unobtained keys in a room. + +## The `createSmartRoute` Method + +This method is the heart of the feature. It is called when the player enters a new room or presses the "Smart Route" keybind. + +```java +// Simplified from FeatureSmartRoute.java + +public void createSmartRoute(DungeonRoom dungeonRoom, RoomRouteHandler roomRouteHandler) { + // 1. Get the current algorithm settings + AlgorithmSetting algorithmSetting = roomRouteHandler.getAlgorithmSetting(); + + // 2. Create a new DAG Builder for the current room + ActionDAGBuilder actionDAGBuilder = new ActionDAGBuilder(dungeonRoom); + + // 3. Iterate through all mechanics in the room + for (Map.Entry value : dungeonRoom.getMechanics().entrySet()) { + + // 4. If the mechanic is an unfound secret... + if (value.getValue() instanceof ISecret && !((ISecret) value.getValue()).isFound(dungeonRoom)) { + try { + // ...add a requirement to the builder: "this mechanic must be in the 'found' state" + actionDAGBuilder.requires(new ActionChangeState(value.getKey(), "found"), algorithmSetting); + } catch (PathfindImpossibleException e) { + // Handle cases where a path is impossible + continue; + } + // 5. If the mechanic is an unobtained key... + } else if (value.getValue() instanceof DungeonRedstoneKeyState && value.getValue().getCurrentState().equalsIgnoreCase("unobtained")) { + try { + // ...add a requirement to the builder: "this key must be in the 'obtained-self' state" + actionDAGBuilder.requires(new ActionChangeState(value.getKey(), "obtained-self"), algorithmSetting); + } catch (PathfindImpossibleException e) { + // Handle cases where a path is impossible + continue; + } + } + } + + try { + // 6. Build the final, combined DAG from all requirements + ActionDAG dag = actionDAGBuilder.build(); + + // 7. Create a new ActionRoute, which triggers the TSP solver on the DAG + ActionRoute actionRoute = new ActionRoute("Smart Route", dungeonRoom, dag); + + // 8. Add the final, solved route to the handler to be displayed + roomRouteHandler.getPath().put("smart", FeatureRegistry.SECRET_LINE_PROPERTIES_SMART_ROUTE.createPathDisplayEngine(actionRoute)); + } catch (PathfindImpossibleException e) { + // Handle cases where a solution is impossible + } +} +``` + +### Breakdown of the Process + +1. **Get Settings:** It retrieves the current pathfinding settings (e.g., whether to use etherwarp, stonk, etc.). +2. **Instantiate Builder:** It creates a fresh `ActionDAGBuilder` for the current room. This builder will accumulate all the tasks we need to perform. +3. **Iterate Mechanics:** It loops through every single defined mechanic in the room's data map. +4. **Add Secret Requirements:** If a mechanic is an `ISecret` and it hasn't been found yet, it adds a requirement to the builder. The `ActionChangeState` tells the builder its goal is to get this specific secret into the `"found"` state. The builder then automatically determines the necessary sub-actions (e.g., `ActionMove`, `ActionClick`) to achieve this goal. +5. **Add Key Requirements:** It does the same for any redstone keys that haven't been picked up, adding a goal to get the key into the `"obtained-self"` state. +6. **Build the DAG:** After iterating through all mechanics, the `actionDAGBuilder.build()` method is called. This takes all the added requirements and their sub-actions and compiles them into a single, massive `ActionDAG` that represents the entire task of clearing the room. +7. **Solve and Display:** This complete `ActionDAG` is then passed to the `ActionRoute` constructor. This triggers the **[TSP Solver](./tsp-solver.md)**, which finds the most efficient path through the graph. The final, solved route is then passed to the `RoomRouteHandler` to be rendered for the player. + +This example perfectly illustrates the power of the ActionDAG architecture. By simply defining a list of high-level goals ("get this secret," "get that key"), the system can automatically build a complex dependency graph and find the single best route to accomplish all of them. \ No newline at end of file diff --git a/docs/developer/core-systems/tsp-solver.md b/docs/developer/core-systems/tsp-solver.md new file mode 100644 index 0000000..ffe147f --- /dev/null +++ b/docs/developer/core-systems/tsp-solver.md @@ -0,0 +1,39 @@ +--- +sidebar_position: 4 +--- + +# The TSP Solver: Finding the Optimal Route + +Once the **[ActionDAG](./action-dag.md)** has been constructed, it represents every possible valid way to complete a room. The next challenge is to find the single most efficient path through this graph. This is a classic computer science challenge known as the **T**raveling **S**alesperson **P**roblem (TSP). Dungeons Guide uses a sophisticated, multi-stage TSP solver to find the optimal route with maximum performance. The `ActionRoute` class is responsible for orchestrating this entire solving process. + +In the context of the mod, the "cities" that must be "visited" are the nodes of the ActionDAG—the individual tasks like moving to a location or clicking a lever. The "distance" or "cost" between two of these actions is the time it takes a player to travel from the location of the first action to the location of the second. This cost is determined by a fast A* pathfinding lookup, made nearly instantaneous by the **[Pre-calculation and Caching](./pre-calculation.md)** system. + +## The Primary Solver: `DPTSP` (C++ Implementation) + +The first tool the mod reaches for is the `DPTSP` class, a highly efficient solver based on the **Dynamic Programming** approach to the Traveling Salesperson Problem, also known as the Held-Karp algorithm. + +- **Native Performance:** To achieve the absolute best performance, the core logic of the `DPTSP` solver is implemented in **C++** and loaded into the game via a native library (`dptsp.dll` or `dptsp.so`). The `DPTSP.java` class acts as a wrapper, preparing the data from the `ActionDAG` and passing it to the high-performance native code through the Java Native Interface (JNI). This is confirmed by the `native` methods (`startCoroutine`, `resumeCoroutine`, etc.) found within the class. + +- **Advantages:** + - **Guaranteed Optimality:** The DPTSP algorithm is guaranteed to find the absolute best, most efficient route. + - **Efficiency:** While its complexity is exponential (`O(n² * 2^n)`), the native C++ implementation is vastly more efficient than a Java equivalent and is capable of solving the vast majority of dungeon rooms in milliseconds. + +- **Usage:** The `ActionRoute` class first attempts to solve the `ActionDAG` using this native `DPTSP` solver. In most cases, this is successful and provides the final, optimal route. + +## The Fallback Solver: `TravelingSalesman` + +In rare cases, a room may be so extraordinarily complex that even the native `DPTSP` solver could take too long. To handle these edge cases without freezing the game, the system gracefully falls back to the `TravelingSalesman` class, which has its own two-stage approach. + +The `ActionRoute` detects when a problem is too large by doing a preliminary check on the number of possible paths in the DAG. If it exceeds a certain threshold, it skips the `DPTSP` and uses this fallback instead. + +1. **Bruteforce Mode:** For problems that are too large for `DPTSP` but still have a manageable number of permutations, the `TravelingSalesman` solver will use a **bruteforce** method. It will systematically check every single valid path through the DAG to find the best one. + +2. **Simulated Annealing Mode:** For the most complex rooms imaginable, where even the bruteforce fallback would be too slow, the solver switches to a **simulated annealing** algorithm. This probabilistic method finds a near-optimal solution in a fraction of the time, prioritizing a smooth user experience over guaranteed mathematical perfection in these extreme edge cases. + +## Summary + +This multi-layered solver architecture provides the best of all worlds: + +- For the vast majority of rooms, the native `DPTSP` solver delivers a **perfectly optimal route** in milliseconds. +- For the rare, highly complex rooms, the system automatically falls back to a slower but still optimal `bruteforce` method. +- For the most extreme edge cases, it uses `simulated annealing` to prevent any lag, ensuring a smooth user experience while still providing an excellent, high-quality route. \ No newline at end of file diff --git a/docs/developer/core-systems/waterboard-solver.md b/docs/developer/core-systems/waterboard-solver.md new file mode 100644 index 0000000..0927b59 --- /dev/null +++ b/docs/developer/core-systems/waterboard-solver.md @@ -0,0 +1,23 @@ +--- +sidebar_position: 1 +--- + +# Waterboard Puzzle Solver + +The Waterboard puzzle is arguably one of the most complex in the game. It is not a simple pathfinding problem, but rather a state-space search problem, requiring a precise sequence and timing of actions to manipulate a dynamic system—the flow of water. To solve this, Dungeons Guide uses a sophisticated optimization technique known as **simulated annealing**, with its core logic implemented in native C++ for maximum performance. + +## System Components + +The solver is broken down into several key classes, each with a distinct responsibility. The `FeatureSolverWaterboard` is the user-facing component that defines the configuration options, allowing players to tune the performance of the underlying algorithm. The `RoomProcessorWaterPuzzle` acts as the central controller, responsible for modeling the puzzle by reading the block data from the world and orchestrating the solving process. It uses a `Simulator` utility class to accurately predict water flow for any given sequence of actions. + +The heart of the solver is the `Waterboard` class, which contains the `solve()` method. This method takes the puzzle model from the `RoomProcessor` and passes it to the native C++ library where the computationally expensive simulated annealing algorithm is executed. + +## The Simulated Annealing Algorithm (C++ Implementation) + +Simulated annealing is a probabilistic technique used to find a good approximation of the global optimum in a large search space. It's inspired by the process of annealing in metallurgy, where a material is heated and then slowly cooled to reduce its defects. + +In the context of the Waterboard puzzle, a "solution" is a list of `Waterboard.Action` objects, where each action consists of flipping a specific lever and then waiting for a certain number of ticks. The "energy" or "cost" of a solution is a measure of how far the resulting water flow is from the target flow required to open the doors. + +The algorithm begins with a random sequence of actions and then iteratively makes small, random modifications. If a change results in a better solution (lower energy), it is always accepted. However, if a change results in a *worse* solution, it might still be accepted based on a "temperature" parameter. This is the key to the algorithm's power. By allowing occasional "bad" moves, especially at a high initial temperature, the solver can avoid getting stuck in "local optima" (good-but-not-the-best solutions) and explore a much wider range of possibilities. As the algorithm runs, the temperature is slowly lowered, causing it to become more "greedy" and eventually settle on a very low-energy, high-quality solution. + +This entire computationally intensive process is handled by a native C++ library (loaded via `NativeLoader.extractLibraryAndLoad("waterboard")`) to ensure it doesn't impact game performance. The final, optimized sequence of actions is then returned to the `RoomProcessorWaterPuzzle`, which renders it as a series of clear, timed instructions for the player. \ No newline at end of file diff --git a/docs/developer/dungeon-state-management.md b/docs/developer/dungeon-state-management.md new file mode 100644 index 0000000..6f08544 --- /dev/null +++ b/docs/developer/dungeon-state-management.md @@ -0,0 +1,50 @@ +--- +sidebar_position: 2 +--- + +# Dungeon State Management + +The ability of Dungeons Guide to provide accurate, real-time information and puzzle solutions hinges on its robust dungeon state management system. This system is responsible for understanding the dungeon's layout, tracking player progress, and monitoring the state of every puzzle and entity within it. + +## The `DungeonContext` + +The heart of the state management system is the `DungeonContext` class. An instance of this class is created every time a player enters a new dungeon and is destroyed when they leave. It serves as a central repository for all information related to the current dungeon run. + +Key responsibilities of `DungeonContext`: + +- **Dungeon Layout:** It holds a reference to the `DungeonRoomScaffoldParser`, which is responsible for parsing the dungeon map data and identifying the individual rooms and their connections. +- **Player and Entity Tracking:** It keeps track of all players in the dungeon, their locations on the map, and the state of important entities (like mimics or bosses). +- **Puzzle and Room State:** Through `RoomProcessor` instances, it monitors the state of every room, including whether puzzles are complete, failed, or in progress. +- **Boss Fight Logic:** It holds an instance of a `BossfightProcessor` specific to the current floor, which manages the complex phases and mechanics of the boss encounter. +- **Event Recording:** It uses a `DungeonEventRecorder` to log significant events that occur during the run, which can be used for debugging or advanced analytics. +- **Pathfinding Execution:** It manages the `PathfinderExecutorExecutor`, which runs pathfinding calculations in the background. + +## The Data Flow: From Game to `DungeonContext` + +The `DungeonContext` is populated and updated by a series of listeners and processors that observe the game world and translate raw game events into meaningful state changes. + +1. **Map Updates (`onMapUpdate`):** This is the primary source of information for the dungeon layout. When the in-game map is updated, the `DungeonContext` receives the new map data. + - If the layout hasn't been determined yet, it uses `DungeonMapConstantRetriever` to parse the map and create a `DungeonMapLayout`. + - This layout is then used to initialize the `DungeonRoomScaffoldParser`, which breaks the map down into a grid of `DungeonRoom` objects. + - Each `DungeonRoom` is then matched against a library of known room layouts to identify it (e.g., "1x1 Room", "Fairy Room", "Blaze Puzzle"). + +2. **Chat Messages (`onChat`):** Many in-game events are only communicated through chat. The `DungeonContext` listens for specific chat messages to detect: + - Puzzle failures (`PUZZLE FAIL!`). + - The end of a dungeon run (`EXTRA STATS`). + - Player deaths. + - Secret DG-to-DG communication for sharing information like secret counts. + +3. **World Ticks (`tick`):** On every game tick, the `DungeonContext` performs several updates: + - It updates the list of players in the dungeon by checking the tab list. + - It checks if the player has entered the boss room by comparing their position to the known dungeon boundary. + - It tells each `DungeonRoom` to re-evaluate its state if it hasn't been successfully identified yet. + +## Room Processors: The Brains of the Operation + +While `DungeonContext` holds the state, the `RoomProcessor` classes contain the logic for interpreting that state. Each `DungeonRoom` can have a `RoomProcessor` attached to it. + +- **`GeneralRoomProcessor`:** Handles common tasks for all rooms, like tracking secrets. +- **Puzzle-Specific Processors:** For rooms with puzzles (e.g., blaze, water board), a specialized processor is attached. This processor understands the specific entities and mechanics of its puzzle and updates the room's state accordingly. For example, the blaze room processor tracks which blazes have been killed and in what order. +- **`BossfightProcessor`:** A special type of processor that manages the entire boss fight, which can have multiple phases and complex mechanics. + +By centralizing all dungeon-related information into the `DungeonContext`, the mod ensures that all features are working with the same, consistent view of the game world. This allows a feature like a solver to simply query the context for the state of a puzzle, without needing to know the low-level details of how that state was determined. \ No newline at end of file diff --git a/docs/features/_category_.json b/docs/features/_category_.json new file mode 100644 index 0000000..56e0bf0 --- /dev/null +++ b/docs/features/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Features", + "position": 2 +} \ No newline at end of file diff --git a/docs/features/boss/_category_.json b/docs/features/boss/_category_.json new file mode 100644 index 0000000..ffae8b3 --- /dev/null +++ b/docs/features/boss/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Boss", + "position": 2 +} \ No newline at end of file diff --git a/docs/features/boss/auto-reparty.md b/docs/features/boss/auto-reparty.md new file mode 100644 index 0000000..9c20d6a --- /dev/null +++ b/docs/features/boss/auto-reparty.md @@ -0,0 +1,12 @@ +--- +sidebar_position: 1 +--- + +# Auto Reparty + +The Auto Reparty feature is a convenient quality-of-life utility that streamlines the process of starting a new dungeon run. When enabled, the mod will automatically handle the administrative task of disbanding your current party and reinviting all the members as soon as your dungeon run concludes. This allows you and your team to get into the next run faster, without the need for a party leader to manually type the commands each time. + +## Configuration + +### Enabled +This feature is a simple toggle. Due to its nature of automating chat commands, it is disabled by default. Please be aware that while such features are common, they exist in a gray area regarding Hypixel's rules. Use this feature at your own risk. \ No newline at end of file diff --git a/docs/features/boss/boss-health-display.md b/docs/features/boss/boss-health-display.md new file mode 100644 index 0000000..7541f6e --- /dev/null +++ b/docs/features/boss/boss-health-display.md @@ -0,0 +1,20 @@ +--- +sidebar_position: 2 +--- + +# Boss Health Display + +Keeping track of the health of multiple enemies during a chaotic boss fight can be challenging. The Boss Health Display feature provides a clear, on-screen HUD element that shows the current health of all major bosses and mini-bosses in the arena, such as the Guardians in the Floor 7 boss fight or the Priests in Floor 6. This allows you to maintain situational awareness and prioritize targets effectively without needing to look directly at them. + +## Configuration + +You can customize how health information is presented to suit your preferences. + +### Show total health +When this option is enabled, the display will show both the current and maximum health of an enemy (e.g., "5M / 10M"). If disabled, it will only show the current health, providing a cleaner, more compact view. + +### Format health +To improve readability, enabling this option will format large health numbers into a more compact form (e.g., 1,234,567 will be displayed as "1.2M"). This can make the HUD element less cluttered and easier to read at a glance. + +### Don't show health of in-attackable enemy +This option helps to reduce screen clutter by hiding the health bars of any bosses or mini-bosses that are currently invulnerable or cannot be attacked. This ensures that the display only shows actionable information, allowing you to focus on the targets that matter. \ No newline at end of file diff --git a/docs/features/boss/box-real-livid.md b/docs/features/boss/box-real-livid.md new file mode 100644 index 0000000..beb9710 --- /dev/null +++ b/docs/features/boss/box-real-livid.md @@ -0,0 +1,12 @@ +--- +sidebar_position: 3 +--- + +# Box Real Livid + +In the Floor 5 boss fight, the Livid boss creates numerous clones of himself, making it difficult to identify the real one. The Box Real Livid feature solves this problem by drawing a distinct, colored box around the one true Livid. This allows you to instantly identify and target the correct enemy, saving time and preventing wasted damage on the clones. + +## Configuration + +### Highlight Color +This option allows you to customize the color of the box that highlights the real Livid. You can choose a color that is highly visible to you, ensuring that the real Livid stands out clearly from the crowd of clones. \ No newline at end of file diff --git a/docs/features/boss/current-phase-display.md b/docs/features/boss/current-phase-display.md new file mode 100644 index 0000000..f5381ca --- /dev/null +++ b/docs/features/boss/current-phase-display.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 4 +--- + +# Current Phase Display + +Boss fights in dungeons often have multiple, distinct phases with different mechanics. The Current Phase Display feature provides a simple but effective HUD element that shows the name of the current phase you are in (e.g., "crush," "terminals," "lasers"). This helps you and your team maintain situational awareness, anticipate upcoming mechanics, and execute the correct strategy for each stage of the fight. + +## Configuration + +This feature is a HUD element and can be enabled or disabled like any other. Its primary configuration is done through the HUD editor, where you can change its position on the screen and customize the text style (color, font, size) to match your personal UI layout. \ No newline at end of file diff --git a/docs/features/boss/f7-terminal-waypoints.md b/docs/features/boss/f7-terminal-waypoints.md new file mode 100644 index 0000000..a376d00 --- /dev/null +++ b/docs/features/boss/f7-terminal-waypoints.md @@ -0,0 +1,26 @@ +--- +sidebar_position: 5 +--- + +# F7 Terminal Waypoints + +The terminal phase of the Floor 7 boss fight can be a hectic and confusing part of the run. The F7 Terminal Waypoints feature provides a powerful set of visual aids to help your team navigate this phase efficiently. It renders customizable waypoints and status indicators on all the terminals, ensuring everyone knows where to go and what to do. + +## Configuration + +This feature offers a high degree of customization to help you tailor the display to your needs. + +### Highlight waypoints in world +This is the main toggle for the feature. When enabled, it will draw a colored highlight box around each terminal, making them easy to spot within the boss arena. + +### Enable beacon beam +For even greater visibility, you can enable this option to add a vertical beacon beam effect to each waypoint. This is particularly useful for spotting terminals from a long distance or across the room. + +### Beam Color & Target Color +These options allow you to customize the color of both the beacon beam and the highlight box around the terminal. You can choose colors that stand out best against the background of the boss arena. + +### Render terminal status on beacon +This setting adds useful text information to each waypoint, showing its current status. The text will indicate whether a terminal is "Done," "Incomplete," or if a specific player is currently near it, which helps with team coordination and prevents multiple players from going to the same terminal. + +### Only render current sub-phase +To reduce screen clutter, you can enable this option to only show waypoints for the terminals that are active in the current sub-phase of the fight. If disabled, all terminals on the floor will be shown at once. \ No newline at end of file diff --git a/docs/features/boss/hide-animals.md b/docs/features/boss/hide-animals.md new file mode 100644 index 0000000..0a3f7fd --- /dev/null +++ b/docs/features/boss/hide-animals.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 6 +--- + +# Hide Animals (F4) + +The Floor 4 boss fight can fill the arena with a large number of non-hostile Spirit Animals, which can create visual clutter and make it difficult to see important enemies and mechanics. The Hide Animals feature provides a simple solution by allowing you to selectively hide the models of these animals, cleaning up your screen and allowing you to focus on the fight. + +## Configuration + +This feature provides a separate toggle for each type of Spirit Animal, giving you fine-grained control over what you see. + +- **Hide Sheep:** When enabled, all Spirit Sheep in the arena will be invisible. +- **Hide Cows:** When enabled, all Spirit Cows in the arena will be invisible. +- **Hide Chickens:** When enabled, all Spirit Chickens in the arena will be invisible. +- **Hide Wolves:** When enabled, all Spirit Wolves in the arena will be invisible. +- **Hide Rabbits:** When enabled, all Spirit Rabbits in the arena will be invisible. \ No newline at end of file diff --git a/docs/features/boss/score-warning-on-portal.md b/docs/features/boss/score-warning-on-portal.md new file mode 100644 index 0000000..a836d63 --- /dev/null +++ b/docs/features/boss/score-warning-on-portal.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 10 +--- + +# Score Warning on Watcher Portal + +Before entering the boss fight, it's crucial to know if your team is on track for a high score. The Score Warning on Watcher Portal feature provides a comprehensive summary of your run's progress, displayed directly on the portal to the boss room. This summary includes warnings for critical issues like undiscovered rooms or failed puzzles, as well as a detailed breakdown of your score estimate, including secrets found, crypts, deaths, and time. This allows your team to make an informed decision about whether to proceed to the boss or go back to find more secrets. + +## Configuration + +This feature can be enabled or disabled in the main configuration menu. Its appearance is highly customizable through a dedicated text style editor. This allows you to change the color, font, and size of different parts of the warning message, such as the main warning text, the field names (e.g., "Total Secrets"), and the values, ensuring the information is presented in a way that is clear and readable for you. \ No newline at end of file diff --git a/docs/features/boss/spirit-bear-percentage.md b/docs/features/boss/spirit-bear-percentage.md new file mode 100644 index 0000000..85cc99b --- /dev/null +++ b/docs/features/boss/spirit-bear-percentage.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 8 +--- + +# Spirit Bear Summon Percentage (F4) + +During the Floor 4 boss fight, the Spirit Bear is a crucial ally that is summoned after a certain number of enemies are defeated. The Spirit Bear Summon Percentage feature provides a convenient HUD element that displays the progress towards this goal as a percentage. This allows you and your team to see exactly how close you are to summoning the bear, helping you to strategize and anticipate this important event in the fight. + +## Configuration + +This feature is a HUD element and can be enabled or disabled in the configuration menu. You can customize its appearance and location using the HUD editor, which allows you to change its on-screen position, as well as the color, size, and style of the text to fit your personal UI preferences. \ No newline at end of file diff --git a/docs/features/boss/spirit-bow-timer.md b/docs/features/boss/spirit-bow-timer.md new file mode 100644 index 0000000..ec59c36 --- /dev/null +++ b/docs/features/boss/spirit-bow-timer.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 9 +--- + +# Spirit Bow Timer (F4) + +The Spirit Bow is a key item in the Floor 4 boss fight, but it only exists for a limited time after being picked up. The Spirit Bow Timer feature provides a crucial HUD element that displays a countdown, showing you exactly how much time is left before the bow disintegrates. This helps you make the most of this powerful weapon, ensuring you can land your shots before it disappears. + +## Configuration + +As a HUD element, the Spirit Bow Timer can be enabled or disabled in the mod's configuration menu. Its visual appearance can be fully customized through the HUD editor, which allows you to move it anywhere on your screen and change the text's style, color, and size to best suit your needs. \ No newline at end of file diff --git a/docs/features/boss/terracotta-timer.md b/docs/features/boss/terracotta-timer.md new file mode 100644 index 0000000..cb7ae87 --- /dev/null +++ b/docs/features/boss/terracotta-timer.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 7 +--- + +# Terracotta Timer (F6) + +The terracotta phase of the Floor 6 boss fight is a timed section that can be stressful to manage. The Terracotta Timer feature provides a simple and clear HUD element that displays a countdown for this phase. This allows you to see at a glance how much time is remaining, helping you pace yourself and coordinate with your team to ensure the phase is completed successfully. + +## Configuration + +As a HUD element, the Terracotta Timer can be enabled or disabled in the configuration menu. Its primary customization options are available in the HUD editor, where you can freely change its position on the screen and adjust the text style, size, and color to perfectly match your user interface. \ No newline at end of file diff --git a/docs/features/cosmetics/_category_.json b/docs/features/cosmetics/_category_.json new file mode 100644 index 0000000..35ef980 --- /dev/null +++ b/docs/features/cosmetics/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Cosmetics", + "position": 5 +} \ No newline at end of file diff --git a/docs/features/cosmetics/nickname-color.md b/docs/features/cosmetics/nickname-color.md new file mode 100644 index 0000000..2cb5157 --- /dev/null +++ b/docs/features/cosmetics/nickname-color.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 1 +--- + +# Nickname Color + +The Nickname Color feature allows you to add a touch of personality to your in-game identity. This cosmetic option lets you select a custom color for your Minecraft username, which will be visible to all other players who are also using the Dungeons Guide mod. This allows you to stand out in chat and express your individual style within the Dungeons Guide community. + +## Configuration + +This feature does not use a standard configuration toggle. Instead, the color for your nickname is chosen through a special, dedicated color selection widget within the mod's main graphical user interface. This provides a rich, interactive way to select the perfect shade. \ No newline at end of file diff --git a/docs/features/cosmetics/nickname-prefix.md b/docs/features/cosmetics/nickname-prefix.md new file mode 100644 index 0000000..aa5d7fd --- /dev/null +++ b/docs/features/cosmetics/nickname-prefix.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 2 +--- + +# Nickname Prefix + +The Nickname Prefix feature offers another layer of cosmetic customization for your in-game identity. This option allows you to choose from a selection of unique prefixes that will appear before your username in chat. This prefix is visible to all other players who are also using the Dungeons Guide mod, allowing you to further personalize your appearance within the community. + +## Configuration + +Similar to the Nickname Color, this feature is not configured with a simple toggle. Instead, you can choose your desired prefix from a list within a special, dedicated prefix selection widget in the mod's main graphical user interface. \ No newline at end of file diff --git a/docs/features/cosmetics/player-model.md b/docs/features/cosmetics/player-model.md new file mode 100644 index 0000000..70b34c7 --- /dev/null +++ b/docs/features/cosmetics/player-model.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 3 +--- + +# Player Model + +The Player Model feature provides the ultimate level of cosmetic customization, allowing you to change your in-game player model to one of several unique options. This cosmetic change is visible to all other players who are also using the Dungeons Guide mod, giving you a distinct and recognizable appearance within the community. + +## Configuration + +This feature is configured through a special, dedicated model selection widget within the mod's main graphical user interface. This provides a visual way to preview and select the player model that best suits your style. \ No newline at end of file diff --git a/docs/features/discord/_category_.json b/docs/features/discord/_category_.json new file mode 100644 index 0000000..aab9cce --- /dev/null +++ b/docs/features/discord/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Discord", + "position": 6 +} \ No newline at end of file diff --git a/docs/features/discord/discord-rich-presence.md b/docs/features/discord/discord-rich-presence.md new file mode 100644 index 0000000..876748c --- /dev/null +++ b/docs/features/discord/discord-rich-presence.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 1 +--- + +# Discord Rich Presence + +The Discord Rich Presence feature integrates your Dungeons Guide experience directly with your Discord profile. When enabled, it will display detailed information about your current in-game status, such as your location, party details, and other relevant data, to your friends on Discord. This feature also includes an "Ask to Join" functionality, allowing other players to request to join your party directly through the Discord interface, making it easier than ever to team up. + +## Configuration + +This feature can be enabled or disabled in the main configuration menu. The "Ask to Join" functionality can also be toggled separately through the in-game UI, giving you full control over whether you want to receive party requests from Discord. \ No newline at end of file diff --git a/docs/features/discord/friend-online-notification.md b/docs/features/discord/friend-online-notification.md new file mode 100644 index 0000000..7567e85 --- /dev/null +++ b/docs/features/discord/friend-online-notification.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 2 +--- + +# Friend Online Notification + +The Friend Online Notification feature helps you stay connected with your friends who also use Dungeons Guide. When enabled, this feature will display a small, non-intrusive notification on your screen whenever one of your Discord friends launches Minecraft with the Dungeons Guide mod active. This makes it easy to see when your friends are online and ready to play, allowing you to team up without having to constantly check your friends list. + +## Configuration + +This feature is a HUD element that can be enabled or disabled in the main configuration menu. Its position on the screen can be fully customized through the HUD editor, allowing you to place the notification wherever it is most convenient for you. You can also adjust the text style, color, and size to match your personal UI preferences. \ No newline at end of file diff --git a/docs/features/qol/_category_.json b/docs/features/qol/_category_.json new file mode 100644 index 0000000..e3dea3b --- /dev/null +++ b/docs/features/qol/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "QOL", + "position": 3 +} \ No newline at end of file diff --git a/docs/features/qol/ability-cooldown.md b/docs/features/qol/ability-cooldown.md new file mode 100644 index 0000000..d85991b --- /dev/null +++ b/docs/features/qol/ability-cooldown.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 2 +--- + +# Ability Cooldown Display + +Many powerful items in dungeons have abilities with significant cooldowns. Keeping track of these timers mentally can be difficult, especially during intense combat. The Ability Cooldown Display provides a clear, on-screen HUD element that shows a timer for your item abilities, ensuring you always know when you can use them again. This helps you optimize your damage output and utility usage without having to guess if an ability is ready. + +## Configuration + +This feature is a HUD element that can be enabled or disabled in the main configuration menu. Its appearance and location can be fully customized through the HUD editor, allowing you to change its on-screen position and adjust the text style, color, and size to seamlessly integrate with your existing UI setup. \ No newline at end of file diff --git a/docs/features/qol/blood-room-warning.md b/docs/features/qol/blood-room-warning.md new file mode 100644 index 0000000..f78a60b --- /dev/null +++ b/docs/features/qol/blood-room-warning.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 4 +--- + +# Blood Room Warning + +The "Blood Room" (the entrance to the boss fight) is a point of no return. Entering it too early can jeopardize your chances of getting a high score. The Blood Room Warning feature provides a critical HUD element that displays your dungeon's progress and gives a clear warning if you should not yet proceed. This helps prevent common mistakes like entering the boss room before all puzzles are complete or all necessary secrets have been found. + +## Configuration + +This feature is a HUD element that can be enabled or disabled in the main configuration menu. Its on-screen position and the style of the text (color, font, size) can be fully customized in the HUD editor, allowing you to place this important warning wherever it is most visible to you. \ No newline at end of file diff --git a/docs/features/qol/box-secret-bats.md b/docs/features/qol/box-secret-bats.md new file mode 100644 index 0000000..a710853 --- /dev/null +++ b/docs/features/qol/box-secret-bats.md @@ -0,0 +1,15 @@ +--- +sidebar_position: 5 +--- + +# Box Secret Bats + +Secret bats can be small, fast-moving, and difficult to spot, especially in dimly lit rooms. The Box Secret Bats feature makes them significantly easier to see by drawing a colored box around each one. This visual aid helps the bats stand out from the environment, allowing you to quickly locate and eliminate them to collect your secret. It's important to note that this feature is purely visual and does not alter the bats' hitboxes in any way. + +## Configuration + +### Enabled +This allows you to toggle the feature on or off. + +### Box Color +You can customize the color of the highlight box to ensure it is highly visible against the various backgrounds of the dungeon rooms. Choosing a bright, contrasting color is recommended. \ No newline at end of file diff --git a/docs/features/qol/box-skeleton-masters.md b/docs/features/qol/box-skeleton-masters.md new file mode 100644 index 0000000..ec8fd01 --- /dev/null +++ b/docs/features/qol/box-skeleton-masters.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 6 +--- + +# Box Skeleton Masters + +Skeleton Masters are a high-priority threat in dungeons, capable of dealing significant damage. The Box Skeleton Masters feature helps you to quickly identify and target these dangerous mobs by drawing a colored box around them. This makes them stand out from the crowd of other skeletons and zombies, allowing you to prioritize them and neutralize the threat more effectively. + +## Configuration + +The appearance of the highlight box can be customized to suit your preferences. + +### Enabled +This allows you to toggle the feature on or off. + +### Box Color +You can choose the color of the highlight box, ensuring that it is easily visible against the varied environments of the dungeon and doesn't blend in with other visual effects. \ No newline at end of file diff --git a/docs/features/qol/custom-party-finder-gui.md b/docs/features/qol/custom-party-finder-gui.md new file mode 100644 index 0000000..2307c99 --- /dev/null +++ b/docs/features/qol/custom-party-finder-gui.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 12 +--- + +# Custom Party Finder GUI + +The default Party Finder interface can be clunky and difficult to navigate. The Custom Party Finder GUI feature replaces the standard interface with a redesigned, more user-friendly version. This custom GUI provides a cleaner layout and a more intuitive experience, making it easier and faster to find and manage your dungeon parties. + +## Configuration + +This feature can be enabled or disabled in the configuration menu. When enabled, it will automatically replace the default Party Finder GUI. There are no other specific options to configure. \ No newline at end of file diff --git a/docs/features/qol/disable-ability-messages.md b/docs/features/qol/disable-ability-messages.md new file mode 100644 index 0000000..c1964eb --- /dev/null +++ b/docs/features/qol/disable-ability-messages.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 10 +--- + +# Disable Ability Messages + +Certain item abilities can spam the chat with messages, such as notifying you that you were hit for a certain amount of damage. While sometimes useful, these messages can quickly clutter your chat and obscure more important information from your party members. The Disable Ability Messages feature provides a simple solution by filtering out and hiding these specific messages, leading to a cleaner and more readable chat experience. + +## Configuration + +This feature is a simple toggle that can be enabled or disabled in the configuration menu. There are no other settings to configure. \ No newline at end of file diff --git a/docs/features/qol/dungeon-map.md b/docs/features/qol/dungeon-map.md new file mode 100644 index 0000000..f2747eb --- /dev/null +++ b/docs/features/qol/dungeon-map.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 8 +--- + +# Dungeon Map + +The in-game dungeon map can be difficult to read and lacks detailed information. The Dungeon Map feature provides a much-improved, custom map overlay that gives you a clear and comprehensive view of the entire dungeon. This enhanced map not only shows the full layout, but also displays the completion progress of each room, the current positions of your teammates, and the total number of secrets contained within each room. This makes it an invaluable tool for navigation, coordination, and ensuring you never miss a secret. + +## Configuration + +This feature is a HUD element and can be enabled or disabled in the main configuration menu. As a core visual component, it can be fully customized through the HUD editor. You can change its size and position on your screen to ensure it is placed conveniently for you, and you can also adjust the style of the map's various text elements to your liking. \ No newline at end of file diff --git a/docs/features/qol/highlight-starred-mobs.md b/docs/features/qol/highlight-starred-mobs.md new file mode 100644 index 0000000..e69f881 --- /dev/null +++ b/docs/features/qol/highlight-starred-mobs.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 7 +--- + +# Highlight Starred Mobs + +In a room filled with enemies, it can be difficult to distinguish the normal mobs from the more dangerous, "starred" variants. The Highlight Starred Mobs feature provides a crucial visual aid by applying a customizable highlight to these priority targets. This allows you to quickly identify and focus down the most significant threats in a room, improving your efficiency and survivability. + +## Configuration + +You can tailor the appearance of the highlight to make it as noticeable as possible. + +### Enabled +This allows you to toggle the feature on or off. + +### Highlight Color +This option lets you choose the color of the highlight that is applied to starred mobs. Selecting a bright and easily recognizable color is recommended to ensure these dangerous enemies never go unnoticed. \ No newline at end of file diff --git a/docs/features/qol/low-health-warning.md b/docs/features/qol/low-health-warning.md new file mode 100644 index 0000000..96ecb4e --- /dev/null +++ b/docs/features/qol/low-health-warning.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 11 +--- + +# Low-Health Warning + +In the chaos of a dungeon, it can be easy to lose track of your teammates' health. The Low-Health Warning feature acts as a safety net by providing a clear, on-screen alert whenever a player in your party drops below 500 HP. The warning displays the player's name and their remaining health, allowing you to quickly identify a teammate in trouble and provide support, potentially preventing a death. + +## Configuration + +This feature is a HUD element and can be enabled or disabled in the main configuration menu. Its position on the screen and the style of the text (color, font, size) can be fully customized in the HUD editor, ensuring that this critical warning is always visible to you. \ No newline at end of file diff --git a/docs/features/qol/reparty-command.md b/docs/features/qol/reparty-command.md new file mode 100644 index 0000000..28df431 --- /dev/null +++ b/docs/features/qol/reparty-command.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 9 +--- + +# Reparty Command + +Manually disbanding and re-forming a party between dungeon runs can be a tedious process. The Reparty Command feature streamlines this by providing a simple and convenient chat command: `/reparty`. When executed by the party leader, this command will instantly disband the current party and reinvite all the previous members, saving time and effort and allowing your team to get into the next run more quickly. + +## Configuration + +This feature is a simple command that can be enabled or disabled. When enabled, the `/reparty` command becomes available for use. There are no other configuration options. \ No newline at end of file diff --git a/docs/features/qol/secrets-chest-close.md b/docs/features/qol/secrets-chest-close.md new file mode 100644 index 0000000..aa9a596 --- /dev/null +++ b/docs/features/qol/secrets-chest-close.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 1 +--- + +# Secrets Chest Close + +Opening a secret chest and manually closing the GUI can be a small but repetitive interruption to the flow of a dungeon run. The Secrets Chest Close feature is a simple quality-of-life improvement that streamlines this process. When this feature is enabled, you can instantly close any secret chest you have opened by simply pressing any key on your keyboard. This allows you to grab the loot and get back to the action with minimal delay. + +## Configuration + +This feature has a single toggle to turn it on or off. There are no other configuration options. \ No newline at end of file diff --git a/docs/features/qol/spirit-boots-fixer.md b/docs/features/qol/spirit-boots-fixer.md new file mode 100644 index 0000000..467f4f5 --- /dev/null +++ b/docs/features/qol/spirit-boots-fixer.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 3 +--- + +# Spirit Boots Fixer + +A well-known and frustrating bug can occur when using Spirit Boots, where activating their ability causes the item in your hand to seemingly disappear, replaced by air. The Spirit Boots Fixer is a simple, background feature that corrects this visual glitch. When enabled, it automatically prevents this bug from happening, ensuring your held item remains visible and accessible after you use the boots' ability. + +## Configuration + +This is a set-and-forget feature. It has a single toggle to turn it on or off, with no other configuration needed. \ No newline at end of file diff --git a/docs/features/solvers/_category_.json b/docs/features/solvers/_category_.json new file mode 100644 index 0000000..83a44e9 --- /dev/null +++ b/docs/features/solvers/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Solvers", + "position": 1 +} \ No newline at end of file diff --git a/docs/features/solvers/blaze-solver.md b/docs/features/solvers/blaze-solver.md new file mode 100644 index 0000000..fae4756 --- /dev/null +++ b/docs/features/solvers/blaze-solver.md @@ -0,0 +1,23 @@ +--- +sidebar_position: 1 +--- + +# Blaze Solver + +The Blaze Solver is an essential tool for navigating one of the more chaotic puzzle rooms in the dungeons. When activated, this feature provides clear, real-time guidance on the correct sequence for dispatching the blazes, removing the guesswork and allowing for a faster and more efficient room clear. The solver highlights the blazes in different colors to indicate their priority, ensuring you always know which target to focus on next. + +## Configuration + +To tailor the visual cues to your preference, the Blaze Solver offers several color customization options. + +### Normal Blaze Color +This setting determines the color of the highlight for all blazes that are not part of the immediate solution. You can set this to a more subdued color to help the primary targets stand out. + +### Next Blaze Color +This is the most critical setting, as it controls the highlight color for the very next blaze you need to kill. A bright, distinct color is recommended to make your next target immediately obvious in the heat of battle. + +### Next Up Blaze Color +To help you plan a step ahead, this option sets the color for the blaze that will become the primary target *after* you've killed the current one. This allows for smoother transitions between targets. + +### Blaze Border Color +This option allows you to configure the color of the outline drawn around the highlight box for all blazes, which can help improve visibility against different backgrounds. \ No newline at end of file diff --git a/docs/features/solvers/bomb-defuse-solver.md b/docs/features/solvers/bomb-defuse-solver.md new file mode 100644 index 0000000..df9cbf6 --- /dev/null +++ b/docs/features/solvers/bomb-defuse-solver.md @@ -0,0 +1,12 @@ +--- +sidebar_position: 2 +--- + +# Bomb Defuse Solver + +The Bomb Defuse Solver is a crucial feature for the pressure plate puzzle, providing a clear visual path to the solution. To comply with Hypixel's rules, this solver requires a player to first visit the left side of the puzzle. Once there, pressing a configurable key will save the solution path, which is then displayed for the player to follow. + +## Configuration + +### Key +This option allows you to set a specific keybind to save the Bomb Defuse solution. This key can also be used to transmit the solution to other Dungeons Guide users in your party, making it a useful tool for team coordination. \ No newline at end of file diff --git a/docs/features/solvers/ice-fill-solver.md b/docs/features/solvers/ice-fill-solver.md new file mode 100644 index 0000000..e30b2ee --- /dev/null +++ b/docs/features/solvers/ice-fill-solver.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 3 +--- + +# Ice Fill Solver + +The Ice Fill Solver provides a clear and easy-to-follow guide through the treacherous ice puzzle. Instead of guessing and slipping, this feature draws a distinct line on the screen, showing you the exact path to take to solve the puzzle correctly on the first try. This saves valuable time and eliminates a common point of frustration in dungeon runs. + +## Configuration + +You can customize the appearance of the solution path to ensure it is clearly visible in any situation. + +### Line Color +This option allows you to choose the color of the line that indicates the correct path. It's recommended to select a bright, vibrant color that stands out against the icy blue of the puzzle room. + +### Line Thickness +With this setting, you can adjust the thickness of the solution line. A thicker line can be easier to see, especially at higher screen resolutions or for players who prefer more prominent visual cues. \ No newline at end of file diff --git a/docs/features/solvers/riddle-solver.md b/docs/features/solvers/riddle-solver.md new file mode 100644 index 0000000..8de7ce9 --- /dev/null +++ b/docs/features/solvers/riddle-solver.md @@ -0,0 +1,12 @@ +--- +sidebar_position: 4 +--- + +# Riddle Solver + +The three-person riddle puzzle requires players to listen to the statements of three NPCs and determine which one is telling the truth. The Riddle Solver automates this process. After you have clicked on all three NPCs to gather their statements, the solver will automatically identify the correct character to talk to, highlighting them with a colored box. This removes the need for manual deduction and speeds up the completion of this common puzzle room. + +## Configuration + +### Target Color +This option allows you to customize the color of the highlight box that appears around the correct NPC. You can choose a color that is easily visible to you, ensuring you can quickly identify the right character and complete the puzzle. \ No newline at end of file diff --git a/docs/features/solvers/silverfish-solver.md b/docs/features/solvers/silverfish-solver.md new file mode 100644 index 0000000..d71ec3b --- /dev/null +++ b/docs/features/solvers/silverfish-solver.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 5 +--- + +# Silverfish Solver + +The Silverfish puzzle requires players to hit the silverfish in a specific direction to guide it towards a target. The Silverfish Solver removes the trial-and-error from this task by drawing a clear line on the screen, indicating the optimal path and direction in which to hit the silverfish. This ensures a quick and efficient solution to the puzzle every time. + +## Configuration + +You can customize the appearance of the solution path to make it as clear as possible in the often chaotic environment of the puzzle room. + +### Line Color +This option allows you to set the color of the line that shows the correct path. Choosing a distinct and bright color will help it stand out from the room's background and other visual effects. + +### Line Thickness +This setting lets you adjust the thickness of the solution line, making it more or less prominent based on your personal preference and screen resolution. A thicker line can be easier to follow at a glance. \ No newline at end of file diff --git a/docs/features/solvers/teleport-solver.md b/docs/features/solvers/teleport-solver.md new file mode 100644 index 0000000..f7a3748 --- /dev/null +++ b/docs/features/solvers/teleport-solver.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 6 +--- + +# Teleport Solver + +The teleport maze puzzle can be a disorienting experience, requiring players to remember which pads they have already visited. The Teleport Solver simplifies this process by keeping track of the pads you've used. It highlights the teleport pads with different colors, allowing you to distinguish between the correct solution path and the pads you have already stepped on but which are not part of the solution. This visual aid helps you navigate the maze efficiently without getting lost. + +## Configuration + +The solver's visual cues can be customized to ensure they are clear and intuitive for you. + +### Solution Color +This option sets the color of the highlight for the teleport pad that is part of the correct solution path. + +### Not-Solution Color +This setting controls the color of the highlight for teleport pads that you have already visited but which are not part of the correct solution. This helps you avoid retreading incorrect paths. \ No newline at end of file diff --git a/docs/features/solvers/tic-tac-toe-solver.md b/docs/features/solvers/tic-tac-toe-solver.md new file mode 100644 index 0000000..caabb67 --- /dev/null +++ b/docs/features/solvers/tic-tac-toe-solver.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 7 +--- + +# Tic-Tac-Toe Solver + +The Tic-Tac-Toe puzzle room challenges players to beat or draw against a surprisingly competent AI opponent. The Tic-Tac-Toe Solver provides a significant advantage by showing you the optimal move to make at every step of the game. It highlights the best square to choose, ensuring you can secure a win or a draw and complete the puzzle quickly and reliably. + +## Configuration + +The solver uses different colors to highlight the recommended move, and you can customize these to your liking. + +### Your Turn Color +This option sets the color of the highlight box that appears on the board during your turn, indicating the best possible move you can make. + +### Enemy Turn Color +This setting controls the color of the highlight box that appears during the AI's turn. This can be useful for analysis or for understanding the board state even when it's not your move. \ No newline at end of file diff --git a/docs/features/solvers/waterboard-solver.md b/docs/features/solvers/waterboard-solver.md new file mode 100644 index 0000000..5d27c13 --- /dev/null +++ b/docs/features/solvers/waterboard-solver.md @@ -0,0 +1,30 @@ +--- +sidebar_position: 8 +--- + +# Waterboard Solver + +The Waterboard puzzle is arguably one of the most complex in the game, requiring a precise sequence of lever flips to achieve the correct water flow. The Dungeons Guide Waterboard Solver is an advanced tool that calculates a one-flow solution for you, displaying the exact levers to flip and the timing required. This eliminates the need for complex manual calculations and trial-and-error, saving a significant amount of time and effort. + +## Configuration + +The Waterboard Solver offers a range of configuration options, from simple quality-of-life toggles to advanced hyperparameters for the underlying simulated annealing algorithm. + +### Block wrong clicks +This is a simple but powerful quality-of-life feature. When enabled, the mod will physically prevent you from clicking on a lever that is not part of the calculated solution, making it impossible to make a mistake and mess up the puzzle. + +### Lever flip waits +This setting controls the minimum time the solver will enforce between lever flips, measured in "water ticks" (where 4 ticks equal 1 second). The default is 6 ticks (1.5 seconds). You can adjust this value based on your own comfort and speed. + +### Advanced Solver Settings +The following settings are for advanced users who wish to fine-tune the performance of the simulated annealing algorithm that solves the puzzle. Modifying these can change the trade-off between the speed at which a solution is found and the efficiency of the solution itself. + +- **Temperature Multiplier:** This value (between 0 and 1) controls how quickly the algorithm "cools down." A value closer to 1 will cause the solver to take longer, but it will be more likely to find a faster, more optimal solution. A value closer to 0 will find a solution very quickly, but that solution may involve more steps. + +- **Temperature Target:** This is the temperature at which the algorithm will stop searching. A higher value will cause the solver to stop sooner, potentially with a slower solution, while a lower value will make it search longer for a faster solution. + +- **Iteration Target:** This is a fallback mechanism. If the solver does not find a better solution after this many iterations, it will stop and return the best solution it has found so far. + +- **Maximum amount of 1-water-tick passes:** This advanced setting controls the number of "no-op" actions the solver can consider. A higher value allows it to find slower, more complex solutions if no fast solution exists, but it will increase the calculation time. + +- **Maximum amount of lever flips per each lever type:** This sets a limit on how many times the solver can use each type of lever in its proposed solution. A higher value allows for more complex solutions at the cost of longer calculation times. \ No newline at end of file diff --git a/docs/features/statistics/_category_.json b/docs/features/statistics/_category_.json new file mode 100644 index 0000000..b8bd307 --- /dev/null +++ b/docs/features/statistics/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Statistics", + "position": 4 +} \ No newline at end of file diff --git a/docs/features/statistics/broken-crypts-indicator.md b/docs/features/statistics/broken-crypts-indicator.md new file mode 100644 index 0000000..27f5d15 --- /dev/null +++ b/docs/features/statistics/broken-crypts-indicator.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 12 +--- + +# Broken Crypts Indicator + +The number of broken crypts in a run contributes to your final score. While this information is available in the tab list, checking it requires an extra key press and can interrupt your gameplay. The Broken Crypts Indicator provides a convenient HUD element that displays the current number of broken crypts directly on your screen, giving you the same information as the tab list without the hassle. + +## Configuration + +As a HUD element, this feature can be enabled or disabled in the main configuration menu. Its position on the screen, as well as the color, size, and style of the text, can be fully customized in the HUD editor to match your personal UI preferences. \ No newline at end of file diff --git a/docs/features/statistics/current-milestone-indicator.md b/docs/features/statistics/current-milestone-indicator.md new file mode 100644 index 0000000..d438476 --- /dev/null +++ b/docs/features/statistics/current-milestone-indicator.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 13 +--- + +# Current Milestone Indicator + +Reaching new milestones in dungeons is a key part of progression. The Current Milestone Indicator is a HUD element that keeps you informed of your progress by displaying the current milestone you have achieved for the dungeon floor you are playing. This allows you to see your accomplishments at a glance without needing to check your stats manually after the run. + +## Configuration + +This feature is a HUD element that can be enabled or disabled in the main configuration menu. You can fully customize its on-screen position and the style of its text (color, font, size) through the HUD editor to ensure it is displayed in a way that is convenient for you. \ No newline at end of file diff --git a/docs/features/statistics/dungeon-cooldown-indicator.md b/docs/features/statistics/dungeon-cooldown-indicator.md new file mode 100644 index 0000000..ae25429 --- /dev/null +++ b/docs/features/statistics/dungeon-cooldown-indicator.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 8 +--- + +# Dungeon Cooldown Indicator + +After leaving a dungeon, there is a 20-second cooldown period before you can start a new run. The Dungeon Cooldown Indicator is a simple HUD element that displays a timer for this cooldown. This allows you to see exactly when you are able to queue for the next dungeon, helping to streamline the process of chain-running dungeons with your party. + +## Configuration + +As a HUD element, this feature can be enabled or disabled in the main configuration menu. Its visual appearance and on-screen location can be fully customized through the HUD editor, allowing you to change the text style, color, size, and position to fit your needs. \ No newline at end of file diff --git a/docs/features/statistics/dungeon-death-indicator.md b/docs/features/statistics/dungeon-death-indicator.md new file mode 100644 index 0000000..5aec539 --- /dev/null +++ b/docs/features/statistics/dungeon-death-indicator.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 9 +--- + +# Dungeon Death Indicator + +Deaths can significantly impact your final score in a dungeon run. The Dungeon Death Indicator is a HUD element that keeps a running tally of the deaths in your party. It displays the name of each player who has died, how many times they have died, and the total number of deaths for the entire party. This provides a clear, at-a-glance summary of your team's performance and helps you understand how your final score is being affected. + +## Configuration + +This feature is a HUD element that can be enabled or disabled in the main configuration menu. You can fully customize its on-screen position and the style of its text (color, font, size) through the HUD editor, ensuring the information is displayed in a way that is convenient and readable for you. \ No newline at end of file diff --git a/docs/features/statistics/dungeon-items-stats.md b/docs/features/statistics/dungeon-items-stats.md new file mode 100644 index 0000000..3b083f6 --- /dev/null +++ b/docs/features/statistics/dungeon-items-stats.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 5 +--- + +# Dungeon Items Stats + +The Dungeon Items Stats feature adds valuable context to the tooltips of items obtained from dungeons. When enabled, it will display additional information about the item, including the specific dungeon floor it originated from and its quality, shown as a percentage. This can be useful for collectors, for understanding the value of an item, or for simply keeping track of where your gear came from. + +## Configuration + +This is a simple feature that can be enabled or disabled in the main configuration menu. There are no other specific options to configure. \ No newline at end of file diff --git a/docs/features/statistics/dungeon-score-pre-calculator.md b/docs/features/statistics/dungeon-score-pre-calculator.md new file mode 100644 index 0000000..c9a7fb2 --- /dev/null +++ b/docs/features/statistics/dungeon-score-pre-calculator.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 10 +--- + +# Dungeon Score Pre-Calculator + +Achieving a high score, particularly an S+, is a primary goal of any dungeon run. The Dungeon Score Pre-Calculator is a powerful HUD element that helps you track your progress towards this goal in real-time. It provides a live estimate of your final score based on your current performance. More importantly, it tells you exactly how many more secrets you need to find to advance to the next score rank (e.g., from S to S+), allowing you to make informed decisions about whether to continue searching for secrets or proceed to the boss. + +## Configuration + +This feature is a HUD element that can be enabled or disabled in the main configuration menu. You can fully customize its on-screen position and the style of its text (color, font, size) through the HUD editor, ensuring this vital information is always clearly visible to you. \ No newline at end of file diff --git a/docs/features/statistics/in-game-time-indicator.md b/docs/features/statistics/in-game-time-indicator.md new file mode 100644 index 0000000..24e9b9a --- /dev/null +++ b/docs/features/statistics/in-game-time-indicator.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 7 +--- + +# In-Game Time Indicator + +While the Real-Time Indicator shows the actual time elapsed, the In-Game Time Indicator displays the official time that Hypixel has recorded for your dungeon run. This is the time that ultimately determines your score for the "Time" category. This HUD element allows you to see this crucial value at a glance, without needing to open any menus, helping you to pace your run effectively to achieve a better score. + +## Configuration + +This feature is a HUD element and can be enabled or disabled in the main configuration menu. You can fully customize its on-screen position and the style of its text (color, font, size) through the HUD editor, ensuring the information is displayed in a way that is convenient and readable for you. \ No newline at end of file diff --git a/docs/features/statistics/obtained-secret-indicator.md b/docs/features/statistics/obtained-secret-indicator.md new file mode 100644 index 0000000..434da75 --- /dev/null +++ b/docs/features/statistics/obtained-secret-indicator.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 11 +--- + +# Obtained Secret Indicator + +Maximizing your score often comes down to finding all the secrets in a dungeon. The Obtained Secret Indicator is a simple but essential HUD element that shows you how many secrets have been found so far, as well as the total number of secrets that exist in the current dungeon. This is displayed as a clear "found / total" fraction, giving you an immediate understanding of your team's progress and how many secrets are still left to be discovered. + +## Configuration + +This feature is a HUD element that can be enabled or disabled in the main configuration menu. You can fully customize its on-screen position and the style of its text (color, font, size) through the HUD editor to ensure it integrates perfectly with your UI. \ No newline at end of file diff --git a/docs/features/statistics/party-profile-viewer.md b/docs/features/statistics/party-profile-viewer.md new file mode 100644 index 0000000..bc2475a --- /dev/null +++ b/docs/features/statistics/party-profile-viewer.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 2 +--- + +# Party Profile Viewer + +When evaluating potential party members, it's essential to have quick access to their key statistics. The Party Profile Viewer provides a powerful, integrated way to inspect a player's profile directly from the chat. By simply hovering over the "view" button next to a player's name, you can see a detailed tooltip that displays their equipped armor, total secrets found, Lily weight, talismans, and a selection of other useful statistics. This allows you to quickly assess a player's experience and gear without needing to visit their profile manually. + +## Configuration + +This feature can be enabled or disabled in the main configuration menu. Its primary setting allows you to choose which additional statistics are displayed in the profile tooltip. This customization is handled through the mod's main GUI, giving you control over what information is most important to you when building a party. \ No newline at end of file diff --git a/docs/features/statistics/price-viewer.md b/docs/features/statistics/price-viewer.md new file mode 100644 index 0000000..b959640 --- /dev/null +++ b/docs/features/statistics/price-viewer.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 4 +--- + +# Price Viewer + +Understanding the value of an item is key to managing your wealth in Skyblock. The Price Viewer feature provides a convenient tooltip that displays the current market value of any item you hover over. It shows both the current Buy It Now (BIN) price and the average Auction House (AH) price, giving you a quick and accurate snapshot of an item's worth without needing to check the Auction House manually. This helps you make informed decisions about what to keep, what to sell, and what to buy. + +## Configuration + +This feature is a HUD element that can be enabled or disabled in the main configuration menu. Its appearance can be customized in the HUD editor, which allows you to adjust the on-screen position and the text style (color, font, size) to your preference. \ No newline at end of file diff --git a/docs/features/statistics/profit-calculator.md b/docs/features/statistics/profit-calculator.md new file mode 100644 index 0000000..27a5553 --- /dev/null +++ b/docs/features/statistics/profit-calculator.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 3 +--- + +# Profit Calculator + +Deciding whether to open a dungeon chest can be a gamble. The Profit Calculator feature takes the guesswork out of this decision by providing a clear, on-screen HUD element that shows you the potential profit or loss of opening the chest in front of you. It analyzes the value of the items inside and compares it to the cost of opening the chest, giving you an instant calculation to help you make smarter economic choices. + +## Configuration + +This feature is a HUD element that can be enabled or disabled in the main configuration menu. You can fully customize its on-screen position and the style of its text (color, font, size) through the HUD editor, ensuring the information is displayed in a way that is convenient and readable for you. \ No newline at end of file diff --git a/docs/features/statistics/real-time-indicator.md b/docs/features/statistics/real-time-indicator.md new file mode 100644 index 0000000..fc74927 --- /dev/null +++ b/docs/features/statistics/real-time-indicator.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 6 +--- + +# Real-Time Indicator + +The Real-Time Indicator is a straightforward and useful HUD element that displays a simple timer, showing you exactly how much real-world time has passed since you began the current dungeon run. This can be helpful for tracking your clear times, for speedrunning, or for simply being aware of how long a run is taking. + +## Configuration + +As a HUD element, this feature can be enabled or disabled in the main configuration menu. Its visual appearance and on-screen location can be fully customized through the HUD editor, allowing you to change the text style, color, size, and position to fit your needs. \ No newline at end of file diff --git a/docs/features/statistics/view-room-name.md b/docs/features/statistics/view-room-name.md new file mode 100644 index 0000000..c125844 --- /dev/null +++ b/docs/features/statistics/view-room-name.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 1 +--- + +# View Room Name + +Knowing the specific name of the room you are in can be useful for callouts and for understanding the dungeon layout. The View Room Name feature provides a simple HUD element that displays the name of your current room in the dungeon. This saves you from having to guess or remember the name of every room, providing a convenient at-a-glance reference. + +## Configuration + +This feature is a HUD element and can be enabled or disabled in the main configuration menu. Its position on the screen, as well as the color, size, and style of the text, can be fully customized in the HUD editor to match your personal UI preferences. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..c339d60 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,13 @@ +--- +sidebar_position: 1 +--- + +# Welcome to the Dungeons Guide Documentation + +Welcome to the official documentation for the Dungeons Guide mod! + +Dungeons Guide is a comprehensive mod for Hypixel Skyblock that provides a wide range of features to help you navigate the dangers of the catacombs. From puzzle solvers to quality-of-life improvements and detailed statistics, Dungeons Guide has everything you need to enhance your dungeoneering experience. + +This documentation is designed to help you get the most out of the mod. Here you will find detailed information about all of the features, how to configure them, and for developers, a high-level overview of the mod's code structure. + +To get started, check out the **[Features](./features/solvers/blaze-solver.md)** section to see everything Dungeons Guide has to offer. \ No newline at end of file