Map Display/API - Revision history

Bergerkiller: Marked this version for translation

2024-09-03T12:34:18Z

Marked this version for translation

← Older revision		Revision as of 12:34, 3 September 2024
Line 2:		Line 2:
	<translate>		<translate>

	== Introduction ==		== Introduction == <!--T:1-->

			<!--T:2-->
	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 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.

	=== Execution Flow ===		=== Execution Flow === <!--T:3-->

			<!--T:4-->
	# 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
	# 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
Line 15:		Line 17:
	# 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

			<!--T:5-->
	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:
	* 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
	* 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'''

	=== The Do-Nots ===		=== The Do-Nots === <!--T:6-->

			<!--T:7-->
	Things you '''must not attempt to do''' because BKCommonLib's API does this for you automatically:		Things you '''must not attempt to do''' because BKCommonLib's API does this for you automatically:
	* Setting Map IDs, item frame tiling. IDs are automatically calculated and updated so they don't clash with other plugins.		* Setting Map IDs, item frame tiling. IDs are automatically calculated and updated so they don't clash with other plugins.
	* Starting the display after giving the ItemStack to a player or putting it in ItemFrames. This is done automatically within a tick.		* Starting the display after giving the ItemStack to a player or putting it in ItemFrames. This is done automatically within a tick.

	=== API ===		=== API === <!--T:8-->

			<!--T:9-->
	There are javadocs [https://ci.mg-dev.eu/javadocs/BKCommonLib here], or you can browse the Map Display related code yourself [https://github.com/bergerhealer/BKCommonLib/tree/master/src/main/java/com/bergerkiller/bukkit/common/map here].		There are javadocs [https://ci.mg-dev.eu/javadocs/BKCommonLib here], or you can browse the Map Display related code yourself [https://github.com/bergerhealer/BKCommonLib/tree/master/src/main/java/com/bergerkiller/bukkit/common/map here].

	== Basic Structure ==		== Basic Structure == <!--T:10-->

			<!--T:11-->
	You start by adding a new class to your plugin that '''extends MapDisplay''' overriding a few methods:		You start by adding a new class to your plugin that '''extends MapDisplay''' overriding a few methods:

			<!--T:12-->
	<pre>		<pre>
	package com.my.plugin;		package com.my.plugin;

			<!--T:13-->
	import com.bergerkiller.bukkit.common.map.MapDisplay;		import com.bergerkiller.bukkit.common.map.MapDisplay;

			<!--T:14-->
	public class MyCustomDisplay extends MapDisplay {		public class MyCustomDisplay extends MapDisplay {
	@Override		@Override
Line 44:		Line 53:
	}		}

	@Override		<!--T:15-->
			@Override
	public void onDetached() {		public void onDetached() {
	// Stop any tasks, unregister stuff or save important information to disk		// Stop any tasks, unregister stuff or save important information to disk
	}		}

	@Override		<!--T:16-->
			@Override
	public void onTick() {		public void onTick() {
	// Perform per-tick updates here		// Perform per-tick updates here
Line 56:		Line 67:
	</pre>		</pre>

			<!--T:17-->
	Then to create an ItemStack that when given loads this display, use the following code:		Then to create an ItemStack that when given loads this display, use the following code:
	<pre>		<pre>
Line 61:		Line 73:
	ItemUtil.setDisplayName(item, "My Custom Display"); // Optional		ItemUtil.setDisplayName(item, "My Custom Display"); // Optional

			<!--T:18-->
	player.getInventory().addItem(item);		player.getInventory().addItem(item);
	seplayerder.sendMessage(ChatColor.GREEN + "Given My Custom Display map!");		seplayerder.sendMessage(ChatColor.GREEN + "Given My Custom Display map!");
	</pre>		</pre>

			<!--T:19-->
	To include additional metadata for use in the display (''properties'' field) you can also use the ''MapDisplayProperties'' class to build the item:		To include additional metadata for use in the display (''properties'' field) you can also use the ''MapDisplayProperties'' class to build the item:
	<pre>		<pre>

Bergerkiller at 12:34, 3 September 2024

2024-09-03T12:34:11Z

← Older revision		Revision as of 12:34, 3 September 2024
Line 5:		Line 5:

	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 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.


	=== Execution Flow ===		=== Execution Flow ===
Line 19:		Line 18:
	* 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
	* 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'''


	=== The Do-Nots ===		=== The Do-Nots ===
