Pings (Tutorial) - Revision history

TheKillerBunny: TheKillerBunny moved page Tutorials/Pings to Pings (Tutorial)

2024-09-27T14:04:40Z

TheKillerBunny moved page Tutorials/Pings to Pings (Tutorial)

← Older revision		Revision as of 14:04, 27 September 2024
(No difference)

TheKillerBunny at 14:04, 27 September 2024

2024-09-27T14:04:04Z

← Older revision		Revision as of 14:04, 27 September 2024
Line 171:		Line 171:
	end		end
	</syntaxhighlight>		</syntaxhighlight>

			[[Category:Tutorials]]

PoolloverNathan: format link

2024-09-27T04:36:09Z

format link

← Older revision		Revision as of 04:36, 27 September 2024
Line 14:		Line 14:

	; HostAPI		; HostAPI
	: The HostAPI exclusivly contains variables that only you, the owner of the avatar and the owner of the machine running Minecraft, has access to. All functions contained within are vanilla variables that are not synced with the Minecraft Server. They are wrapped in a nice, explicit package stating that they are never synced. This is unlike the PlayerAPI, which you can assume is always synced (to some extent — some methods such as [[PlayerAPI/isGrounded]] feel the need to be ''special'')		: The HostAPI exclusivly contains variables that only you, the owner of the avatar and the owner of the machine running Minecraft, has access to. All functions contained within are vanilla variables that are not synced with the Minecraft Server. They are wrapped in a nice, explicit package stating that they are never synced. This is unlike the PlayerAPI, which you can assume is always synced (to some extent — some methods such as <code>[[PlayerAPI/isGrounded\|isGrounded]]</code> feel the need to be ''special'')

PoolloverNathan: minor reformatting; mention leaving buffer room

2024-09-27T04:34:58Z

minor reformatting; mention leaving buffer room

