Configuration

Configuration of HoloAPI can be done in the following two files:

config.yml - Used for all main HoloAPI configuration
language.yml - Allows control over messages sent by HoloAPI

On this page, you will learn how to:

Configure HoloAPI to your liking
Set up the following prepared hologram templates for use in the plugin:
- Images
- Animations (GIFs)

Config.yml

Options inside of this file are as follows:

Option	Default value	Description
`command`	`holo`	Utilising dynamic command registration, the HoloAPI command can be customised to your liking.
`primaryChatColour`	`3`	Primary chat colour used for HoloAPI messages. Will affect language.yml when first loaded.
`secondaryChatColour`	`b`	Secondary chat colour used for HoloAPI messages. Will affect language.yml when first loaded.
`autoUpdate`	`false`	If set to true, HoloAPI will update automatically from dev.bukkit.org. See the BukkitDev page for more information on this.
`checkForUpdates`	`true`	If set to true, HoloAPI will check for updates from dev.bukkit.org and notify the console if one is available. See the BukkitDev page for more information on this.
`verticalLineSpacing`	`0.25`	Spacing between each line of holograms
`transparency.withBorder`	`&r`	The character value used for image holograms when `requiresBorder` is set to `true`.
`transparency.noBorder`		The character value used for image holograms when `requiresBorder` is set to `false`.
`multicolorFormat.character`	`&s`	ChatColor character that HoloAPI replaces with the multicolour format.
`multicolorFormat.colours`	`&d,&5,&1,&9,&b,&a,&e,&6,&c,&3`	Sequence of colours used by the format.
`multicolorFormat.delay`	`5`	Delay (in ticks) between colour changes.
`timezone.offset`	`0`	Sets the offset for the `%time%` hologram tag
`timezone.showZoneMarker`	`true`	Sets whether the zone marker is shown in the `%time%` hologram tag

Special Characters (Unicode)

The specialCharacters section of the configuration file allows the definition of codes that are automatically translated by HoloAPI into the specified unicode character.

HoloAPI comes with the following character configuration built in:

specialCharacters:
  '[x]': '2591'
  '[xx]': '2592'
  '[xxx]': '2593'
  '[xxxx]': '2588'
  '[/]': '26A1'
  '[<3]': '2764'
  '[:)]': '263A'
  '[:(]': '2639'
  '[s]': '2600'
  '[*]': '2605'

Using the above configuration, placing [:)] anywhere in a hologram will replace it with the specified special character, which in this case is a smiley face (☺︎).

Chat Bubbles

Note: Chat bubbles are disabled by default

When enabled, chat bubbles will automatically appear above players' heads indicating any words spoken into chat. The default chat bubbles appear as shown below.

The values that can be configured are as follows.

Option	Default value	Description
`chatBubbles.show`	`false`	Sets whether chat bubbles are enabled
`chatBubbles.rise`	`true`	Sets if the bubbles rise upwards after being created
`chatBubbles.followPlayer`	`false`	If true, bubbles will follow the player as they move. HoloAPI currently exhibits the smoothest chat bubble movement of all hologram plugins.
`chatBubbles.showPlayerName`	`true`	If false, the player name will not be shown
`chatBubbles.nameFormat`	`&6&o`	Format of the player name as shown in the chat bubble
`chatBubbles.displayDurationSeconds`	`8`	Duration the bubble is shown for
`chatBubbles.charactersPerLine`	`30`	Number of characters allowed per line
`chatBubbles.distanceAbovePlayerTag`	`0.5`	Distance (in blocks) the hologram is created above the player's head

Indicators

Note: Indicators are disabled by default

Indicators are small holograms shown when specific events are fired.

For example, this hologram is indicating that the player gained 1 health point.

Gain health

Various types of holographic indicators can be enabled and configured in the indicators section of the config.

Image and Animated Holograms

Image Holograms

The Images section of the config file can be used to control the images loaded into HoloAPI for use through both the commands and API. Only loaded images are available directly from HoloAPI.

Note: The images section is not loaded with the HoloAPI config by default, and must be created by the user.

Images MUST be placed in the images folder of the HoloAPI directory (plugins/HoloAPI/images/). This WILL NOT work unless the image is found.

The following is an example setup of an image.

