JCM:Scripting/PIDS - Revision history

AmberFrost: More organization

2025-02-23T15:37:15Z

More organization

← Older revision		Revision as of 23:37, 23 February 2025
Line 4:		Line 4:

	=== Draw/Rendering ===		=== Draw/Rendering ===
	JCM PIDS Scripting allows you to draw either a Text/Texture onto the Minecraft World.		JCM PIDS Scripting allows you to draw either a '''Text''' or '''Texture''' onto the Minecraft World.

	'''~~Note that the text/textures~~ are just regular polygons rendered onto the Minecraft World rather than being a 2D plane with a texture. Therefore it is possible for elements to overflow beyond the PIDS screen, and it is the developer responsibility to ensure such events should not happen.'''		'''When drawn, they are just regular polygons rendered onto the Minecraft World rather than being a 2D plane with a texture. Therefore it is possible for elements to overflow beyond the PIDS screen, and it is the developer responsibility to ensure such events should not happen.'''

	If you absolutely require sophisticated image processing/clipping, you may [[JCM:Scripting:Documentation:PIDS#Using AWT Graphics/Dynamic Textures\|follow this section]] to draw a ~~single~~ texture onto a 2D Plane. However it may result in slightly slower performance/higher memory usage.		If you absolutely require sophisticated image processing/clipping, you may [[JCM:Scripting:Documentation:PIDS#Using AWT Graphics/Dynamic Textures\|follow this section]] to draw and manipulate a texture and draw it onto a 2D Plane. However it may result in slightly slower performance/higher memory usage.

	==== Draw Layer/Order ====		==== Draw Layer/Order ====
	~~JCM's~~ Draw ~~Order~~/z-index is depicted by the order the image is drawn in. Whichever elements gets drawn later, whichever element goes in-front. See the image below: (z-differences is exaggerated for demonstration purposes)		The Draw order/z-index is depicted by the order the image is drawn in. Whichever elements gets drawn later, whichever element goes in-front. See the image below: (z-differences is exaggerated for demonstration purposes)

	[[File:JCM-PIDS Scripting Draw Order.png\|369x369px]]		[[File:JCM-PIDS Scripting Draw Order.png\|369x369px]]

	The number depicts the order in which the element is drawn in. 1 gets drawn first, then 2, 3, 4, 5 and finally 6.		The number depicts the order in which the element is drawn in. 1 gets drawn first, then 2, 3, 4, 5 and finally 6.

			As such, element 6 is the frontmost element, which can cover element 1-5 if overlapped.

	=== Global Environment ===		=== Global Environment ===
Line 26:		Line 28:
	== Implementation ==		== Implementation ==

	===~~Adding~~ a Scripted PIDS Preset===		===Registering a Scripted PIDS Preset===
	A preset is automatically considered as a Scripted PIDS Preset by specifying either <code>scriptFiles</code> '''or''' <code>scriptTexts</code> property in <code>joban_custom_resources.json</code>:		A preset is automatically considered as a Scripted PIDS Preset by specifying either <code>scriptFiles</code> '''or''' <code>scriptTexts</code> property in <code>joban_custom_resources.json</code>:

Line 43:		Line 45:
	<code>scriptTexts</code> allows you to directly write JS inside, but should only be used for simple variable declaration.		<code>scriptTexts</code> allows you to directly write JS inside, but should only be used for simple variable declaration.

	At the moment, mixing Scripted PIDS Preset and JSON PIDS Preset is not possible.		''Note: At the moment, mixing Scripted PIDS Preset and JSON PIDS Preset is not possible.''

	~~=== Check JCM Version ===~~
	~~You can obtain JCM version by using <code>Resources.getAddonVersion("jcm")</code>.~~

	~~This would return a string formatted like: <code>2.0.0-beta.5</code>~~

	=== Called Functions ===		=== Called Functions ===
Line 86:		Line 83:

	=== API Reference ===		=== API Reference ===

			==== Check JCM Version ====
			You can obtain JCM version by using <code>Resources.getAddonVersion("jcm")</code>.

			This would return a string formatted like: <code>2.0.0-beta.5</code>

	==== Rendering Related ====		==== Rendering Related ====

AmberFrost: LX86 moved page JCM:Scripting:Documentation:PIDS to JCM:Scripting/PIDS

2025-02-23T15:27:33Z

LX86 moved page JCM:Scripting:Documentation:PIDS to JCM:Scripting/PIDS

← Older revision	Revision as of 23:27, 23 February 2025
(No difference)

AmberFrost: Fix headings & introduction

2025-02-23T13:26:55Z

Fix headings & introduction

← Older revision		Revision as of 21:26, 23 February 2025
Line 1:		Line 1:
			PIDS Scripting allows you to use [[JCM:Scripting:Documentation\|JavaScript]] to control PIDS Preset contents.

	== Concept ==		== Concept ==

	~~=== Global Environment ===~~
	~~A script is evaluated & executed when a PIDS Preset is loaded during the resource-pack loading phase.~~

	~~Therefore, the same type of PIDS Preset will use the same working environment (global variables and etc).~~

	Code written in top-level space outside of functions will run when a resource package is loaded, and can be used to load resources such as models and textures. It is recommended to store resources (such as models, fonts and textures) in global variables, which do not need to be different for each PIDS block, to avoid excessive memory usage caused by loading a copy of the same content for each PIDS.

	=== Draw/Rendering ===		=== Draw/Rendering ===
Line 21:		Line 16:

	The number depicts the order in which the element is drawn in. 1 gets drawn first, then 2, 3, 4, 5 and finally 6.		The number depicts the order in which the element is drawn in. 1 gets drawn first, then 2, 3, 4, 5 and finally 6.

			=== Global Environment ===
			A script is evaluated & executed when a PIDS Preset is loaded during the resource-pack loading phase.

			Therefore, the same type of PIDS Preset will use the same working environment (global variables and etc).

			Code written in top-level space outside of functions will run when a resource package is loaded, and can be used to load resources such as models and textures. It is recommended to store resources (such as models, fonts and textures) in global variables, which do not need to be different for each PIDS block, to avoid excessive memory usage caused by loading a copy of the same content for each PIDS.

	== Implementation ==		== Implementation ==
Line 83:		Line 85:
	The following lists all the rendering control operations that can be performed and all the information that can be obtained about PIDS.		The following lists all the rendering control operations that can be performed and all the information that can be obtained about PIDS.

	== API Reference ==		=== API Reference ===

	=== Rendering Related ===		==== Rendering Related ====

	==== Text (aka TextWrapper) ====		===== Text (aka TextWrapper) =====
	{\| class="wikitable"		{\| class="wikitable"
	!Functions And Objects		!Functions And Objects
Line 159:		Line 161:
	\|}		\|}

	=== Texture (aka TextureWrapper) ===		===== Texture (aka TextureWrapper) =====
	{\| class="wikitable"		{\| class="wikitable"
	!Functions And Objects		!Functions And Objects
Line 187:		Line 189:
	\|}		\|}

	=== PIDS Object Related ===		==== PIDS Object Related ====

	==== PIDSWrapper ====		===== PIDSWrapper =====
	{\| class="wikitable"		{\| class="wikitable"
	!Functions And Objects		!Functions And Objects
Line 231:		Line 233:
	\|}		\|}

	==== ArrivalsWrapper ====		===== ArrivalsWrapper =====
	{\| class="wikitable"		{\| class="wikitable"
	!Functions And Objects		!Functions And Objects
Line 247:		Line 249:
	\|}		\|}

	==== ArrivalWrapper ====		===== ArrivalWrapper =====
	{\| class="wikitable"		{\| class="wikitable"
	!Functions And Objects		!Functions And Objects
Line 311:		Line 313:
	\|}		\|}

	=== Transport Simulation Core Related ===		==== Transport Simulation Core Related ====

	==== Platform ====		===== Platform =====
	{\| class="wikitable"		{\| class="wikitable"
	!Functions And Objects		!Functions And Objects
Line 334:		Line 336:
	\|}		\|}

	==== Route ====		===== Route =====
	{\| class="wikitable"		{\| class="wikitable"
	!Functions And Objects		!Functions And Objects
Line 369:		Line 371:
	\|}		\|}

	== Using AWT Graphics/Dynamic Textures ==		=== Using AWT Graphics/Dynamic Textures ===

	While not a regular tested use case for PIDS, you can create a [[JCM:Scripting:Documentation:Dynamic Textures\|Dynamic Textures]] and draw it onto a PIDS:<pre>		While not a regular tested use case for PIDS, you can create a [[JCM:Scripting:Documentation:Dynamic Textures\|Dynamic Textures]] and draw it onto a PIDS:<pre>
	importPackage(java.awt);		importPackage(java.awt);

AmberFrost: Add z-order demonstration image

2025-02-23T13:15:14Z

Add z-order demonstration image

← Older revision		Revision as of 21:15, 23 February 2025
Line 16:		Line 16:

	==== Draw Layer/Order ====		==== Draw Layer/Order ====
	JCM's Draw Order/z-index is depicted by the order the image is drawn in. Whichever elements gets drawn later, whichever element goes in-front.		JCM's Draw Order/z-index is depicted by the order the image is drawn in. Whichever elements gets drawn later, whichever element goes in-front. See the image below: (z-differences is exaggerated for demonstration purposes)

			[[File:JCM-PIDS Scripting Draw Order.png\|369x369px]]

			The number depicts the order in which the element is drawn in. 1 gets drawn first, then 2, 3, 4, 5 and finally 6.

	== Implementation ==		== Implementation ==

AmberFrost: Test Edit JCM

2025-02-23T13:00:19Z

Test Edit JCM

← Older revision		Revision as of 21:00, 23 February 2025
Line 6:		Line 6:
	Therefore, the same type of PIDS Preset will use the same working environment (global variables and etc).		Therefore, the same type of PIDS Preset will use the same working environment (global variables and etc).

	Code written in top-level space outside of functions will run when a resource package is loaded, and can be used to load resources such as models and textures. It is recommended to store resources (such as models, fonts and textures) in global variables, which do not need to be different for each PIDS block, to avoid excessive memory usage caused by loading a copy of the same content for each PIDS.		Code written in top-level space outside of functions will run when a resource package is loaded, and can be used to load resources such as models and textures. It is recommended to store resources (such as models, fonts and textures) in global variables, which do not need to be different for each PIDS block, to avoid excessive memory usage caused by loading a copy of the same content for each PIDS.

	=== Draw/Rendering ===		=== Draw/Rendering ===

AmberFrost: Test Edit

2025-02-23T12:57:53Z

Test Edit

← Older revision		Revision as of 20:57, 23 February 2025
Line 6:		Line 6:
	Therefore, the same type of PIDS Preset will use the same working environment (global variables and etc).		Therefore, the same type of PIDS Preset will use the same working environment (global variables and etc).

	Code written in top-level space outside of functions will run when a resource package is loaded, and can be used to load resources such as models and textures. It is recommended to store resources (such as models, fonts and textures) in global variables, which do not need to be different for each PIDS block, to avoid excessive memory usage caused by loading a copy of the same content for each PIDS.		Code written in top-level space outside of functions will run when a resource package is loaded, and can be used to load resources such as models and textures. It is recommended to store resources (such as models, fonts and textures) in global variables, which do not need to be different for each PIDS block, to avoid excessive memory usage caused by loading a copy of the same content for each PIDS.

	=== Draw/Rendering ===		=== Draw/Rendering ===

AmberFrost at 12:44, 23 February 2025

2025-02-23T12:44:32Z

← Older revision		Revision as of 20:44, 23 February 2025
Line 1:		Line 1:
			== Concept ==

			=== Global Environment ===
			A script is evaluated & executed when a PIDS Preset is loaded during the resource-pack loading phase.

			Therefore, the same type of PIDS Preset will use the same working environment (global variables and etc).

			Code written in top-level space outside of functions will run when a resource package is loaded, and can be used to load resources such as models and textures. It is recommended to store resources (such as models, fonts and textures) in global variables, which do not need to be different for each PIDS block, to avoid excessive memory usage caused by loading a copy of the same content for each PIDS.

			=== Draw/Rendering ===
			JCM PIDS Scripting allows you to draw either a Text/Texture onto the Minecraft World.

			'''Note that the text/textures are just regular polygons rendered onto the Minecraft World rather than being a 2D plane with a texture. Therefore it is possible for elements to overflow beyond the PIDS screen, and it is the developer responsibility to ensure such events should not happen.'''

			If you absolutely require sophisticated image processing/clipping, you may [[JCM:Scripting:Documentation:PIDS#Using AWT Graphics/Dynamic Textures\|follow this section]] to draw a single texture onto a 2D Plane. However it may result in slightly slower performance/higher memory usage.

			==== Draw Layer/Order ====
			JCM's Draw Order/z-index is depicted by the order the image is drawn in. Whichever elements gets drawn later, whichever element goes in-front.

			== Implementation ==

	===Adding a Scripted PIDS Preset===		===Adding a Scripted PIDS Preset===
	A preset is automatically considered as a Scripted PIDS Preset by specifying either <code>scriptFiles</code> '''or''' <code>scriptTexts</code> property in <code>joban_custom_resources.json</code>:		A preset is automatically considered as a Scripted PIDS Preset by specifying either <code>scriptFiles</code> '''or''' <code>scriptTexts</code> property in <code>joban_custom_resources.json</code>:
Line 18:		Line 39:
	At the moment, mixing Scripted PIDS Preset and JSON PIDS Preset is not possible.		At the moment, mixing Scripted PIDS Preset and JSON PIDS Preset is not possible.

	=== ~~Global Environment ===~~		=== Check JCM Version ===
	~~A script is evaluated & executed when a PIDS Preset is loaded during the resource-pack loading phase.~~

	~~Therefore, the same type of PIDS Preset will use the same working environment (global variables and etc).~~

	Code written in top-level space outside of functions will run when a resource package is loaded, and can be used to load resources such as models and textures. It is recommended to store resources (such as models, fonts and textures) in global variables, which do not need to be different for each PIDS block, to avoid excessive memory usage caused by loading a copy of the same content for each PIDS.

	~~=== Draw Procedure ===~~
	~~To conserve in-game performance, JCM runs the script in a separate thread from the PIDS rendering logic.~~

	When you command JCM to draw text/texture with <code>Text.draw</code> or <code>Texture.draw</code>, it doesn't actually initiates the rendering, but merely adds the object to a list of things that should be rendered.

	~~When the next frame comes around,~~ JCM will update the list of things that should be drawn, and then it draws the element. Therefore the scripting performance itself should have minimal impact even by drawing a lot of elements. (In-game is another story)

	Unless you use [[JCM:Scripting:Documentation:PIDS#Using AWT Graphics/Dynamic Textures\|AWT Graphics to render the PIDS]], all text and texture drawn are '''regular polygon drawn to the Minecraft world'''. As such it is possible for elements to overflow beyond the PIDS screen, and it is the developer responsibility to ensure it would not happen.

	== ~~Versioning~~ ==
	You can obtain JCM version by using <code>Resources.getAddonVersion("jcm")</code>.		You can obtain JCM version by using <code>Resources.getAddonVersion("jcm")</code>.

	This would return a string formatted like: <code>2.0.0-beta.5</code>		This would return a string formatted like: <code>2.0.0-beta.5</code>

	== Called Functions ==		=== Called Functions ===
	Your script should include the following functions that JCM will call as needed:		Your script should include the following functions that JCM will call as needed:
	function create(ctx, state, pids) { ... }		function create(ctx, state, pids) { ... }
Line 74:		Line 79:
	The following lists all the rendering control operations that can be performed and all the information that can be obtained about PIDS.		The following lists all the rendering control operations that can be performed and all the information that can be obtained about PIDS.

	== ~~Type Definition~~ ==		== API Reference ==

	=== Rendering Related ===		=== Rendering Related ===

	==== Text (TextWrapper) ====		==== Text (aka TextWrapper) ====
	{\| class="wikitable"		{\| class="wikitable"
	!Functions And Objects		!Functions And Objects
Line 150:		Line 155:
	\|}		\|}

	=== Texture (TextureWrapper) ===		=== Texture (aka TextureWrapper) ===
	{\| class="wikitable"		{\| class="wikitable"
	!Functions And Objects		!Functions And Objects

AmberFrost: Document supported texture format

2025-02-13T15:15:44Z

Document supported texture format

← Older revision		Revision as of 23:15, 13 February 2025
Line 166:		Line 166:
	\|<code>Texture.texture(id: string): TextureWrapper</code> / <code>Texture.texture(id: Identifier): TextureWrapper</code>		\|<code>Texture.texture(id: string): TextureWrapper</code> / <code>Texture.texture(id: Identifier): TextureWrapper</code>
	\|Set the texture ID to draw.		\|Set the texture ID to draw.
			Note that the texture ID should point to a PNG file or an .mcmeta file.
	\|-		\|-
	\|<code>Texture.color(color: number): TextureWrapper</code>		\|<code>Texture.color(color: number): TextureWrapper</code>

AmberFrost: Better documentation for Text.font() function.

2025-02-07T08:28:01Z

Better documentation for Text.font() function.

← Older revision		Revision as of 16:28, 7 February 2025
Line 91:		Line 91:
	\|<code>Text.size(w: number, h: number): TextWrapper</code>		\|<code>Text.size(w: number, h: number): TextWrapper</code>
	\|Set the width and height of the element		\|Set the width and height of the element
	(Used in conjunction with <code>Text.stretchXY()</code> and <code>Text.scaleXY()</code>		(Used in conjunction with <code>Text.stretchXY()</code> and <code>Text.scaleXY()</code>)
	\|-		\|-
	\|<code>Text.text(str: string): TextWrapper</code>		\|<code>Text.text(str: string): TextWrapper</code>
Line 97:		Line 97:
	\|-		\|-
	\|<code>Text.scale(i: double): TextWrapper</code>		\|<code>Text.scale(i: double): TextWrapper</code>
	\|Set the text's scale to i		\|Set the text's scale to i. Defaults to <code>1</code>
	\|-		\|-
	\|<code>Text.leftAlign(): TextWrapper</code>		\|<code>Text.leftAlign(): TextWrapper</code>
Line 138:		Line 138:
	\|-		\|-
	\|<code>Text.font(id: string): TextWrapper</code> / <code>Text.font(id: Identifier): TextWrapper</code>		\|<code>Text.font(id: string): TextWrapper</code> / <code>Text.font(id: Identifier): TextWrapper</code>
	\|Set the font ~~used~~		\|Set the font by it's ID. Defaults to <code>mtr:mtr</code>
			The font should be loaded in Minecraft via the font json format.

			This does not have any effect if '''Use Custom MTR Font''' is disabled in MTR Mod's Config.
	\|-		\|-
	\|<code>Text.color(color: number): TextWrapper</code>		\|<code>Text.color(color: number): TextWrapper</code>
Line 162:		Line 165:
	\|-		\|-
	\|<code>Texture.texture(id: string): TextureWrapper</code> / <code>Texture.texture(id: Identifier): TextureWrapper</code>		\|<code>Texture.texture(id: string): TextureWrapper</code> / <code>Texture.texture(id: Identifier): TextureWrapper</code>
	\|Set the texture to draw ~~to id~~.		\|Set the texture ID to draw.
	\|-		\|-
	\|<code>Texture.color(color: number): TextureWrapper</code>		\|<code>Texture.color(color: number): TextureWrapper</code>

AmberFrost: semicolon;

2024-11-11T06:00:45Z

semicolon;

← Older revision		Revision as of 14:00, 11 November 2024
Line 8:		Line 8:
	"id": "pids_tut",		"id": "pids_tut",
	"name": "JS Tutorial Preset",		"name": "JS Tutorial Preset",
	"scriptTexts": ["print('Goodbye World')"],		"scriptTexts": ["print('Goodbye World');"],
	"scriptFiles": ["jsblock:scripts/pids_tut.js"]		"scriptFiles": ["jsblock:scripts/pids_tut.js"]
	}		}