Merge pull request #48 from JimmyHelp/multiplayer

multiplayer tutorial

docs/enums/ModelPartParentTypes.md

@@ -1,5 +1,7 @@
 import Emoji from '@site/src/components/Emoji';
 
+# ParentTypes
+
 ParentTypes are applied to ModelParts to apply specific transformations, or change how the ModelPart behaves.
 
 ## Applying ParentTypes via BlockBench

docs/globals/Player/Player.md

@@ -746,7 +746,8 @@ player:getBoundingBox()
 
 Returns whether or not this entity is currently on the ground
 
-:::cation Due to a glitch in Minecraft's code this function is unreliable, and will misfire in multiple situations such as being underwater, standing on a boat, or standing on a slime block. One workaround is to check the blockstate of the block directly underneath the player like so: <code>world.getBlockState(player:getPos():add(0,-0.1,0)):isSolidBlock()</code>
+:::caution
+Due to a glitch in Minecraft's code this function is unreliable, and will misfire in multiple situations such as being underwater, standing on a boat, or standing on a slime block. One workaround is to check the blockstate of the block directly underneath the player like so: <code>world.getBlockState(player:getPos():add(0,-0.1,0)):isSolidBlock()</code>
 :::
 
 **Example**:

docs/globals/World/BlockState.md

@@ -55,7 +55,7 @@ The saved position is used in BlockState functions that require a position
 **Example**:
 
 ```lua
-block:getID()
+block:getPos()
 ```
 
 ---

docs/start_here/Multiplayer.md

