> For the complete documentation index, see [llms.txt](https://donkolia.gitbook.io/minesantum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://donkolia.gitbook.io/minesantum/santumholograms.md). # SantumHolograms {% embed url="" %} Welcome to the official documentation for SantumHolograms. This is an advanced and highly customizable hologram plugin designed for modern servers. It provides robust features such as dynamic visibility conditions, interactive actions, and seamless integration with PlaceholderAPI. The plugin is built with performance in mind using native Bukkit display entities ## Key Features * Fully asynchronous condition evaluation to ensure zero server lag * Native Bukkit TextDisplay and Interaction entities for perfect chunk loading synchronization * Conditional text rendering based on real-time player states * Clickable actions with permission escalation and custom feedback * Support for infinite subfolders to organize your hologram configurations cleanly * Advanced viewer modes to restrict hologram visibility to specific players or groups * Custom hex color backgrounds and dynamic quaternion rotations ## Configuration Guide Every hologram is configured in its own YAML file inside the `holograms` folder or any of its subfolders. Below is a detailed explanation of every single setting available for your holograms ```yaml ejemplo: enabled: true location: world: world x: 0.5 y: 100.5 z: 0.5 visibility_distance: -1 scale_x: 2.0 scale_y: 2.0 scale_z: 2.0 custom_rotation: false rotation_x: 0.0 rotation_y: 0.0 rotation_z: 0.0 text_shadow: true see_through: false text_alignment: center background: transparent visible_conditions: - "%player_level% == 2" text_conditions: - "%player_level% == 2" text: - '&bTienes nivel suficiente para entrar' - '&eTu nivel es: &f%player_level%' text_reject_conditions: - '&aNo tienes nivel suficiente para entrar' - '&eTu nivel es: &f%player_level%' actions: - "message: &a¡Has reclamado tu recompensa!" - "centered_message: &ePremio entregado" - "as_console: give %player_name% diamond 1" - "as_op: say %player_name% es genial" - "as_player: me acaba de recibir un diamante" actions_conditions: - "%player_level%+0 >= 1" actions_conditions_reject: - "message: &cNecesitas ser al menos nivel 1." - "centered_message: &4Acción rechazada" viewer_none_mode: "global_visible" viewer_list: none ``` ### Core Settings **enabled**\ Set this to `true` to make the hologram active or `false` to disable it without deleting the file **location**\ Defines the exact position where the hologram will spawn. You must specify the `world` name along with the exact `x`, `y`, and `z` coordinates **visibility\_distance**\ The maximum distance in blocks from which a player can see the hologram. Set this to `-1` for infinite visibility as long as the chunk is loaded ### Appearance Settings **scale\_x / scale\_y / scale\_z**\ Controls the size of the hologram in the game world. You can stretch or squash the text by using different values for each axis **custom\_rotation**\ If set to `true` the hologram will stay fixed in the world and will not rotate to follow the player's camera. If set to `false` the text will always face the player looking at it **rotation\_x / rotation\_y / rotation\_z**\ When `custom_rotation` is enabled these values define the exact rotation angles of the hologram. This allows you to place text flat on the ground or angled against a wall **text\_shadow**\ Adds a dark drop shadow behind the text for better readability against bright backgrounds **see\_through**\ If enabled the hologram will be visible through blocks and walls **text\_alignment**\ Defines how multiple lines of text align with each other. Valid options are `left`, `right`, and `center` **background**\ The background color of the hologram text. You can use `transparent` for no background or any standard HEX color code like `#FF2B00` ### Dynamic Text and Conditions **visible\_conditions**\ A list of PlaceholderAPI mathematical conditions that a player must meet to see the hologram. If these conditions fail the player will not see the hologram at all\ Example: `"%player_level% == 2"` **text\_conditions**\ A secondary set of conditions evaluated only if the player can already see the hologram. This determines which set of text lines will be displayed to the player **text**\ The main text lines shown to the player if they meet the `text_conditions`. Supports color codes and all PlaceholderAPI variables **text\_reject\_conditions**\ The alternative text lines shown if the player fails the `text_conditions`. This is incredibly useful to show a locked state or requirements the player is missing ### Interactive Actions **actions**\ A list of commands or messages executed when a player right-clicks the hologram. This only triggers if the player meets the `actions_conditions` **actions\_conditions**\ PlaceholderAPI mathematical conditions required to execute the actions. If the player fails these conditions the `actions_conditions_reject` list will be executed instead **actions\_conditions\_reject**\ The alternative actions executed when a player clicks but fails the action conditions. Perfect for warning messages or error sounds ### Supported Action Types When defining actions you must use specific prefixes to tell the plugin how to execute them: * **message:** Sends a standard chat message to the player * **centered\_message:** Sends a perfectly centered chat message to the player * **as\_console:** Executes a command from the server console with full privileges * **as\_op:** Temporarily grants the player operator permissions to run the command * **as\_player:** Forces the player to run the command or chat message normally You can use `%player_name%` inside any command to target the clicking player ### Viewer Mode Explanation The viewer mode system allows you to create private holograms or blacklist specific players from seeing them. This is controlled by two settings working together **viewer\_list**\ A list of player names or UUIDs that are registered for this specific hologram. You can also set this to `none` if you do not want to use specific player tracking **viewer\_none\_mode**\ Defines the default visibility state of the hologram and how it interacts with the `viewer_list` * **global\_visible**\ By default everyone can see the hologram. However if a player is added to the `viewer_list` they will be BLACKLISTED and the hologram will be hidden from them * **global\_invisible**\ By default nobody can see the hologram. However if a player is added to the `viewer_list` they will be WHITELISTED and the hologram will become visible specifically for them --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://donkolia.gitbook.io/minesantum/santumholograms.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.