Line 26:		Line 24:
	* Setting Map IDs, item frame tiling. IDs are automatically calculated and updated so they don't clash with other plugins.		* Setting Map IDs, item frame tiling. IDs are automatically calculated and updated so they don't clash with other plugins.
	* Starting the display after giving the ItemStack to a player or putting it in ItemFrames. This is done automatically within a tick.		* Starting the display after giving the ItemStack to a player or putting it in ItemFrames. This is done automatically within a tick.


	=== API ===		=== API ===

	There are javadocs [https://ci.mg-dev.eu/javadocs/BKCommonLib here], or you can browse the Map Display related code yourself [https://github.com/bergerhealer/BKCommonLib/tree/master/src/main/java/com/bergerkiller/bukkit/common/map here].		There are javadocs [https://ci.mg-dev.eu/javadocs/BKCommonLib here], or you can browse the Map Display related code yourself [https://github.com/bergerhealer/BKCommonLib/tree/master/src/main/java/com/bergerkiller/bukkit/common/map here].


	~~== Code Block Test ==~~

	~~</translate>~~
	~~{{code\|lang=css\|font-family: 'Times New Roman', serif;}}~~
	~~<translate>~~


	~~== Using syntax highlight ==~~

	~~<syntaxhighlight lang="css">font-family: 'Times New Roman', serif; </syntaxhighlight>~~


	== Basic Structure ==		== Basic Structure ==

Bergerkiller: Prepared the page for translation

2024-09-03T12:33:34Z

Prepared the page for translation

← Older revision		Revision as of 12:33, 3 September 2024
Line 1:		Line 1:
			<languages/>
			<translate>

	== Introduction ==		== 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 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.


	=== Execution Flow ===		=== Execution Flow ===

	# 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
	# 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
Line 13:		Line 19:
	* 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
	* 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'''


	=== The Do-Nots ===		=== The Do-Nots ===

	Things you '''must not attempt to do''' because BKCommonLib's API does this for you automatically:		Things you '''must not attempt to do''' because BKCommonLib's API does this for you automatically:
	* Setting Map IDs, item frame tiling. IDs are automatically calculated and updated so they don't clash with other plugins.		* Setting Map IDs, item frame tiling. IDs are automatically calculated and updated so they don't clash with other plugins.
	* Starting the display after giving the ItemStack to a player or putting it in ItemFrames. This is done automatically within a tick.		* Starting the display after giving the ItemStack to a player or putting it in ItemFrames. This is done automatically within a tick.


	=== API ===		=== API ===

	There are javadocs [https://ci.mg-dev.eu/javadocs/BKCommonLib here], or you can browse the Map Display related code yourself [https://github.com/bergerhealer/BKCommonLib/tree/master/src/main/java/com/bergerkiller/bukkit/common/map here].		There are javadocs [https://ci.mg-dev.eu/javadocs/BKCommonLib here], or you can browse the Map Display related code yourself [https://github.com/bergerhealer/BKCommonLib/tree/master/src/main/java/com/bergerkiller/bukkit/common/map here].


	== Code Block Test ==		== Code Block Test ==

			</translate>
	{{code\|lang=css\|font-family: 'Times New Roman', serif;}}		{{code\|lang=css\|font-family: 'Times New Roman', serif;}}
			<translate>


	== Using syntax highlight ==		== Using syntax highlight ==

	<syntaxhighlight lang="css">font-family: 'Times New Roman', serif; </syntaxhighlight>		<syntaxhighlight lang="css">font-family: 'Times New Roman', serif; </syntaxhighlight>


	== Basic Structure ==		== Basic Structure ==

	You start by adding a new class to your plugin that '''extends MapDisplay''' overriding a few methods:		You start by adding a new class to your plugin that '''extends MapDisplay''' overriding a few methods:

Line 71:		Line 89:
	// Rest is the same		// Rest is the same
	</pre>		</pre>
			</translate>

Bergerkiller at 13:17, 16 September 2023

2023-09-16T13:17:39Z

← Older revision		Revision as of 13:17, 16 September 2023
Line 65:		Line 65:
	To include additional metadata for use in the display (''properties'' field) you can also use the ''MapDisplayProperties'' class to build the item:		To include additional metadata for use in the display (''properties'' field) you can also use the ''MapDisplayProperties'' class to build the item:
	<pre>		<pre>
	~~ItemStack item~~ = MapDisplayProperties.createNew(MyCustomDisplay.class)		MapDisplayProperties prop = MapDisplayProperties.createNew(MyCustomDisplay.class);
	.set("creator", player.getName())		prop.set("creator", player.getName());
	.set("background", "https://url/to/some/image.png")		prop.set("background", "https://url/to/some/image.png");
	.getMapItem();		ItemStack item = prop.getMapItem();
	// Rest is the same		// Rest is the same
	~~</pre>~~
	</pre>		</pre>

Bergerkiller at 13:14, 16 September 2023

2023-09-16T13:14:56Z

@@ Line 52: / Line 52: @@
+     }
+}
 </pre>

Bergerkiller: /* Code Block Test */

2023-03-21T15:10:28Z

Code Block Test

← Older revision		Revision as of 15:10, 21 March 2023
Line 24:		Line 24:
	== Code Block Test ==		== Code Block Test ==
	{{code\|lang=css\|font-family: 'Times New Roman', serif;}}		{{code\|lang=css\|font-family: 'Times New Roman', serif;}}

			== Using syntax highlight ==
			<syntaxhighlight lang="css">font-family: 'Times New Roman', serif; </syntaxhighlight>

	== Basic Structure ==		== Basic Structure ==

Bergerkiller: /* Basic Structure */

2023-03-21T15:09:11Z

Basic Structure

← Older revision		Revision as of 15:09, 21 March 2023
Line 21:		Line 21:
	=== API ===		=== API ===
	There are javadocs [https://ci.mg-dev.eu/javadocs/BKCommonLib here], or you can browse the Map Display related code yourself [https://github.com/bergerhealer/BKCommonLib/tree/master/src/main/java/com/bergerkiller/bukkit/common/map here].		There are javadocs [https://ci.mg-dev.eu/javadocs/BKCommonLib here], or you can browse the Map Display related code yourself [https://github.com/bergerhealer/BKCommonLib/tree/master/src/main/java/com/bergerkiller/bukkit/common/map here].

			== Code Block Test ==
			{{code\|lang=css\|font-family: 'Times New Roman', serif;}}

	== Basic Structure ==		== Basic Structure ==

Bergerkiller at 12:54, 21 March 2023

2023-03-21T12:54:23Z

← Older revision		Revision as of 12:54, 21 March 2023
Line 25:		Line 25:
	You start by adding a new class to your plugin that '''extends MapDisplay''' overriding a few methods:		You start by adding a new class to your plugin that '''extends MapDisplay''' overriding a few methods:

	<~~syntaxhighlight lang="java"~~>		<pre>
	package com.my.plugin;		package com.my.plugin;

Line 46:		Line 46:
	}		}
	}		}
	</~~syntaxhighlight~~>		</pre>

Bergerkiller at 12:54, 21 March 2023

2023-03-21T12:54:00Z

← Older revision		Revision as of 12:54, 21 March 2023
Line 25:		Line 25:
	You start by adding a new class to your plugin that '''extends MapDisplay''' overriding a few methods:		You start by adding a new class to your plugin that '''extends MapDisplay''' overriding a few methods:

	<syntaxhighlight lang="java" ~~line~~>		<syntaxhighlight lang="java">
	package com.my.plugin;		package com.my.plugin;

Bergerkiller at 12:53, 21 March 2023

2023-03-21T12:53:07Z

← Older revision		Revision as of 12:53, 21 March 2023
Line 25:		Line 25:
	You start by adding a new class to your plugin that '''extends MapDisplay''' overriding a few methods:		You start by adding a new class to your plugin that '''extends MapDisplay''' overriding a few methods:

	<~~pre~~>		<syntaxhighlight lang="java" line>
	package com.my.plugin;		package com.my.plugin;

Line 46:		Line 46:
	}		}
	}		}
	</~~pre~~>		</syntaxhighlight>