@@ -0,0 +1,95 @@
+## The Cloud
+
+The cloud (also referred to as the backend or the server) is where avatars are stored for use in multiplayer. You upload one avatar to the cloud, and that avatar is what other players see equipped to you. When you look at other players, if they uploaded an avatar to the cloud, that is the avatar you see.
+
+### How to know you're connected
+
+You have to be connected to the cloud to upload an avatar and to see other people’s avatars.
+
+You can see if you're connected by looking at the fourth part of the avatar status bar.
+
+<img src={require("@site/static/img/multiplayer/connected.png").default} width="400" alt="The cloud connection circle displaying that the cloud is connecyed"></img><br/>
+
+If your fourth part is a red X, you’re not connected to the cloud.
+
+<img src={require("@site/static/img/multiplayer/disconnected.png").default} width="400" alt="The cloud connection circle displaying that the cloud is disconnected"></img><br/>
+
+### How to connect to the cloud
+
+Figura will automatically attempt to connect you to the cloud when you join a server.
+
+-   Check your internet connection
+-   Press the reload button, this will attempt to get information from the cloud and may connect you
+-   Leave and re-join the server, or restart Minecraft
+-   Check the Discord’s announcements channel for information on if the cloud is offline
+
+### Offline Mode Servers and Cracked Accounts
+
+Figura uses a player’s UUID (a value unique to every valid Minecraft account) to identify players and entities and correctly apply avatars to them from the cloud.
+
+Cracked (non-licensed/pirated) Minecraft accounts do not have a valid UUID of their own and as a result can’t use avatars from the cloud. There is no way around this.
+
+Offline mode servers usually scramble the UUIDs of every account (cracked or licensed) logged onto the server. And because your UUID won’t match your username anymore, even licensed accounts can’t use avatars from the cloud while in an offline mode server. For licensed accounts there may be a work around if you connected to the server before it went into offline mode. Otherwise, a plugin that attempts to fix UUIDs like easyauth may be able to solve this problem.
+
+Additionally, Aternos servers are known to mess with Figura’s multiplayer capabilities even when in online mode.
+
+## Uploading an avatar
+
+Equip the avatar you want to upload by selecting it in the avatar list, and then press the upload button.
+
+<img src={require("@site/static/img/multiplayer/upload.png").default} width="40" alt="The Figura upload button"></img><br/>
+
+This does two things:
+
+1. It sends the avatar to the cloud
+2. It then takes that cloud avatar (called the uploaded avatar) and equips it to you
+
+:::warning
+Many new users of Figura think they need to press the upload button every time they make changes to their avatar, but this is not the case. You do not need to press upload every time you save any of the avatar files, if you did not upload the avatar Figura will automatically reload the avatar and show the changes to you. If you uploaded the avatar it will stop following changes made to the files after it is uploaded.
+:::
+
+### The other buttons
+
+<img src={require("@site/static/img/multiplayer/reload.png").default} width="40" alt="The Figura reload button"></img><br/>
+
+The reload button unequips your avatar and reloads the avatar uploaded to the cloud, which it then equips to you.
+
+:::warning
+Many new users of Figura think they need to press the reload button every time they make changes to their avatar, but this is not the case. You do not need to press reload every time you save any of the avatar files, if you did not upload the avatar Figura will automatically reload the avatar and show the changes to you. This button will not show you any changes you have made to the avatar's files, and may even seemingly revert changes you have made as it reverts back to the last avatar you uploaded to the cloud.
+:::
+
+<img src={require("@site/static/img/multiplayer/delete.png").default} width="40" alt="The Figura delete button"></img><br/>
+
+The delete button removes the uploaded avatar from the cloud.
+
+## Local vs Uploaded Avatars
+
+The local avatar is an avatar you have equipped that is directly linked to the files on your computer. Whenever you update one of the files on your computer the local avatar immediately updates itself to match the change.
+
+An uploaded avatar is the avatar you have uploaded to the cloud. It is completely disconnected from the files you have on your computer. This avatar will be equipped to you when you press upload, press reload, or join a single or multiplayer server. Any changes you make to the files on your computer will not be made to the uploaded avatar.
+
+## Permissions
+
+This menu can be accessed via the Figura menu. It’s sometimes called the trust menu.
+
+<img src={require("@site/static/img/multiplayer/permissions.png").default} width="800" alt="The Figura permissions menu, the button to access the advanced options is highlighted with a red square"></img><br/>
+
+The button indicated near the bottom right corner of the screen pulls up a menu that lets you adjust permission levels. Alternatively, you can click and drag player names around to move them to different levels.
+
+The permission levels and settings dictate how much of another player’s avatar you can see. The first time you see another player with a Figura avatar they’ll be put into the Default trust level. These settings are only for how YOU see other people’s avatars. Your settings will not affect how other players see your avatar.
+
+The default level is going to be adequate for most avatars, but notably the “Nameplate Change” setting is set to disabled by default. This means, for every player in your default level you can’t see any changes they’ve made to their nameplate. This is so people can’t make completely invisible avatars in the default level.
+
+Problems with permissions can be seen in someone's nameplate. A shield symbol pops up when someone's avatar is trying to do something that your permission settings for them don't allow. If you hover over it you can see which permissions are being blocked.
+
+<img src={require("@site/static/img/multiplayer/nameplate.png").default} width="800" alt="Screenshot of a player nameplate that has the 'This Avatar utilizes a higher Permission category!' warning. The warnings are 'Could not edit nameplate' and 'Could not cancel a sound'"></img><br/>
+
+## Script Errors
+
+Like permission issues, script errors you might see on your friend's avatar are displayed in their nameplate. You can hover over the red X for more information.
+
+<img src={require("@site/static/img/multiplayer/error.png").default} width="800" alt="Screenshot of a player nameplate that has the 'This Avatar contains an error!' warning. The error cause is 'Hi, this is a test error'"></img><br/>
+
+Sometimes your script can error for other players, but appear fine for you. Sometimes this is caused by permissions, in which case they can simply bring your permission level to max and then reload your avatar.
+
+Most of the time, however, it’s caused by an error in your script. You’ll have to work with your friend in order to diagnose and solve the script error. But in the meantime they can reload your avatar to hopefully temporarily dismiss the error.

docs/tutorials/How-To-Read-Documentation.md → docs/tutorials/.How-To-Read-Documentation.md

@@ -1,5 +1,9 @@
 # How To Read Documentation
 