← Older revision		Revision as of 04:34, 27 September 2024
Line 7:		Line 7:
	What does this mean for you, the user? It means that certain functionality that only your client has access to will not be synced with other players.<br/> Some examples:		What does this mean for you, the user? It means that certain functionality that only your client has access to will not be synced with other players.<br/> Some examples:

	* Keybinds~~<br/>~~		; Keybinds
	** If the Minecraft Server tracked every single keystroke, it would be a major security issue. The exact keystrokes are never sent, only the result of those keystrokes.		: If the Minecraft Server tracked every single keystroke, it would be a major security issue. The exact keystrokes are never sent, only the result of those keystrokes.

	* Action Wheel		; Action Wheel
	** The Action Wheel is a feature added by Figura. Remember how I said that Figura never comunicates with the Minecraft Server? It should be obvious why the Action Wheel isnt synced.		: The Action Wheel is a feature added by Figura. Remember how I said that Figura never comunicates with the Minecraft Server? It should be obvious why the Action Wheel isnt synced.

	* HostAPI		; HostAPI
	** The HostAPI exclusivly contains variables that only you, the owner of the avatar and the owner of the machine running Minecraft, has access to. All functions contained within are vanilla variables that are not synced with the Minecraft Server. They are wrapped in a nice, explicit package stating that they are never synced. This is unlike the PlayerAPI, which you can assume is always synced (to some extent ~~(I’m looking at you <code>~~isGrounded~~</code>)~~)		: The HostAPI exclusivly contains variables that only you, the owner of the avatar and the owner of the machine running Minecraft, has access to. All functions contained within are vanilla variables that are not synced with the Minecraft Server. They are wrapped in a nice, explicit package stating that they are never synced. This is unlike the PlayerAPI, which you can assume is always synced (to some extent — some methods such as [[PlayerAPI/isGrounded]] feel the need to be ''special'')


	So how can we sync information with other players if we cannot do it through the Minecraft Server? The answer is Pings.~~<br/>~~		So how can we sync information with other players if we cannot do it through the Minecraft Server? The answer is Pings.

	== General Pings ==		== General Pings ==
	Pings utilize Figura’s Backend to sync information with other clients.~~<br/>~~ Pings are functions that when called, triggers all other clients to call the same function for their instance of your avatar.		Pings utilize Figura’s Backend to sync information with other clients. Pings are functions that when called, triggers all other clients to call the same function for their instance of your avatar.

	=== Ping Rate Limiting ===		=== Ping Rate Limiting ===
	The backend restricts you on how much data you can send over a period of time.~~<br/>~~ The developer given limits are:		The backend restricts you on how much data you can send over a period of time. The developer given limits are:

	* 1024 bytes per second		* 1024 bytes per second
	* 32 pings per second		* 32 pings per second

			If either of these are reached, the backend will ignore any comunication from you for some amount of time.

	~~If either of these are reached~~, ~~the backend will ignore any comunication from you for~~ some ~~amount~~ of ~~time~~.		{{note\|In some cases, fluctuations in network speed may cause some pings to become clumped close enough to reach this limit if they are slightly below. It's wise to leave a bit of buffer room just in case.}}

	=== Pingable Values ===		=== Pingable Values ===
Line 107:		Line 108:
	Calling a ping function when the script is first loaded is a horrible idea. The ping will only ever execute for other clients when you, the host, load the avatar. Not only that, it may never be executed on other clients, as they might not have your avatar loaded by the time you broadcast the ping.		Calling a ping function when the script is first loaded is a horrible idea. The ping will only ever execute for other clients when you, the host, load the avatar. Not only that, it may never be executed on other clients, as they might not have your avatar loaded by the time you broadcast the ping.

	How do we get around this? Well, when you assign a function to an index in the <code>pings</code> table, the Lua Function gets replaced with a Java Function. This happens because of metatables, specifically the <code>__newindex</code> metamethod. Functions cannot be modified, so if we store the function before ~~assing~~ it to the <code>pings</code> table, we can use it like a regular function, and use the same code as a ping function.		How do we get around this? Well, when you assign a function to an index in the <code>pings</code> table, the Lua Function gets replaced with a Java Function. This happens because of metatables, specifically the <code>__newindex</code> metamethod. Functions cannot be modified, so if we store the function before adding it to the <code>pings</code> table, we can use it like a regular function, and use the same code as a ping function.

	<syntaxhighlight lang="lua">local function doThing(state)		<syntaxhighlight lang="lua">local function doThing(state)

PenguinEncounter: reword

2024-09-27T00:46:06Z

reword

← Older revision		Revision as of 00:46, 27 September 2024
Line 40:		Line 40:

	* {{Type\|integer}} - 1-4 Bytes		* {{Type\|integer}} - 1-4 Bytes
	** {{Type\|integers}} only take up as many bytes as ~~it needs~~.		** {{Type\|integers}} only take up as many bytes as they need.
	** {{Type\|integers}} are signed. For example, to only use a single byte the value must be between -128 and 127.		** {{Type\|integers}} are signed. For example, to only use a single byte the value must be between -128 and 127.

Line 47:		Line 47:

	* {{Type\|string}} - 2+n Bytes		* {{Type\|string}} - 2+n Bytes
	** {{Type\|strings}} will always use 2 bytes to store the length.		** {{Type\|strings}} will always use 2 bytes to store the length of the string.
	** ~~Ascii~~ characters will be a single byte each.		** ASCII characters will be a single byte each.
	** UTF-8 characters will be multiple bytes per character.		** UTF-8 characters will be multiple bytes per character.
	** The absolute maximum size of string you can send is <code>65535</code> characters. If a larger string is sent, it will be truncated.		** The absolute maximum size of string you can send is <code>65535</code> characters. If a larger string is sent, it will be truncated.

	* {{Type\|table}} - ~~Too Many~~ Bytes		* {{Type\|table}} - (all keys) + (all values) Bytes
	** Every key and value is send as data, resulting in high byte costs.		** Every key and value is send as data, resulting in high byte costs.
	** It is recommended to never send a table over pings.		** It is recommended to never send a table over pings.

	* {{Type\|Vector}} - 1+8*N Bytes		* {{Type\|Vector}} - 1+8*N Bytes
	** {{Type\|Vectors}} ~~have~~ a single byte ~~that stores~~ the size of the Vector.		** {{Type\|Vectors}} use a single byte to store the size of the Vector.
	** Vectors are always assumed to store {{Type\|doubles}}. If you have a Vector of integers, I recommend sending them as 3 seperate arguments instead.		** Vectors are always assumed to store {{Type\|doubles}}. If you have a Vector of integers, I recommend sending them as 3 seperate arguments instead.

PenguinEncounter: Undo revision 187 by PenguinEncounter (talk): actually, lets not

2024-09-27T00:42:31Z

Undo revision 187 by PenguinEncounter (talk): actually, lets not

← Older revision		Revision as of 00:42, 27 September 2024
Line 1:		Line 1:
	With normal mods, there is comunication between the Minecraft Server and it’s clients which allows everything to stay in sync. <br/> Figura is completely client-side. It will never comunicate with the Minecraft Server you are connected to. Figura does not have a server-side component, meaning nothing will happen if you put the mod on a server.<br/>		With normal mods, there is comunication between the Minecraft Server and it’s clients which allows everything to stay in sync. <br/> Figura is completely client-side. It will never comunicate with the Minecraft Server you are connected to. Figura does not have a server-side component, meaning nothing will happen if you put the mod on a server.<br/>


	----		----


	What does this mean for you, the user? It means that certain functionality that only your client has access to will not be synced with other players.<br/> Some examples:		What does this mean for you, the user? It means that certain functionality that only your client has access to will not be synced with other players.<br/> Some examples:

PenguinEncounter: let's get rid of some of those line breaks

2024-09-27T00:42:20Z

let's get rid of some of those line breaks

← Older revision		Revision as of 00:42, 27 September 2024
Line 1:		Line 1:
	With normal mods, there is comunication between the Minecraft Server and it’s clients which allows everything to stay in sync. <br/> Figura is completely client-side. It will never comunicate with the Minecraft Server you are connected to. Figura does not have a server-side component, meaning nothing will happen if you put the mod on a server.<br/>		With normal mods, there is comunication between the Minecraft Server and it’s clients which allows everything to stay in sync. <br/> Figura is completely client-side. It will never comunicate with the Minecraft Server you are connected to. Figura does not have a server-side component, meaning nothing will happen if you put the mod on a server.<br/>


	----		----


	What does this mean for you, the user? It means that certain functionality that only your client has access to will not be synced with other players.<br/> Some examples:		What does this mean for you, the user? It means that certain functionality that only your client has access to will not be synced with other players.<br/> Some examples:

TheKillerBunny at 00:30, 27 September 2024

2024-09-27T00:30:47Z

Show changes

TheKillerBunny at 00:27, 27 September 2024

2024-09-27T00:27:04Z

Show changes

Manuel: Automated upload of converted .txt file.

2024-09-26T20:45:13Z

Automated upload of converted .txt file.

New page

Information on pings

With normal mods, there is comunication between the Minecraft Server and it’s clients which allows everything to stay in sync. Figura is completely client-side. It will never comunicate with the Minecraft Server you are connected to. Figura does not have a server-side component, meaning nothing will happen if you put the mod on a server. 

What does this mean for you, the user? It means that certain functionality that only your client has access to will not be synced with other players. Some examples:

* Keybinds 

** If the Minecraft Server tracked every single keystroke, it would be a major security issue. The exact keystrokes are never sent, only the result of those keystrokes.

* Action Wheel 

** The Action Wheel is a feature added by Figura. Remember how I said that Figura never comunicates with the Minecraft Server? It should be obvious why the Action Wheel isnt synced.

* HostAPI 

** The HostAPI exclusivly contains variables that only you, the owner of the avatar and the owner of the machine running Minecraft, has access to. All functions contained within are vanilla variables that are not synced with the Minecraft Server. They are wrapped in a nice, explicit package stating that they are never synced. This is unlike the PlayerAPI, which you can assume is always synced (to some extent (I’m looking at you <code>isGrounded</code>))

So how can we sync information with other players if we cannot do it through the Minecraft Server? The answer is Pings. 



== General Pings ==

Pings utilize Figura’s Backend to sync information with other clients. Pings are functions that when called, triggers all other clients to call the same function for their instance of your avatar.



=== Ping Rate Limiting ===

The backend restricts you on how much data you can send over a period of time. The developer given limits are:

* 1024 bytes per second

* 32 pings per second

If either of these are reached, the backend will ignore any comunication from you for some amount of time.



=== Pingable Values ===

Pings can send most primitive types and some userdata types. All pingable types use a single byte to represent the type of data that is being sent. This byte is not included in the listed byte totals.

* <code>nil</code> - 0 Bytes

** if a type that is not supported is used as a parameter, it will be replaced with <code>nil</code>.

* <code>boolean</code> - 0 Bytes

* <code>integer</code> - 1-4 Bytes

** <code>integers</code> only take up as many bytes as it needs.

** <code>integers</code> are signed. For example, to only use a single byte the value must be between -128 and 127.

* <code>double</code> - 8 Bytes

** If the number has a decimal at all, or is outside the range of a 4 byte <code>integer</code>, it will be sent as a <code>double</code>.

* <code>string</code> - 2+n Bytes

** <code>strings</code> will always use 2 bytes to store the length.

** Ascii characters will be a single byte each.

** UTF-8 characters will be multiple bytes per character.

** The absolute maximum size of string you can send is <code>65535</code> characters. If a larger string is sent, it will be truncated.

* <code>table</code> - Too Many Bytes

** Every key and value is send as data, resulting in high byte costs.

** It is recommended to never send a table over pings.

* <code>VectorN</code> - 1+8*N Bytes

** Vectors have a single byte that stores the size of the Vector.

** Vectors are always assumed to store <code>doubles</code>. If you have a Vector of integers, I recommend sending them as 3 seperate arguments instead.

* <code>MatrixN</code> - 2+8*W*H Bytes

** Matrices store both the width and height of the matrix, then every value as a <code>double</code>.



=== Ping ===

Below is an example ping.

<syntaxhighlight lang="lua">function pings.pingName(a)

print("Ping")

print(".")

print("Data Recieved:", a)

print(".")

print("Pong")

end</syntaxhighlight>

It accepts a single variable, which it will print to the chat as an example.

To call it, just call it like any other lua function.

<syntaxhighlight lang="lua">pings.pingName("This is a string wooooooooooooooooo")</syntaxhighlight>

When you as the host call the ping, the function will execute for all other clients, regardless of their current state.

Do note that if a non-host client reaches a line where a ping gets called, it is completely ignored. No data is sent to the backend, and the contents of the ping will not be executed.

Ping functions can be passed into functions that expect a function as a parameter, such as Action <code>onToggle</code>.

<syntaxhighlight lang="lua">actionVariable:onToggle(pings.pingName)</syntaxhighlight>

Remember that we are passing the function itself as a variable. The below would be passing the ''return result'' of the ping function, which is nigh guarenteed to be <code>nil</code> as Pings ''should never'' return a value.

<syntaxhighlight lang="lua">--do not do

actionVariable:onToggle(pings.pingName())</syntaxhighlight>



== Advanced Pings ==

Situational techniques that may be handy, depending on the use case.



=== Ping on Init ===

Calling a ping function when the script is first loaded is a horrible idea. The ping will only ever execute for other clients when you, the host, load the avatar. Not only that, it may never be executed on other clients, as they might not have your avatar loaded by the time you broadcast the ping.

How do we get around this? Well, when you assign a function to an index in the <code>pings</code> table, the Lua Function gets replaced with a Java Function. This happens because of metatables, specifically the <code>__newindex</code> metamethod. Functions cannot be modified, so if we store the function before assing it to the <code>pings</code> table, we can use it like a regular function, and use the same code as a ping function.

<syntaxhighlight lang="lua">local function doThing(state)

models.modelA:setVisible(state)

models.modelB:setVisible(not state)

end

pings.doThing = doThing

-- doThing and pings.doThing are 2 completely seperate values at this point, as the pings table has replaced the index at pings.doThing with a Java Function that wraps the doThing Lua Function.

-- <code>doThing==pings.doThing</code> will return <code>false</code>

print(doThing, pings.doThing, doThing == pings.doThing)

local keybindState = false

-- I call the local doThing instead of pings.doThing, as pings.doThing is a function that invokes network code.

-- This ensures that the default state is set correctly. If this was a ping function, both models will be visible for other clients until you press the keybind.

doThing(keybindState)

local keyA = keybinds:newKeybind("KeybindName", "key.keyboard.k")

function keyA.press()

keybindState = not keybindState

-- We still need to call the ping function in the keybind.

pings.doThing(keybindState)

end</syntaxhighlight>

The alternative is to reiterate the <code>models.modelA:setVisible(state) models.modelB:setVisible(not state)</code> part of the ping. For larger pings it will be combersome to rewrite code that is already defined, which is why this technique is useful.



=== Byte Array ===

There are some situations where you will want to send a large amount of raw bytes, and you need to do it efficiently. The most efficient way is to send a string.

Asside from the 2 constant bytes for the length, a string will always be 1 byte per ascii character (UTF-8 characters are multiple ascii characters, interpreted as a single character). This makes it very consistent in terms of bytes, making it easy to predict and avoid being rate limited.

Below is a basic conversion of a byte array to a string, ready to be pinged and converted back into a byte array on the client’s end.

<syntaxhighlight lang="lua">function pings.recieveData(str)

local byteArray = table.pack(string.byte(str))

printTable(byteArray)

end

local packet=[]

for i=1,20 do

table.insert(packet, math.random(0,255))

end

local keyA = keybinds:newKeybind("KeybindName", "key.keyboard.k")

function keyA.press()

local packedString = string.char(table.unpack(packet))

pings.recieveData(packedString)

end

</syntaxhighlight>

← Older revision		Revision as of 00:46, 27 September 2024
Line 40:		Line 40:

	* {{Type\|integer}} - 1-4 Bytes		* {{Type\|integer}} - 1-4 Bytes
	** {{Type\|integers}} only take up as many bytes as ~~it needs~~.		** {{Type\|integers}} only take up as many bytes as they need.
	** {{Type\|integers}} are signed. For example, to only use a single byte the value must be between -128 and 127.		** {{Type\|integers}} are signed. For example, to only use a single byte the value must be between -128 and 127.

Line 47:		Line 47:

	* {{Type\|string}} - 2+n Bytes		* {{Type\|string}} - 2+n Bytes
	** {{Type\|strings}} will always use 2 bytes to store the length.		** {{Type\|strings}} will always use 2 bytes to store the length of the string.
	** ~~Ascii~~ characters will be a single byte each.		** ASCII characters will be a single byte each.
	** UTF-8 characters will be multiple bytes per character.		** UTF-8 characters will be multiple bytes per character.
	** The absolute maximum size of string you can send is <code>65535</code> characters. If a larger string is sent, it will be truncated.		** The absolute maximum size of string you can send is <code>65535</code> characters. If a larger string is sent, it will be truncated.

	* {{Type\|table}} - ~~Too Many~~ Bytes		* {{Type\|table}} - (all keys) + (all values) Bytes
	** Every key and value is send as data, resulting in high byte costs.		** Every key and value is send as data, resulting in high byte costs.
	** It is recommended to never send a table over pings.		** It is recommended to never send a table over pings.

	* {{Type\|Vector}} - 1+8*N Bytes		* {{Type\|Vector}} - 1+8*N Bytes
	** {{Type\|Vectors}} ~~have~~ a single byte ~~that stores~~ the size of the Vector.		** {{Type\|Vectors}} use a single byte to store the size of the Vector.
	** Vectors are always assumed to store {{Type\|doubles}}. If you have a Vector of integers, I recommend sending them as 3 seperate arguments instead.		** Vectors are always assumed to store {{Type\|doubles}}. If you have a Vector of integers, I recommend sending them as 3 seperate arguments instead.