images:
  myfavouriteimage:
    path: horse.png
    characterType: BLOCK
    height: 20
    type: FILE
    requiresBorder: false

The values above are as follows:

Value	Explanation
`path`	The path of the image in the `images` folder. (In the example, the `horse.png` image is located in `plugins/HoloAPI/images/`).
`characterType`	Character display type of the image. Four possible options are: `BLOCK`, `DARK`, `MEDIUM` and `LIGHT`.
`height`	Display height of the image when loaded in-game
`type`	File type (see below for more information)
`requiresBorder`	Some images work better with this set to true, depending on the placement of transparent pixels.

To create a hologram based on this image in-game, the command /holo create image myfavouriteimage would need to be used.

Animated Holograms

The animations section of the config.yml can be used to load in specific GIFs to use for animated holograms. As with images, only loaded animations will be available within HoloAPI.

Note: The animations section is not loaded with the HoloAPI config by default, and must be created by the user.

GIFs MUST be placed in the animaions folder of the HoloAPI directory (plugins/HoloAPI/animations/). This directory is created by default when HoloAPI is loaded for the first time

The following is an example of how to set up an animation:

animations:
  myfirstanimation:
    path: myanimation.gif
    characterType: BLOCK
    height: 30
    frameRate: 10
    type: FILE
    requiresBorder: false

The values above are as follows (very similar to images):

Value	Explanation
`path`	The path of the GIF in the `animations` folder. (In the example, the `myanimation.gif` image is located in `plugins/HoloAPI/animations/`). This file MUST be a GIF.
`characterType`	Character display type of the animation. Four possible options are: `BLOCK`, `DARK`, `MEDIUM` and `LIGHT`.
`height`	Maximum display height of the animation frames
`frameRate`	Rate of change in frames (measured in ticks, where 20 ticks is the equivalent of 1 second). In the example, the animation would show two frames per second.
`type`	File type (see below for more information)
`requiresBorder`	Some animations work better with this set off, depending on the placement of transparent pixels. By default, this will be set to true.

File Types

Along with the support of local images, HoloAPI also provides support for loading URL images out-of-the-box. Usage of this feature is NOT recommended.

By changing the type value of an image configuration to URL, the path value becomes the HTTP address for the desired image.

Default Configuration

These configuration files are generated using HoloAPI v1.1.0

config.yml

# +----------------------------------------------------+
# <                      HoloAPI                       >
# <               ---------------------                >
# <                 Configuration File                 >
# <                                                    >
# <   See the HoloAPI Wiki before editing this file    >
# <      (https://github.com/DSH105/HoloAPI/wiki)      >
# +----------------------------------------------------+

command: holo
bungeecord: false
primaryChatColour: '3'
secondaryChatColour: b
autoUpdate: false
checkForUpdates: true
verticalLineSpacing: 0.25
transparency:
  withBorder: ' &r '
  noBorder: ' '
timezone:
  offset: 0
  showZoneMarker: true
multicolorFormat:
  character: '&s'
  colours: '&d,&5,&1,&9,&b,&a,&e,&6,&c,&3'
  delay: 5
chatBubbles:
  show: false
  rise: true
  followPlayer: true
  showPlayerName: true
  nameFormat: '&6&o'
  displayDurationSeconds: 8
  charactersPerLine: 30
  distanceAbovePlayerTag: 0.5
specialCharacters:
  '[x]': '2591'
  '[xx]': '2592'
  '[xxx]': '2593'
  '[xxxx]': '2588'
  '[/]': 26A1
  '[<3]': '2764'
  '[:)]': 263A
  '[:(]': '2639'
  '[s]': '2600'
  '[*]': '2605'
  '[|]': '23B9'
indicators:
  damage:
    enable: false
    enableType:
      drowning: true
      fire: true
      magic: true
      poison: true
      starvation: true
      thorns: true
      wither: true
    yOffset: 2
    format:
      default: '&c&l'
      drowning: '&b&l'
      fire: '&4&l'
      magic: '&5&l'
      poison: '&2&l'
      starvation: '&6&l'
      thorns: '&e&l'
      wither: '&8&l'
    timeVisible: 4
    showForPlayers: true
    showForMobs: true
  exp:
    enable: false
    yOffset: 2
    format: '&a&l'
    timeVisible: 4
  potion:
    enable: false
    yOffset: 2
    timeVisible: 4
    showForPlayers: true
    showForMobs: true
    format:
      goldenapple: '&e&l+ %effect%'
      godapple: '&e&l+ %effect% II'
      speed: '&e&l %effect% %amp%'
      slow: '&e&l %effect% %amp%'
      fast_digging: '&e&l %effect% %amp%'
      slow_digging: '&e&l %effect% %amp%'
      increase_damage: '&e&l %effect% %amp%'
      heal: '&e&l %effect% %amp%'
      harm: '&e&l %effect% %amp%'
      jump: '&e&l %effect% %amp%'
      confusion: '&e&l %effect% %amp%'
      regeneration: '&e&l %effect% %amp%'
      damage_resistance: '&e&l %effect% %amp%'
      fire_resistance: '&e&l %effect% %amp%'
      water_breathing: '&e&l %effect% %amp%'
      invisibility: '&e&l %effect% %amp%'
      blindness: '&e&l %effect% %amp%'
      night_vision: '&e&l %effect% %amp%'
      hunger: '&e&l %effect% %amp%'
      weakness: '&e&l %effect% %amp%'
      poison: '&e&l %effect% %amp%'
      wither: '&e&l %effect% %amp%'
      health_boost: '&e&l %effect% %amp%'
      absorption: '&e&l %effect% %amp%'
      saturation: '&e&l %effect% %amp%'
  gainHealth:
    enable: false
    yOffset: 2
    format: '&a&l'
    timeVisible: 4
    showForPlayers: true
    showForMobs: true

language.yml

update_not_available: '&3An update is not available.'
no_permission: '&3You are not permitted to do that.'
cmd_error: '&3Error for input string: &b%cmd%&3. Use &b/holo help &3for help.'
cmd_doesnotexist: '&3Command does not exist: &b%cmd%&3. Use &b/holo help &3for help.'
cmd_help: '&3Use &b/holo help &3for help.'
help_index_too_big: '&3Page &b%index% &3does not exist.'
in_game_only: '&3Please log in to do that.'
not_conversable: '&3Command Sender cannot be conversed with. Please use an alternate
  command with more arguments.'
not_location: '&3Could not create Location. Please revise command arguments.'
string_error: '&3Error parsing &b%string%&3. Please revise command arguments.'
null_player: '&b%player% &3is not online. Please try a different Player.'
int_only: '&b%string% &3must to be an integer.'
whups: '&3Whups. Something bad happened.'
configs_reloaded: '&3Configuration files reloaded.'
plugin_information: '&3Running HoloAPI v&b%version%&3. Use &b/holo help &3for help.'
line_index_too_big: '&3Line &b%index% &3does not exist.'
hover_tip: '&e&oHover over to see a preview of the hologram. Click to insert teleport
  command.'
hover_tip_commands: '&e&oHover over to see more information about the commands. Click
  to insert it into the chat window.'
url_image_loaded: '&3Custom URL image of key &b%key% loaded.'
loading_url_image: '&3Loading custom URL image of key &b%key%&3. Create hologram when
  the image has finished loading.'
loading_url_animation: '&3Loading custom URL animation of key &b%key%&3. Create hologram
  when the animation has finished loading.'
active_displays: '&3Active Holographic Displays:'
images_not_loaded: '&3Images are not loaded yet. Try again later.'
invalid_invisibility: '&b%visibility% &3is not a registered visibility type.'
reading_txt: '&3Reading text from &b%url%&3...'
touch_actions: '&3Touch actions for hologram of ID &b%id%&3:'
no_touch_actions: '&3Hologram of ID &b%id% &3does not have any Touch Actions stored.'
touch_actions_cleared: '&3Touch Actions for Hologram of ID &b%id% &3cleared.'
command_touch_action_added: '&3Touch Action for command &b%command% &3added to hologram
  of ID &b%id%&3.'
command_touch_action_removed: '&3Touch Action for command &b%command% &3removed from
  hologram of ID &b%id%&3.'
touch_action_removed: '&3Touch Action of ID &b%touchid% &3removed from hologram of
  ID &b%id%&3.'
touch_action_not_found: '&3Touch Action of ID &b%touchid% &3not found.'
failed_image_load: '&3Failed to load custom image. Make sure that it is correctly
  configured in &bconfig.yml&3.'
image_not_found: '&3Image generator &3not found.'
hologram_not_found: '&3Hologram of ID &b%id% &3not found.'
no_active_holograms: '&3There are currently no active holographic displays.'
hologram_created: '&3Hologram of ID &b%id% &3created.'
hologram_removed_memory: '&3Hologram of ID &b%id% &3removed from memory.'
hologram_cleared_file: '&3Hologram of ID &b%id% &3cleared from file and memory.'
hologram_moved: '&3Hologram position moved.'
hologram_reload: '&3Performing manual reload of all holograms and images...'
hologram_teleport_to: '&3You have been teleported to the hologram of ID &b%id%&3.'
hologram_update_line: '&3Line &b%index% &3has been updated to &r%input%&3.'
hologram_refresh: '&3Hologram of ID &b%id% &3refreshed.'
hologram_copied: '&3Hologram of ID &b%id% &3copied.'
hologram_animated_copied: '&3Animated Hologram of ID &b%id% &3copied.'
hologram_nearby: '&3Holograms within a radius of &b%radius%&3:'
hologram_added_line: '&3Line added to hologram of ID &b%id%&3.'
hologram_add_line_animated: '&3Lines cannot be added to Animated Holograms.'
hologram_visibility_set: '&3Visibility of Hologram of ID &b%id% &3set to &b%visibility%&3.'
hologram_visibility_unregistered: '&3Hologram of ID &b%id% &3has an unknown or unregistered
  visibility.'
hologram_visibility: '&3Visibility of Hologram of ID &b%id% &3is registered as &b%visibility%&3.'
hologram_already_see: '&b%player% &3can already see Hologram &b%id%&3.'
hologram_already_not_see: '&3Hologram &b%id% &3is already hidden for &b%player%&3.'
hologram_show: '&b%player% &3can now see Hologram &b%id%&3.'
hologram_hide: '&3Hologram &b%id% &3hidden for &b%player%&3.'
hologram_duplicate_id: '&3Hologram save IDs must be unique. A hologram of ID &b%id%
  &3already exists in the HoloAPI data files!'
hologram_set_id: '&3Save ID of hologram &b%oldid% &3set to &b%newid%&3.'
no_nearby_holograms: '&3There are no holograms within a radius of &b%radius%&3.'
yes_no_input_invalid: '&3Please enter either &bYes &3or &bNo&3.'
yes_no_clear_from_file: '&3Would you like to clear this hologram from the save file?
  Please enter either &bYes &3or &bNo&3.'
yes_no_command_touch_action_as_console: '&3Should this command be executed as the
  console? Please enter either &bYes &3or &bNo&3.'
prompt_update_line: '&3What do you want to set this line to?'
prompt_delay: '&3Enter the desired delay (in ticks) of the frames in the new animated
  hologram.'
prompt_input: '&3Enter the desired lines of the new hologram. Enter &bDone &3when
  finished.'
prompt_input_frames: '&3Enter the desired lines of the new animated hologram. Enter
  &bDone &3when finished or &bNext &3to start building the next frame.'
prompt_input_next: '&3Added new line: &r%input%&3. Enter next line.'
prompt_input_fail: '&3Hologram lines cannot be empty. Retry or enter &bExit &3 to
  cancel.'
prompt_input_invalid: '&3Input invalid.'
prompt_next_frame: '&3Frame %num% selected. Enter first line.'
prompt_find_location: '&3Enter the location of the new hologram in the following format:
  &bworld x y z&3.'
prompt_input_fail_int: '&3X, Y and Z coordinates must be integers.'
prompt_input_fail_world: '&b%world% &3world doesn''t exist. Please re-enter the location.'
prompt_input_fail_format: '&3Please use the following format: &bworld x y z&3.'
prompt_enter_new_line: '&3Enter the new line for the hologram.'
hologram_not_created: '&3The hologram was not created as it was empty.'
builder_input_fail_text_image: '&3Enter a valid line type (&bText &3or &bImage&3).'
builder_input_line_data: '&3What would you like this line to say?'
builder_input_image_path: '&3What image do you want to add?'
builder_input_next_with_number: '&3Added %line% line. Enter type for next line (&bText
  &3 or &bImage).'

Feel like you can make HoloAPI better? Got something awesome to contribute? We're always looking for help! Feel free to place a fork in this repository and submit a pull request!