+:::danger
+This article needs to be entirely rewritten for the current docs.
+:::
+
 **This article is a WIP.**
 
 As of writing this article, the GitHub wiki is not complete, but there are other sources of documentation for Figura out there. The most updated one is called Figs and it's made and managed by GitHub user applejuiceyy. [Here's a link](https://applejuiceyy.github.io/figs/).

docs/tutorials/ActionWheel.md

@@ -2,6 +2,8 @@
 title: Action Wheel
 ---
 
+If you're just here to copy-paste something without the tutorial go [here](./ActionWheel/#here-is-the-full-copy-paste-for-an-example-action-wheel)
+
 The Action Wheel is a gui element provided by Figura that allows for adding highly customizable Actions that can provide additional functionality to your avatar.
 
 The Action Wheel operates on Pages. Only a single Page can be active at a time.<br/>
@@ -11,7 +13,7 @@ The docs page for the [Action Wheel](../globals/action-wheel) has more examples
 
 ## Example Action Wheel
 
-First step is to create the Page that will hold the Actions. This is done via the <code>newPage</code> function.
+The first step is to create the Page that will hold the Actions. This is done via the <code>newPage</code> function.
 
 ```lua
 local mainPage = action_wheel:newPage()
@@ -117,7 +119,7 @@ mainPage:newAction()
     -- Do not do use this code. It will not work.
 ```
 
-Here is the full copy paste for an example Action Wheel
+#### Here is the full copy paste for an example Action Wheel
 
 <!-- prettier-ignore -->
 ```lua
@@ -137,15 +139,15 @@ local action = mainPage:newAction()
 
 ### Toggle Example
 
-This is an exmaple of the onToggle function, which swaps between two states
+This is an exmaple of the onToggle function, which swaps between two states. It does not work on its own as it doesn't have a page.
 
 <!-- prettier-ignore -->
 ```lua
 function pings.toggling(state)
     models:setVisible(state)
 end
 
-local toggleaction = myPage:newAction()
+local toggleaction = mainPage:newAction() -- If you're getting an error here it's probably because you didn't make the page
     :title("disabled")
     :toggleTitle("enabled")
     :item("red_wool")
@@ -180,7 +182,7 @@ function pings.toggling(state)
     models:setVisible(state)
 end
 
-local toggleaction = myPage:newAction()
+local toggleaction = mainPage:newAction()
     -- this action is saved to toggleaction. it's important that actions are saved to unique variables
     :title("disabled")
     :toggleTitle("enabled")
@@ -232,3 +234,7 @@ Go [here](../globals/Action-Wheel/Action.md) for more information on Actions. Go
 ## Advanced Action Wheel
 
 Go [here](../tutorials/ActionWheel-Advanced) for an advanced action wheel tutorial.
+
+#### For when you want to skip the tutorials altogether
+
+If you scrolled to the bottom of the page just to copy-paste something without the tutorial go [here](./ActionWheel/#here-is-the-full-copy-paste-for-an-example-action-wheel)

docs/tutorials/Animations.md

@@ -6,7 +6,7 @@ In order to play an animation you need to index the animation through the Blockb
 
 Let's say we have a Blockbench model named <code>example</code>
 
-<img src={require("@site/static/img/animation/exampleBbmodel.png").default} width="100"></img>
+<img src={require("@site/static/img/animation/exampleBbmodel.png").default} width="200"></img>
 
 and an animation named <code>idle</code>
 
@@ -20,7 +20,7 @@ animations.example.idle:play()
 
 <code>animations</code> stores all the animation data for every Blockbench model.<br/>
 
-The next part of the index is always the Blockbench model name that contains the animation you want to play, in our case this is <code>example.bbmodel</code> (if your Blockbench model is in a subfolder, that will need to be included as well, but you can find more information about that in ModelPart Indexing)
+The next part of the index is always the Blockbench model name that contains the animation you want to play, in our case this is <code>example.bbmodel</code> (if your Blockbench model is in a subfolder, that will need to be included as well like <code>animations["subfolder.example"].idle</code>)
 
 And the last is always the animation name, in this case <code>idle</code>.
 

docs/tutorials/Custom-Items.md

@@ -10,11 +10,11 @@ You'll need to use the Item [keyword](../enums/ModelPartParentTypes) and the ite
 
 ## Item Keyword
 
-If you give a Blockbench group the Item keyword (by starting the group name with <code>Item</code>) it will be primed and ready to be used as an item. Without the event the Item group will vanish- and so will every item you hold.
+If you give a Blockbench group the Item keyword (by starting the group name with <code>Item</code>) it will be primed and ready to be used as an item. Without the event the Item group will vanish- and so will every item you hold. It has to be Item with a capital I.
 
 ## Item Render Event
 
-The item_render event runs once a frame for every item you're holding (so, a max of two) and do their own things in their version of the event.
+The item_render event runs once a frame for every item you're rendering and they do their own things in their own version of the event.
 
 In order to make the Item show up you must return it in the item_render event. This example assumes the bbmodel is named <code>model</code> and that the keyworded group is named Item. If you wish to test this change <code>model</code> to your bbmodel name and the Item group to your version.
 
@@ -28,6 +28,16 @@ This will replace every single item you're holding with your custom item
 
 ## Replacing Specific Items
 
+Here's an exmaple for replacing a single item:
+
+```lua
+function events.item_render(item)
+    if item.id == "minecraft:crossbow" then
+        return models.model.ItemBow
+    end
+end
+```
+
 You can use the event's arguments to get different information from the item you're holding, and they are: the itemstack, rendering mode, position, rotation, scale, and if its in the left hand. [Possible item rendering modes.](../enums/ItemDisplayModes)
 
 ```lua

docs/tutorials/Keybinds.md

@@ -14,7 +14,7 @@ local exampleKey = keybinds:newKeybind("Keybind Name", "key.keyboard.h")
 
 At this point, the keybind will show up in the avatar's keybind list- accessible via the Figura menu- with the name Keybind Name and assigned to the letter H. But pressing H won't do anything yet.
 
-More keybinds ids can be found in the Keybinds: Enums page
+More keybinds ids can be found in the [KeybindsList](../enums/Keybinds-List.md) page
 
 There are multiple ways to detect keybinds, but the most common is through <code>press</code> and <code>release</code> as they are easiest to ping. If you're not familiar with pings see [Pings](./Pings).
 
@@ -100,4 +100,4 @@ If you want to detect a vanilla action like attacking or walking forwards but wa
 local exampleKey = keybinds:newKeybind("Keybind Name", keybinds:getVanillaKey("key.forward"))
 ```
 
-This will now detect the forward key regardless of what it's bound to. <code>getVanillaKey()</code> is going to need a key id from a specific list of ids that all correspond to a vanilla keybind. They can be found in the keyIDs enum.
+This will now detect the forward key regardless of what it's bound to. <code>getVanillaKey()</code> is going to need a key id from a specific list of ids that all correspond to a vanilla keybind. They can be found in the [keyIDs](../enums/KeyIDs.md) enum.

docs/tutorials/Particles.md

@@ -8,7 +8,7 @@ Most of the article assumes you know to avoid calling the player in init.
 particles:newParticle(particleID, position, velocity)
 ```
 
-If you're looking on the [Minecraft wiki](https://minecraft.wiki/w/Particles) then the particle id is the name under the 'Java Edition ID Name' column. Or, it's the same id used by the /particle command. If you're using Minecraft particles you can exclude the Minecraft "mod name".
+If you're looking at the [Minecraft wiki](https://minecraft.wiki/w/Particles) then the particle id is the name under the 'Java Edition ID Name' column. Or, it's the same id used by the /particle command. If you're using Minecraft particles you can exclude the Minecraft "mod name".
 
 ```lua
 particles:newParticle("minecraft:explosion", player:getPos())

docs/tutorials/Sounds.md

@@ -38,7 +38,7 @@ Ex: If your file is <code>horn.ogg</code> then your playSound line would look li
 sounds:playSound("horn", player:getPos())
 ```
 
-Minecraft will only play specific sound files, namely sounds that are .ogg files. Here's an [online OGG converter](https://audio.online-convert.com/convert-to-ogg). You will want to change the audio channels setting to <code>mono</code> and the audio codec to <code>Vorbis</code> because Minecraft likes the Vorbic codec.
+Minecraft will only play specific sound files, namely sounds that are .ogg files. Here's an [online OGG converter](https://audio.online-convert.com/convert-to-ogg). You will want to change the audio channels setting to <code>mono</code> and the audio codec to <code>Vorbis</code>.
 
 If your custom sound is stored in a subfolder in the avatar, the subfolder name gets added onto the sound name like this:
 
@@ -67,10 +67,10 @@ local wDeath = sounds["entity.wither.death"]
 Now you have the wither death sound available for your use wherever within that local scope.
 
 ```lua
-wDeath:play()
+wDeath:play():loop(true)
 ```
 
-Will play the sound, but without a position it will be at (0,0,0) in the world.
+Will play the sound and make it loop, but without a position it will be at (0,0,0) in the world.
 
 ```lua
 function events.tick()
@@ -82,7 +82,7 @@ Full example:
 
 ```lua
 local wDeath = sounds["entity.wither.death"]
-wDeath:play()
+wDeath:play():loop(true)
 function events.tick()
     wDeath:pos(player:getPos())
 end