From 02ef09a06596e565930b26ad422e42275e9af69a Mon Sep 17 00:00:00 2001 From: Kulltero <33698270+Kulltero@users.noreply.github.com> Date: Wed, 1 Feb 2023 01:37:36 +0100 Subject: [PATCH 1/8] Upload Initial Documentation files Uploading Documentation onto a clean branch because having 557 Stackedit commits doesn't seem sensible --- README.md | 37 +++++++ docs/Basics.md | 62 +++++++++++ docs/Bugs-Tips.md | 118 +++++++++++++++++++++ docs/components/Countdown.md | 39 +++++++ docs/components/NeedsX.md | 19 ++++ docs/components/README.md | 32 ++++++ docs/components/RectTransform.md | 60 +++++++++++ docs/components/UnityEngine.UI.Button.md | 34 ++++++ docs/components/UnityEngine.UI.Image.md | 52 +++++++++ docs/components/UnityEngine.UI.InputField | 46 ++++++++ docs/components/UnityEngine.UI.Outline.md | 27 +++++ docs/components/UnityEngine.UI.RawImage.md | 89 ++++++++++++++++ docs/components/UnityEngine.UI.Text.md | 61 +++++++++++ 13 files changed, 676 insertions(+) create mode 100644 README.md create mode 100644 docs/Basics.md create mode 100644 docs/Bugs-Tips.md create mode 100644 docs/components/Countdown.md create mode 100644 docs/components/NeedsX.md create mode 100644 docs/components/README.md create mode 100644 docs/components/RectTransform.md create mode 100644 docs/components/UnityEngine.UI.Button.md create mode 100644 docs/components/UnityEngine.UI.Image.md create mode 100644 docs/components/UnityEngine.UI.InputField create mode 100644 docs/components/UnityEngine.UI.Outline.md create mode 100644 docs/components/UnityEngine.UI.RawImage.md create mode 100644 docs/components/UnityEngine.UI.Text.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c90b70d --- /dev/null +++ b/README.md @@ -0,0 +1,37 @@ +# Rust Community Repository +> This Repository is part of the game Rust. It has no relation to the Programming Language + +Client Code for the `CommunityEntity` Class to fulfill Server-side Modder Requests. +Holds the Custom User Interface System (CUI System), which lets developers create interactable UI through a simple JSON Schema + +## Table of Contents +> Click one of the Topics or dive directly into the Component Documentation +- [The Basics](/docs/Basics.md) +- [Components](/docs/components/README.md) + - [RectTransform](/docs/components/RectTransform.md) + - [RawImage](/docs/components/UnityEngine.UI.RawImage.md) + - [Image](/docs/components/UnityEngine.UI.Image.md) + - [Text](/docs/components/UnityEngine.UI.Text.md) + - [Outline](/docs/components/UnityEngine.UI.Outline.md) + - [Button](/docs/components/UnityEngine.UI.Button.md) + - [InputField](/docs/components/UnityEngine.UI.InputField.md) + - [NeedsCursor & NeedsKeyboard](/docs/components/NeedsX.md) + - [Countdown](/docs/components/Countdown.md) +- [Tips, Bugs & Edgecases](/docs/Bugs-Tips.md) +- [Credits & Acknowledgements](#Credits) + +## Credits +External Contributors & People who improved the CUI System +- [@bawNg](https://github.com/bawNg) - PRs [#1](https://github.com/Facepunch/Rust.Community/pull/1), [#2](https://github.com/Facepunch/Rust.Community/pull/2), [#5](https://github.com/Facepunch/Rust.Community/pull/5) +- [@balu92](https://github.com/balu92) - PRs [#7](https://github.com/Facepunch/Rust.Community/pull/7), [#9](https://github.com/Facepunch/Rust.Community/pull/9) +- [@Jake-Rich](https://github.com/Jake-Rich) - PRs [#16](https://github.com/Facepunch/Rust.Community/pull/16), [#30](https://github.com/Facepunch/Rust.Community/pull/39) +- [@Mughisi](https://github.com/Mughisi) - PRs [#19](https://github.com/Facepunch/Rust.Community/pull/19), [#22](https://github.com/Facepunch/Rust.Community/pull/22) +- [@shooter46](https://github.com/shooter46) - PR [#28](https://github.com/Facepunch/Rust.Community/pull/28) +- [@Alitop](https://github.com/Alitop) - PR [#32](https://github.com/Facepunch/Rust.Community/pull/32) +- [@TactiTac0z](https://github.com/TactiTac0z) - PR [#40](https://github.com/Facepunch/Rust.Community/pull/40) +- [@Kulltero](https://github.com/Kulltero) - PR [#43](https://github.com/Facepunch/Rust.Community/pull/43) +> And of course, Facepunch, who has put a lot of ffort into giving Developers the CUI System & the ability to improve it + +--- +### Disclaimer +the readme & Documentation is Community maintained it aims to give Developers a starting Point and educate them on effectively using CUIs for their Projects diff --git a/docs/Basics.md b/docs/Basics.md new file mode 100644 index 0000000..b3c348e --- /dev/null +++ b/docs/Basics.md @@ -0,0 +1,62 @@ +# The Basics of CUI +**< [Previous Topic](/README.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/docs/components/README.md) >** + +There are a few basic Concepts that are needed to make your own CUI, below you will learn about what Panels are & how to create and destroy UI Elements + +## The Schema +the JSON Schema to send UI to the Player consists of a List of Elements, where each Element creates a new Panel on the Client. Elements have One or more Components that control the Look & Functionality. + +```json +[{ + "name": "AddUI CreatedPanel", + "parent": "Overlay", + "components": [...], + "fadeOut": 0.0, + "destroyUi": "" +}, ...] +``` +> the values in these JSON examples represent the default Values that are assigned if no property is specified. +> … represent One or more collapsed Objects + +| Key | Type | Notes | +| :-- | :------- | :------------------- | +| `name` | string | the identifier of your panel, needed when destroying UI or adding panels inside this one | +| `parent` | string | tells the client which Panel or Layer to Parent to | +| `components` | List of Components | One or more Components, without these there's no point in sending a panel | +| `fadeOut` | float | makes the Panel fade out instead of disappearing immediately. *Currently doesn't fade out any child Panels* | +| `destroyUi` | string | destroys the Panel specified in the string before creating your Panel. useful for updating UI | + +### About Naming +It's recommended to always name your Panels *something*, this is because the CUI System doesn't support multiple Panels with the same name and may cause *Ghost Panels* which cant be destroyed. + +It's also recommended to prefix the Name of your Panel with something unique to your Mod, which ensures there are no accidental name Conflicts with other Mods + + +## Sending & destroying UI + +There are two RPC Calls you can use to send & destroy UI respectively + +Adding UI: +```c# +BasePlayer player = targetPlayer; +string json = "..."; // your UI in JSON form +var community = CommunityEntity.ServerInstance; +SendInfo sendInfo = new SendInfo(player.net.connection); +community.ClientRPCEx(sendInfo, null, "AddUI", json); +``` + +Destroying UI: +```c# +BasePlayer player = targetPlayer; +string panel = "AddUi CreatedPanel"; // the name of the Panel you wish to destroy +var community = CommunityEntity.ServerInstance; +SendInfo sendInfo = new SendInfo(player.net.connection); +community.ClientRPCEx(sendInfo, null, "DestroyUI", panel); +``` +When destroying a Panel, all child Panels will also get destroyed. +> your Modding Framework may have helper Methods to simplify these steps. + +---- +the next Topic explains Components in detail + +**< [Previous Topic](/README.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/docs/components/README.md) >** diff --git a/docs/Bugs-Tips.md b/docs/Bugs-Tips.md new file mode 100644 index 0000000..af7870d --- /dev/null +++ b/docs/Bugs-Tips.md @@ -0,0 +1,118 @@ +# Bugs & Tips + +**< [Previous Topic](/docs/components/README.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/README.md) >** + +When working with the CUI System you will often encounter weird Bugs & Situations. this document lists some ways to prevent them & shows you additional tricks to enhance your UIs + +## Table of Contents +- [Common Error Messages](#common-error-messages) +- [Bugs](#bugs) +- [Tricks](#tricks) + +# Common Error Messages +> these errors will appear in your client console when testing the UI, make sure to test for these before releasing your mod + +### AddUI: Unknown Parent for *name*: *parent* +this happens when the parent you supplied in your panel Payload doesn't exist. double-check for spelling mistakes, and formatting issues & ensure your parent appears in your JSON list before the Panel you get this error on. + + + +--- + +### Error downloading image: *URL* ( *error* ) +the Client couldn't download your Image, double check your URL & look at the error part within the brackets for what could cause it. + + + +--- + +### A GameObject can only contain one 'Graphic' component. +this error indicates that you're trying to add multiple Unity Components that Derive from `UnityEngine.UI.Graphic`. the **[Components](/docs/components/README.md)** topic has a list of allowed Components and lists the categories they are in. any Component of the **Visual** Category is a Component that derives from or adds a `UnityEngine.UI.Graphic` to the Panel. to get around this Limitation you can put other Visual Components on a child Panel instead. + +# Bugs + +### Orphaned UI Panels, UI that Can't be Destroyed, or Ghost Panels. +**Symptom:** you have 1 or more Panels that are stuck on your Screen and can't be removed by Calling **DestroyUI** with their Name. + +**Cause:** you have 2 or more Panels that shared the same Name & were active at the same time. if these are parented directly to a Layer and one is destroyed the other Panel Can't be destroyed anymore. the only way to remove the UI Panel from your Screen is by reconnecting. double-check your UI and ensure any Panel directly parented to a Layer has a unique Name. also, ensure that you don't accidentally send the same UI twice. + + + +--- + +### Flickering when destroying & re-sending UI on the same frame. +**Symptom:** when updating Part of your UI. the Player gets a noticeable Delay between the old UI being destroyed & the new UI being created. + +**Cause:** the presumed cause of this issue is the Server Delaying your AddUI Packet to the next Network Cycle. this happens very unpredictably but is more likely with larger UI Updates. the solution is to use the `destroyUi` field on your panel Payload, it works the same way a DestroyUI call works, but is combined with your panel Payload to prevent network scheduling from creating the Flickering issue. + + + +--- + +### Very Inconsistent Alpha handling for images +**Symptom:** when using Images with somewhat transparent pixels the images get rendered more Opaque than they are, resulting in heavy artifacts. +**Linked Issue:** **[#42 - Rust has an Opacity Issue](https://github.com/Facepunch/Rust.Community/issues/42)** + +**Cause:** no known Cause or Workaround found. vote on the Linked issue if you encounter this bug or have more info as to why this might happen + + + +--- + +### Panels with a blur Material & Transparency cause underlying Panels to be invisible. +**Symptom:** when using a burry Material on a Color with Transparency, any underlying Image Components with blur get cut out. +**Visual Example:** +![image](https://user-images.githubusercontent.com/33698270/215882128-d1f0798c-d7ed-4986-9675-4fba48632ad7.png) +> an image of the following UI setup +> parent: black with 98% alpha +> +> square 1: child of Parent, gray with 20% alpha +> +> square 2: child of Parent, gray with 100% alpha +> +> square 3: child of Parent, gray with 20% alpha and a text element behind it. + + +**Cause:** no exact Cause is known, but it seems to be related to the blurry Materials themselves. this bug only occurs when all underlying Images are using a blurry material with transparency. if at least 1 element is opaque the bug does not occur. this can be a text or image element. + + + +# Tricks + +### Use Outlines like an advanced User +Outlines can go way beyond the basic use case of putting them on your square Panels. applying Outlines to Text can be a great way to make them stand out, for example when you can't control the background behind it. +![image](https://user-images.githubusercontent.com/33698270/215885917-4916ee09-a891-4609-82a4-51bb07881bde.png) + +> can you read this? + +![image](https://user-images.githubusercontent.com/33698270/215886796-346be279-2d8e-43c4-a28f-f740bcf50ff5.png) + +> adding a 1px outline with a darker color makes it much clearer. + +Another advanced trick is stacking Outlines with lowered Opacity to create a staggered outline or glow/shadow effect. unlike **Visual** Components, the Outline Component doesn't derive from `UnityEngine.UI.Graphic`, meaning there's no limit on how many Outlines a Panel can have. + +![image](https://user-images.githubusercontent.com/33698270/215899049-e0aa0cd7-b607-466e-a0b7-0cfafa62bdae.png) + +> right has no outlines. left is simulating a 3D effect using 3 stacked Outlines with low opacity. looks great in certain scenarios. + + +--- + +### Positioning your CUI alongside rust UI +for features that augment Rust's existing UI, like when you're working with Furnaces & other storage Inventories, its important to make sure your CUI doesn't interfere with the UI you augment. + +Rust UI uses the same Placement system CUI does. it anchors all of the UI to the Bottom Middle of the Screen and then uses offsets to position each element. by doing the same you can ensure that your CUI is positioned properly, regardless of Screensize & Aspect Ratio. + +a RectTransform Example that covers the Belt-bar +```json +{ + "type": "RectTransform", + "anchormin": "0.5 0.0", + "anchormax": "0.5 0.0", + "offsetmin": "-200 18", + "offsetmax": "180 78" +} +``` +![image](https://user-images.githubusercontent.com/33698270/215901408-c152fecb-8453-4597-8cd6-61038b2b976d.png) + +**< [Previous Topic](/docs/components/README.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/README.md) >** diff --git a/docs/components/Countdown.md b/docs/components/Countdown.md new file mode 100644 index 0000000..dd27305 --- /dev/null +++ b/docs/components/Countdown.md @@ -0,0 +1,39 @@ +# Components: Countdown +**< [Previous Component](/docs/components/NeedsX.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/README.md) >** + +- Identifier: `Countdown` +- Category: **Misc** +- Unity Documentation: **N/A** + +The Countdown Component lets you turn an existing Text Component into a Timer, Countdown, or Count-up. the Countdown Component automatically **destroys** the Panel when it's done counting. +```json +{ + "type": "Countdown", + "endtime": 0, + "startTime": 0, + "step": 1, + "command": "" +} +``` + +Countdown-specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `endTime` | int | the Number it should count to | +| `startTime` | int | the Number it should start counting from | +| `step` | int | the Number it should increment by, also acts as the update interval | +| `command` | string | the Command that should be executed when the Countdown finishes. | + +## Working with Countdowns +for Countdowns to work you need to add a **[Text](/docs/components/UnityEngine.UI.Text.md)** Component to your Panel. your Text Component's content should include the string `%TIME_LEFT%`, which the Countdown will replace with the current Number. + +Examples: +- `the Event will end in %TIME_LEFT% Seconds` => the Event Will end in 30 Seconds +- `Power-up Buff - %TIME_LEFT%s` => Power-up Buff - 30s + +### Counting Up vs counting Down +- to count Down set your `startTime` higher than your `endTime` & set your `step` to at least 1. +- to count Up set your `startTime` lower than your `endTime` + + +**< [Previous Component](/docs/components/NeedsX.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/README.md) >** diff --git a/docs/components/NeedsX.md b/docs/components/NeedsX.md new file mode 100644 index 0000000..4b41a46 --- /dev/null +++ b/docs/components/NeedsX.md @@ -0,0 +1,19 @@ +# Components: NeedsCursor & NeedsKeyboard +**< [Previous Component](/docs/components/UnityEngine.UI.InputField.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/Countdown.md) >** + +- Identifier: `NeedsCursor` or `NeedsKeyboard` +- Category: **Misc** +- Unity Documentation: **N/A** + +The NeedsCursor & NeedsKeyboard Components are Components with no additional Fields. Their only purpose is to tell Rust's input Controller if mouse & keyboard Behavior should only be focused on your UI. +```json +{ + "type": "NeedsCursor" + // or + "type": "NeedsKeyboard" +} +``` + +unlike the `needsKeyboard` and `hudMenuInput` fields on an InputField Component, these Components Prevent default Behavior until your Panel is Destroyed + +**< [Previous Component](/docs/components/UnityEngine.UI.InputField.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/Countdown.md) >** diff --git a/docs/components/README.md b/docs/components/README.md new file mode 100644 index 0000000..f2a1a3e --- /dev/null +++ b/docs/components/README.md @@ -0,0 +1,32 @@ +# Components +**< [Previous Topic](/docs/Basics.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/docs/Tips-Pitfalls.md) >** + +The CUI System comes with a Set of Components you can use to build your UI, some are visual, and others add Interactivity. + +Components are added to a Panel by sending them as a List in the Schema shown in [The Basics](/docs/Basics.md). to identify the Type of Component sent, a `type` Field is added by every Component +```json +[{ + "type": "UnityEngine.UI.Text", + // More Component fields ... +}, +...] +``` + +## Component List +- [RectTransform](/docs/components/RectTransform.md) +- [RawImage](/docs/components/UnityEngine.UI.RawImage.md) +- [Image](/docs/components/UnityEngine.UI.Image.md) +- [Text](/docs/components/UnityEngine.UI.Text.md) +- [Outline](/docs/components/UnityEngine.UI.Outline.md) +- [Button](/docs/components/UnityEngine.UI.Button.md) +- [InputField](/docs/components/UnityEngine.UI.InputField.md) +- [NeedsCursor & NeedsKeyboard](/docs/components/NeedsX.md) +- [Countdown](/docs/components/Countdown.md) + +## About Component Categories +Each Component Page has a *Category* listed, which helps you identify what a Component does. pay attention to the **Visual** Category, as it means the Component Adds a Unity Component deriving from `UnityEngine.UI.Graphic`. This is important because **each Panel can only have 1 Graphic Component**. + +--- +The next Topic explains common Pitfalls & Things you need to look out for + +**< [Previous Topic](/docs/Basics.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/docs/Bugs-Tips.md) >** diff --git a/docs/components/RectTransform.md b/docs/components/RectTransform.md new file mode 100644 index 0000000..182d226 --- /dev/null +++ b/docs/components/RectTransform.md @@ -0,0 +1,60 @@ +# Components: RectTransform +**< [Previous Component](/docs/components/README.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.RawImage.md) >** + +- Identifier: `RectTransform` +- Category: **Position** +- Unity Documentation: **[RectTransform @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/class-RectTransform.html)** + +The RectTransform is a Component that specifies the Position & Size of the Panel it's attached to. +it allows you to position a Panel via [Anchors & Offsets](#anchors-and-offsets). +```json +{ + "type": "RectTransform", + "anchormin": "0.0 0.0", + "anchormax": "1.0 1.0", + "offsetmin": "0.0 0.0", + "offsetmax": "1.0 1.0", +} +``` +RectTransform specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `anchormin` | string | specifies the anchor for the bottom left Corner | +| `anchormax` | string | specifies the anchor for the top right Corner | +| `offsetmin` | string | specifies the Pixel offset for the bottom left Corner | +| `offsetmax` | string | specifies the Pixel offset for the top right Corner | + +both Anchors & Offsets come with a *-min* and *-max* Field, where the min holds x & y Values for the bottom left Corner & the max holds x & y Values for the top right Corner + +## Positioning in Rust +a Panel's Position is always relative to its Parent, even when parenting directly to a Layer. +Unity's Coordinate System in a 2D Space goes from Left to Right, Bottom to Top. +| `x 0.0 y 1.0` | `x 1.0 y 1.0` | +| ------------- | ------------- | +| `x 0.0 y 0.0` | `x 1.0 y 0.0` | +> this might be confusing to people coming from the web-design space, where the x coordinate commonly goes down the screen instead of up + +## Anchors and Offsets +Anchors Specify where your Panel starts & ends. Offsets let you move the start & end Points with pixel Values. + +Anchors use a normalized Percentage of the Parent, where `0.0` is the Start and `1.0` is the End. [The "Anchors" Section](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/UIBasicLayout.html#anchors) in the Unity Documentation has some visual examples which also apply here. + +Offsets use [scaled](#offsets-and-scaling) pixel Values to move the Corners relative to the Anchors you provide. + +Positioning using only Anchors is great for when you want your Panel to cover a Percentage of the Screen or Parent, but for any other cases, a mixture of Anchors & Offsets should be used to Position your UI. + +A common Technique is to use Anchors to specify what part of the Parent the UI should be anchored to (Top Left Corner or Dead Center. Etc.) and to use Offsets for Size & Position. + +## Offsets and Scaling +Rust will automatically scale Offsets depending on the Player's Resolution, which ensures your Offsets are predictable. + +By default, Rust handles Offsets based on a Resolution of **1280** by **720**. This means that for smaller & larger **16:9** Resolutions Rust will simply multiply Offsets by the difference between the Player's Resolution and 720p, + +For non-16:9 Resolutions such as Ultrawide or windowed Mode, Rust will apply Letterboxing before calculating the scaling Factor + + +https://user-images.githubusercontent.com/33698270/214582004-c695e73c-9125-4ccb-9cfb-abc883b5c0a0.mp4 +> a video of a gray Rectangle positioned at the Center of the Screen (anchor min & max at `0.5 0.5`) with an offset of 1280 x 720 px. see how Unity applies Letterboxing before scaling the Rectangle to ensure it never gets stretched. NOTE: the black Bars are only to illustrate in this Example, your ingame UI won't have any black Bars + + +**< [Previous Component](/docs/components/README.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.RawImage.md) >** diff --git a/docs/components/UnityEngine.UI.Button.md b/docs/components/UnityEngine.UI.Button.md new file mode 100644 index 0000000..5ae304b --- /dev/null +++ b/docs/components/UnityEngine.UI.Button.md @@ -0,0 +1,34 @@ +# Components: Button +**< [Previous Component](/docs/components/UnityEngine.UI.Outline.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.InputField.md) >** + +- Identifier: `UnityEngine.UI.Button` +- Category: **Interactive, Visual** +- Unity Documentation: **[Button @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-Button.html)** + +The Button Component is an Interactive Component that lets you execute Commands & Destroy UI when it gets pressed. it automatically adds a `UnityEngine.UI.Image` to the panel, allowing you to change the `sprite`, `material` & `color` on it +```json +{ + "type": "UnityEngine.UI.Button", + "command": "", + "close": "", + "sprite": "Assets/Icons/rust.png", + "color": "1.0 1.0 1.0 1.0", + "material": "", + "imagetype": "Simple" +} +``` +Button-specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `command` | string | the Command that should get sent to the Server on Click | +| `close` | string | the Name of the Panel that should get closed on Click | +| `sprite` | string | the asset Path to the sprite | +| `color` | string | the normalized RGBA values of your color | +| `material` | string | the asset Path to the Material | +| `imagetype` | string (enum `Image.Type`) | sets the display mode of the Image* | +\* Currently non-functioning for anything other than Rust's built-in Sprites + +### Button as a Parent +click events bubble up, meaning that they will get triggered on every Panel until a Component consumes them. This means it's possible to use the Button as a Parent and still get notified when the Player clicks a child Panel. + +**< [Previous Component](/docs/components/UnityEngine.UI.Outline.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.InputField.md) >** diff --git a/docs/components/UnityEngine.UI.Image.md b/docs/components/UnityEngine.UI.Image.md new file mode 100644 index 0000000..d78292e --- /dev/null +++ b/docs/components/UnityEngine.UI.Image.md @@ -0,0 +1,52 @@ +# Components: Image +**< [Previous Component](/docs/components/UnityEngine.UI.RawImage.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.Text.md) >** + +- Identifier: `UnityEngine.UI.Image` +- Category: **Visual** +- Unity Documentation: **[Image @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-Image.html)** + +The Image is a Visual Component that allows you to display Images from your Server & the Web or Rust Sprites. it can also be used with a single color to act as a Background for your panel +```json +{ + "type": "UnityEngine.UI.Image", + "sprite": "Assets/Icons/rust.png", + "color": "1.0 1.0 1.0 1.0", + "material": "", + "imagetype": "Simple", + "png": "", + "itemid": 0, + "skinid": 0 +} +``` +RawImage specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `sprite` | string | the asset Path to the sprite | +| `color` | string | the normalized RGBA values of your color | +| `material` | string | the asset Path to the Material | +| `imagetype` | string (enum `Image.Type`) | sets the display mode of the Image* | +| `png` | string | the CRC Checksum of the Image hosted on the Server | +| `itemid` | int | the Item ID of your item | +| `skinid` | ulong | the Skin ID of your skin | + +\* Currently non-functioning for anything other than Rust's built-in Sprites +## RawImages vs Images +Like RawImages, Images share the ability to show Sprites, Colors, Materials & Images hosted on the Server, but they cannot directly load Images from the Web. + +The Image Component has convenient Ways to display any Item or Skin and is recommended when using Rust's Sprites. + +## Items and Skins +using the `itemid` & `skinid` fields you can let the Client handle the displaying of related Images. + +Tip: use the ItemDefinition of your Item to easily find an Item's ID & other useful Information +```c# +string shortname = "your.item.shortname"; +var itemDef = ItemManager.FindItemDefinition(shortname); +int itemid = itemDef.itemid; +// other useful Fields: displayName, displayDescription, category & stackable +``` + + +--- +check the [RawImage](/docs/components/UnityEngine.UI.RawImage.md) Documentation to learn about Fields the Components share. +**< [Previous Component](/docs/components/UnityEngine.UI.RawImage.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.Text.md) >** diff --git a/docs/components/UnityEngine.UI.InputField b/docs/components/UnityEngine.UI.InputField new file mode 100644 index 0000000..b1ab472 --- /dev/null +++ b/docs/components/UnityEngine.UI.InputField @@ -0,0 +1,46 @@ +# Components: InputField +**< [Previous Component](/docs/components/UnityEngine.UI.Button.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/NeedsX.md) >** + +- Identifier: `UnityEngine.UI.InputField` +- Category: **Interactive, Visual** +- Unity Documentation: **[InputField @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-InputField.html)** + +The InputField Component is an Interactive Component that allows Players to enter arbitrary text that gets sent back as a Command. it automatically adds a `UnityEngine.UI.Text` to the panel, allowing you to change the `fontSize`, `font`, `align`ment & text`color` of it +```json +{ + "type": "UnityEngine.UI.InputField", + "fontSize": 14, + "font": "RobotoCondensed-Bold.ttf", + "align": "UpperLeft", + "color": "1.0 1.0 1.0 1.0", + "command": "", + "text": "", + "readOnly": false, + "lineType": "SingleLine", + "password": null, + "needsKeyboard": null, + "hudMenuInput": null, + "autofocus": null, +} +``` +> `password`, `needsKeyboard`, `hudMenuInput`, and `autofocus` are key presence Fields, key presence Fields don't have a specific type and act as a Boolean. +> if the key is present it equals true, if absent it equals false. + +InputField specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `command` | string | the Command that should get sent to the Server alongside the Player's Input. The Input will get appended to the Command after a Space. | +| `text` | string | the default Text of the InputField can be combined with `readOnly` | +| `readOnly` | bool | prevents the Content from being edited | +| `lineType` | string (enum `InputField.LineType`) | dictates if the Field should allow multiple Lines & how to handle when the Player presses `enter` | +| `password` | key presence Field | if the input should be obscured | +| `needsKeyboard` | key presence Field | prevents default Keyboard behavior (movement, item switching etc) while the field is Focused | +| `hudMenuInput` | key presence Field | same as above but for Rust UI (Inventory, Crafting, etc.) | +| `autofocus` | key presence Field | selects the field upon creation | + +### Receiving Input & the lineType Setting +to receive the Player's input Text, listen for the Command you specify in the `command` field. the Input will get sent as soon as the Player unfocuses the InputField, for example by clicking out of it. + +depending on the `lineType` Setting, if it's set to SingleLine or MultiLineSubmit pressing `enter` will also cause the Input to get sent to the Server. Pressing `enter` with the MultiLineNewline Setting inserts a Newline instead. + +**< [Previous Component](/docs/components/UnityEngine.UI.Button.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/NeedsX.md) >** diff --git a/docs/components/UnityEngine.UI.Outline.md b/docs/components/UnityEngine.UI.Outline.md new file mode 100644 index 0000000..6b8f1da --- /dev/null +++ b/docs/components/UnityEngine.UI.Outline.md @@ -0,0 +1,27 @@ +# Components: Outline +**< [Previous Component](/docs/components/UnityEngine.UI.Text.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.Button.md) >** + +- Identifier: `UnityEngine.UI.Outline` +- Category: **Effect** +- Unity Documentation: **[Outline @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-Outline.html)** + +The Outline Component is an Effect Component that puts a colored outline on any Visual Component. it supports any Image, Text, Button, or Input field. +```json +{ + "type": "UnityEngine.UI.Outline", + "color": "1.0 1.0 1.0 1.0", + "distance": "1.0 -1.0", + "useGraphicAlpha": null +} +``` +> `useGraphicAlpha` is a key presence Field, key presence Fields don't have a specific type and act as a Boolean. +> if the key is present it equals true, if absent it equals false. + +Outline specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `color` | string | the Color of your Outline | +| `distance` | string | the distance of your Outline (formatted as `X Y`) | +| `useGraphicAlpha` | key presence Field | multiplies the Alpha of the graphic onto the color of the Outline | + +**< [Previous Component](/docs/components/UnityEngine.UI.Text.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.Button.md) >** diff --git a/docs/components/UnityEngine.UI.RawImage.md b/docs/components/UnityEngine.UI.RawImage.md new file mode 100644 index 0000000..3711091 --- /dev/null +++ b/docs/components/UnityEngine.UI.RawImage.md @@ -0,0 +1,89 @@ +# Components: RawImage +**< [Previous Component](/docs/components/RectTransform.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.Image.md) >** + +- Identifier: `UnityEngine.UI.RawImage` +- Category: **Visual** +- Unity Documentation: **[RawImage @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-RawImage.html)** + +The RawImage is a Visual Component that allows you to display Images from your Server & the Web or Rust Sprites. it can also be used with a single color to act as a Background for your panel +```json +{ + "type": "UnityEngine.UI.RawImage", + "sprite": "Assets/Icons/rust.png", + "color": "1.0 1.0 1.0 1.0", + "material": "", + "url": "", + "png": "" +} +``` +RawImage specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `sprite` | string | the asset Path to the sprite | +| `color` | string | the normalized RGBA values of your color | +| `material` | string | the asset Path to the Material | +| `url` | string | the URL of the Image you want to show | +| `png` | string | the CRC Checksum of the Image hosted on the Server | + +## Images can be your Backgrounds +the most common use for RawImage is its Ability to display any* Color you give it. therefore it's often used to give Panels a Background Color. Colors are sent as a `string` of 4 normalized `floats` + +Tip: if you're used to using hexadecimal you can use this function to convert your colors on the fly: +```c# +static public string NormalizeHex(string hex, byte alpha = 255){ + if (string.IsNullOrEmpty(hex) || hex.Length < 7) + hex = "#FFFFFF"; + var str = hex.Trim('#'); + + var r = byte.Parse(str.Substring(0, 2), System.Globalization.NumberStyles.HexNumber); + var g = byte.Parse(str.Substring(2, 2), System.Globalization.NumberStyles.HexNumber); + var b = byte.Parse(str.Substring(4, 2), System.Globalization.NumberStyles.HexNumber); + var a = alpha; + // if the hex has alpha encoded, use it instead + if (str.Length >= 8) + a = byte.Parse(str.Substring(6, 2), System.Globalization.NumberStyles.HexNumber); + + return $"{(double)r / 255:f3} {(double)g / 255:f3} {(double)b / 255:f3} {(double)a / 255:f3}"; +} +``` + +Images can also be combined with a Subset of Materials to enhance your UIs, some Materials can be combined with a Color, while others will enforce their own Color. some Materials won't have any visual Effect. +> \* Colors are limited to a Precision of 0.01 per Channel, giving you only 1.000.000 Colors to choose from (excluding the alpha Channel) + +## Using Rust's Sprites +You can re-use any of Rust's Sprites by specifying an asset path in the `sprite` field. + +## Loading your own Images +the RawImage Component has two Ways of displaying your own Images, the first is by downloading the image onto the game Server & supplying the CRC Checksum in the `png` field, and the second is by hosting the image online and supplying a direct link to it in the `url` field + +Loading Images from your Server requires a bit of setup but has the benefit of the Client caching the image once it's loaded from your server, resulting in faster loading times on subsequent UI sends. + +### Loading Images from your Server +to load Images from your own Server you have to download & store the image in Rust's `FileStorage`. + +```c# + +private IEnumerator SaveImageFromURL(string URL){ + using (UnityWebRequest request = UnityWebRequestTexture.GetTexture(URL)){ + // Download your image from the web + yield return request.SendWebRequest(); + + if (uwr.result != UnityWebRequest.Result.Success) + yield break; + + var texture = DownloadHandlerTexture.GetContent(request); + byte[] data = texture.EncodeToPNG(); + + // this CRC is what you send to the client. save it somewhere for later + uint crc = FileStorage.server.Store(data, FileStorage.Type.png, CommunityEntity.ServerInstance.net.ID); + } +} +``` +the rust Client will then automatically fetch the Image from the Server. You will have to re-download the Image every Wipe as the CommunityEntity's netID will differ, which will cause the Client to not find your Image. + +## Combining Images & Color +when using an image you can use the `color` property to modify the image's Color on the fly, this is great when using Icons that are White or Grayscale, as it allows you to communicate Information by changing the Color of the Icon instead of having to load multiple versions. + +--- +before using RawImage, take a look at the Image Component to see if it's better suited for your usecase. +**< [Previous Component](/docs/components/README.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.RawImage.md) >** diff --git a/docs/components/UnityEngine.UI.Text.md b/docs/components/UnityEngine.UI.Text.md new file mode 100644 index 0000000..2b5e8f5 --- /dev/null +++ b/docs/components/UnityEngine.UI.Text.md @@ -0,0 +1,61 @@ +# Components: Text +**< [Previous Component](/docs/components/UnityEngine.UI.Image.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.Outline.md) >** + +- Identifier: `UnityEngine.UI.Text` +- Category: **Visual** +- Unity Documentation: **[Text @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-Text.html)** + +The Text Component is a Visual Component that allows you to display any Text you want. it has Options for Alignment, Color, and overflow Options & Supports RichText. +```json +{ + "type": "UnityEngine.UI.Text", + "text": "Text", + "fontSize": 14, + "font": "RobotoCondensed-Bold.ttf", + "align": "UpperLeft", + "color": "1.0 1.0 1.0 1.0", + "verticalOverflow": "Truncate" +} +``` +Text-specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `text` | string | the Content of your Text Component | +| `fontSize` | int | the default font size of your Text | +| `font` | string | the Asset name of the Font you wish to use | +| `align` | string (enum `TextAnchor`) | the way your Text should be aligned | +| `color` | string | the default Color of your Text | +| `verticalOverflow` | string (enum `VerticalWrapMode`) | how Text Overflowing vertically should be handled | + +### Available Fonts: +- `DroidSansMono.ttf` +- `PermanentMarker.ttf` +- `RobotoCondensed-Bold.ttf` +- `RobotoCondensed-Regular.ttf` + +### Text Alignment Options: +| `UpperLeft` | `UpperCenter` | `UpperRight` | +| ------------ | -------------- | ------------- | +| `MiddleLeft` | `MiddleCenter` | `MiddleRight` | +| `LowerLeft` | `LowerCenter` | `LowerRight` | + + +## Using Unity RichText +Rust Allows you to use Unity **[Rich Text](https://docs.unity3d.com/2021.3/Documentation/Manual/StyledText.html)** to give you more control over text styling. this lets you empathize Paragraphs, Sentences, Words & individual Letters. + +to modify a selection of text, simply wrap it in XML-style tags: `i am bold` +RichText tags can be Nested to combine Effects: `bold and in red` + +Supported Tags: +| **_Tag_** | **_Description_** | **_Example_** | +| :-------: | :----------------- | :------------ | +| **b** | Renders the Text as bold | `I am bold` | +| **i** | Renders the Text as italic | `I am italic` | +| **size** | Sets the fontSize to the Value supplied | `I am small. i am not.` | +| **color** | Changes the Color of the Text | `I am Coffee coloured` | +for colors, Unity Supports an assortment of named Colors you can find in **[this Table](https://docs.unity3d.com/2021.3/Documentation/Manual/StyledText.html#ColorNames).** + + + + +**< [Previous Component](/docs/components/UnityEngine.UI.Image.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.Outline.md) >** From 4d4ddd97b8f3b81c80bd5722392cee2e624dc894 Mon Sep 17 00:00:00 2001 From: Kulltero <33698270+Kulltero@users.noreply.github.com> Date: Wed, 1 Feb 2023 01:37:36 +0100 Subject: [PATCH 2/8] Upload Initial Documentation files Uploading Documentation onto a clean branch because having 557 Stackedit commits doesn't seem sensible --- README.md | 37 +++++++ docs/Basics.md | 62 +++++++++++ docs/Bugs-Tips.md | 118 +++++++++++++++++++++ docs/components/Countdown.md | 39 +++++++ docs/components/NeedsX.md | 19 ++++ docs/components/README.md | 32 ++++++ docs/components/RectTransform.md | 60 +++++++++++ docs/components/UnityEngine.UI.Button.md | 34 ++++++ docs/components/UnityEngine.UI.Image.md | 52 +++++++++ docs/components/UnityEngine.UI.InputField | 46 ++++++++ docs/components/UnityEngine.UI.Outline.md | 27 +++++ docs/components/UnityEngine.UI.RawImage.md | 89 ++++++++++++++++ docs/components/UnityEngine.UI.Text.md | 61 +++++++++++ 13 files changed, 676 insertions(+) create mode 100644 README.md create mode 100644 docs/Basics.md create mode 100644 docs/Bugs-Tips.md create mode 100644 docs/components/Countdown.md create mode 100644 docs/components/NeedsX.md create mode 100644 docs/components/README.md create mode 100644 docs/components/RectTransform.md create mode 100644 docs/components/UnityEngine.UI.Button.md create mode 100644 docs/components/UnityEngine.UI.Image.md create mode 100644 docs/components/UnityEngine.UI.InputField create mode 100644 docs/components/UnityEngine.UI.Outline.md create mode 100644 docs/components/UnityEngine.UI.RawImage.md create mode 100644 docs/components/UnityEngine.UI.Text.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c8f0d01 --- /dev/null +++ b/README.md @@ -0,0 +1,37 @@ +# Rust Community Repository +> This Repository is part of the game Rust. It has no relation to the Programming Language + +Client Code for the `CommunityEntity` Class to fulfill Server-side Modder Requests. +Holds the Custom User Interface System (CUI System), which lets developers create interactable UI through a simple JSON Schema + +## Table of Contents +> Click one of the Topics or dive directly into the Component Documentation +- [The Basics](/docs/Basics.md) +- [Components](/docs/components/README.md) + - [RectTransform](/docs/components/RectTransform.md) + - [RawImage](/docs/components/UnityEngine.UI.RawImage.md) + - [Image](/docs/components/UnityEngine.UI.Image.md) + - [Text](/docs/components/UnityEngine.UI.Text.md) + - [Outline](/docs/components/UnityEngine.UI.Outline.md) + - [Button](/docs/components/UnityEngine.UI.Button.md) + - [InputField](/docs/components/UnityEngine.UI.InputField.md) + - [NeedsCursor & NeedsKeyboard](/docs/components/NeedsX.md) + - [Countdown](/docs/components/Countdown.md) +- [Tips, Bugs & Edgecases](/docs/Bugs-Tips.md) +- [Credits & Acknowledgements](#Credits) + +## Credits +External Contributors & People who improved the CUI System +- [@bawNg](https://github.com/bawNg) - PRs [#1](https://github.com/Facepunch/Rust.Community/pull/1), [#2](https://github.com/Facepunch/Rust.Community/pull/2), [#5](https://github.com/Facepunch/Rust.Community/pull/5) +- [@balu92](https://github.com/balu92) - PRs [#7](https://github.com/Facepunch/Rust.Community/pull/7), [#9](https://github.com/Facepunch/Rust.Community/pull/9) +- [@Jake-Rich](https://github.com/Jake-Rich) - PRs [#16](https://github.com/Facepunch/Rust.Community/pull/16), [#30](https://github.com/Facepunch/Rust.Community/pull/39) +- [@Mughisi](https://github.com/Mughisi) - PRs [#19](https://github.com/Facepunch/Rust.Community/pull/19), [#22](https://github.com/Facepunch/Rust.Community/pull/22) +- [@shooter46](https://github.com/shooter46) - PR [#28](https://github.com/Facepunch/Rust.Community/pull/28) +- [@Alitop](https://github.com/Alitop) - PR [#32](https://github.com/Facepunch/Rust.Community/pull/32) +- [@TactiTac0z](https://github.com/TactiTac0z) - PR [#40](https://github.com/Facepunch/Rust.Community/pull/40) +- [@Kulltero](https://github.com/Kulltero) - PR [#43](https://github.com/Facepunch/Rust.Community/pull/43) +> And of course, Facepunch, who has put a lot of ffort into giving Developers the CUI System & the ability to improve it + +--- +### Disclaimer +the readme & Documentation is Community maintained. It aims to give Developers a starting Point and educate them on effectively using CUIs for their Projects diff --git a/docs/Basics.md b/docs/Basics.md new file mode 100644 index 0000000..b3c348e --- /dev/null +++ b/docs/Basics.md @@ -0,0 +1,62 @@ +# The Basics of CUI +**< [Previous Topic](/README.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/docs/components/README.md) >** + +There are a few basic Concepts that are needed to make your own CUI, below you will learn about what Panels are & how to create and destroy UI Elements + +## The Schema +the JSON Schema to send UI to the Player consists of a List of Elements, where each Element creates a new Panel on the Client. Elements have One or more Components that control the Look & Functionality. + +```json +[{ + "name": "AddUI CreatedPanel", + "parent": "Overlay", + "components": [...], + "fadeOut": 0.0, + "destroyUi": "" +}, ...] +``` +> the values in these JSON examples represent the default Values that are assigned if no property is specified. +> … represent One or more collapsed Objects + +| Key | Type | Notes | +| :-- | :------- | :------------------- | +| `name` | string | the identifier of your panel, needed when destroying UI or adding panels inside this one | +| `parent` | string | tells the client which Panel or Layer to Parent to | +| `components` | List of Components | One or more Components, without these there's no point in sending a panel | +| `fadeOut` | float | makes the Panel fade out instead of disappearing immediately. *Currently doesn't fade out any child Panels* | +| `destroyUi` | string | destroys the Panel specified in the string before creating your Panel. useful for updating UI | + +### About Naming +It's recommended to always name your Panels *something*, this is because the CUI System doesn't support multiple Panels with the same name and may cause *Ghost Panels* which cant be destroyed. + +It's also recommended to prefix the Name of your Panel with something unique to your Mod, which ensures there are no accidental name Conflicts with other Mods + + +## Sending & destroying UI + +There are two RPC Calls you can use to send & destroy UI respectively + +Adding UI: +```c# +BasePlayer player = targetPlayer; +string json = "..."; // your UI in JSON form +var community = CommunityEntity.ServerInstance; +SendInfo sendInfo = new SendInfo(player.net.connection); +community.ClientRPCEx(sendInfo, null, "AddUI", json); +``` + +Destroying UI: +```c# +BasePlayer player = targetPlayer; +string panel = "AddUi CreatedPanel"; // the name of the Panel you wish to destroy +var community = CommunityEntity.ServerInstance; +SendInfo sendInfo = new SendInfo(player.net.connection); +community.ClientRPCEx(sendInfo, null, "DestroyUI", panel); +``` +When destroying a Panel, all child Panels will also get destroyed. +> your Modding Framework may have helper Methods to simplify these steps. + +---- +the next Topic explains Components in detail + +**< [Previous Topic](/README.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/docs/components/README.md) >** diff --git a/docs/Bugs-Tips.md b/docs/Bugs-Tips.md new file mode 100644 index 0000000..af7870d --- /dev/null +++ b/docs/Bugs-Tips.md @@ -0,0 +1,118 @@ +# Bugs & Tips + +**< [Previous Topic](/docs/components/README.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/README.md) >** + +When working with the CUI System you will often encounter weird Bugs & Situations. this document lists some ways to prevent them & shows you additional tricks to enhance your UIs + +## Table of Contents +- [Common Error Messages](#common-error-messages) +- [Bugs](#bugs) +- [Tricks](#tricks) + +# Common Error Messages +> these errors will appear in your client console when testing the UI, make sure to test for these before releasing your mod + +### AddUI: Unknown Parent for *name*: *parent* +this happens when the parent you supplied in your panel Payload doesn't exist. double-check for spelling mistakes, and formatting issues & ensure your parent appears in your JSON list before the Panel you get this error on. + + + +--- + +### Error downloading image: *URL* ( *error* ) +the Client couldn't download your Image, double check your URL & look at the error part within the brackets for what could cause it. + + + +--- + +### A GameObject can only contain one 'Graphic' component. +this error indicates that you're trying to add multiple Unity Components that Derive from `UnityEngine.UI.Graphic`. the **[Components](/docs/components/README.md)** topic has a list of allowed Components and lists the categories they are in. any Component of the **Visual** Category is a Component that derives from or adds a `UnityEngine.UI.Graphic` to the Panel. to get around this Limitation you can put other Visual Components on a child Panel instead. + +# Bugs + +### Orphaned UI Panels, UI that Can't be Destroyed, or Ghost Panels. +**Symptom:** you have 1 or more Panels that are stuck on your Screen and can't be removed by Calling **DestroyUI** with their Name. + +**Cause:** you have 2 or more Panels that shared the same Name & were active at the same time. if these are parented directly to a Layer and one is destroyed the other Panel Can't be destroyed anymore. the only way to remove the UI Panel from your Screen is by reconnecting. double-check your UI and ensure any Panel directly parented to a Layer has a unique Name. also, ensure that you don't accidentally send the same UI twice. + + + +--- + +### Flickering when destroying & re-sending UI on the same frame. +**Symptom:** when updating Part of your UI. the Player gets a noticeable Delay between the old UI being destroyed & the new UI being created. + +**Cause:** the presumed cause of this issue is the Server Delaying your AddUI Packet to the next Network Cycle. this happens very unpredictably but is more likely with larger UI Updates. the solution is to use the `destroyUi` field on your panel Payload, it works the same way a DestroyUI call works, but is combined with your panel Payload to prevent network scheduling from creating the Flickering issue. + + + +--- + +### Very Inconsistent Alpha handling for images +**Symptom:** when using Images with somewhat transparent pixels the images get rendered more Opaque than they are, resulting in heavy artifacts. +**Linked Issue:** **[#42 - Rust has an Opacity Issue](https://github.com/Facepunch/Rust.Community/issues/42)** + +**Cause:** no known Cause or Workaround found. vote on the Linked issue if you encounter this bug or have more info as to why this might happen + + + +--- + +### Panels with a blur Material & Transparency cause underlying Panels to be invisible. +**Symptom:** when using a burry Material on a Color with Transparency, any underlying Image Components with blur get cut out. +**Visual Example:** +![image](https://user-images.githubusercontent.com/33698270/215882128-d1f0798c-d7ed-4986-9675-4fba48632ad7.png) +> an image of the following UI setup +> parent: black with 98% alpha +> +> square 1: child of Parent, gray with 20% alpha +> +> square 2: child of Parent, gray with 100% alpha +> +> square 3: child of Parent, gray with 20% alpha and a text element behind it. + + +**Cause:** no exact Cause is known, but it seems to be related to the blurry Materials themselves. this bug only occurs when all underlying Images are using a blurry material with transparency. if at least 1 element is opaque the bug does not occur. this can be a text or image element. + + + +# Tricks + +### Use Outlines like an advanced User +Outlines can go way beyond the basic use case of putting them on your square Panels. applying Outlines to Text can be a great way to make them stand out, for example when you can't control the background behind it. +![image](https://user-images.githubusercontent.com/33698270/215885917-4916ee09-a891-4609-82a4-51bb07881bde.png) + +> can you read this? + +![image](https://user-images.githubusercontent.com/33698270/215886796-346be279-2d8e-43c4-a28f-f740bcf50ff5.png) + +> adding a 1px outline with a darker color makes it much clearer. + +Another advanced trick is stacking Outlines with lowered Opacity to create a staggered outline or glow/shadow effect. unlike **Visual** Components, the Outline Component doesn't derive from `UnityEngine.UI.Graphic`, meaning there's no limit on how many Outlines a Panel can have. + +![image](https://user-images.githubusercontent.com/33698270/215899049-e0aa0cd7-b607-466e-a0b7-0cfafa62bdae.png) + +> right has no outlines. left is simulating a 3D effect using 3 stacked Outlines with low opacity. looks great in certain scenarios. + + +--- + +### Positioning your CUI alongside rust UI +for features that augment Rust's existing UI, like when you're working with Furnaces & other storage Inventories, its important to make sure your CUI doesn't interfere with the UI you augment. + +Rust UI uses the same Placement system CUI does. it anchors all of the UI to the Bottom Middle of the Screen and then uses offsets to position each element. by doing the same you can ensure that your CUI is positioned properly, regardless of Screensize & Aspect Ratio. + +a RectTransform Example that covers the Belt-bar +```json +{ + "type": "RectTransform", + "anchormin": "0.5 0.0", + "anchormax": "0.5 0.0", + "offsetmin": "-200 18", + "offsetmax": "180 78" +} +``` +![image](https://user-images.githubusercontent.com/33698270/215901408-c152fecb-8453-4597-8cd6-61038b2b976d.png) + +**< [Previous Topic](/docs/components/README.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/README.md) >** diff --git a/docs/components/Countdown.md b/docs/components/Countdown.md new file mode 100644 index 0000000..dd27305 --- /dev/null +++ b/docs/components/Countdown.md @@ -0,0 +1,39 @@ +# Components: Countdown +**< [Previous Component](/docs/components/NeedsX.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/README.md) >** + +- Identifier: `Countdown` +- Category: **Misc** +- Unity Documentation: **N/A** + +The Countdown Component lets you turn an existing Text Component into a Timer, Countdown, or Count-up. the Countdown Component automatically **destroys** the Panel when it's done counting. +```json +{ + "type": "Countdown", + "endtime": 0, + "startTime": 0, + "step": 1, + "command": "" +} +``` + +Countdown-specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `endTime` | int | the Number it should count to | +| `startTime` | int | the Number it should start counting from | +| `step` | int | the Number it should increment by, also acts as the update interval | +| `command` | string | the Command that should be executed when the Countdown finishes. | + +## Working with Countdowns +for Countdowns to work you need to add a **[Text](/docs/components/UnityEngine.UI.Text.md)** Component to your Panel. your Text Component's content should include the string `%TIME_LEFT%`, which the Countdown will replace with the current Number. + +Examples: +- `the Event will end in %TIME_LEFT% Seconds` => the Event Will end in 30 Seconds +- `Power-up Buff - %TIME_LEFT%s` => Power-up Buff - 30s + +### Counting Up vs counting Down +- to count Down set your `startTime` higher than your `endTime` & set your `step` to at least 1. +- to count Up set your `startTime` lower than your `endTime` + + +**< [Previous Component](/docs/components/NeedsX.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/README.md) >** diff --git a/docs/components/NeedsX.md b/docs/components/NeedsX.md new file mode 100644 index 0000000..4b41a46 --- /dev/null +++ b/docs/components/NeedsX.md @@ -0,0 +1,19 @@ +# Components: NeedsCursor & NeedsKeyboard +**< [Previous Component](/docs/components/UnityEngine.UI.InputField.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/Countdown.md) >** + +- Identifier: `NeedsCursor` or `NeedsKeyboard` +- Category: **Misc** +- Unity Documentation: **N/A** + +The NeedsCursor & NeedsKeyboard Components are Components with no additional Fields. Their only purpose is to tell Rust's input Controller if mouse & keyboard Behavior should only be focused on your UI. +```json +{ + "type": "NeedsCursor" + // or + "type": "NeedsKeyboard" +} +``` + +unlike the `needsKeyboard` and `hudMenuInput` fields on an InputField Component, these Components Prevent default Behavior until your Panel is Destroyed + +**< [Previous Component](/docs/components/UnityEngine.UI.InputField.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/Countdown.md) >** diff --git a/docs/components/README.md b/docs/components/README.md new file mode 100644 index 0000000..f2a1a3e --- /dev/null +++ b/docs/components/README.md @@ -0,0 +1,32 @@ +# Components +**< [Previous Topic](/docs/Basics.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/docs/Tips-Pitfalls.md) >** + +The CUI System comes with a Set of Components you can use to build your UI, some are visual, and others add Interactivity. + +Components are added to a Panel by sending them as a List in the Schema shown in [The Basics](/docs/Basics.md). to identify the Type of Component sent, a `type` Field is added by every Component +```json +[{ + "type": "UnityEngine.UI.Text", + // More Component fields ... +}, +...] +``` + +## Component List +- [RectTransform](/docs/components/RectTransform.md) +- [RawImage](/docs/components/UnityEngine.UI.RawImage.md) +- [Image](/docs/components/UnityEngine.UI.Image.md) +- [Text](/docs/components/UnityEngine.UI.Text.md) +- [Outline](/docs/components/UnityEngine.UI.Outline.md) +- [Button](/docs/components/UnityEngine.UI.Button.md) +- [InputField](/docs/components/UnityEngine.UI.InputField.md) +- [NeedsCursor & NeedsKeyboard](/docs/components/NeedsX.md) +- [Countdown](/docs/components/Countdown.md) + +## About Component Categories +Each Component Page has a *Category* listed, which helps you identify what a Component does. pay attention to the **Visual** Category, as it means the Component Adds a Unity Component deriving from `UnityEngine.UI.Graphic`. This is important because **each Panel can only have 1 Graphic Component**. + +--- +The next Topic explains common Pitfalls & Things you need to look out for + +**< [Previous Topic](/docs/Basics.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/docs/Bugs-Tips.md) >** diff --git a/docs/components/RectTransform.md b/docs/components/RectTransform.md new file mode 100644 index 0000000..182d226 --- /dev/null +++ b/docs/components/RectTransform.md @@ -0,0 +1,60 @@ +# Components: RectTransform +**< [Previous Component](/docs/components/README.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.RawImage.md) >** + +- Identifier: `RectTransform` +- Category: **Position** +- Unity Documentation: **[RectTransform @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/class-RectTransform.html)** + +The RectTransform is a Component that specifies the Position & Size of the Panel it's attached to. +it allows you to position a Panel via [Anchors & Offsets](#anchors-and-offsets). +```json +{ + "type": "RectTransform", + "anchormin": "0.0 0.0", + "anchormax": "1.0 1.0", + "offsetmin": "0.0 0.0", + "offsetmax": "1.0 1.0", +} +``` +RectTransform specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `anchormin` | string | specifies the anchor for the bottom left Corner | +| `anchormax` | string | specifies the anchor for the top right Corner | +| `offsetmin` | string | specifies the Pixel offset for the bottom left Corner | +| `offsetmax` | string | specifies the Pixel offset for the top right Corner | + +both Anchors & Offsets come with a *-min* and *-max* Field, where the min holds x & y Values for the bottom left Corner & the max holds x & y Values for the top right Corner + +## Positioning in Rust +a Panel's Position is always relative to its Parent, even when parenting directly to a Layer. +Unity's Coordinate System in a 2D Space goes from Left to Right, Bottom to Top. +| `x 0.0 y 1.0` | `x 1.0 y 1.0` | +| ------------- | ------------- | +| `x 0.0 y 0.0` | `x 1.0 y 0.0` | +> this might be confusing to people coming from the web-design space, where the x coordinate commonly goes down the screen instead of up + +## Anchors and Offsets +Anchors Specify where your Panel starts & ends. Offsets let you move the start & end Points with pixel Values. + +Anchors use a normalized Percentage of the Parent, where `0.0` is the Start and `1.0` is the End. [The "Anchors" Section](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/UIBasicLayout.html#anchors) in the Unity Documentation has some visual examples which also apply here. + +Offsets use [scaled](#offsets-and-scaling) pixel Values to move the Corners relative to the Anchors you provide. + +Positioning using only Anchors is great for when you want your Panel to cover a Percentage of the Screen or Parent, but for any other cases, a mixture of Anchors & Offsets should be used to Position your UI. + +A common Technique is to use Anchors to specify what part of the Parent the UI should be anchored to (Top Left Corner or Dead Center. Etc.) and to use Offsets for Size & Position. + +## Offsets and Scaling +Rust will automatically scale Offsets depending on the Player's Resolution, which ensures your Offsets are predictable. + +By default, Rust handles Offsets based on a Resolution of **1280** by **720**. This means that for smaller & larger **16:9** Resolutions Rust will simply multiply Offsets by the difference between the Player's Resolution and 720p, + +For non-16:9 Resolutions such as Ultrawide or windowed Mode, Rust will apply Letterboxing before calculating the scaling Factor + + +https://user-images.githubusercontent.com/33698270/214582004-c695e73c-9125-4ccb-9cfb-abc883b5c0a0.mp4 +> a video of a gray Rectangle positioned at the Center of the Screen (anchor min & max at `0.5 0.5`) with an offset of 1280 x 720 px. see how Unity applies Letterboxing before scaling the Rectangle to ensure it never gets stretched. NOTE: the black Bars are only to illustrate in this Example, your ingame UI won't have any black Bars + + +**< [Previous Component](/docs/components/README.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.RawImage.md) >** diff --git a/docs/components/UnityEngine.UI.Button.md b/docs/components/UnityEngine.UI.Button.md new file mode 100644 index 0000000..5ae304b --- /dev/null +++ b/docs/components/UnityEngine.UI.Button.md @@ -0,0 +1,34 @@ +# Components: Button +**< [Previous Component](/docs/components/UnityEngine.UI.Outline.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.InputField.md) >** + +- Identifier: `UnityEngine.UI.Button` +- Category: **Interactive, Visual** +- Unity Documentation: **[Button @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-Button.html)** + +The Button Component is an Interactive Component that lets you execute Commands & Destroy UI when it gets pressed. it automatically adds a `UnityEngine.UI.Image` to the panel, allowing you to change the `sprite`, `material` & `color` on it +```json +{ + "type": "UnityEngine.UI.Button", + "command": "", + "close": "", + "sprite": "Assets/Icons/rust.png", + "color": "1.0 1.0 1.0 1.0", + "material": "", + "imagetype": "Simple" +} +``` +Button-specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `command` | string | the Command that should get sent to the Server on Click | +| `close` | string | the Name of the Panel that should get closed on Click | +| `sprite` | string | the asset Path to the sprite | +| `color` | string | the normalized RGBA values of your color | +| `material` | string | the asset Path to the Material | +| `imagetype` | string (enum `Image.Type`) | sets the display mode of the Image* | +\* Currently non-functioning for anything other than Rust's built-in Sprites + +### Button as a Parent +click events bubble up, meaning that they will get triggered on every Panel until a Component consumes them. This means it's possible to use the Button as a Parent and still get notified when the Player clicks a child Panel. + +**< [Previous Component](/docs/components/UnityEngine.UI.Outline.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.InputField.md) >** diff --git a/docs/components/UnityEngine.UI.Image.md b/docs/components/UnityEngine.UI.Image.md new file mode 100644 index 0000000..d78292e --- /dev/null +++ b/docs/components/UnityEngine.UI.Image.md @@ -0,0 +1,52 @@ +# Components: Image +**< [Previous Component](/docs/components/UnityEngine.UI.RawImage.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.Text.md) >** + +- Identifier: `UnityEngine.UI.Image` +- Category: **Visual** +- Unity Documentation: **[Image @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-Image.html)** + +The Image is a Visual Component that allows you to display Images from your Server & the Web or Rust Sprites. it can also be used with a single color to act as a Background for your panel +```json +{ + "type": "UnityEngine.UI.Image", + "sprite": "Assets/Icons/rust.png", + "color": "1.0 1.0 1.0 1.0", + "material": "", + "imagetype": "Simple", + "png": "", + "itemid": 0, + "skinid": 0 +} +``` +RawImage specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `sprite` | string | the asset Path to the sprite | +| `color` | string | the normalized RGBA values of your color | +| `material` | string | the asset Path to the Material | +| `imagetype` | string (enum `Image.Type`) | sets the display mode of the Image* | +| `png` | string | the CRC Checksum of the Image hosted on the Server | +| `itemid` | int | the Item ID of your item | +| `skinid` | ulong | the Skin ID of your skin | + +\* Currently non-functioning for anything other than Rust's built-in Sprites +## RawImages vs Images +Like RawImages, Images share the ability to show Sprites, Colors, Materials & Images hosted on the Server, but they cannot directly load Images from the Web. + +The Image Component has convenient Ways to display any Item or Skin and is recommended when using Rust's Sprites. + +## Items and Skins +using the `itemid` & `skinid` fields you can let the Client handle the displaying of related Images. + +Tip: use the ItemDefinition of your Item to easily find an Item's ID & other useful Information +```c# +string shortname = "your.item.shortname"; +var itemDef = ItemManager.FindItemDefinition(shortname); +int itemid = itemDef.itemid; +// other useful Fields: displayName, displayDescription, category & stackable +``` + + +--- +check the [RawImage](/docs/components/UnityEngine.UI.RawImage.md) Documentation to learn about Fields the Components share. +**< [Previous Component](/docs/components/UnityEngine.UI.RawImage.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.Text.md) >** diff --git a/docs/components/UnityEngine.UI.InputField b/docs/components/UnityEngine.UI.InputField new file mode 100644 index 0000000..b1ab472 --- /dev/null +++ b/docs/components/UnityEngine.UI.InputField @@ -0,0 +1,46 @@ +# Components: InputField +**< [Previous Component](/docs/components/UnityEngine.UI.Button.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/NeedsX.md) >** + +- Identifier: `UnityEngine.UI.InputField` +- Category: **Interactive, Visual** +- Unity Documentation: **[InputField @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-InputField.html)** + +The InputField Component is an Interactive Component that allows Players to enter arbitrary text that gets sent back as a Command. it automatically adds a `UnityEngine.UI.Text` to the panel, allowing you to change the `fontSize`, `font`, `align`ment & text`color` of it +```json +{ + "type": "UnityEngine.UI.InputField", + "fontSize": 14, + "font": "RobotoCondensed-Bold.ttf", + "align": "UpperLeft", + "color": "1.0 1.0 1.0 1.0", + "command": "", + "text": "", + "readOnly": false, + "lineType": "SingleLine", + "password": null, + "needsKeyboard": null, + "hudMenuInput": null, + "autofocus": null, +} +``` +> `password`, `needsKeyboard`, `hudMenuInput`, and `autofocus` are key presence Fields, key presence Fields don't have a specific type and act as a Boolean. +> if the key is present it equals true, if absent it equals false. + +InputField specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `command` | string | the Command that should get sent to the Server alongside the Player's Input. The Input will get appended to the Command after a Space. | +| `text` | string | the default Text of the InputField can be combined with `readOnly` | +| `readOnly` | bool | prevents the Content from being edited | +| `lineType` | string (enum `InputField.LineType`) | dictates if the Field should allow multiple Lines & how to handle when the Player presses `enter` | +| `password` | key presence Field | if the input should be obscured | +| `needsKeyboard` | key presence Field | prevents default Keyboard behavior (movement, item switching etc) while the field is Focused | +| `hudMenuInput` | key presence Field | same as above but for Rust UI (Inventory, Crafting, etc.) | +| `autofocus` | key presence Field | selects the field upon creation | + +### Receiving Input & the lineType Setting +to receive the Player's input Text, listen for the Command you specify in the `command` field. the Input will get sent as soon as the Player unfocuses the InputField, for example by clicking out of it. + +depending on the `lineType` Setting, if it's set to SingleLine or MultiLineSubmit pressing `enter` will also cause the Input to get sent to the Server. Pressing `enter` with the MultiLineNewline Setting inserts a Newline instead. + +**< [Previous Component](/docs/components/UnityEngine.UI.Button.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/NeedsX.md) >** diff --git a/docs/components/UnityEngine.UI.Outline.md b/docs/components/UnityEngine.UI.Outline.md new file mode 100644 index 0000000..6b8f1da --- /dev/null +++ b/docs/components/UnityEngine.UI.Outline.md @@ -0,0 +1,27 @@ +# Components: Outline +**< [Previous Component](/docs/components/UnityEngine.UI.Text.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.Button.md) >** + +- Identifier: `UnityEngine.UI.Outline` +- Category: **Effect** +- Unity Documentation: **[Outline @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-Outline.html)** + +The Outline Component is an Effect Component that puts a colored outline on any Visual Component. it supports any Image, Text, Button, or Input field. +```json +{ + "type": "UnityEngine.UI.Outline", + "color": "1.0 1.0 1.0 1.0", + "distance": "1.0 -1.0", + "useGraphicAlpha": null +} +``` +> `useGraphicAlpha` is a key presence Field, key presence Fields don't have a specific type and act as a Boolean. +> if the key is present it equals true, if absent it equals false. + +Outline specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `color` | string | the Color of your Outline | +| `distance` | string | the distance of your Outline (formatted as `X Y`) | +| `useGraphicAlpha` | key presence Field | multiplies the Alpha of the graphic onto the color of the Outline | + +**< [Previous Component](/docs/components/UnityEngine.UI.Text.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.Button.md) >** diff --git a/docs/components/UnityEngine.UI.RawImage.md b/docs/components/UnityEngine.UI.RawImage.md new file mode 100644 index 0000000..3711091 --- /dev/null +++ b/docs/components/UnityEngine.UI.RawImage.md @@ -0,0 +1,89 @@ +# Components: RawImage +**< [Previous Component](/docs/components/RectTransform.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.Image.md) >** + +- Identifier: `UnityEngine.UI.RawImage` +- Category: **Visual** +- Unity Documentation: **[RawImage @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-RawImage.html)** + +The RawImage is a Visual Component that allows you to display Images from your Server & the Web or Rust Sprites. it can also be used with a single color to act as a Background for your panel +```json +{ + "type": "UnityEngine.UI.RawImage", + "sprite": "Assets/Icons/rust.png", + "color": "1.0 1.0 1.0 1.0", + "material": "", + "url": "", + "png": "" +} +``` +RawImage specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `sprite` | string | the asset Path to the sprite | +| `color` | string | the normalized RGBA values of your color | +| `material` | string | the asset Path to the Material | +| `url` | string | the URL of the Image you want to show | +| `png` | string | the CRC Checksum of the Image hosted on the Server | + +## Images can be your Backgrounds +the most common use for RawImage is its Ability to display any* Color you give it. therefore it's often used to give Panels a Background Color. Colors are sent as a `string` of 4 normalized `floats` + +Tip: if you're used to using hexadecimal you can use this function to convert your colors on the fly: +```c# +static public string NormalizeHex(string hex, byte alpha = 255){ + if (string.IsNullOrEmpty(hex) || hex.Length < 7) + hex = "#FFFFFF"; + var str = hex.Trim('#'); + + var r = byte.Parse(str.Substring(0, 2), System.Globalization.NumberStyles.HexNumber); + var g = byte.Parse(str.Substring(2, 2), System.Globalization.NumberStyles.HexNumber); + var b = byte.Parse(str.Substring(4, 2), System.Globalization.NumberStyles.HexNumber); + var a = alpha; + // if the hex has alpha encoded, use it instead + if (str.Length >= 8) + a = byte.Parse(str.Substring(6, 2), System.Globalization.NumberStyles.HexNumber); + + return $"{(double)r / 255:f3} {(double)g / 255:f3} {(double)b / 255:f3} {(double)a / 255:f3}"; +} +``` + +Images can also be combined with a Subset of Materials to enhance your UIs, some Materials can be combined with a Color, while others will enforce their own Color. some Materials won't have any visual Effect. +> \* Colors are limited to a Precision of 0.01 per Channel, giving you only 1.000.000 Colors to choose from (excluding the alpha Channel) + +## Using Rust's Sprites +You can re-use any of Rust's Sprites by specifying an asset path in the `sprite` field. + +## Loading your own Images +the RawImage Component has two Ways of displaying your own Images, the first is by downloading the image onto the game Server & supplying the CRC Checksum in the `png` field, and the second is by hosting the image online and supplying a direct link to it in the `url` field + +Loading Images from your Server requires a bit of setup but has the benefit of the Client caching the image once it's loaded from your server, resulting in faster loading times on subsequent UI sends. + +### Loading Images from your Server +to load Images from your own Server you have to download & store the image in Rust's `FileStorage`. + +```c# + +private IEnumerator SaveImageFromURL(string URL){ + using (UnityWebRequest request = UnityWebRequestTexture.GetTexture(URL)){ + // Download your image from the web + yield return request.SendWebRequest(); + + if (uwr.result != UnityWebRequest.Result.Success) + yield break; + + var texture = DownloadHandlerTexture.GetContent(request); + byte[] data = texture.EncodeToPNG(); + + // this CRC is what you send to the client. save it somewhere for later + uint crc = FileStorage.server.Store(data, FileStorage.Type.png, CommunityEntity.ServerInstance.net.ID); + } +} +``` +the rust Client will then automatically fetch the Image from the Server. You will have to re-download the Image every Wipe as the CommunityEntity's netID will differ, which will cause the Client to not find your Image. + +## Combining Images & Color +when using an image you can use the `color` property to modify the image's Color on the fly, this is great when using Icons that are White or Grayscale, as it allows you to communicate Information by changing the Color of the Icon instead of having to load multiple versions. + +--- +before using RawImage, take a look at the Image Component to see if it's better suited for your usecase. +**< [Previous Component](/docs/components/README.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.RawImage.md) >** diff --git a/docs/components/UnityEngine.UI.Text.md b/docs/components/UnityEngine.UI.Text.md new file mode 100644 index 0000000..2b5e8f5 --- /dev/null +++ b/docs/components/UnityEngine.UI.Text.md @@ -0,0 +1,61 @@ +# Components: Text +**< [Previous Component](/docs/components/UnityEngine.UI.Image.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.Outline.md) >** + +- Identifier: `UnityEngine.UI.Text` +- Category: **Visual** +- Unity Documentation: **[Text @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-Text.html)** + +The Text Component is a Visual Component that allows you to display any Text you want. it has Options for Alignment, Color, and overflow Options & Supports RichText. +```json +{ + "type": "UnityEngine.UI.Text", + "text": "Text", + "fontSize": 14, + "font": "RobotoCondensed-Bold.ttf", + "align": "UpperLeft", + "color": "1.0 1.0 1.0 1.0", + "verticalOverflow": "Truncate" +} +``` +Text-specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `text` | string | the Content of your Text Component | +| `fontSize` | int | the default font size of your Text | +| `font` | string | the Asset name of the Font you wish to use | +| `align` | string (enum `TextAnchor`) | the way your Text should be aligned | +| `color` | string | the default Color of your Text | +| `verticalOverflow` | string (enum `VerticalWrapMode`) | how Text Overflowing vertically should be handled | + +### Available Fonts: +- `DroidSansMono.ttf` +- `PermanentMarker.ttf` +- `RobotoCondensed-Bold.ttf` +- `RobotoCondensed-Regular.ttf` + +### Text Alignment Options: +| `UpperLeft` | `UpperCenter` | `UpperRight` | +| ------------ | -------------- | ------------- | +| `MiddleLeft` | `MiddleCenter` | `MiddleRight` | +| `LowerLeft` | `LowerCenter` | `LowerRight` | + + +## Using Unity RichText +Rust Allows you to use Unity **[Rich Text](https://docs.unity3d.com/2021.3/Documentation/Manual/StyledText.html)** to give you more control over text styling. this lets you empathize Paragraphs, Sentences, Words & individual Letters. + +to modify a selection of text, simply wrap it in XML-style tags: `i am bold` +RichText tags can be Nested to combine Effects: `bold and in red` + +Supported Tags: +| **_Tag_** | **_Description_** | **_Example_** | +| :-------: | :----------------- | :------------ | +| **b** | Renders the Text as bold | `I am bold` | +| **i** | Renders the Text as italic | `I am italic` | +| **size** | Sets the fontSize to the Value supplied | `I am small. i am not.` | +| **color** | Changes the Color of the Text | `I am Coffee coloured` | +for colors, Unity Supports an assortment of named Colors you can find in **[this Table](https://docs.unity3d.com/2021.3/Documentation/Manual/StyledText.html#ColorNames).** + + + + +**< [Previous Component](/docs/components/UnityEngine.UI.Image.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.Outline.md) >** From 8cb074fa1a936ce415c8bbac5937b0bd14b3c8f8 Mon Sep 17 00:00:00 2001 From: Kulltero <33698270+Kulltero@users.noreply.github.com> Date: Wed, 1 Feb 2023 04:26:50 +0100 Subject: [PATCH 3/8] fix InputField file name --- .../{UnityEngine.UI.InputField => UnityEngine.UI.InputField.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/components/{UnityEngine.UI.InputField => UnityEngine.UI.InputField.md} (100%) diff --git a/docs/components/UnityEngine.UI.InputField b/docs/components/UnityEngine.UI.InputField.md similarity index 100% rename from docs/components/UnityEngine.UI.InputField rename to docs/components/UnityEngine.UI.InputField.md From dd550803561cd4afaeabbeaf047da9640654f61e Mon Sep 17 00:00:00 2001 From: Kulltero <33698270+Kulltero@users.noreply.github.com> Date: Wed, 1 Feb 2023 06:13:22 +0100 Subject: [PATCH 4/8] Fix InputField, Add fadeIn Fixed InputField name & added section about Text Selection added notice explaining the default values in the json examples --- docs/components/Countdown.md | 2 + docs/components/RectTransform.md | 2 + docs/components/UnityEngine.UI.Button.md | 7 ++- docs/components/UnityEngine.UI.Image.md | 9 +++- docs/components/UnityEngine.UI.InputField | 46 ++++++++++++++++++++ docs/components/UnityEngine.UI.InputField.md | 10 +++++ docs/components/UnityEngine.UI.Outline.md | 1 + docs/components/UnityEngine.UI.RawImage.md | 9 +++- docs/components/UnityEngine.UI.Text.md | 7 ++- 9 files changed, 87 insertions(+), 6 deletions(-) create mode 100644 docs/components/UnityEngine.UI.InputField diff --git a/docs/components/Countdown.md b/docs/components/Countdown.md index dd27305..7dd7e88 100644 --- a/docs/components/Countdown.md +++ b/docs/components/Countdown.md @@ -15,6 +15,8 @@ The Countdown Component lets you turn an existing Text Component into a Timer, C "command": "" } ``` +> the values in these JSON examples represent the default Values that are assigned if no property is specified. + Countdown-specific Fields: | Key | Type | Notes | diff --git a/docs/components/RectTransform.md b/docs/components/RectTransform.md index 182d226..733afac 100644 --- a/docs/components/RectTransform.md +++ b/docs/components/RectTransform.md @@ -16,6 +16,8 @@ it allows you to position a Panel via [Anchors & Offsets](#anchors-and-offsets). "offsetmax": "1.0 1.0", } ``` +> the values in these JSON examples represent the default Values that are assigned if no property is specified. + RectTransform specific Fields: | Key | Type | Notes | | :---------- | :----- | :------------------- | diff --git a/docs/components/UnityEngine.UI.Button.md b/docs/components/UnityEngine.UI.Button.md index 5ae304b..ce65397 100644 --- a/docs/components/UnityEngine.UI.Button.md +++ b/docs/components/UnityEngine.UI.Button.md @@ -14,9 +14,13 @@ The Button Component is an Interactive Component that lets you execute Commands "sprite": "Assets/Icons/rust.png", "color": "1.0 1.0 1.0 1.0", "material": "", - "imagetype": "Simple" + "imagetype": "Simple", + "fadeIn": 0.0 } ``` +> the values in these JSON examples represent the default Values that are assigned if no property is specified. + + Button-specific Fields: | Key | Type | Notes | | :---------- | :----- | :------------------- | @@ -26,6 +30,7 @@ Button-specific Fields: | `color` | string | the normalized RGBA values of your color | | `material` | string | the asset Path to the Material | | `imagetype` | string (enum `Image.Type`) | sets the display mode of the Image* | +| `fadeIn` | float | the Duration the Panel should take to fade in | \* Currently non-functioning for anything other than Rust's built-in Sprites ### Button as a Parent diff --git a/docs/components/UnityEngine.UI.Image.md b/docs/components/UnityEngine.UI.Image.md index d78292e..e2ee056 100644 --- a/docs/components/UnityEngine.UI.Image.md +++ b/docs/components/UnityEngine.UI.Image.md @@ -15,9 +15,13 @@ The Image is a Visual Component that allows you to display Images from your Serv "imagetype": "Simple", "png": "", "itemid": 0, - "skinid": 0 + "skinid": 0, + "fadeIn": 0.0 } ``` +> the values in these JSON examples represent the default Values that are assigned if no property is specified. + + RawImage specific Fields: | Key | Type | Notes | | :---------- | :----- | :------------------- | @@ -28,7 +32,7 @@ RawImage specific Fields: | `png` | string | the CRC Checksum of the Image hosted on the Server | | `itemid` | int | the Item ID of your item | | `skinid` | ulong | the Skin ID of your skin | - +| `fadeIn` | float | the Duration the Panel should take to fade in | \* Currently non-functioning for anything other than Rust's built-in Sprites ## RawImages vs Images Like RawImages, Images share the ability to show Sprites, Colors, Materials & Images hosted on the Server, but they cannot directly load Images from the Web. @@ -37,6 +41,7 @@ The Image Component has convenient Ways to display any Item or Skin and is recom ## Items and Skins using the `itemid` & `skinid` fields you can let the Client handle the displaying of related Images. +NOTE: there is currently a bug when supplying a skinid of `0`, causing the player to crash, avoid including the field altogether if you don't intend to send a skinid Tip: use the ItemDefinition of your Item to easily find an Item's ID & other useful Information ```c# diff --git a/docs/components/UnityEngine.UI.InputField b/docs/components/UnityEngine.UI.InputField new file mode 100644 index 0000000..b1ab472 --- /dev/null +++ b/docs/components/UnityEngine.UI.InputField @@ -0,0 +1,46 @@ +# Components: InputField +**< [Previous Component](/docs/components/UnityEngine.UI.Button.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/NeedsX.md) >** + +- Identifier: `UnityEngine.UI.InputField` +- Category: **Interactive, Visual** +- Unity Documentation: **[InputField @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-InputField.html)** + +The InputField Component is an Interactive Component that allows Players to enter arbitrary text that gets sent back as a Command. it automatically adds a `UnityEngine.UI.Text` to the panel, allowing you to change the `fontSize`, `font`, `align`ment & text`color` of it +```json +{ + "type": "UnityEngine.UI.InputField", + "fontSize": 14, + "font": "RobotoCondensed-Bold.ttf", + "align": "UpperLeft", + "color": "1.0 1.0 1.0 1.0", + "command": "", + "text": "", + "readOnly": false, + "lineType": "SingleLine", + "password": null, + "needsKeyboard": null, + "hudMenuInput": null, + "autofocus": null, +} +``` +> `password`, `needsKeyboard`, `hudMenuInput`, and `autofocus` are key presence Fields, key presence Fields don't have a specific type and act as a Boolean. +> if the key is present it equals true, if absent it equals false. + +InputField specific Fields: +| Key | Type | Notes | +| :---------- | :----- | :------------------- | +| `command` | string | the Command that should get sent to the Server alongside the Player's Input. The Input will get appended to the Command after a Space. | +| `text` | string | the default Text of the InputField can be combined with `readOnly` | +| `readOnly` | bool | prevents the Content from being edited | +| `lineType` | string (enum `InputField.LineType`) | dictates if the Field should allow multiple Lines & how to handle when the Player presses `enter` | +| `password` | key presence Field | if the input should be obscured | +| `needsKeyboard` | key presence Field | prevents default Keyboard behavior (movement, item switching etc) while the field is Focused | +| `hudMenuInput` | key presence Field | same as above but for Rust UI (Inventory, Crafting, etc.) | +| `autofocus` | key presence Field | selects the field upon creation | + +### Receiving Input & the lineType Setting +to receive the Player's input Text, listen for the Command you specify in the `command` field. the Input will get sent as soon as the Player unfocuses the InputField, for example by clicking out of it. + +depending on the `lineType` Setting, if it's set to SingleLine or MultiLineSubmit pressing `enter` will also cause the Input to get sent to the Server. Pressing `enter` with the MultiLineNewline Setting inserts a Newline instead. + +**< [Previous Component](/docs/components/UnityEngine.UI.Button.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/NeedsX.md) >** diff --git a/docs/components/UnityEngine.UI.InputField.md b/docs/components/UnityEngine.UI.InputField.md index b1ab472..6899bf5 100644 --- a/docs/components/UnityEngine.UI.InputField.md +++ b/docs/components/UnityEngine.UI.InputField.md @@ -21,8 +21,11 @@ The InputField Component is an Interactive Component that allows Players to ente "needsKeyboard": null, "hudMenuInput": null, "autofocus": null, + "fadeIn": 0.0 } ``` +> the values in these JSON examples represent the default Values that are assigned if no property is specified. + > `password`, `needsKeyboard`, `hudMenuInput`, and `autofocus` are key presence Fields, key presence Fields don't have a specific type and act as a Boolean. > if the key is present it equals true, if absent it equals false. @@ -37,6 +40,13 @@ InputField specific Fields: | `needsKeyboard` | key presence Field | prevents default Keyboard behavior (movement, item switching etc) while the field is Focused | | `hudMenuInput` | key presence Field | same as above but for Rust UI (Inventory, Crafting, etc.) | | `autofocus` | key presence Field | selects the field upon creation | +| `fadeIn` | float | the Duration the Panel should take to fade in | + +### Selecting Text +an underutilized Power of the InputField is that you can select its contents. this is helpful when creating forms & editors, but can also be used for other features. you can use it for displaying links to your website or discord, allowing players to select and copy it instead of having to type it out + +it's recommended to wrap your InputField in another panel, ensuring its the only child of it's parent as it prevents the Selected text from being covered by other children. + ### Receiving Input & the lineType Setting to receive the Player's input Text, listen for the Command you specify in the `command` field. the Input will get sent as soon as the Player unfocuses the InputField, for example by clicking out of it. diff --git a/docs/components/UnityEngine.UI.Outline.md b/docs/components/UnityEngine.UI.Outline.md index 6b8f1da..a53f8ad 100644 --- a/docs/components/UnityEngine.UI.Outline.md +++ b/docs/components/UnityEngine.UI.Outline.md @@ -14,6 +14,7 @@ The Outline Component is an Effect Component that puts a colored outline on any "useGraphicAlpha": null } ``` +> the values in these JSON examples represent the default Values that are assigned if no property is specified. > `useGraphicAlpha` is a key presence Field, key presence Fields don't have a specific type and act as a Boolean. > if the key is present it equals true, if absent it equals false. diff --git a/docs/components/UnityEngine.UI.RawImage.md b/docs/components/UnityEngine.UI.RawImage.md index 3711091..4ba2819 100644 --- a/docs/components/UnityEngine.UI.RawImage.md +++ b/docs/components/UnityEngine.UI.RawImage.md @@ -13,9 +13,13 @@ The RawImage is a Visual Component that allows you to display Images from your S "color": "1.0 1.0 1.0 1.0", "material": "", "url": "", - "png": "" + "png": "", + "fadeIn": 0.0 } ``` +> the values in these JSON examples represent the default Values that are assigned if no property is specified. + + RawImage specific Fields: | Key | Type | Notes | | :---------- | :----- | :------------------- | @@ -24,6 +28,7 @@ RawImage specific Fields: | `material` | string | the asset Path to the Material | | `url` | string | the URL of the Image you want to show | | `png` | string | the CRC Checksum of the Image hosted on the Server | +| `fadeIn` | float | the Duration the Panel should take to fade in | ## Images can be your Backgrounds the most common use for RawImage is its Ability to display any* Color you give it. therefore it's often used to give Panels a Background Color. Colors are sent as a `string` of 4 normalized `floats` @@ -73,7 +78,7 @@ private IEnumerator SaveImageFromURL(string URL){ var texture = DownloadHandlerTexture.GetContent(request); byte[] data = texture.EncodeToPNG(); - + // this CRC is what you send to the client. save it somewhere for later uint crc = FileStorage.server.Store(data, FileStorage.Type.png, CommunityEntity.ServerInstance.net.ID); } diff --git a/docs/components/UnityEngine.UI.Text.md b/docs/components/UnityEngine.UI.Text.md index 2b5e8f5..196517b 100644 --- a/docs/components/UnityEngine.UI.Text.md +++ b/docs/components/UnityEngine.UI.Text.md @@ -14,9 +14,13 @@ The Text Component is a Visual Component that allows you to display any Text you "font": "RobotoCondensed-Bold.ttf", "align": "UpperLeft", "color": "1.0 1.0 1.0 1.0", - "verticalOverflow": "Truncate" + "verticalOverflow": "Truncate", + "fadeIn": 0.0 } ``` +> the values in these JSON examples represent the default Values that are assigned if no property is specified. + + Text-specific Fields: | Key | Type | Notes | | :---------- | :----- | :------------------- | @@ -26,6 +30,7 @@ Text-specific Fields: | `align` | string (enum `TextAnchor`) | the way your Text should be aligned | | `color` | string | the default Color of your Text | | `verticalOverflow` | string (enum `VerticalWrapMode`) | how Text Overflowing vertically should be handled | +| `fadeIn` | float | the Duration the Panel should take to fade in | ### Available Fonts: - `DroidSansMono.ttf` From 8680b44866b7ab888aa68ba700f341e96e60cb02 Mon Sep 17 00:00:00 2001 From: Kulltero <33698270+Kulltero@users.noreply.github.com> Date: Thu, 2 Feb 2023 01:10:23 +0100 Subject: [PATCH 5/8] improvements based on @WheteThunger feedback Improved spelling & fixed capitalization issues added section for Layers in the Basics expanded on Positioning in Bugs-Tips expanded on the imagetype setting for the image component added references to the bugs/error messages in some of the other pages added explanation for hudMenuInput & needsKeyboard fields on Input Component --- README.md | 10 ++-- docs/Basics.md | 40 +++++++++----- docs/Bugs-Tips.md | 57 ++++++++++++-------- docs/components/Countdown.md | 27 +++++----- docs/components/NeedsX.md | 2 +- docs/components/README.md | 6 +-- docs/components/RectTransform.md | 37 ++++++------- docs/components/UnityEngine.UI.Button.md | 21 ++++---- docs/components/UnityEngine.UI.Image.md | 42 +++++++++------ docs/components/UnityEngine.UI.InputField.md | 38 ++++++------- docs/components/UnityEngine.UI.Outline.md | 11 ++-- docs/components/UnityEngine.UI.RawImage.md | 37 +++++++------ docs/components/UnityEngine.UI.Text.md | 33 ++++++------ 13 files changed, 202 insertions(+), 159 deletions(-) diff --git a/README.md b/README.md index c8f0d01..bd10d3e 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Rust Community Repository -> This Repository is part of the game Rust. It has no relation to the Programming Language +> This Repository is part of the game Rust. It has no relation to the Programming Language. Client Code for the `CommunityEntity` Class to fulfill Server-side Modder Requests. -Holds the Custom User Interface System (CUI System), which lets developers create interactable UI through a simple JSON Schema +Holds the Custom User Interface System (CUI System), which lets developers create interactive UI through a simple JSON Schema. ## Table of Contents > Click one of the Topics or dive directly into the Component Documentation @@ -17,7 +17,7 @@ Holds the Custom User Interface System (CUI System), which lets developers creat - [InputField](/docs/components/UnityEngine.UI.InputField.md) - [NeedsCursor & NeedsKeyboard](/docs/components/NeedsX.md) - [Countdown](/docs/components/Countdown.md) -- [Tips, Bugs & Edgecases](/docs/Bugs-Tips.md) +- [Tips, Bugs & Edge cases](/docs/Bugs-Tips.md) - [Credits & Acknowledgements](#Credits) ## Credits @@ -30,8 +30,8 @@ External Contributors & People who improved the CUI System - [@Alitop](https://github.com/Alitop) - PR [#32](https://github.com/Facepunch/Rust.Community/pull/32) - [@TactiTac0z](https://github.com/TactiTac0z) - PR [#40](https://github.com/Facepunch/Rust.Community/pull/40) - [@Kulltero](https://github.com/Kulltero) - PR [#43](https://github.com/Facepunch/Rust.Community/pull/43) -> And of course, Facepunch, who has put a lot of ffort into giving Developers the CUI System & the ability to improve it +> And of course, Facepunch, who has put a lot of effort into giving Developers the CUI System & the ability to improve it. --- ### Disclaimer -the readme & Documentation is Community maintained. It aims to give Developers a starting Point and educate them on effectively using CUIs for their Projects +The README & Documentation is Community maintained. It aims to give Developers a starting Point and educate them on effectively using CUIs for their Projects. diff --git a/docs/Basics.md b/docs/Basics.md index b3c348e..1329f7a 100644 --- a/docs/Basics.md +++ b/docs/Basics.md @@ -1,9 +1,10 @@ # The Basics of CUI -**< [Previous Topic](/README.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/docs/components/README.md) >** +**[Back to the Start](/README.md)** | **[Next Topic](/docs/components/README.md) >** There are a few basic Concepts that are needed to make your own CUI, below you will learn about what Panels are & how to create and destroy UI Elements ## The Schema + the JSON Schema to send UI to the Player consists of a List of Elements, where each Element creates a new Panel on the Client. Elements have One or more Components that control the Look & Functionality. ```json @@ -15,21 +16,34 @@ the JSON Schema to send UI to the Player consists of a List of Elements, where e "destroyUi": "" }, ...] ``` -> the values in these JSON examples represent the default Values that are assigned if no property is specified. +> The values in these JSON examples represent the default values that are assigned if no property is specified. > … represent One or more collapsed Objects | Key | Type | Notes | | :-- | :------- | :------------------- | -| `name` | string | the identifier of your panel, needed when destroying UI or adding panels inside this one | -| `parent` | string | tells the client which Panel or Layer to Parent to | -| `components` | List of Components | One or more Components, without these there's no point in sending a panel | -| `fadeOut` | float | makes the Panel fade out instead of disappearing immediately. *Currently doesn't fade out any child Panels* | -| `destroyUi` | string | destroys the Panel specified in the string before creating your Panel. useful for updating UI | +| `name` | string | The identifier of your panel, needed when destroying UI or adding panels inside this one | +| `parent` | string | Tells the client which Panel or Layer to Parent to. **[Needs to be a valid Panel or Layer name](/docs/Bugs-Tips.md#addui-unknown-parent-for-name--parent)** | +| `components` |List of Components | One or more Components, without these there’s no point in sending a panel | +| `fadeOut` | float | Makes the Panel fade out instead of disappearing immediately. _Currently doesn’t fade out any child panels._ | +| `destroyUi` | string | Destroys the Panel specified in the string before creating your Panel. Useful **[preventing flickering](/docs/Bugs-Tips.md#flickering-when-destroying--re-sending-ui-on-the-same-frame)** when updating UI. | + + +### About Layers +layers are used when creating your top most Panel. They differ from Panels because they are static GameObjects that cannot be destroyed via a DestroyUI call. Depending on the Layer you parent to, your UI will appear above or below Rust's own UI elements. + +#### Available Layer values +- `Overall` the top most layer in front of all of Rust's UI +- `Overlay` +- `Hud` +- `Hud.Menu` +- `Under` the lowermost layer, your UI will appear behind all of Rust's UI + ### About Naming -It's recommended to always name your Panels *something*, this is because the CUI System doesn't support multiple Panels with the same name and may cause *Ghost Panels* which cant be destroyed. -It's also recommended to prefix the Name of your Panel with something unique to your Mod, which ensures there are no accidental name Conflicts with other Mods +It’s recommended to always name your Panels _something_, this is because the CUI System doesn’t support multiple Panels with the same name and may cause **[Ghost panels](/docs/Bugs-Tips.md#orphaned-ui-panels-ui-that-cant-be-destroyed-or-ghost-panels)** which can't be destroyed. + +It’s also recommended to prefix the Name of your Panel with something unique to your Mod, which ensures there are no accidental name Conflicts with other Mods ## Sending & destroying UI @@ -53,10 +67,10 @@ var community = CommunityEntity.ServerInstance; SendInfo sendInfo = new SendInfo(player.net.connection); community.ClientRPCEx(sendInfo, null, "DestroyUI", panel); ``` -When destroying a Panel, all child Panels will also get destroyed. -> your Modding Framework may have helper Methods to simplify these steps. +When destroying a Panel, all child panels will also get destroyed. +> Your Modding Framework may have helper Methods to simplify these steps. ---- -the next Topic explains Components in detail +The next Topic explains Components in detail -**< [Previous Topic](/README.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/docs/components/README.md) >** +**[Back to the Start](/README.md)** | **[Next Topic](/docs/components/README.md) >** diff --git a/docs/Bugs-Tips.md b/docs/Bugs-Tips.md index af7870d..65b56fb 100644 --- a/docs/Bugs-Tips.md +++ b/docs/Bugs-Tips.md @@ -1,66 +1,73 @@ # Bugs & Tips -**< [Previous Topic](/docs/components/README.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/README.md) >** +**< [Previous Topic](/docs/components/README.md)** | **[Back to the Start](/README.md)** -When working with the CUI System you will often encounter weird Bugs & Situations. this document lists some ways to prevent them & shows you additional tricks to enhance your UIs +When working with the CUI System, you will often encounter weird Bugs & Situations. This document lists some ways to prevent them & shows you additional tricks to enhance your UIs. ## Table of Contents - [Common Error Messages](#common-error-messages) - [Bugs](#bugs) - [Tricks](#tricks) + # Common Error Messages > these errors will appear in your client console when testing the UI, make sure to test for these before releasing your mod -### AddUI: Unknown Parent for *name*: *parent* -this happens when the parent you supplied in your panel Payload doesn't exist. double-check for spelling mistakes, and formatting issues & ensure your parent appears in your JSON list before the Panel you get this error on. +### AddUI: Unknown Parent for *name*: *parent* +this happens when the parent you supplied in your panel Payload doesn't exist. Double-check for spelling mistakes, and formatting issues & ensure your parent appears in your JSON list before the Panel you get this error on. --- ### Error downloading image: *URL* ( *error* ) -the Client couldn't download your Image, double check your URL & look at the error part within the brackets for what could cause it. +the Client couldn't download your Image, double-check your URL & look at the error part within the brackets for what could cause it. --- ### A GameObject can only contain one 'Graphic' component. -this error indicates that you're trying to add multiple Unity Components that Derive from `UnityEngine.UI.Graphic`. the **[Components](/docs/components/README.md)** topic has a list of allowed Components and lists the categories they are in. any Component of the **Visual** Category is a Component that derives from or adds a `UnityEngine.UI.Graphic` to the Panel. to get around this Limitation you can put other Visual Components on a child Panel instead. + +This error indicates that you're trying to add multiple Unity Components that derive from `UnityEngine.UI.Graphic`. The **[Components](/docs/components/README.md)** topic has a list of allowed Components and lists the categories they are in. any Component of the **Visual** Category is a Component that derives from or adds a `UnityEngine.UI.Graphic` to the Panel. To get around this Limitation, you can put other Visual Components on a child panel instead. # Bugs + ### Orphaned UI Panels, UI that Can't be Destroyed, or Ghost Panels. -**Symptom:** you have 1 or more Panels that are stuck on your Screen and can't be removed by Calling **DestroyUI** with their Name. -**Cause:** you have 2 or more Panels that shared the same Name & were active at the same time. if these are parented directly to a Layer and one is destroyed the other Panel Can't be destroyed anymore. the only way to remove the UI Panel from your Screen is by reconnecting. double-check your UI and ensure any Panel directly parented to a Layer has a unique Name. also, ensure that you don't accidentally send the same UI twice. +**Symptom:** you have 1 or more panels that are stuck on your Screen and can't be removed by Calling **DestroyUI** with their Name. + +**Cause:** you have 2 or more panels that shared the same name & were active at the same time. If these are parented directly to a Layer and one is destroyed, the other Panel Can't be destroyed anymore. The only way to remove the UI Panel from your Screen is by reconnecting. Double-check your UI and ensure any Panel directly parented to a Layer has a unique Name. Also, ensure that you don't accidentally send the same UI twice. --- + ### Flickering when destroying & re-sending UI on the same frame. + **Symptom:** when updating Part of your UI. the Player gets a noticeable Delay between the old UI being destroyed & the new UI being created. -**Cause:** the presumed cause of this issue is the Server Delaying your AddUI Packet to the next Network Cycle. this happens very unpredictably but is more likely with larger UI Updates. the solution is to use the `destroyUi` field on your panel Payload, it works the same way a DestroyUI call works, but is combined with your panel Payload to prevent network scheduling from creating the Flickering issue. +**Cause:** the presumed cause of this issue is the Server Delaying your AddUI Packet to the next Network Cycle. This happens very unpredictably, but is more likely with larger UI Updates. The solution is to use the `destroyUi` field on your panel Payload, it works the same way a DestroyUI call works, but is combined with your panel Payload to prevent network scheduling from creating the flickering issue. --- ### Very Inconsistent Alpha handling for images -**Symptom:** when using Images with somewhat transparent pixels the images get rendered more Opaque than they are, resulting in heavy artifacts. -**Linked Issue:** **[#42 - Rust has an Opacity Issue](https://github.com/Facepunch/Rust.Community/issues/42)** -**Cause:** no known Cause or Workaround found. vote on the Linked issue if you encounter this bug or have more info as to why this might happen +**Symptom:** when using images with somewhat transparent pixels, the images get rendered more Opaque than they are, resulting in heavy artifacts. +**Linked Issue:** **[#42 - Rust has an Opacity Issue](https://github.com/Facepunch/Rust.Community/issues/42)** + +**Cause:** no known Cause or Workaround found. Vote on the Linked issue if you encounter this bug or have more info as to why this might happen. --- ### Panels with a blur Material & Transparency cause underlying Panels to be invisible. -**Symptom:** when using a burry Material on a Color with Transparency, any underlying Image Components with blur get cut out. +**Symptom:** when using a blurry Material on a Color with Transparency, any underlying Image Components with blur get cut out. **Visual Example:** ![image](https://user-images.githubusercontent.com/33698270/215882128-d1f0798c-d7ed-4986-9675-4fba48632ad7.png) > an image of the following UI setup @@ -73,23 +80,23 @@ this error indicates that you're trying to add multiple Unity Components that De > square 3: child of Parent, gray with 20% alpha and a text element behind it. -**Cause:** no exact Cause is known, but it seems to be related to the blurry Materials themselves. this bug only occurs when all underlying Images are using a blurry material with transparency. if at least 1 element is opaque the bug does not occur. this can be a text or image element. +**Cause:** no exact Cause is known, but it seems to be related to the blurry Materials themselves. This bug only occurs when all underlying Images are using a blurry material with transparency. If at least 1 element is opaque, the bug does not occur. This can be a text or image element. # Tricks ### Use Outlines like an advanced User -Outlines can go way beyond the basic use case of putting them on your square Panels. applying Outlines to Text can be a great way to make them stand out, for example when you can't control the background behind it. +Outlines can go way beyond the basic use case of putting them on your square Panels. Applying Outlines to Text can be a great way to make them stand out, for example when you can't control the background behind it. ![image](https://user-images.githubusercontent.com/33698270/215885917-4916ee09-a891-4609-82a4-51bb07881bde.png) -> can you read this? +> Can you read this? ![image](https://user-images.githubusercontent.com/33698270/215886796-346be279-2d8e-43c4-a28f-f740bcf50ff5.png) -> adding a 1px outline with a darker color makes it much clearer. +> Adding a 1px outline with a darker color makes it much clearer. -Another advanced trick is stacking Outlines with lowered Opacity to create a staggered outline or glow/shadow effect. unlike **Visual** Components, the Outline Component doesn't derive from `UnityEngine.UI.Graphic`, meaning there's no limit on how many Outlines a Panel can have. +Another advanced trick is stacking Outlines with lowered Opacity to create a staggered outline or glow/shadow effect. Unlike **Visual** Components, the Outline Component doesn't derive from `UnityEngine.UI.Graphic`, meaning there's no limit on how many Outlines a Panel can have. ![image](https://user-images.githubusercontent.com/33698270/215899049-e0aa0cd7-b607-466e-a0b7-0cfafa62bdae.png) @@ -98,10 +105,18 @@ Another advanced trick is stacking Outlines with lowered Opacity to create a sta --- + ### Positioning your CUI alongside rust UI -for features that augment Rust's existing UI, like when you're working with Furnaces & other storage Inventories, its important to make sure your CUI doesn't interfere with the UI you augment. -Rust UI uses the same Placement system CUI does. it anchors all of the UI to the Bottom Middle of the Screen and then uses offsets to position each element. by doing the same you can ensure that your CUI is positioned properly, regardless of Screensize & Aspect Ratio. +for features that augment Rust's existing UI, like when you're working with Furnaces & other storage inventories, it's important to make sure your CUI doesn't interfere with the UI you augment. + +Rust UI uses the same Placement system CUI does. It primarily uses offsets for sizing & positioning and anchors to a specific Point depending on the UI. by doing the same, you can ensure that your CUI is positioned properly, regardless of Screen size & Aspect Ratio. + +UIs like the inventory, belt bar & storage containers are anchored to the bottom of the screen, but many other UIs don't follow that convention. + +A great way to discover what a UI element is anchored to is to use the windowed mode and stretch it to extreme aspect ratios. This clearly reveals anchoring thanks to rust's offset scaling +![image](https://user-images.githubusercontent.com/33698270/216077347-5461623c-8ff4-4890-8633-062519c4e371.png) +> Stretching our window show that the Crafting & Contacts buttons are anchored to the top middle, while the status bars are anchored to the bottom right corner a RectTransform Example that covers the Belt-bar ```json @@ -115,4 +130,4 @@ a RectTransform Example that covers the Belt-bar ``` ![image](https://user-images.githubusercontent.com/33698270/215901408-c152fecb-8453-4597-8cd6-61038b2b976d.png) -**< [Previous Topic](/docs/components/README.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/README.md) >** +**< [Previous Topic](/docs/components/README.md)** | **[Back to the Start](/README.md)** diff --git a/docs/components/Countdown.md b/docs/components/Countdown.md index 7dd7e88..75969ca 100644 --- a/docs/components/Countdown.md +++ b/docs/components/Countdown.md @@ -1,11 +1,11 @@ # Components: Countdown -**< [Previous Component](/docs/components/NeedsX.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/README.md) >** +**< [Previous Component](/docs/components/NeedsX.md)** | **[Back to Components](/docs/components/README.md)** - Identifier: `Countdown` - Category: **Misc** - Unity Documentation: **N/A** -The Countdown Component lets you turn an existing Text Component into a Timer, Countdown, or Count-up. the Countdown Component automatically **destroys** the Panel when it's done counting. +The Countdown Component lets you turn an existing Text Component into a Timer, Countdown, or Count-up. The Countdown Component automatically **destroys** the Panel when it’s done counting. ```json { "type": "Countdown", @@ -15,27 +15,26 @@ The Countdown Component lets you turn an existing Text Component into a Timer, C "command": "" } ``` -> the values in these JSON examples represent the default Values that are assigned if no property is specified. - Countdown-specific Fields: | Key | Type | Notes | | :---------- | :----- | :------------------- | -| `endTime` | int | the Number it should count to | -| `startTime` | int | the Number it should start counting from | -| `step` | int | the Number it should increment by, also acts as the update interval | -| `command` | string | the Command that should be executed when the Countdown finishes. | +| `endTime` | int | The Number it should count to | +| `startTime` | int | The Number it should start counting from | +| `step` | int | The Number it should increment by, also acts as the update interval | +| `command` | string | The command that should be executed when the Countdown finishes. | ## Working with Countdowns -for Countdowns to work you need to add a **[Text](/docs/components/UnityEngine.UI.Text.md)** Component to your Panel. your Text Component's content should include the string `%TIME_LEFT%`, which the Countdown will replace with the current Number. + +for Countdowns to work, you need to add a **[Text](https://stackedit.io/docs/components/UnityEngine.UI.Text.md)** Component to your Panel. Your Text Component’s content should include the string `%TIME_LEFT%`, which the Countdown will replace with the current Number. Examples: -- `the Event will end in %TIME_LEFT% Seconds` => the Event Will end in 30 Seconds -- `Power-up Buff - %TIME_LEFT%s` => Power-up Buff - 30s +- `the Event will end in %TIME_LEFT% Seconds` ⇒ the Event Will end in 30 Seconds +- `Power-up Buff - %TIME_LEFT%s` ⇒ Power-up Buff - 30s ### Counting Up vs counting Down -- to count Down set your `startTime` higher than your `endTime` & set your `step` to at least 1. -- to count Up set your `startTime` lower than your `endTime` +- to count Down, set your `startTime` higher than your `endTime` & set your `step` to at least 1. +- To count Up, set your `startTime` lower than your `endTime` -**< [Previous Component](/docs/components/NeedsX.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/README.md) >** +**< [Previous Component](/docs/components/NeedsX.md)** | **[Back to Components](/docs/components/README.md)** diff --git a/docs/components/NeedsX.md b/docs/components/NeedsX.md index 4b41a46..ed4b882 100644 --- a/docs/components/NeedsX.md +++ b/docs/components/NeedsX.md @@ -14,6 +14,6 @@ The NeedsCursor & NeedsKeyboard Components are Components with no additional Fie } ``` -unlike the `needsKeyboard` and `hudMenuInput` fields on an InputField Component, these Components Prevent default Behavior until your Panel is Destroyed +Unlike the `needsKeyboard` and `hudMenuInput` fields on an InputField Component, these Components Prevent default Behavior until your Panel is Destroyed **< [Previous Component](/docs/components/UnityEngine.UI.InputField.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/Countdown.md) >** diff --git a/docs/components/README.md b/docs/components/README.md index f2a1a3e..fb95435 100644 --- a/docs/components/README.md +++ b/docs/components/README.md @@ -1,9 +1,9 @@ # Components -**< [Previous Topic](/docs/Basics.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/docs/Tips-Pitfalls.md) >** +**< [Previous Topic](/docs/Basics.md)** | **[Back to the Start](/README.md)** | **[Next Topic](/docs/Bugs-Tips.md) >** The CUI System comes with a Set of Components you can use to build your UI, some are visual, and others add Interactivity. -Components are added to a Panel by sending them as a List in the Schema shown in [The Basics](/docs/Basics.md). to identify the Type of Component sent, a `type` Field is added by every Component +Components are added to a panel by sending them as a List in the Schema shown in [The Basics](/docs/Basics.md). To identify the Type of Component sent, a `type` Field is added by every Component. ```json [{ "type": "UnityEngine.UI.Text", @@ -24,7 +24,7 @@ Components are added to a Panel by sending them as a List in the Schema shown in - [Countdown](/docs/components/Countdown.md) ## About Component Categories -Each Component Page has a *Category* listed, which helps you identify what a Component does. pay attention to the **Visual** Category, as it means the Component Adds a Unity Component deriving from `UnityEngine.UI.Graphic`. This is important because **each Panel can only have 1 Graphic Component**. +Each Component Page has a _Category_ listed, which helps you identify what a Component does. Pay attention to the **Visual** Category, as it means the Component Adds a Unity Component deriving from `UnityEngine.UI.Graphic`. This is important because **each panel can only have 1 Graphic Component**. --- The next Topic explains common Pitfalls & Things you need to look out for diff --git a/docs/components/RectTransform.md b/docs/components/RectTransform.md index 733afac..78fa0f2 100644 --- a/docs/components/RectTransform.md +++ b/docs/components/RectTransform.md @@ -1,12 +1,12 @@ # Components: RectTransform -**< [Previous Component](/docs/components/README.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.RawImage.md) >** +**[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.RawImage.md) >** - Identifier: `RectTransform` - Category: **Position** - Unity Documentation: **[RectTransform @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/class-RectTransform.html)** The RectTransform is a Component that specifies the Position & Size of the Panel it's attached to. -it allows you to position a Panel via [Anchors & Offsets](#anchors-and-offsets). +It allows you to position a Panel via [Anchors & Offsets](#anchors-and-offsets). ```json { "type": "RectTransform", @@ -16,15 +16,13 @@ it allows you to position a Panel via [Anchors & Offsets](#anchors-and-offsets). "offsetmax": "1.0 1.0", } ``` -> the values in these JSON examples represent the default Values that are assigned if no property is specified. - RectTransform specific Fields: | Key | Type | Notes | | :---------- | :----- | :------------------- | -| `anchormin` | string | specifies the anchor for the bottom left Corner | -| `anchormax` | string | specifies the anchor for the top right Corner | -| `offsetmin` | string | specifies the Pixel offset for the bottom left Corner | -| `offsetmax` | string | specifies the Pixel offset for the top right Corner | +| `anchormin` | string | Specifies the anchor for the bottom left Corner | +| `anchormax` | string | Specifies the anchor for the top right Corner | +| `offsetmin` | string | Specifies the Pixel offset for the bottom left Corner | +| `offsetmax` | string | Specifies the Pixel offset for the top right Corner | both Anchors & Offsets come with a *-min* and *-max* Field, where the min holds x & y Values for the bottom left Corner & the max holds x & y Values for the top right Corner @@ -37,26 +35,29 @@ Unity's Coordinate System in a 2D Space goes from Left to Right, Bottom to Top. > this might be confusing to people coming from the web-design space, where the x coordinate commonly goes down the screen instead of up ## Anchors and Offsets -Anchors Specify where your Panel starts & ends. Offsets let you move the start & end Points with pixel Values. +Anchors Specify where your Panel starts & ends. Offsets let you move the start & end points with pixel values. -Anchors use a normalized Percentage of the Parent, where `0.0` is the Start and `1.0` is the End. [The "Anchors" Section](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/UIBasicLayout.html#anchors) in the Unity Documentation has some visual examples which also apply here. +Anchors use a normalized Percentage of the Parent, where `0.0` is the Start and `1.0` is the End. [The “Anchors” Section](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/UIBasicLayout.html#anchors) in the Unity Documentation has some visual examples which also apply here. -Offsets use [scaled](#offsets-and-scaling) pixel Values to move the Corners relative to the Anchors you provide. +Offsets use [scaled](#offsets-and-scaling) pixel values to move the corners relative to the Anchors you provide. -Positioning using only Anchors is great for when you want your Panel to cover a Percentage of the Screen or Parent, but for any other cases, a mixture of Anchors & Offsets should be used to Position your UI. +Positioning using only anchors is great for when you want your Panel to cover a Percentage of the Screen or Parent, but for any other cases, a mixture of Anchors & Offsets should be used to position your UI. -A common Technique is to use Anchors to specify what part of the Parent the UI should be anchored to (Top Left Corner or Dead Center. Etc.) and to use Offsets for Size & Position. +A common Technique is to use anchors to specify what part of the Parent the UI should be anchored to (Top Left Corner or Dead Center. Etc.) and to use Offsets for Size & Position. +Anchors Specify where your Panel starts & ends. Offsets let you move the start & end Points with pixel Values. ## Offsets and Scaling -Rust will automatically scale Offsets depending on the Player's Resolution, which ensures your Offsets are predictable. -By default, Rust handles Offsets based on a Resolution of **1280** by **720**. This means that for smaller & larger **16:9** Resolutions Rust will simply multiply Offsets by the difference between the Player's Resolution and 720p, +Rust will automatically scale offsets depending on the Player’s Resolution, which ensures your Offsets are predictable. + +By default, Rust handles Offsets based on a Resolution of **1280** by **720**. This means that for smaller & larger **16:9** Resolutions, Rust will simply multiply Offset by the difference between the Player’s Resolution and 720p, -For non-16:9 Resolutions such as Ultrawide or windowed Mode, Rust will apply Letterboxing before calculating the scaling Factor +For non-16:9 Resolutions such as Ultrawide or windowed Mode, Rust will apply Letter boxing before calculating the scaling Factor +> NOTE: when scaling offsets rust also takes the player's `graphics.uiscale` into account. https://user-images.githubusercontent.com/33698270/214582004-c695e73c-9125-4ccb-9cfb-abc883b5c0a0.mp4 -> a video of a gray Rectangle positioned at the Center of the Screen (anchor min & max at `0.5 0.5`) with an offset of 1280 x 720 px. see how Unity applies Letterboxing before scaling the Rectangle to ensure it never gets stretched. NOTE: the black Bars are only to illustrate in this Example, your ingame UI won't have any black Bars +> a video of a gray Rectangle positioned at the Center of the Screen (anchor min & max at `0.5 0.5`) with an offset of 1280 x 720 px. see how Unity applies Letter boxing before scaling the Rectangle to ensure it never gets stretched. NOTE: the black Bars are only to illustrate in this Example, your in game UI won’t have any black Bars -**< [Previous Component](/docs/components/README.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.RawImage.md) >** +**[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.RawImage.md) >** diff --git a/docs/components/UnityEngine.UI.Button.md b/docs/components/UnityEngine.UI.Button.md index ce65397..90e333d 100644 --- a/docs/components/UnityEngine.UI.Button.md +++ b/docs/components/UnityEngine.UI.Button.md @@ -5,7 +5,7 @@ - Category: **Interactive, Visual** - Unity Documentation: **[Button @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-Button.html)** -The Button Component is an Interactive Component that lets you execute Commands & Destroy UI when it gets pressed. it automatically adds a `UnityEngine.UI.Image` to the panel, allowing you to change the `sprite`, `material` & `color` on it +The Button Component is an Interactive Component that lets you execute Commands & Destroy UI when it gets pressed. It automatically adds a `UnityEngine.UI.Image` to the panel, allowing you to change the `sprite`, `material` & `color` on it. ```json { "type": "UnityEngine.UI.Button", @@ -18,22 +18,19 @@ The Button Component is an Interactive Component that lets you execute Commands "fadeIn": 0.0 } ``` -> the values in these JSON examples represent the default Values that are assigned if no property is specified. - - Button-specific Fields: | Key | Type | Notes | | :---------- | :----- | :------------------- | -| `command` | string | the Command that should get sent to the Server on Click | -| `close` | string | the Name of the Panel that should get closed on Click | -| `sprite` | string | the asset Path to the sprite | -| `color` | string | the normalized RGBA values of your color | -| `material` | string | the asset Path to the Material | -| `imagetype` | string (enum `Image.Type`) | sets the display mode of the Image* | -| `fadeIn` | float | the Duration the Panel should take to fade in | +| `command` | string | The command that should get sent to the Server on Click | +| `close` | string | The Name of the Panel that should get closed on Click | +| `sprite` | string | The asset Path to the sprite | +| `color` | string | The normalized RGBA values of your color | +| `material` | string | The asset Path to the Material | +| `imagetype` | string (enum `Image.Type`) | Sets the display mode of the Image* | +| `fadeIn` | float | The Duration the Panel should take to fade in | \* Currently non-functioning for anything other than Rust's built-in Sprites ### Button as a Parent -click events bubble up, meaning that they will get triggered on every Panel until a Component consumes them. This means it's possible to use the Button as a Parent and still get notified when the Player clicks a child Panel. +click events bubble up, meaning that they will get triggered on every Panel until a Component consumes them. This means it’s possible to use the Button as a Parent and still get notified when the Player clicks a child panel. **< [Previous Component](/docs/components/UnityEngine.UI.Outline.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.InputField.md) >** diff --git a/docs/components/UnityEngine.UI.Image.md b/docs/components/UnityEngine.UI.Image.md index e2ee056..6d36f8f 100644 --- a/docs/components/UnityEngine.UI.Image.md +++ b/docs/components/UnityEngine.UI.Image.md @@ -5,7 +5,7 @@ - Category: **Visual** - Unity Documentation: **[Image @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-Image.html)** -The Image is a Visual Component that allows you to display Images from your Server & the Web or Rust Sprites. it can also be used with a single color to act as a Background for your panel +The Image is a Visual Component that allows you to display images from your Server & the Web or Rust Sprites. It can also be used with a single color to act as a Background for your panel. ```json { "type": "UnityEngine.UI.Image", @@ -19,31 +19,41 @@ The Image is a Visual Component that allows you to display Images from your Serv "fadeIn": 0.0 } ``` -> the values in these JSON examples represent the default Values that are assigned if no property is specified. - - RawImage specific Fields: | Key | Type | Notes | | :---------- | :----- | :------------------- | -| `sprite` | string | the asset Path to the sprite | -| `color` | string | the normalized RGBA values of your color | -| `material` | string | the asset Path to the Material | -| `imagetype` | string (enum `Image.Type`) | sets the display mode of the Image* | -| `png` | string | the CRC Checksum of the Image hosted on the Server | -| `itemid` | int | the Item ID of your item | -| `skinid` | ulong | the Skin ID of your skin | -| `fadeIn` | float | the Duration the Panel should take to fade in | +| `sprite` | string | The asset Path to the sprite | +| `color` | string | The normalized RGBA values of your color | +| `material` | string | The asset Path to the Material | +| `imagetype` | string (enum `Image.Type`) | Sets the display mode of the Image* | +| `png` | string | The CRC Checksum of the Image hosted on the Server | +| `itemid` | int | The Item ID of your item | +| `skinid` | ulong | The Skin ID of your skin | +| `fadeIn` | float | The Duration the Panel should take to fade in | \* Currently non-functioning for anything other than Rust's built-in Sprites + +## imagetype and sprites +the imagetype lets you provide a specific `Image.Type` option to change how the Component renders the image. + +An important thing to remember is that currently, Simple is the only option that works with images loaded from your server. This is because the Sliced, Tiled & Filled options require extra parameters to be set on the sprite. The image Component's JSON API currently doesn't wrap these parameters. + +Available options for `Image.Type` +| Value | Description | +| :---- | :---------- | +| `Simple` | Displays the full Image | +| `Sliced` | Displays the Image as a 9-sliced graphic. | +| `Tiled` | Displays a sliced Sprite with its resizable sections tiled instead of stretched. | +| `Filled` | Displays only a portion of the Image. | + ## RawImages vs Images -Like RawImages, Images share the ability to show Sprites, Colors, Materials & Images hosted on the Server, but they cannot directly load Images from the Web. +Like RawImages, Images share the ability to show Sprites, Colors, Materials & Images hosted on the Server, but they cannot directly load images from the Web. The Image Component has convenient Ways to display any Item or Skin and is recommended when using Rust's Sprites. ## Items and Skins -using the `itemid` & `skinid` fields you can let the Client handle the displaying of related Images. -NOTE: there is currently a bug when supplying a skinid of `0`, causing the player to crash, avoid including the field altogether if you don't intend to send a skinid +using the `itemid` & `skinid` fields, you can let the Client handle the displaying of related Images. -Tip: use the ItemDefinition of your Item to easily find an Item's ID & other useful Information +Tip: use the ItemDefinition of your Item to easily find an Item’s ID & other useful Information ```c# string shortname = "your.item.shortname"; var itemDef = ItemManager.FindItemDefinition(shortname); diff --git a/docs/components/UnityEngine.UI.InputField.md b/docs/components/UnityEngine.UI.InputField.md index 6899bf5..5aa1671 100644 --- a/docs/components/UnityEngine.UI.InputField.md +++ b/docs/components/UnityEngine.UI.InputField.md @@ -5,7 +5,7 @@ - Category: **Interactive, Visual** - Unity Documentation: **[InputField @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-InputField.html)** -The InputField Component is an Interactive Component that allows Players to enter arbitrary text that gets sent back as a Command. it automatically adds a `UnityEngine.UI.Text` to the panel, allowing you to change the `fontSize`, `font`, `align`ment & text`color` of it +The InputField Component is an Interactive Component that allows Players to enter arbitrary text that gets sent back as a Command. It automatically adds a `UnityEngine.UI.Text` to the panel, allowing you to change the `fontSize`, `font`, `align`ment & text`color` of it. ```json { "type": "UnityEngine.UI.InputField", @@ -24,33 +24,35 @@ The InputField Component is an Interactive Component that allows Players to ente "fadeIn": 0.0 } ``` -> the values in these JSON examples represent the default Values that are assigned if no property is specified. - > `password`, `needsKeyboard`, `hudMenuInput`, and `autofocus` are key presence Fields, key presence Fields don't have a specific type and act as a Boolean. -> if the key is present it equals true, if absent it equals false. +> If the key is present it equals true, if absent it equals false. InputField specific Fields: | Key | Type | Notes | | :---------- | :----- | :------------------- | -| `command` | string | the Command that should get sent to the Server alongside the Player's Input. The Input will get appended to the Command after a Space. | -| `text` | string | the default Text of the InputField can be combined with `readOnly` | -| `readOnly` | bool | prevents the Content from being edited | -| `lineType` | string (enum `InputField.LineType`) | dictates if the Field should allow multiple Lines & how to handle when the Player presses `enter` | -| `password` | key presence Field | if the input should be obscured | -| `needsKeyboard` | key presence Field | prevents default Keyboard behavior (movement, item switching etc) while the field is Focused | -| `hudMenuInput` | key presence Field | same as above but for Rust UI (Inventory, Crafting, etc.) | -| `autofocus` | key presence Field | selects the field upon creation | -| `fadeIn` | float | the Duration the Panel should take to fade in | +| `command` | string | The command that should get sent to the Server alongside the Player's Input. The Input will get appended to the Command after a Space. | +| `text` | string | The default Text of the InputField can be combined with `readOnly` | +| `readOnly` | bool | Prevents the Content from being edited | +| `lineType` | string (enum `InputField.LineType`) | Dictates if the Field should allow multiple Lines & how to handle when the Player presses `enter` | +| `password` | key presence Field | If the input should be obscured | +| `needsKeyboard` | key presence Field | Prevents default Keyboard behavior (movement, item switching etc.) While the field is Focused | +| `hudMenuInput` | key presence Field | Same as above but for Rust UI (Inventory, Crafting, etc.) | +| `autofocus` | key presence Field | Selects the field upon creation | +| `fadeIn` | float | The Duration the Panel should take to fade in | + +### needsKeyboard vs hudMenuInput +while both prevent Vanilla behavior, they have some key differences that are good to keep in mind. +needsKeyboard works well for normal use, but will close any Rust UI the player has open when the player selects an InputField with it enabled. +This is the primary reason why hudMenuInput was added. It won't close Rust's UI when selected, but won't prevent the player from moving & executing key binds. ### Selecting Text -an underutilized Power of the InputField is that you can select its contents. this is helpful when creating forms & editors, but can also be used for other features. you can use it for displaying links to your website or discord, allowing players to select and copy it instead of having to type it out - -it's recommended to wrap your InputField in another panel, ensuring its the only child of it's parent as it prevents the Selected text from being covered by other children. +an underutilized Power of the InputField is that you can select its contents. This is helpful when creating forms & editors, but can also be used for other features. Like using it for displaying links to your website or discord, allowing players to select and copy it instead of having to type it out. +It’s recommended to wrap your InputField in another panel, ensuring it's the only child of it’s parent, as it prevents the selected text from being covered by other children. ### Receiving Input & the lineType Setting -to receive the Player's input Text, listen for the Command you specify in the `command` field. the Input will get sent as soon as the Player unfocuses the InputField, for example by clicking out of it. +to receive the Player’s input text, listen for the command you specify in the `command` field. The Input will get sent as soon as the Player unfocuses the InputField, for example by clicking out of it. -depending on the `lineType` Setting, if it's set to SingleLine or MultiLineSubmit pressing `enter` will also cause the Input to get sent to the Server. Pressing `enter` with the MultiLineNewline Setting inserts a Newline instead. +Depending on the `lineType` Setting, if it’s set to SingleLine or MultiLineSubmit pressing `enter` will also cause the Input to get sent to the Server. Pressing `enter` with the MultiLineNewline Setting inserts a Newline instead. **< [Previous Component](/docs/components/UnityEngine.UI.Button.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/NeedsX.md) >** diff --git a/docs/components/UnityEngine.UI.Outline.md b/docs/components/UnityEngine.UI.Outline.md index a53f8ad..e59c8da 100644 --- a/docs/components/UnityEngine.UI.Outline.md +++ b/docs/components/UnityEngine.UI.Outline.md @@ -5,7 +5,7 @@ - Category: **Effect** - Unity Documentation: **[Outline @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-Outline.html)** -The Outline Component is an Effect Component that puts a colored outline on any Visual Component. it supports any Image, Text, Button, or Input field. +The Outline Component is an Effect Component that puts a colored outline on any Visual Component. It supports any Image, Text, Button, or Input field. ```json { "type": "UnityEngine.UI.Outline", @@ -14,15 +14,14 @@ The Outline Component is an Effect Component that puts a colored outline on any "useGraphicAlpha": null } ``` -> the values in these JSON examples represent the default Values that are assigned if no property is specified. > `useGraphicAlpha` is a key presence Field, key presence Fields don't have a specific type and act as a Boolean. -> if the key is present it equals true, if absent it equals false. +> If the key is present it equals true, if absent it equals false. Outline specific Fields: | Key | Type | Notes | | :---------- | :----- | :------------------- | -| `color` | string | the Color of your Outline | -| `distance` | string | the distance of your Outline (formatted as `X Y`) | -| `useGraphicAlpha` | key presence Field | multiplies the Alpha of the graphic onto the color of the Outline | +| `color` | string | The Color of your Outline | +| `distance` | string | The distance of your Outline (formatted as `X Y`) | +| `useGraphicAlpha` | key presence Field | Multiplies the Alpha of the graphic onto the color of the Outline | **< [Previous Component](/docs/components/UnityEngine.UI.Text.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.Button.md) >** diff --git a/docs/components/UnityEngine.UI.RawImage.md b/docs/components/UnityEngine.UI.RawImage.md index 4ba2819..e7a1f8e 100644 --- a/docs/components/UnityEngine.UI.RawImage.md +++ b/docs/components/UnityEngine.UI.RawImage.md @@ -5,7 +5,9 @@ - Category: **Visual** - Unity Documentation: **[RawImage @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-RawImage.html)** -The RawImage is a Visual Component that allows you to display Images from your Server & the Web or Rust Sprites. it can also be used with a single color to act as a Background for your panel +the most common use for RawImage is its Ability to display any* Color you give it. Therefore, it’s often used to give panels a Background Color. Colors are sent as a `string` of 4 normalized `floats` + +Tip: if you’re used to using hexadecimal, you can use this function to convert your colors on the fly: ```json { "type": "UnityEngine.UI.RawImage", @@ -17,18 +19,15 @@ The RawImage is a Visual Component that allows you to display Images from your S "fadeIn": 0.0 } ``` -> the values in these JSON examples represent the default Values that are assigned if no property is specified. - - RawImage specific Fields: | Key | Type | Notes | | :---------- | :----- | :------------------- | -| `sprite` | string | the asset Path to the sprite | -| `color` | string | the normalized RGBA values of your color | -| `material` | string | the asset Path to the Material | -| `url` | string | the URL of the Image you want to show | -| `png` | string | the CRC Checksum of the Image hosted on the Server | -| `fadeIn` | float | the Duration the Panel should take to fade in | +| `sprite` | string | The asset Path to the sprite | +| `color` | string | The normalized RGBA values of your color | +| `material` | string | The asset Path to the Material | +| `url` | string | The URL of the Image you want to show | +| `png` | string | The CRC Checksum of the Image hosted on the Server | +| `fadeIn` | float | The Duration the Panel should take to fade in | ## Images can be your Backgrounds the most common use for RawImage is its Ability to display any* Color you give it. therefore it's often used to give Panels a Background Color. Colors are sent as a `string` of 4 normalized `floats` @@ -53,18 +52,22 @@ static public string NormalizeHex(string hex, byte alpha = 255){ ``` Images can also be combined with a Subset of Materials to enhance your UIs, some Materials can be combined with a Color, while others will enforce their own Color. some Materials won't have any visual Effect. -> \* Colors are limited to a Precision of 0.01 per Channel, giving you only 1.000.000 Colors to choose from (excluding the alpha Channel) +> \* Colors are limited to a Precision of 0.01 per Channel, giving you only 1,000,000 Colors to choose from (excluding the alpha Channel) ## Using Rust's Sprites You can re-use any of Rust's Sprites by specifying an asset path in the `sprite` field. ## Loading your own Images -the RawImage Component has two Ways of displaying your own Images, the first is by downloading the image onto the game Server & supplying the CRC Checksum in the `png` field, and the second is by hosting the image online and supplying a direct link to it in the `url` field +the RawImage Component has two Ways of displaying your own Images, loading from the server & loading from the web. + +Loading images from the server is done by downloading the image onto the game Server & supplying the CRC Checksum in the `png` field. + +Loading images from the web is done by hosting the image online and supplying a direct link to it in the `url` field -Loading Images from your Server requires a bit of setup but has the benefit of the Client caching the image once it's loaded from your server, resulting in faster loading times on subsequent UI sends. +Loading Images from your Server requires a bit of setup but has the benefit of the Client caching the image once it’s loaded from your server, resulting in faster loading times on subsequent UI sends. ### Loading Images from your Server -to load Images from your own Server you have to download & store the image in Rust's `FileStorage`. +to load images from your own Server, you have to download & store the image in Rust's `FileStorage`. ```c# @@ -84,11 +87,11 @@ private IEnumerator SaveImageFromURL(string URL){ } } ``` -the rust Client will then automatically fetch the Image from the Server. You will have to re-download the Image every Wipe as the CommunityEntity's netID will differ, which will cause the Client to not find your Image. +The rust Client will then automatically fetch the Image from the Server. You will have to re-download the image every Wipe as the CommunityEntity’s netID will differ, which will cause the Client to not find your Image. ## Combining Images & Color when using an image you can use the `color` property to modify the image's Color on the fly, this is great when using Icons that are White or Grayscale, as it allows you to communicate Information by changing the Color of the Icon instead of having to load multiple versions. --- -before using RawImage, take a look at the Image Component to see if it's better suited for your usecase. -**< [Previous Component](/docs/components/README.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.RawImage.md) >** +Before using RawImage, take a look at the Image Component to see if it’s better suited for your use case. +**< [Previous Component](/docs/components/README.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/UnityEngine.UI.Image.md) >** diff --git a/docs/components/UnityEngine.UI.Text.md b/docs/components/UnityEngine.UI.Text.md index 196517b..17b1f0f 100644 --- a/docs/components/UnityEngine.UI.Text.md +++ b/docs/components/UnityEngine.UI.Text.md @@ -5,7 +5,7 @@ - Category: **Visual** - Unity Documentation: **[Text @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-Text.html)** -The Text Component is a Visual Component that allows you to display any Text you want. it has Options for Alignment, Color, and overflow Options & Supports RichText. +The Text Component is a Visual Component that allows you to display any Text you want. It has Options for Alignment, Color, and overflow Options & Supports RichText. ```json { "type": "UnityEngine.UI.Text", @@ -18,19 +18,16 @@ The Text Component is a Visual Component that allows you to display any Text you "fadeIn": 0.0 } ``` -> the values in these JSON examples represent the default Values that are assigned if no property is specified. - - Text-specific Fields: | Key | Type | Notes | | :---------- | :----- | :------------------- | -| `text` | string | the Content of your Text Component | -| `fontSize` | int | the default font size of your Text | -| `font` | string | the Asset name of the Font you wish to use | -| `align` | string (enum `TextAnchor`) | the way your Text should be aligned | -| `color` | string | the default Color of your Text | -| `verticalOverflow` | string (enum `VerticalWrapMode`) | how Text Overflowing vertically should be handled | -| `fadeIn` | float | the Duration the Panel should take to fade in | +| `text` | string | The Content of your Text Component | +| `fontSize` | int | The default font size of your Text | +| `font` | string | The Asset name of the Font you wish to use | +| `align` | string (enum `TextAnchor`) | The way your Text should be aligned | +| `color` | string | The default Color of your Text | +| `verticalOverflow` | string (enum `VerticalWrapMode`) | How Text Overflowing vertically should be handled | +| `fadeIn` | float | The Duration the Panel should take to fade in | ### Available Fonts: - `DroidSansMono.ttf` @@ -39,16 +36,23 @@ Text-specific Fields: - `RobotoCondensed-Regular.ttf` ### Text Alignment Options: +The TextAnchor enum has the following options available | `UpperLeft` | `UpperCenter` | `UpperRight` | | ------------ | -------------- | ------------- | | `MiddleLeft` | `MiddleCenter` | `MiddleRight` | | `LowerLeft` | `LowerCenter` | `LowerRight` | +### VerticalWrapMode Options: +The VerticalWrapMode enum has the following options available +| Option | Notes | +| :----- | :---- | +| 'Truncate'| Text will be clipped when reaching the bottom. | +| 'Overflow'| Text will continue to generate past the bottom edge of the panel. | ## Using Unity RichText -Rust Allows you to use Unity **[Rich Text](https://docs.unity3d.com/2021.3/Documentation/Manual/StyledText.html)** to give you more control over text styling. this lets you empathize Paragraphs, Sentences, Words & individual Letters. +Rust Allows you to use Unity **[Rich Text](https://docs.unity3d.com/2021.3/Documentation/Manual/StyledText.html)** to give you more control over text styling. This lets you empathize Paragraphs, Sentences, Words & individual Letters. -to modify a selection of text, simply wrap it in XML-style tags: `i am bold` +To modify a selection of text, simply wrap it in XML-style tags: `i am bold` RichText tags can be Nested to combine Effects: `bold and in red` Supported Tags: @@ -58,8 +62,7 @@ Supported Tags: | **i** | Renders the Text as italic | `I am italic` | | **size** | Sets the fontSize to the Value supplied | `I am small. i am not.` | | **color** | Changes the Color of the Text | `I am Coffee coloured` | -for colors, Unity Supports an assortment of named Colors you can find in **[this Table](https://docs.unity3d.com/2021.3/Documentation/Manual/StyledText.html#ColorNames).** - +For colors, Unity Supports an assortment of named Colors you can find in **[this table](https://docs.unity3d.com/2021.3/Documentation/Manual/StyledText.html#ColorNames).** From 7c4b2b4ae13af0af34f87336afeb95ff4c6e0262 Mon Sep 17 00:00:00 2001 From: Kulltero <33698270+Kulltero@users.noreply.github.com> Date: Thu, 2 Feb 2023 01:27:31 +0100 Subject: [PATCH 6/8] Add Note about SkinID = 0 bug added note explaining that supplying a skinid of 0 causes client issues --- docs/components/UnityEngine.UI.Image.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/components/UnityEngine.UI.Image.md b/docs/components/UnityEngine.UI.Image.md index 6d36f8f..ac08d6e 100644 --- a/docs/components/UnityEngine.UI.Image.md +++ b/docs/components/UnityEngine.UI.Image.md @@ -52,6 +52,7 @@ The Image Component has convenient Ways to display any Item or Skin and is recom ## Items and Skins using the `itemid` & `skinid` fields, you can let the Client handle the displaying of related Images. +NOTE: there is currently a bug when supplying a skinid of `0`, causing the player to crash, avoid including the field altogether if you don't intend to send a skinid Tip: use the ItemDefinition of your Item to easily find an Item’s ID & other useful Information ```c# From 906616ec6508a27f2e461df1cc26bf979d92a49b Mon Sep 17 00:00:00 2001 From: Kulltero <33698270+Kulltero@users.noreply.github.com> Date: Wed, 8 Feb 2023 03:04:44 +0100 Subject: [PATCH 7/8] Amend Layer Descriptions Corrected ordering of all Layer values & added descriptions to Hud & Hud.Menu --- docs/Basics.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/Basics.md b/docs/Basics.md index 1329f7a..ef24e5c 100644 --- a/docs/Basics.md +++ b/docs/Basics.md @@ -32,10 +32,10 @@ the JSON Schema to send UI to the Player consists of a List of Elements, where e layers are used when creating your top most Panel. They differ from Panels because they are static GameObjects that cannot be destroyed via a DestroyUI call. Depending on the Layer you parent to, your UI will appear above or below Rust's own UI elements. #### Available Layer values -- `Overall` the top most layer in front of all of Rust's UI +- `Overall` the top most layer in front of all of Rust's UI - `Overlay` -- `Hud` -- `Hud.Menu` +- `Hud.Menu` the layer where rust positions menus like your inventory +- `Hud` the layer where Rust stores most HUD elements like your status bar - `Under` the lowermost layer, your UI will appear behind all of Rust's UI From 8f511061fce3c63b114d95bb299b027bb10b24f0 Mon Sep 17 00:00:00 2001 From: Kulltero <33698270+Kulltero@users.noreply.github.com> Date: Fri, 10 Feb 2023 12:46:50 +0100 Subject: [PATCH 8/8] fix fadeIn using spaces in json --- docs/components/UnityEngine.UI.Button.md | 2 +- docs/components/UnityEngine.UI.Image.md | 2 +- docs/components/UnityEngine.UI.InputField | 46 -------------------- docs/components/UnityEngine.UI.InputField.md | 2 +- docs/components/UnityEngine.UI.RawImage.md | 2 +- docs/components/UnityEngine.UI.Text.md | 2 +- 6 files changed, 5 insertions(+), 51 deletions(-) delete mode 100644 docs/components/UnityEngine.UI.InputField diff --git a/docs/components/UnityEngine.UI.Button.md b/docs/components/UnityEngine.UI.Button.md index 90e333d..7799728 100644 --- a/docs/components/UnityEngine.UI.Button.md +++ b/docs/components/UnityEngine.UI.Button.md @@ -15,7 +15,7 @@ The Button Component is an Interactive Component that lets you execute Commands "color": "1.0 1.0 1.0 1.0", "material": "", "imagetype": "Simple", - "fadeIn": 0.0 + "fadeIn": 0.0 } ``` Button-specific Fields: diff --git a/docs/components/UnityEngine.UI.Image.md b/docs/components/UnityEngine.UI.Image.md index ac08d6e..b34ef0e 100644 --- a/docs/components/UnityEngine.UI.Image.md +++ b/docs/components/UnityEngine.UI.Image.md @@ -16,7 +16,7 @@ The Image is a Visual Component that allows you to display images from your Serv "png": "", "itemid": 0, "skinid": 0, - "fadeIn": 0.0 + "fadeIn": 0.0 } ``` RawImage specific Fields: diff --git a/docs/components/UnityEngine.UI.InputField b/docs/components/UnityEngine.UI.InputField deleted file mode 100644 index b1ab472..0000000 --- a/docs/components/UnityEngine.UI.InputField +++ /dev/null @@ -1,46 +0,0 @@ -# Components: InputField -**< [Previous Component](/docs/components/UnityEngine.UI.Button.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/NeedsX.md) >** - -- Identifier: `UnityEngine.UI.InputField` -- Category: **Interactive, Visual** -- Unity Documentation: **[InputField @ docs.unity3d.com](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-InputField.html)** - -The InputField Component is an Interactive Component that allows Players to enter arbitrary text that gets sent back as a Command. it automatically adds a `UnityEngine.UI.Text` to the panel, allowing you to change the `fontSize`, `font`, `align`ment & text`color` of it -```json -{ - "type": "UnityEngine.UI.InputField", - "fontSize": 14, - "font": "RobotoCondensed-Bold.ttf", - "align": "UpperLeft", - "color": "1.0 1.0 1.0 1.0", - "command": "", - "text": "", - "readOnly": false, - "lineType": "SingleLine", - "password": null, - "needsKeyboard": null, - "hudMenuInput": null, - "autofocus": null, -} -``` -> `password`, `needsKeyboard`, `hudMenuInput`, and `autofocus` are key presence Fields, key presence Fields don't have a specific type and act as a Boolean. -> if the key is present it equals true, if absent it equals false. - -InputField specific Fields: -| Key | Type | Notes | -| :---------- | :----- | :------------------- | -| `command` | string | the Command that should get sent to the Server alongside the Player's Input. The Input will get appended to the Command after a Space. | -| `text` | string | the default Text of the InputField can be combined with `readOnly` | -| `readOnly` | bool | prevents the Content from being edited | -| `lineType` | string (enum `InputField.LineType`) | dictates if the Field should allow multiple Lines & how to handle when the Player presses `enter` | -| `password` | key presence Field | if the input should be obscured | -| `needsKeyboard` | key presence Field | prevents default Keyboard behavior (movement, item switching etc) while the field is Focused | -| `hudMenuInput` | key presence Field | same as above but for Rust UI (Inventory, Crafting, etc.) | -| `autofocus` | key presence Field | selects the field upon creation | - -### Receiving Input & the lineType Setting -to receive the Player's input Text, listen for the Command you specify in the `command` field. the Input will get sent as soon as the Player unfocuses the InputField, for example by clicking out of it. - -depending on the `lineType` Setting, if it's set to SingleLine or MultiLineSubmit pressing `enter` will also cause the Input to get sent to the Server. Pressing `enter` with the MultiLineNewline Setting inserts a Newline instead. - -**< [Previous Component](/docs/components/UnityEngine.UI.Button.md)** | **[Back to Components](/docs/components/README.md)** | **[Next Component](/docs/components/NeedsX.md) >** diff --git a/docs/components/UnityEngine.UI.InputField.md b/docs/components/UnityEngine.UI.InputField.md index 5aa1671..ac4f77d 100644 --- a/docs/components/UnityEngine.UI.InputField.md +++ b/docs/components/UnityEngine.UI.InputField.md @@ -21,7 +21,7 @@ The InputField Component is an Interactive Component that allows Players to ente "needsKeyboard": null, "hudMenuInput": null, "autofocus": null, - "fadeIn": 0.0 + "fadeIn": 0.0 } ``` > `password`, `needsKeyboard`, `hudMenuInput`, and `autofocus` are key presence Fields, key presence Fields don't have a specific type and act as a Boolean. diff --git a/docs/components/UnityEngine.UI.RawImage.md b/docs/components/UnityEngine.UI.RawImage.md index e7a1f8e..47ea6d7 100644 --- a/docs/components/UnityEngine.UI.RawImage.md +++ b/docs/components/UnityEngine.UI.RawImage.md @@ -16,7 +16,7 @@ Tip: if you’re used to using hexadecimal, you can use this function to convert "material": "", "url": "", "png": "", - "fadeIn": 0.0 + "fadeIn": 0.0 } ``` RawImage specific Fields: diff --git a/docs/components/UnityEngine.UI.Text.md b/docs/components/UnityEngine.UI.Text.md index 17b1f0f..fe72820 100644 --- a/docs/components/UnityEngine.UI.Text.md +++ b/docs/components/UnityEngine.UI.Text.md @@ -15,7 +15,7 @@ The Text Component is a Visual Component that allows you to display any Text you "align": "UpperLeft", "color": "1.0 1.0 1.0 1.0", "verticalOverflow": "Truncate", - "fadeIn": 0.0 + "fadeIn": 0.0 } ``` Text-specific Fields: