Difference between revisions of "Map Display/API"

From BergerHealer Wiki
Jump to navigation Jump to search
(Created page with "== Introduction == Map Displays are programmed different from what you might be used to with Bukkit. They are completely callback driven, which means you don't start and stop...")
 
Line 3: Line 3:
  
 
Map Display execution follows the following flow:
 
Map Display execution follows the following flow:
1. BKCommonLib identifies an ItemStack in an ItemFrame or player inventory which declares a Map Display
+
# BKCommonLib identifies an ItemStack in an ItemFrame or player inventory which declares a Map Display
2. BKCommonLib optionally discovers neighbouring item frames to increase the resolution of the display
+
# BKCommonLib optionally discovers neighbouring item frames to increase the resolution of the display
3. BKCommonLib sees in item metadata what Map Display class should be loaded, constructs it, and starts the main update loop
+
# BKCommonLib sees in item metadata what Map Display class should be loaded, constructs it, and starts the main update loop
4. Main update loop calls MapDisplay ''onAttached()'', then regularly calls ''onTick()'' and performs other background updates
+
# Main update loop calls MapDisplay ''onAttached()'', then regularly calls ''onTick()'' and performs other background updates
5. If a player is clicking on item frames with the map, or is holding the map and controlling it, event callbacks are fired
+
# If a player is clicking on item frames with the map, or is holding the map and controlling it, event callbacks are fired
6. Once no player is nearby anymore to view it, hold it or all chunks unload containing the map (Session Mode), ''onDetached()'' is called and the display update loop is shut down
+
# Once no player is nearby anymore to view it, hold it or all chunks unload containing the map (Session Mode), ''onDetached()'' is called and the display update loop is shut down
  
 
All of the above means you should only concern yourself with a few things:
 
All of the above means you should only concern yourself with a few things:
1. Creating the initial ItemStack where you set the Map Display class and initial settings to use
+
* Creating the initial ItemStack where you set the Map Display class and initial settings to use
2. Implementing the Map Display class so that it responds to input and draws the right information, optionally using '''Widgets'''
+
* Implementing the Map Display class so that it responds to input and draws the right information, optionally using '''Widgets'''
  
 
Things you '''must completely ignore''' because BKCommonLib's API does this for you automatically:
 
Things you '''must completely ignore''' because BKCommonLib's API does this for you automatically:
1. Setting Map IDs, item frame tiling
+
* Setting Map IDs, item frame tiling
2. Starting the display after giving the ItemStack to a player or putting it in ItemFrames
+
* Starting the display after giving the ItemStack to a player or putting it in ItemFrames

Revision as of 10:31, 21 March 2023

Introduction

Map Displays are programmed different from what you might be used to with Bukkit. They are completely callback driven, which means you don't start and stop the display yourself. Instead, you override methods in the Map Display class to load and display the contents you want. If you want to show unique information per display, this information must be stored in the Map Item itself.

Map Display execution follows the following flow:

  1. BKCommonLib identifies an ItemStack in an ItemFrame or player inventory which declares a Map Display
  2. BKCommonLib optionally discovers neighbouring item frames to increase the resolution of the display
  3. BKCommonLib sees in item metadata what Map Display class should be loaded, constructs it, and starts the main update loop
  4. Main update loop calls MapDisplay onAttached(), then regularly calls onTick() and performs other background updates
  5. If a player is clicking on item frames with the map, or is holding the map and controlling it, event callbacks are fired
  6. Once no player is nearby anymore to view it, hold it or all chunks unload containing the map (Session Mode), onDetached() is called and the display update loop is shut down

All of the above means you should only concern yourself with a few things:

  • Creating the initial ItemStack where you set the Map Display class and initial settings to use
  • Implementing the Map Display class so that it responds to input and draws the right information, optionally using Widgets

Things you must completely ignore because BKCommonLib's API does this for you automatically:

  • Setting Map IDs, item frame tiling
  • Starting the display after giving the ItemStack to a player or putting it in ItemFrames