From e41b8c5b325c3507aa2fae91d96fb03d52c9ea6f Mon Sep 17 00:00:00 2001 From: "Simon (Darkside) Jackson" Date: Fri, 19 Jun 2026 15:46:19 +0100 Subject: [PATCH 1/4] Release V3 - take 3 :D (#525) * Add hardening to workflows --- .github/workflows/main-publish.yml | 16 +++++++++--- .github/workflows/refreshbranch.yml | 27 ++++++++++++++++++++ .github/workflows/tagrelease.yml | 27 ++++++++++++++++++++ .github/workflows/upversionandtagrelease.yml | 27 ++++++++++++++++++++ 4 files changed, 93 insertions(+), 4 deletions(-) diff --git a/.github/workflows/main-publish.yml b/.github/workflows/main-publish.yml index f667dc63..3452bc7d 100644 --- a/.github/workflows/main-publish.yml +++ b/.github/workflows/main-publish.yml @@ -57,7 +57,10 @@ jobs: secrets: inherit release-Complete: - if: ${{ always() }} + # Only succeed if no upstream release job actually failed. Skipped siblings + # (the build-types that didn't match the PR title) are tolerated; a real + # failure makes this job skip so it can no longer report a false "success". + if: ${{ !failure() && !cancelled() }} needs: [upversion-major-Package, upversion-minor-Package, upversion-patch-Package, release-Package-only] name: Release complete runs-on: ubuntu-latest @@ -67,19 +70,24 @@ jobs: # Refresh the development branch with the main publish refresh-development: - if: ${{ always() }} + # Skip if the release didn't actually complete, so we never refresh + # development from a half-finished or failed release. + if: ${{ needs.release-Complete.result == 'success' }} needs: [release-Complete] name: Refresh development branch uses: ./.github/workflows/refreshbranch.yml with: build-host: ubuntu-latest target-branch: development - source-branch: main + # The branch this release PR merged into (the trigger pins this to the + # release branch). Avoids hardcoding a branch name that doesn't exist. + source-branch: ${{ github.event.pull_request.base.ref }} secrets: inherit # Up version the development branch ready for future development upversion-development: - if: ${{ always() }} + # Only re-version development once it has been refreshed successfully. + if: ${{ needs.refresh-development.result == 'success' }} needs: [refresh-development] name: UpVersion the development branch for the next release uses: ./.github/workflows/upversionandtagrelease.yml diff --git a/.github/workflows/refreshbranch.yml b/.github/workflows/refreshbranch.yml index 129d610c..4ed0862c 100644 --- a/.github/workflows/refreshbranch.yml +++ b/.github/workflows/refreshbranch.yml @@ -29,6 +29,33 @@ jobs: echo "Build Script Version: $scriptVersion" echo "::endgroup::" shell: pwsh + - name: Validate GIT_PAT + env: + GIT_PAT: ${{ secrets.GIT_PAT }} + shell: pwsh + run: | + if ([string]::IsNullOrWhiteSpace($env:GIT_PAT)) { + Write-Error "GIT_PAT secret is empty or not set. Add a valid Personal Access Token to the repository/org secrets and re-run." + exit 1 + } + $headers = @{ + Authorization = "Bearer $env:GIT_PAT" + "User-Agent" = "uiextensions-release-preflight" + Accept = "application/vnd.github+json" + } + try { + $repo = Invoke-RestMethod -Uri "https://api.github.com/repos/$env:GITHUB_REPOSITORY" -Headers $headers -ErrorAction Stop + } + catch { + $code = if ($_.Exception.Response) { [int]$_.Exception.Response.StatusCode } else { "unknown" } + Write-Error "GIT_PAT was rejected by GitHub (HTTP $code). It is likely expired, revoked, or lacks access to $env:GITHUB_REPOSITORY. Regenerate the token and update the GIT_PAT secret. Details: $($_.Exception.Message)" + exit 1 + } + if ($null -ne $repo.permissions -and -not $repo.permissions.push) { + Write-Error "GIT_PAT authenticated but does not have push access to $env:GITHUB_REPOSITORY. Grant 'repo' (classic PAT) or Contents: read & write (fine-grained PAT)." + exit 1 + } + Write-Host "GIT_PAT validated: authenticated with push access to $env:GITHUB_REPOSITORY." - uses: actions/checkout@v7 with: ref: ${{ inputs.target-branch }} diff --git a/.github/workflows/tagrelease.yml b/.github/workflows/tagrelease.yml index 7a8d6826..38d10e03 100644 --- a/.github/workflows/tagrelease.yml +++ b/.github/workflows/tagrelease.yml @@ -29,6 +29,33 @@ jobs: echo "Build Script Version: $scriptVersion" echo "::endgroup::" shell: pwsh + - name: Validate GIT_PAT + env: + GIT_PAT: ${{ secrets.GIT_PAT }} + shell: pwsh + run: | + if ([string]::IsNullOrWhiteSpace($env:GIT_PAT)) { + Write-Error "GIT_PAT secret is empty or not set. Add a valid Personal Access Token to the repository/org secrets and re-run." + exit 1 + } + $headers = @{ + Authorization = "Bearer $env:GIT_PAT" + "User-Agent" = "uiextensions-release-preflight" + Accept = "application/vnd.github+json" + } + try { + $repo = Invoke-RestMethod -Uri "https://api.github.com/repos/$env:GITHUB_REPOSITORY" -Headers $headers -ErrorAction Stop + } + catch { + $code = if ($_.Exception.Response) { [int]$_.Exception.Response.StatusCode } else { "unknown" } + Write-Error "GIT_PAT was rejected by GitHub (HTTP $code). It is likely expired, revoked, or lacks access to $env:GITHUB_REPOSITORY. Regenerate the token and update the GIT_PAT secret. Details: $($_.Exception.Message)" + exit 1 + } + if ($null -ne $repo.permissions -and -not $repo.permissions.push) { + Write-Error "GIT_PAT authenticated but does not have push access to $env:GITHUB_REPOSITORY. Grant 'repo' (classic PAT) or Contents: read & write (fine-grained PAT)." + exit 1 + } + Write-Host "GIT_PAT validated: authenticated with push access to $env:GITHUB_REPOSITORY." - uses: actions/checkout@v7 with: fetch-depth: 0 diff --git a/.github/workflows/upversionandtagrelease.yml b/.github/workflows/upversionandtagrelease.yml index ca7ccdea..bd6732bc 100644 --- a/.github/workflows/upversionandtagrelease.yml +++ b/.github/workflows/upversionandtagrelease.yml @@ -48,6 +48,33 @@ jobs: echo "Build Script Version: $scriptVersion" echo "::endgroup::" shell: pwsh + - name: Validate GIT_PAT + env: + GIT_PAT: ${{ secrets.GIT_PAT }} + shell: pwsh + run: | + if ([string]::IsNullOrWhiteSpace($env:GIT_PAT)) { + Write-Error "GIT_PAT secret is empty or not set. Add a valid Personal Access Token to the repository/org secrets and re-run." + exit 1 + } + $headers = @{ + Authorization = "Bearer $env:GIT_PAT" + "User-Agent" = "uiextensions-release-preflight" + Accept = "application/vnd.github+json" + } + try { + $repo = Invoke-RestMethod -Uri "https://api.github.com/repos/$env:GITHUB_REPOSITORY" -Headers $headers -ErrorAction Stop + } + catch { + $code = if ($_.Exception.Response) { [int]$_.Exception.Response.StatusCode } else { "unknown" } + Write-Error "GIT_PAT was rejected by GitHub (HTTP $code). It is likely expired, revoked, or lacks access to $env:GITHUB_REPOSITORY. Regenerate the token and update the GIT_PAT secret. Details: $($_.Exception.Message)" + exit 1 + } + if ($null -ne $repo.permissions -and -not $repo.permissions.push) { + Write-Error "GIT_PAT authenticated but does not have push access to $env:GITHUB_REPOSITORY. Grant 'repo' (classic PAT) or Contents: read & write (fine-grained PAT)." + exit 1 + } + Write-Host "GIT_PAT validated: authenticated with push access to $env:GITHUB_REPOSITORY." - uses: actions/checkout@v7 with: ref: ${{ inputs.target-branch }} From 5975de7b1ccf76a9e448f1546d58cb1647e42e92 Mon Sep 17 00:00:00 2001 From: action Date: Fri, 19 Jun 2026 15:23:31 +0000 Subject: [PATCH 2/4] Auto increment pre-release version to 3.0.0 [skip ci] --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index ec166e1c..6bb5e0db 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "com.unity.uiextensions", "displayName": "Unity UI Extensions", - "version": "3.0.0-pre.1", + "version": "3.0.0", "description": "An extension project for the Unity3D UI system, all crafted and contributed by the awesome Unity community", "author": "Simon darkside Jackson <@SimonDarksideJ>", "contributors": [ From d47f838ba918bbb9b26f242bd944940a711f525f Mon Sep 17 00:00:00 2001 From: "Simon (Darkside) Jackson" Date: Fri, 19 Jun 2026 18:50:25 +0100 Subject: [PATCH 3/4] Refresh README for V3.0.0 branding [skip ci] --- CHANGELOG.md | 43 +++++ README.md | 471 +++++++++++++++++++++++++-------------------------- 2 files changed, 270 insertions(+), 244 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 83c2e7da..67b27655 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,49 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/). +## Release 3.0.0 - Unity 6, reimagined - 2026/06 + +The V3 relaunch brings **full Unity 6 support**, a refreshed brand, and the start of a two-package ecosystem — the proven uGUI library you know, now joined by a modern UI Toolkit companion. + +> **Two packages. One ecosystem.** These notes cover the **uGUI** package (`com.unity.uiextensions`). Meet its new companion: [UI Toolkit Extensions](https://github.com/Unity-UI-Extensions/com.unity.uitoolkitextensions). + +### Highlights + +- **Full Unity 6 support** — the whole library verified and updated for Unity 6, with legacy dependencies cleared out and the examples refreshed. +- **Two-package ecosystem** — the new UI Toolkit Extensions package launches alongside under the shared 3.0 banner. + +### Added + +- New control: **GridRawImage** +- New control: **UI Knob 2** (`UI_Knob2`) +- New control: **UI Segmented Circle** / Segmented Control +- New control: **UI Graphic Selector** +- UILineConnector: the pivot can now be used as the reference point when drawing lines (#490) +- UILineConnector: new "close line" option to finish a line off and fill any gaps at the end +- BoxSlider: added `SetXWithoutNotify` and `SetYWithoutNotify` + +### Changed / Fixed + +- Reorderable List: fixed a null-reference exception, and resolved element-stacking when moving elements slightly +- Scroll Snap: resolved a race condition that could raise a NaN error when lerping; made rescaling and full-screen scroll snap more resilient +- HSS/VSS: guarded against a divide-by-zero when the scroll snap has a single page; `GetCurrentPage` made more resilient +- Infinite Scroll: resolved out-of-bounds issues +- Flow Layout Group: addressed layout issues and fixed the last line overflowing the rect bounds +- UI Particle System: new "CullingMode" option to resolve unscaled delta time (#486 / #487) +- Gradient2: optimised `ModifyMesh`; fixed radial triangle add order (#384) +- ScrollRect: force `ScrollRect.content` setup (#485) +- UILineConnector: improved point-array calculation (#495); refresh on global scale change +- Layout groups now rebuild on disable/enable +- General TMPro/Text compatibility housekeeping (#477) +- Compile-flag support for Unity 6 (#493) + +### Contributors + +Huge thanks to everyone who contributed to this release: +[@SimonDarksideJ](https://github.com/SimonDarksideJ), [@bluefallsky](https://github.com/bluefallsky), [@hugoymh](https://github.com/hugoymh), [@JavierMonton](https://github.com/JavierMonton), [@Dover8](https://github.com/Dover8), [@fgrg2801](https://github.com/fgrg2801), [@Moderbord](https://github.com/Moderbord). + +----- + ## Release 2.3.2 - Rejuvenation - 2023/11/26 2023 is certainly an interesting year to keep you on your toes, and finding time to keep managing all the requests and updates that come in are taking their toll, especially for a FREE project, but nonetheless, I still do it. diff --git a/README.md b/README.md index 83221812..690e92b3 100644 --- a/README.md +++ b/README.md @@ -1,244 +1,227 @@ -# Unity UI Extensions README - -This is an extension project for the new Unity UI system which can be found at: [Unity UI Source](https://github.com/Unity-Technologies/uGUI) - -> [Check out the control demos on our Tumblr page](https://unityuiextensions.tumblr.com/) - -[![openupm](https://img.shields.io/npm/v/com.unity.uiextensions?label=openupm®istry_uri=https://package.openupm.com)](https://openupm.com/packages/com.unity.uiextensions/) -[![Publish main branch and increment version](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/actions/workflows/main-publish.yml/badge.svg)](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/actions/workflows/main-publish.yml) -[![Publish development branch on Merge](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/actions/workflows/development-publish.yml/badge.svg)](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/actions/workflows/development-publish.yml) -[![Build and test UPM packages for platforms, all branches except main](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/actions/workflows/development-buildandtestupmrelease.yml/badge.svg)](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/actions/workflows/development-buildandtestupmrelease.yml) - -## [Intro](https://unity-ui-extensions.github.io/GettingStarted) - -For more info, here's a little introduction video for the project: - -[![View Intro Video](http://img.youtube.com/vi/njoIeE4akq0/0.jpg)](http://www.youtube.com/watch?v=njoIeE4akq0 "Unity UI Extensions intro video") - -You can follow the UI Extensions team for updates and news on: - -### [Twitter - #unityuiextensions](https://twitter.com/search?q=%23unityuiextensions) / [Facebook](https://www.facebook.com/UnityUIExtensions/) / [YouTube](https://www.youtube.com/@UnityUIExtensions) - -> Ways to get in touch: -> -> - [Gitter Chat](https://gitter.im/Unity-UI-Extensions/Lobby) site for the UI Extensions project -> - [GitHub Discussions](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/discussions), if you have any questions, queries or suggestions - ------ - -## [What is this repository for?](https://unity-ui-extensions.github.io/About) - -In this repository is a collection of extension scripts / effects and controls to enhance your Unity UI experience. These scripts have been gathered from many sources, combined and improved over time. - -> The majority of the scripts came from the Scripts thread on the [Unity UI forum here](http://bit.ly/UnityUIScriptsForumPost) - -You can either download / fork this project to access the scripts, or you can also download these pre-compiled Unity Assets, chock full of goodness for each release: - -## [Download Latest - Version 2.3](https://unity-ui-extensions.github.io/Downloads) - -We have expanded where you can download the UnityPackage asset and widened the options to contribute to the project. - -> I will still stress however, ***contribution is optional***. **The assets / code will always remain FREE** - -| [![Download from Itch.IO](https://unity-ui-extensions.github.io/SiteImages/itchio.png)](https://unityuiextensions.itch.io/uiextensions2-0 "Download from Itch.IO") | [![Download from Itch.IO](https://unity-ui-extensions.github.io/SiteImages/unionassets.png)](https://unionassets.com/unity-ui-extensions "Download from Union Assets") | [![Download from Itch.IO](https://unity-ui-extensions.github.io/SiteImages/patreon.jpg)](https://www.patreon.com/UnityUIExtensions "Support Unity UI Extensions on Patreon & download")| -| :--- | :--- | :--- | -| [Grab from Itchio](https://unityuiextensions.itch.io/uiextensions2-0) | [Obtain via Union Assets](https://unionassets.com/unity-ui-extensions) |[Support through Patreon](https://www.patreon.com/UnityUIExtensions) | - -> Still available to download on the [GitHub site](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/releases) if you prefer - -To view previous releases, visit the [release archive](https://unity-ui-extensions.github.io/Downloads) - ------ - -## [Supporting the UI Extensions project](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=89L8T9N6BR7LJ) - -If you wish to further support the Unity UI Extensions project itself, then you can either subsidize your downloads above, or using the links below. - -All funds go to support the project, no matter the amount. **Donations in code are also extremely welcome** - -|[![Donate via PayPal](https://www.paypalobjects.com/webstatic/mktg/Logo/pp-logo-150px.png)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=89L8T9N6BR7LJ "Donating via Paypal")|[![Buy us a Coffee](https://uploads-ssl.webflow.com/5c14e387dab576fe667689cf/5cbed8a4ae2b88347c06c923_BuyMeACoffee_blue-p-500.png)](https://ko-fi.com/uiextensions "Buy us a Coffee")| -|-|-| -||| - -> (PayPal account not required and you can remain anonymous if you wish) - ------ - -## [Getting Started](https://unity-ui-extensions.github.io/GettingStarted) - -To get started with the project, here's a little guide: - -[![View Getting Started Video](http://img.youtube.com/vi/sVLeYmsNQAI/0.jpg)](http://www.youtube.com/watch?v=sVLeYmsNQAI "Unity UI getting started video") - ------ - -## [Updates:](https://unity-ui-extensions.github.io/ReleaseNotes/RELEASENOTES) - -## Release 2.4.0 - Unity supports Unity UI - 2025/11/20 - -Stay tuned as we begin work on a Unity 6 update, to verify Unity 6 support and possibly get some new controls in the mix. - -## Release 2.3.2 - Rejuvenation - 2023/11/26 - -2023 is certainly an interesting year to keep you on your toes, and finding time to keep managing all the requests and updates that come in are taking their toll, especially for a FREE project, but nonetheless, I still do it. - -Mainly bugfixes for the end of year update, promoting some resolutions that have been verified and tested since the last release. - -To get up to speed with the Unity UI Extensions, check out the [Getting Started](https://unity-ui-extensions.github.io/GettingStarted.html) Page. - -> Ways to get in touch: -> -> - [GitHub Discussions](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/discussions), if you have any questions, queries or suggestions -> - [Gitter Chat](https://gitter.im/Unity-UI-Extensions/Lobby) site for the UI Extensions project -> -> Much easier that posting a question / issue on YouTube, Twitter or Facebook :D - -## Breaking changes - -For customers upgrading from earlier versions of Unity to Unity 2020, please be aware of the Breaking change related to Text Based components. You will need to manually replace any UI using the older ```Text``` component and replace them with ```TextMeshPro``` versions. This is unavoidable due to Unity deprecating the Text component. - -> New users to 2022 are unaffected as all the Editor commands have been updated to use the newer TextMeshPro versions. - -For more details, see the [deprecation notice](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/discussions/428) on GitHub. - -## Added - -- Add CalculatePointOnCurve for uilinerenderer (@victornor) - -## Changed - -- fix: Fixed an null reference exception with the ResetSelectableHighlight (@FejZa) -- fix: Resolved an issue where the last line in a flow layout group would overflow the rect bounds. -- fix: GetPosition when Segments is null (@victornor) -- fix: Fix Bug! NicerOutline color.a Loss when m_UseGraphicAlpha is true (wanliyun) -- fix: Update to force Enumerated start for Accordion elements, Resolves: #455 -- Added argument to the UpdateLayout method for the HSS/VSS to move to a new starting page. -- Updated implementations to handle 2023 support, with 2023 moving in to public release. -- Added extra event on the AutoCompleteComboBox, to fire when an item in the list is selected, with its display name. -- FlowLayoutGroup components updated to latest (likely the last as the author has stopped development) - -## Deprecated - -- All deprecated Text based components now have "obsolete" tags, to avoid breaking code. Note, these do not function in 2022 and above, as Unity have "changed" things. For any affected component, I recommend updating to use TextMeshPro native features. - -- [UI Extensions Issue log](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/issues) - -## Upgrade Notes - -We recommend using the UPM delivery method. If you are using the Unity asset, there should be no issues updating but if you have a problem, just deleted the old Unity-UI-Extensions folder and import the asset new. - ------ - -## Release History - -For the full release history, follow the below link to the full release notes page. - -### [Release Notes](https://unity-ui-extensions.github.io/ReleaseNotes/RELEASENOTES) - ------ - -## [Controls and extensions listed in this project](https://unity-ui-extensions.github.io/Controls) - -There are almost 70+ extension controls / effect and other utilities in the project which are listed on the following page: - -> ## [Check out the control demos on our Tumblr page](https://www.tumblr.com/blog/unityuiextensions) -> -> | [![UI Line Renderer](https://unity-ui-extensions.github.io/SiteImages/LineRenderer.gif)](https://www.tumblr.com/blog/unityuiextensions "UI Line Renderer") | [![UI Knob](https://unity-ui-extensions.github.io/SiteImages/UIKnob.gif)](https://www.tumblr.com/blog/unityuiextensions "UI Knob") | [![ScrollSnap](https://unity-ui-extensions.github.io/SiteImages/ScrollSnap.gif)](https://www.tumblr.com/blog/unityuiextensions "Scroll Snap")| -> | :--- | :--- | :--- | -> | [UI Line Renderer](https://www.tumblr.com/blog/unityuiextensions) | [UI Knob](https://www.tumblr.com/blog/unityuiextensions) |[Scroll Snap](https://www.tumblr.com/blog/unityuiextensions) | - -## [UI Extensions controls list](https://unity-ui-extensions.github.io/Controls) - -[Controls](https://unity-ui-extensions.github.io/Controls.html#controls) - -|Accordion|ColorPicker|Selection Box|UI Flippable|ComboBox| -|-|-|-|-|-| -|AutoComplete ComboBox|DropDown List|BoundToolTip|UIWindowBase|UI Knob| -|TextPic|Input Focus|Box Slider|Cooldown Button|Segmented Control| -|Stepper|Range Slider|Radial Slider|MultiTouch Scroll Rect|MinMax SLider| - -[Primitives](https://unity-ui-extensions.github.io/Controls.html#primitives) - -|UILineRenderer|UILineTextureRenderer|UICircle|DiamondGraph|UICornerCut| -|-|-|-|-|-| -|UIPolygon|UISquircle|||| - -[Layouts](https://unity-ui-extensions.github.io/Controls.html#layouts) - -|Horizontal Scroll Snap|Vertical Scroll Snap|Flow Layout Group|Radial Layout|Tile Size Fitter| -|-|-|-|-|-| -|Scroll Snap (alt implementation)|Reorderable List|UI Vertical Scroller|Curved Layout|Table Layout| -|FancyScrollView|Card UI|Scroll Position Controller (obsolete)|Content Scroll Snap Horizontal|Scroller| -|ResizePanel|RescalePanel|RescaleDragPanel||| - -[Effects](https://unity-ui-extensions.github.io/Controls.html#effect-components) - -|Best Fit Outline|Curved Text|Gradient|Gradient2|Letter Spacing| -|-|-|-|-|-| -|NicerOutline|RaycastMask|UIFlippable|UIImageCrop|SoftAlphaMask| -|CylinderText|UIParticleSystem|CurlyUI|Shine Effect|Shader Effects| - -> Text Effects are not supported with TextMeshPro due to its architecture, try using the native TextMeshPro effects instead. - -[Additional Components](https://unity-ui-extensions.github.io/Controls.html#additional-components) - -|ReturnKeyTrigger|TabNavigation|uGUITools|ScrollRectTweener|ScrollRectLinker| -|-|-|-|-|-| -|ScrollRectEx|UI_InfiniteScroll|UI_ScrollRectOcclusion|UIScrollToSelection|UISelectableExtension| -|switchToRectTransform|ScrollConflictManager|CLFZ2 (Encryption)|DragCorrector|PPIViewer| -|UI_TweenScale|UI_MagneticInfiniteScroll|UI_ScrollRectOcclusion|NonDrawingGraphic| -|UILineConnector| -|UIHighlightable|Menu Manager|Pagination Manager||| - -*More to come* - ------ - -## [How do I get set up?](https://unity-ui-extensions.github.io/UPMInstallation.html) - -The recommended way to add the Unity UI Extensions project to your solution is to use the Unity package Manager. Simply use the Unity Package Manager to reference the project to install it - -New for 2020, we have added OpenUPM support and the package can be installed using the following [OpenUPM CLI](https://openupm.com/docs/) command: - -```cli -`openupm add com.unity.uiextensions` -``` - -> For more details on using [OpenUPM CLI, check the docs here](https://github.com/openupm/openupm-cli#installation). - -- Unity Package Manager - manual - -Alternatively, you can also add the package manually through the Unity package manager using the scope ```com.unity.uiextensions```, see the [Unity Package Manager docs](https://learn.unity.com/tutorial/the-package-manager) for more information. - -- Unity 2018 or lower -The pre-compiled Unity assets are the only solution for Unity 2018 or earlier due to the changes in the Unity UI framework in Unity made for 2019. -Either clone / download this repository to your machine and then copy the scripts in, or use the pre-packaged .UnityPackage for your version of Unity and import it as a custom package in to your project. - -## [Contribution guidelines](https://unity-ui-extensions.github.io/ContributionGuidelines) - -Got a script you want added? Then just fork the [GitHub repository](https://github.com/unity-UI-Extensions/com.unity.uiextensions) and submit a PR. All contributions accepted (including fixes) - -Just ensure: - -- The header of the script should match the standard used in all scripts. -- The script uses the **Unity.UI.Extensions** namespace so they do not affect any other developments. -- (optional) Add Component and Editor options where possible. (editor options are in the Editor\UIExtensionsMenuOptions.cs file) - -## [License](https://raw.githubusercontent.com/Unity-UI-Extensions/com.unity.uiextensions/release/LICENSE.md) - -All scripts conform to the BSD-3-Clause license and are free to use / distribute. See the [LICENSE](https://raw.githubusercontent.com/Unity-UI-Extensions/com.unity.uiextensions/release/LICENSE.md) file for more information = - -## [Like what you see?](https://unity-ui-extensions.github.io/FurtherInfo) - -All these scripts were put together for my latest book Unity3D UI Essentials -Check out the [page on my blog](http://bit.ly/Unity3DUIEssentials) for more details and learn all about the inner workings of the new Unity UI System. - -## [The downloads](https://unity-ui-extensions.github.io/Downloads) - -As this repo was created to support my new Unity UI Title ["Unity 3D UI Essentials"](http://bit.ly/Unity3DUIEssentials), in the downloads section you will find two custom assets (SpaceShip-DemoScene-Start.unitypackage and RollABallSample-Start.unitypackage). These are just here as starter scenes for doing UI tasks in the book. - -I will add more sample scenes for the UI examples in this repository and detail them above over time. - -## [Previous Releases](https://unity-ui-extensions.github.io/Downloads) - -Please see the [full downloads list](https://unity-ui-extensions.github.io/Downloads) for all previous releases and their corresponding download links. +

+ + Unity UI Extensions — uGUI + +

+ +

Stop rebuilding UI from scratch

+ +

+ 100+ battle-tested uGUI controls for Unity — open source, community-driven, production-ready.
+ The controls you would build anyway, already polished and edge-case handled. +

+ +

+ 100+ controls · 21 example scenes · battle-tested since 2015 · 100% free · BSD-3-Clause +

+ +

+ openupm + Publish main branch and increment version + Publish development branch on Merge + Build and test UPM packages for platforms, all branches except main +

+ +----- + +## [Supercharge your Unity UI](https://unity-ui-extensions.github.io/ugui/) + +Unity UI Extensions is the flagship open-source UI control collection for Unity's **uGUI** system — the controls you would build anyway, already polished and edge-case handled. Gathered from many sources, combined and improved, and battle-tested by the community since 2015. + +> Built on the Unity UI system: [Unity UI Source](https://github.com/Unity-Technologies/uGUI) + +For more info, here's a little introduction video for the project: + +[![View Intro Video](http://img.youtube.com/vi/njoIeE4akq0/0.jpg)](http://www.youtube.com/watch?v=njoIeE4akq0 "Unity UI Extensions intro video") + +You can follow the UI Extensions team for updates and news on: + +### [Twitter - #unityuiextensions](https://twitter.com/search?q=%23unityuiextensions) / [Facebook](https://www.facebook.com/UnityUIExtensions/) / [YouTube](https://www.youtube.com/@UnityUIExtensions) + +> Ways to get in touch: +> +> - [Gitter Chat](https://gitter.im/Unity-UI-Extensions/Lobby) site for the UI Extensions project +> - [GitHub Discussions](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/discussions), if you have any questions, queries or suggestions + +----- + +## [What is this repository for?](https://unity-ui-extensions.github.io/ugui/) + +In this repository is a collection of extension scripts / effects and controls to enhance your Unity UI experience. These scripts have been gathered from many sources, combined and improved over time. + +> The majority of the scripts came from the Scripts thread on the [Unity UI forum here](http://bit.ly/UnityUIScriptsForumPost) + +You can either download / fork this project to access the scripts, or you can download these pre-compiled Unity Assets, chock full of goodness for each release: + +## [Download the latest release — Version 3.0](https://unity-ui-extensions.github.io/ugui/install/) + +Prefer a ready-made package? Grab the pre-compiled UnityPackage for every release. We've widened the options to contribute to the project too. + +> I will still stress however, ***contribution is optional***. **The assets / code will always remain FREE** + +| [![Download from itch.io](https://unity-ui-extensions.github.io/SiteImages/itchio.png)](https://unityuiextensions.itch.io/uiextensions2-0 "Download from itch.io") | [![Support on Patreon](https://unity-ui-extensions.github.io/SiteImages/patreon.jpg)](https://www.patreon.com/UnityUIExtensions "Support Unity UI Extensions on Patreon & download") | +| :---: | :---: | +| [Grab it on itch.io](https://unityuiextensions.itch.io/uiextensions2-0) | [Support via Patreon](https://www.patreon.com/UnityUIExtensions) | + +> Still available to download on the [GitHub site](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/releases) if you prefer + +To view previous releases, visit the [release archive](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/releases) + +> ### 🎛️ Two packages. One ecosystem. +> +> This is the **uGUI** package (`com.unity.uiextensions`), for Unity's established UI system. Building with Unity 6's modern runtime UI? Meet its companion: +> +> **[UI Toolkit Extensions →](https://github.com/Unity-UI-Extensions/com.unity.uitoolkitextensions)** — a growing library of controls, components and utilities for the UI Toolkit solution. + +----- + +## [Supporting the UI Extensions project](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=89L8T9N6BR7LJ) + +If you wish to further support the Unity UI Extensions project itself, then you can either subsidise your downloads above, or use the links below. + +All funds go to support the project, no matter the amount. **Donations in code are also extremely welcome.** + +|[![Donate via PayPal](https://www.paypalobjects.com/webstatic/mktg/Logo/pp-logo-150px.png)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=89L8T9N6BR7LJ "Donating via Paypal")|[![Buy us a Coffee](https://uploads-ssl.webflow.com/5c14e387dab576fe667689cf/5cbed8a4ae2b88347c06c923_BuyMeACoffee_blue-p-500.png)](https://ko-fi.com/uiextensions "Buy us a Coffee")| +|-|-| +||| + +> (PayPal account not required and you can remain anonymous if you wish) + +----- + +## [Getting Started](https://unity-ui-extensions.github.io/ugui/install/) + +To get started with the project, here's a little guide: + +[![View Getting Started Video](http://img.youtube.com/vi/sVLeYmsNQAI/0.jpg)](http://www.youtube.com/watch?v=sVLeYmsNQAI "Unity UI getting started video") + +----- + +## What's new in 3.0 — Unity 6, reimagined + +The V3 relaunch brings **full Unity 6 support**, a fresh coat of paint, and the start of a two-package ecosystem. + +- **Unity 6 ready** — the whole library verified and updated for Unity 6, with legacy dependencies cleared out. +- **New controls** — GridRawImage, UI Knob 2, UI Segmented Circle and a UI Graphic Selector join the collection. +- **Battle-hardened** — fixes across Reorderable List, Scroll Snap, Infinite Scroll, Flow Layout Group, UI Particle System and more. +- **Sharper UILineConnector** — pivot reference points, closing lines and smarter point-array maths. + +> 📓 Read the full, detailed [Release Notes](https://unity-ui-extensions.github.io/ugui/releasenotes/). + +### Earlier releases + +Looking for previous versions? The complete history lives on the [Release Notes](https://unity-ui-extensions.github.io/ugui/releasenotes/) page. + +### Upgrade notes + +We recommend the UPM delivery method. If you are using the Unity asset, there should be no issues updating — but if you hit a problem, just delete the old Unity-UI-Extensions folder and import the asset fresh. + +> **Upgrading from Unity 2019 or earlier?** Text-based components were replaced with `TextMeshPro` equivalents when Unity deprecated the legacy `Text` component. See the [deprecation notice](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/discussions/428) for details. New projects on 2022+ are unaffected. + +----- + +## [Controls and extensions listed in this project](https://unity-ui-extensions.github.io/ugui/#controls) + +There are 100+ extension controls / effects and other utilities in the project which are listed on the following page: + +> ## [Check out the control demos on our Tumblr page](https://www.tumblr.com/blog/unityuiextensions) +> +> | [![UI Line Renderer](https://unity-ui-extensions.github.io/SiteImages/LineRenderer.gif)](https://www.tumblr.com/blog/unityuiextensions "UI Line Renderer") | [![UI Knob](https://unity-ui-extensions.github.io/SiteImages/UIKnob.gif)](https://www.tumblr.com/blog/unityuiextensions "UI Knob") | [![ScrollSnap](https://unity-ui-extensions.github.io/SiteImages/ScrollSnap.gif)](https://www.tumblr.com/blog/unityuiextensions "Scroll Snap")| +> | :--- | :--- | :--- | +> | [UI Line Renderer](https://www.tumblr.com/blog/unityuiextensions) | [UI Knob](https://www.tumblr.com/blog/unityuiextensions) |[Scroll Snap](https://www.tumblr.com/blog/unityuiextensions) | + +## [UI Extensions controls list](https://unity-ui-extensions.github.io/ugui/#controls) + +[Controls](https://unity-ui-extensions.github.io/ugui/controls/) + +|Accordion|ColorPicker|Selection Box|UI Flippable|ComboBox| +|-|-|-|-|-| +|AutoComplete ComboBox|DropDown List|BoundToolTip|UIWindowBase|UI Knob| +|TextPic|Input Focus|Box Slider|Cooldown Button|Segmented Control| +|Stepper|Range Slider|Radial Slider|MultiTouch Scroll Rect|MinMax SLider| + +[Primitives](https://unity-ui-extensions.github.io/ugui/controls/) + +|UILineRenderer|UILineTextureRenderer|UICircle|DiamondGraph|UICornerCut| +|-|-|-|-|-| +|UIPolygon|UISquircle|||| + +[Layouts](https://unity-ui-extensions.github.io/ugui/controls/) + +|Horizontal Scroll Snap|Vertical Scroll Snap|Flow Layout Group|Radial Layout|Tile Size Fitter| +|-|-|-|-|-| +|Scroll Snap (alt implementation)|Reorderable List|UI Vertical Scroller|Curved Layout|Table Layout| +|FancyScrollView|Card UI|Scroll Position Controller (obsolete)|Content Scroll Snap Horizontal|Scroller| +|ResizePanel|RescalePanel|RescaleDragPanel||| + +[Effects](https://unity-ui-extensions.github.io/ugui/controls/) + +|Best Fit Outline|Curved Text|Gradient|Gradient2|Letter Spacing| +|-|-|-|-|-| +|NicerOutline|RaycastMask|UIFlippable|UIImageCrop|SoftAlphaMask| +|CylinderText|UIParticleSystem|CurlyUI|Shine Effect|Shader Effects| + +> Text Effects are not supported with TextMeshPro due to its architecture, try using the native TextMeshPro effects instead. + +[Additional Components](https://unity-ui-extensions.github.io/ugui/controls/) + +|ReturnKeyTrigger|TabNavigation|uGUITools|ScrollRectTweener|ScrollRectLinker| +|-|-|-|-|-| +|ScrollRectEx|UI_InfiniteScroll|UI_ScrollRectOcclusion|UIScrollToSelection|UISelectableExtension| +|switchToRectTransform|ScrollConflictManager|CLFZ2 (Encryption)|DragCorrector|PPIViewer| +|UI_TweenScale|UI_MagneticInfiniteScroll|UI_ScrollRectOcclusion|NonDrawingGraphic| +|UILineConnector| +|UIHighlightable|Menu Manager|Pagination Manager||| + +*More to come* + +----- + +## [How do I get set up?](https://unity-ui-extensions.github.io/ugui/install/) + +The recommended way to add the Unity UI Extensions project to your solution is to use the Unity package Manager. Simply use the Unity Package Manager to reference the project to install it + +New for 2020, we have added OpenUPM support and the package can be installed using the following [OpenUPM CLI](https://openupm.com/docs/) command: + +```cli +`openupm add com.unity.uiextensions` +``` + +> For more details on using [OpenUPM CLI, check the docs here](https://github.com/openupm/openupm-cli#installation). + +- Unity Package Manager - manual + +Alternatively, you can also add the package manually through the Unity package manager using the scope ```com.unity.uiextensions```, see the [Unity Package Manager docs](https://learn.unity.com/tutorial/the-package-manager) for more information. + +- Unity 2018 or lower +The pre-compiled Unity assets are the only solution for Unity 2018 or earlier due to the changes in the Unity UI framework in Unity made for 2019. +Either clone / download this repository to your machine and then copy the scripts in, or use the pre-packaged .UnityPackage for your version of Unity and import it as a custom package in to your project. + +## [Contribution guidelines](https://github.com/Unity-UI-Extensions/com.unity.uiextensions) + +Got a script you want added? Then just fork the [GitHub repository](https://github.com/unity-UI-Extensions/com.unity.uiextensions) and submit a PR. All contributions accepted (including fixes) + +Just ensure: + +- The header of the script should match the standard used in all scripts. +- The script uses the **Unity.UI.Extensions** namespace so they do not affect any other developments. +- (optional) Add Component and Editor options where possible. (editor options are in the Editor\UIExtensionsMenuOptions.cs file) + +## [License](https://raw.githubusercontent.com/Unity-UI-Extensions/com.unity.uiextensions/release/LICENSE.md) + +All scripts conform to the BSD-3-Clause licence and are free to use / distribute. See the [LICENSE](https://raw.githubusercontent.com/Unity-UI-Extensions/com.unity.uiextensions/release/LICENSE.md) file for more information. + +## [Like what you see?](http://bit.ly/Unity3DUIEssentials) + +All these scripts were put together for my latest book Unity3D UI Essentials +Check out the [page on my blog](http://bit.ly/Unity3DUIEssentials) for more details and learn all about the inner workings of the new Unity UI System. + +## [The downloads](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/releases) + +As this repo was created to support my new Unity UI Title ["Unity 3D UI Essentials"](http://bit.ly/Unity3DUIEssentials), in the downloads section you will find two custom assets (SpaceShip-DemoScene-Start.unitypackage and RollABallSample-Start.unitypackage). These are just here as starter scenes for doing UI tasks in the book. + +I will add more sample scenes for the UI examples in this repository and detail them above over time. + +## [Previous Releases](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/releases) + +Please see the [full downloads list](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/releases) for all previous releases and their corresponding download links. From 3be24863a99c295b3e569d70c482f249fc29c8b3 Mon Sep 17 00:00:00 2001 From: "Simon (Darkside) Jackson" Date: Wed, 24 Jun 2026 14:19:47 +0100 Subject: [PATCH 4/4] Minor documentation patch --- Documentation~/Examples/Accordion.md | 19 +++++ Documentation~/Examples/CardUI.md | 27 +++++++ Documentation~/Examples/ColorPicker.md | 19 +++++ Documentation~/Examples/ComboBox.md | 48 ++++++++++++ Documentation~/Examples/Cooldown.md | 46 +++++++++++ Documentation~/Examples/CurlyUI.md | 19 +++++ Documentation~/Examples/FancyScrollView.md | 45 +++++++++++ Documentation~/Examples/FlowLayoutGroup.md | 19 +++++ Documentation~/Examples/GridRawImage.md | 19 +++++ .../Examples/InputFieldEnterSubmit.md | 19 +++++ Documentation~/Examples/MenuExample.md | 43 ++++++++++ Documentation~/Examples/RadialSlider.md | 45 +++++++++++ Documentation~/Examples/ReorderableList.md | 19 +++++ .../Examples/ScrollRectConflictManager.md | 19 +++++ Documentation~/Examples/ScrollSnaps.md | 63 +++++++++++++++ Documentation~/Examples/SelectionBox.md | 19 +++++ Documentation~/Examples/UICircleProgress.md | 47 +++++++++++ Documentation~/Examples/UICircleSegmented.md | 19 +++++ Documentation~/Examples/UIKnob.md | 40 ++++++++++ Documentation~/Examples/UILineRenderer.md | 40 ++++++++++ Documentation~/Examples/UIParticleSystem.md | 39 ++++++++++ Documentation~/Examples/UIVerticalScroller.md | 34 ++++++++ Documentation~/com.unity.uiextensions.md | 78 ++++++++++--------- README.md | 2 +- .../GridRawImage/BitArray/BitArray256.cs | 16 +++- .../GridRawImage/BitArray/BitArray8.cs | 16 +++- .../GridRawImage/BitArray/IBitArray.cs | 16 +++- Runtime/Scripts/Effects/UIParticleSystem.cs | 16 +++- 28 files changed, 798 insertions(+), 53 deletions(-) create mode 100644 Documentation~/Examples/Accordion.md create mode 100644 Documentation~/Examples/CardUI.md create mode 100644 Documentation~/Examples/ColorPicker.md create mode 100644 Documentation~/Examples/ComboBox.md create mode 100644 Documentation~/Examples/Cooldown.md create mode 100644 Documentation~/Examples/CurlyUI.md create mode 100644 Documentation~/Examples/FancyScrollView.md create mode 100644 Documentation~/Examples/FlowLayoutGroup.md create mode 100644 Documentation~/Examples/GridRawImage.md create mode 100644 Documentation~/Examples/InputFieldEnterSubmit.md create mode 100644 Documentation~/Examples/MenuExample.md create mode 100644 Documentation~/Examples/RadialSlider.md create mode 100644 Documentation~/Examples/ReorderableList.md create mode 100644 Documentation~/Examples/ScrollRectConflictManager.md create mode 100644 Documentation~/Examples/ScrollSnaps.md create mode 100644 Documentation~/Examples/SelectionBox.md create mode 100644 Documentation~/Examples/UICircleProgress.md create mode 100644 Documentation~/Examples/UICircleSegmented.md create mode 100644 Documentation~/Examples/UIKnob.md create mode 100644 Documentation~/Examples/UILineRenderer.md create mode 100644 Documentation~/Examples/UIParticleSystem.md create mode 100644 Documentation~/Examples/UIVerticalScroller.md diff --git a/Documentation~/Examples/Accordion.md b/Documentation~/Examples/Accordion.md new file mode 100644 index 00000000..11531920 --- /dev/null +++ b/Documentation~/Examples/Accordion.md @@ -0,0 +1,19 @@ +# Example: Accordion + +## Overview + +This scene demonstrates the Accordion control: a vertical stack of expandable/collapsible sections where opening one section animates its content into view. Use it when you need a compact panel of grouped content (settings categories, FAQs, inspector-style sections) that the user can reveal one piece at a time. + +## Controls Featured + +- [Accordion](/ugui/controls/accordion/) — the scene wires an Accordion Group around several Accordion Elements, each with a header and animated content body. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/Accordion/` into your project's `Assets/` folder. +2. Open the example scene in that folder (`Accordion.unity`). +3. Press **Play**. + +## What to Expect + +At runtime you see a list of Accordion Elements, each showing a header. Clicking a header expands that element to reveal its content, animating open with the group's configured transition (instant or a tween over the transition duration). By default opening one element collapses the previously open one; with **Allow Multiple** enabled, several can stay open at once, and **Toggle On** lets you click an open header to close it again. The **On Value Changed** event fires whenever the active element changes. diff --git a/Documentation~/Examples/CardUI.md b/Documentation~/Examples/CardUI.md new file mode 100644 index 00000000..a81f5ab2 --- /dev/null +++ b/Documentation~/Examples/CardUI.md @@ -0,0 +1,27 @@ +# Example: Card UI + +## Overview + +This example ships a collection of scenes showing the different Card UI presentation styles in one place: 2D expanding cards, a 2D popup with falling cards, a 2D card stack, 3D expanding cards, and a superellipse playground. Use it when you want a card-based interface for content presentation, hands of cards, or stacked/expandable panels. + +## Controls Featured + +- [Card UI](/ugui/controls/card-ui/) — each scene exercises a different card behaviour (expand, popup/fall, stack depth, 3D rounded panels) from the Card UI suite. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/CardUI/` into your project's `Assets/` folder. +2. Open one of the example scenes in that folder: `2D Card Expanding.unity`, `2D Card Popup.unity`, `2D Card Stack.unity`, `3D Card Expanding.unity`, or `Superellipse Playground.unity`. +3. Press **Play**. + +## What to Expect + +What you see depends on the scene you open: + +- **2D Card Expanding** — clickable cards that expand from a compact layout to a larger view and collapse again. +- **2D Card Popup** — physics-driven cards that pop up and fall into place. +- **2D Card Stack** — cards arranged in a depth-ordered stack, offset so each sits over the one behind it. +- **3D Card Expanding** — custom panel meshes with rounded (superellipse) corners for a 3D card effect. +- **Superellipse Playground** — a sandbox for tuning the rounded-corner superellipse shapes used by the 3D cards. + +Expand/popup/stack animations run over the configured animation duration, and selecting or closing a card fires the relevant card event where exposed. diff --git a/Documentation~/Examples/ColorPicker.md b/Documentation~/Examples/ColorPicker.md new file mode 100644 index 00000000..063c2d81 --- /dev/null +++ b/Documentation~/Examples/ColorPicker.md @@ -0,0 +1,19 @@ +# Example: Color Picker + +## Overview + +This scene demonstrates the Color Picker control built from the `Picker 2.0` prefab, combining a box slider, HSV/RGB sliders, hex input, alpha, an on-screen colour sampler, and saveable presets. Use it whenever your project needs runtime colour selection, for example in an editor tool, character customiser, or paint feature. + +## Controls Featured + +- [Color Picker](/ugui/controls/color-picker/) — the `PickerTest` scene drops the `Picker 2.0` prefab into a canvas, exposing the combined HSV/RGB sliders, hex field, colour sampler, and preset swatches. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/ColorPicker/` into your project's `Assets/` folder. +2. Open the example scene in that folder (`PickerTest.unity`). +3. Press **Play**. + +## What to Expect + +At runtime you can drag the box slider and the HSV/RGB/alpha sliders, or type a hex code, to change the current colour; the picker raises its **On Value Changed** event each time the colour changes. The colour sampler lets you click anywhere on screen to pick that pixel's colour into the picker. Presets let you save the current colour as a swatch and reload it later; depending on the presets **Save Mode** (None, JSON, or PlayerPrefs) user-defined swatches persist between sessions, alongside any predefined preset colours. The picker and its presets/sampler are configured entirely in the prefab, so no scripting is required to try it. diff --git a/Documentation~/Examples/ComboBox.md b/Documentation~/Examples/ComboBox.md new file mode 100644 index 00000000..62ef0a1f --- /dev/null +++ b/Documentation~/Examples/ComboBox.md @@ -0,0 +1,48 @@ +# Example: ComboBox & Dropdowns + +## Overview + +This scene places the three Unity UI Extensions selection controls side by side so you can compare them: the plain ComboBox, the AutoComplete ComboBox, and the DropDown List. It ships demo scripts that populate the controls, refresh their options at runtime, add items from an input field, and log every change event. Use it to decide which selection control best fits your UI and to see the correct way to manage their contents from code. + +## Controls Featured + +- [ComboBox](/ugui/controls/combobox/) — a fixed text combobox; the demo adds items to it and logs its selection-changed event. +- [AutoComplete ComboBox](/ugui/controls/autocomplete-combobox/) — a text field with live filtering against a vocabulary; the demo logs its text, validity, selection, and item-selected events. +- [DropDown List](/ugui/controls/dropdown-list/) — a richer dropdown supporting text and images; the demo refreshes its items and logs its changed event. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/ComboBox/` into your project's `Assets/` folder. +2. Open the example scene in that folder (`ComboBox.unity`). +3. Press **Play**. + +## What to Expect + +At runtime each of the three controls is pre-populated with a shared set of options (`More`, `ComboBox`, `Example`, `Goodness`). Open the ComboBox or DropDown List to pick from the list, or type into the AutoComplete ComboBox to filter matches as you go. An input field plus buttons let you add new entries into each control live. Every interaction is written to the Console: the ComboBox and DropDown log their selection changes, while the AutoComplete logs separate events for text changes, validity changes, selection changes, and item selection. This makes it a useful reference for wiring up the controls' events and for the recommended `SetAvailableOptions` / `RefreshItems` / `AddItem` APIs rather than editing the options list directly. + +## Key Code Patterns + +Populate (and reset) each control's options at startup — note `RefreshItems` for the DropDown List versus `SetAvailableOptions` for the others: + +```csharp +private string[] dropDownItems = { "More", "ComboBox", "Example", "Goodness" }; + +void Start() +{ + acb.SetAvailableOptions(dropDownItems); // AutoCompleteComboBox + cb.SetAvailableOptions(dropDownItems); // ComboBox + ddl.RefreshItems(dropDownItems); // DropDownList +} +``` + +Add a single item from an input field at runtime: + +```csharp +public void AddComboBox() +{ + if (!string.IsNullOrWhiteSpace(input.text)) + { + comboBox.AddItem(input.text); + } +} +``` diff --git a/Documentation~/Examples/Cooldown.md b/Documentation~/Examples/Cooldown.md new file mode 100644 index 00000000..6061f375 --- /dev/null +++ b/Documentation~/Examples/Cooldown.md @@ -0,0 +1,46 @@ +# Example: Cooldown Button + +## Overview + +This scene demonstrates the Cooldown Button control, which makes a Selectable (Button, Toggle, etc.) unusable for a set time after it is clicked. It also shows how to drive visual feedback from the button's cooldown progress by pairing it with a Unity Image fill and with the SoftMask effect. Use it for ability/power-up buttons, rate-limited actions, or any UI where an action needs a recovery delay. + +## Controls Featured + +- [Cooldown Button](/ugui/controls/cooldown-button/) — the scene attaches a CooldownButton and reads its timing properties (`CooldownTimeRemaining`, `CooldownTimeElapsed`, `CooldownTimeout`, `CooldownPercentComplete`) each frame to animate the cooldown effect. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/Cooldown/` into your project's `Assets/` folder. +2. Open the example scene in that folder (`CooldownExamples.unity`). +3. Press **Play**. + +## What to Expect + +Clicking a cooldown button starts its timer and triggers the **On Cooldown Start** event. While the timer runs, the linked visuals update every frame: one example sweeps a Unity Image's radial fill from empty to full, optionally showing the cooldown percentage as text, while another drives the `CutOff` of a SoftMask to reveal/wipe the graphic over the cooldown. Clicking the button again before it finishes fires **On Button Click During Cooldown** so you can give "still cooling down" feedback, and **On Cooldown Finish** fires once the timeout elapses and the button is ready again. + +## Key Code Patterns + +Driving a Unity Image's radial fill from the button's remaining time: + +```csharp +public CooldownButton coolDown; +private Image target; + +void Update() +{ + target.fillAmount = Mathf.Lerp(0, 1, coolDown.CooldownTimeRemaining / coolDown.CooldownTimeout); + if (displayText) + { + displayText.text = string.Format("{0}%", coolDown.CooldownPercentComplete); + } +} +``` + +Driving the SoftMask cutoff from elapsed time: + +```csharp +void Update() +{ + sauim.CutOff = Mathf.Lerp(0, 1, cooldown.CooldownTimeElapsed / cooldown.CooldownTimeout); +} +``` diff --git a/Documentation~/Examples/CurlyUI.md b/Documentation~/Examples/CurlyUI.md new file mode 100644 index 00000000..937caea7 --- /dev/null +++ b/Documentation~/Examples/CurlyUI.md @@ -0,0 +1,19 @@ +# Example: CurlyUI + +## Overview + +This scene demonstrates CurlyUI, an effect that warps standard uGUI graphics (Image, Text, RawImage) along configurable bezier curves so your UI can bend and arc instead of sitting flat. Use it for stylised banners, curved menus, or any UI element that needs to follow a non-rectangular shape. + +## Controls Featured + +- [CurlyUI](/ugui/controls/curly-ui/) — the demo scene applies the CUI effect components to UI graphics, exposing the bezier handles that define how each element is curved. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/CurlyUI/` into your project's `Assets/` folder. +2. Open the example scene in that folder (`CurlyUIDemo.unity`). +3. Press **Play**. + +## What to Expect + +The scene shows UI graphics that have been bent along curves rather than drawn flat, driven by the CurlyUI effect's bezier control points. With **Is Curved** enabled the curve is applied to the attached element, and the **Resolution** setting controls how finely the underlying mesh is subdivided (higher resolution gives a smoother curve at the cost of more geometry). The curve shape is authored in the editor by dragging the bezier handles on each curved element, with helper buttons to fit the curve back to the RectTransform; the effect itself is visible both in the Scene/Game view at edit time and at runtime. diff --git a/Documentation~/Examples/FancyScrollView.md b/Documentation~/Examples/FancyScrollView.md new file mode 100644 index 00000000..f7ee0c45 --- /dev/null +++ b/Documentation~/Examples/FancyScrollView.md @@ -0,0 +1,45 @@ +# Example: Fancy Scroll View + +## Overview + +This sample is a full tour of the Fancy Scroll View control, shipping nine separate scenes that build from a simple animated list up to advanced layouts and effects. Use it when you need a high-performance, virtualised scroll view with custom cell animation, infinite/looping content, grid layouts, or runtime texture loading. + +## Controls Featured + +- [Fancy Scroll View](/ugui/controls/fancy-scroll-view/) — each scene wires a `FancyScrollView`-derived `ScrollView` to a scroll position controller and feeds it cell data programmatically. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/FancyScrollView/` into your project's `Assets/` folder. +2. Open the example scene(s) in that folder. +3. Press **Play**. + +## What to Expect + +The folder contains nine scenes that you can switch between using the in-scene scenes dropdown: + +- **01_Basic** — a simple animated list populated with twenty cells at start-up. +- **02_FocusOn** — selectable cells that animate to focus when chosen. +- **03_InfiniteScroll** — endlessly looping content. +- **04_Metaball** and **05_Voronoi** — list scrolling combined with custom background visual effects. +- **06_LoopTabBar** — a looping tab bar with screen transitions. +- **07_ScrollRect** — Fancy Scroll View driven by a standard `ScrollRect` with configurable alignment. +- **08_GridView** — a multi-column grid layout. +- **09_LoadTexture** — cells that load their textures asynchronously at runtime. + +At runtime each scene populates its scroll view with generated `ItemData`, and cells animate as they move through the viewport. + +## Key Code Patterns + +The basic example generates a set of `ItemData` and hands it to the scroll view: + +```csharp +void Start() +{ + var items = Enumerable.Range(0, 20) + .Select(i => new ItemData($"Cell {i}")) + .ToArray(); + + scrollView.UpdateData(items); +} +``` diff --git a/Documentation~/Examples/FlowLayoutGroup.md b/Documentation~/Examples/FlowLayoutGroup.md new file mode 100644 index 00000000..93c91f7d --- /dev/null +++ b/Documentation~/Examples/FlowLayoutGroup.md @@ -0,0 +1,19 @@ +# Example: Flow Layout Group + +## Overview + +This scene demonstrates the Flow Layout Group, a layout component that arranges its child elements in rows (or columns) and automatically wraps them onto the next line when they run out of space. Use it when you need a flexible, wrapping layout for a variable number of items, similar to a CSS flexbox. + +## Controls Featured + +- [Flow Layout Group](/ugui/controls/flow-layout-group/) — the scene's container uses the component to auto-arrange and wrap its child UI elements. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/FlowLayoutGroup/` into your project's `Assets/` folder. +2. Open the `FlowLayoutGroup` example scene in that folder. +3. Press **Play**. + +## What to Expect + +The scene shows a parent container with the Flow Layout Group attached and a collection of child elements inside it. The children are laid out left to right and wrap onto a new row once the available width is exhausted, so the arrangement reflows to fit the container rather than overflowing or clipping. diff --git a/Documentation~/Examples/GridRawImage.md b/Documentation~/Examples/GridRawImage.md new file mode 100644 index 00000000..4f6ce4e9 --- /dev/null +++ b/Documentation~/Examples/GridRawImage.md @@ -0,0 +1,19 @@ +# Example: Grid Raw Image + +## Overview + +This scene demonstrates the Grid Raw Image control, a custom uGUI graphic that draws a grid of texture cells from a single texture, GameObject, and draw call. Use it for tile-based UI such as Tetris-style inventories or grid backgrounds where you want efficient rendering and per-cell geometry raycasting. + +## Controls Featured + +- [Grid Raw Image](/ugui/controls/grid-raw-image/) — the scene renders a configurable grid of textured cells using one Grid Raw Image component. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/GridRawImage/` into your project's `Assets/` folder. +2. Open the `Demo GridImage` example scene in that folder. +3. Press **Play**. + +## What to Expect + +The scene displays a Grid Raw Image laid out as a grid of cells drawn from a single texture. Properties such as the cell size, resize factor, extrude amount, and shape (which cells are active) control how the grid is built, letting you preview non-rectangular grids and skipped cells while still rendering in a single draw call. diff --git a/Documentation~/Examples/InputFieldEnterSubmit.md b/Documentation~/Examples/InputFieldEnterSubmit.md new file mode 100644 index 00000000..4c2f725e --- /dev/null +++ b/Documentation~/Examples/InputFieldEnterSubmit.md @@ -0,0 +1,19 @@ +# Example: Input Field Enter Submit + +## Overview + +This scene demonstrates the Input Field Enter Submit utility, which fires a submit event from a standard Unity InputField when the Enter key (or numeric keypad Enter) is pressed. Use it for search boxes, chat input, command prompts, or any form-like field where Enter should commit the text. + +## Controls Featured + +- [Input Field Enter Submit](/ugui/controls/input-field-enter-submit/) — the scene attaches the component to an InputField so pressing Enter raises its `EnterSubmit` event with the current text. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/InputFieldEnterSubmit/` into your project's `Assets/` folder. +2. Open the `InputFieldEnterSubmitDemo` example scene in that folder. +3. Press **Play**. + +## What to Expect + +The scene presents an InputField with the Input Field Enter Submit component attached. As you type and press Enter, the component invokes its `EnterSubmit` event, passing the current text. Depending on the **Defocus Input** setting, the field either keeps focus for further input or releases focus after submission. diff --git a/Documentation~/Examples/MenuExample.md b/Documentation~/Examples/MenuExample.md new file mode 100644 index 00000000..05e5e74a --- /dev/null +++ b/Documentation~/Examples/MenuExample.md @@ -0,0 +1,43 @@ +# Example: Menu System + +## Overview + +This scene is a full working implementation of the Menu System, a generic, reusable menu framework (refactored from the Unite 2017 demo). It shows a Menu Manager driving navigation between several menu screens. Use it as a template for building stacked, hierarchical menus such as main menu, options, in-game, and pause screens. + +## Controls Featured + +- [Menu System](/ugui/controls/menu-system/) — the scene's Menu Manager loads and transitions between menu prefabs, each backed by a `Menu` or `SimpleMenu` script. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/MenuExample/` into your project's `Assets/` folder. +2. Open the `MainScene` example scene in that folder. +3. Press **Play**. + +## What to Expect + +The Menu Manager opens the start screen (the main menu) at launch. From there you can navigate into the options and game menus, open an "awesome" menu, and trigger a pause menu, with the manager handling the flow and stacking between screens. Back actions move up the menu hierarchy, and quitting from the main menu calls `Application.Quit`. Each menu is a separate prefab with a matching script derived from the shared menu base classes. + +## Key Code Patterns + +Menu scripts derive from the generic `SimpleMenu` (or `Menu`) base and show or hide other menus via their static `Show` methods: + +```csharp +public class MainMenu : SimpleMenu +{ + public void OnPlayPressed() + { + GameMenu.Show(); + } + + public void OnOptionsPressed() + { + OptionsMenu.Show(); + } + + public override void OnBackPressed() + { + Application.Quit(); + } +} +``` diff --git a/Documentation~/Examples/RadialSlider.md b/Documentation~/Examples/RadialSlider.md new file mode 100644 index 00000000..6cce64d1 --- /dev/null +++ b/Documentation~/Examples/RadialSlider.md @@ -0,0 +1,45 @@ +# Example: Radial Slider + +## Overview + +This scene demonstrates the Radial Slider, a circular arc slider that fills in a radial pattern from a start angle. It shows reading the slider value at runtime, driving the slider value/angle programmatically from an input field, and reporting pointer interaction. Use it when you need a dial- or gauge-style input instead of a straight linear slider. + +## Controls Featured + +- [Radial Slider](/ugui/controls/radial-slider/) — the central dial that the user drags or clicks to set a value, with optional Lerp-to-target behaviour. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/RadialSlider/` into your project's `Assets/` folder. +2. Open the `radial_slider` example scene in that folder. +3. Press **Play**. + +## What to Expect + +A radial slider is shown on the canvas. Dragging or clicking around the arc changes the fill and raises the slider's value-changed events (an integer value and a text value). Pointer enter, down, and up events are written to an on-screen text field so you can see the raw interaction state. An input field lets you type a number and push it back into the slider as either a value or an angle, demonstrating two-way control of the slider from script. + +## Key Code Patterns + +Setting the slider value (or angle) from external input: + +```csharp +public class UpdateRadialValue : MonoBehaviour +{ + public InputField input; + public RadialSlider slider; + + public void UpdateSliderValue() + { + float value; + float.TryParse(input.text, out value); + slider.Value = value; + } + + public void UpdateSliderAndle() + { + int value; + int.TryParse(input.text, out value); + slider.Angle = value; + } +} +``` diff --git a/Documentation~/Examples/ReorderableList.md b/Documentation~/Examples/ReorderableList.md new file mode 100644 index 00000000..19e8eff5 --- /dev/null +++ b/Documentation~/Examples/ReorderableList.md @@ -0,0 +1,19 @@ +# Example: Reorderable List + +## Overview + +This scene demonstrates the Reorderable List, a set of list and grid containers whose child items can be dragged and dropped to reorder them or move them between containers. It shows the different layout flavours (vertical, horizontal and grid) and the per-container options for grabbing, transferring, cloning and dropping items. Use it when you need drag-and-drop inventories, hotbars, or rankable lists. + +## Controls Featured + +- [Reorderable List](/ugui/controls/reorderable-list/) — multiple list/grid containers that let the user drag items within and between them, with visual reordering feedback. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/ReorderableList/` into your project's `Assets/` folder. +2. Open the `ReorderableList` example scene in that folder. +3. Press **Play**. + +## What to Expect + +Several reorderable containers are laid out on the canvas. You can grab a child item and drag it to a new position within its list, and the surrounding items shift to make room. Where containers are configured as transferable, items can be dragged from one container and dropped into another; where cloning is enabled, dragging leaves the original in place and drops a copy. Containers set as draggable-only or droppable-only restrict the direction items can move, and the element grabbed/dropped/added/removed events fire as the items are interacted with. diff --git a/Documentation~/Examples/ScrollRectConflictManager.md b/Documentation~/Examples/ScrollRectConflictManager.md new file mode 100644 index 00000000..f88a5775 --- /dev/null +++ b/Documentation~/Examples/ScrollRectConflictManager.md @@ -0,0 +1,19 @@ +# Example: Scroll Rect Conflict Manager + +## Overview + +This scene demonstrates the Scroll Conflict Manager, which resolves the dragging conflict that occurs when one ScrollRect is nested inside another. Natively, a child ScrollRect only scrolls along its own axis and swallows the drag; this component lets the gesture flow to the correct ScrollRect based on the initial drag direction. Use it whenever you have a horizontal pager containing vertically scrolling pages (or vice versa). + +## Controls Featured + +- [Scroll Conflict Manager](/ugui/controls/scroll-conflict-manager/) — added to the child ScrollRect and pointed at the parent ScrollRect to arbitrate which one handles each drag. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/ScrollRectConflictManager/` into your project's `Assets/` folder. +2. Open the `ScrollrectConflictManagerDemo` example scene in that folder. +3. Press **Play**. + +## What to Expect + +The scene shows a horizontally paged ScrollRect whose pages each contain their own vertically scrolling content. Dragging mostly sideways scrolls between the pages, while dragging mostly up and down scrolls the content inside the current page. The direction is locked to the initial drag, so a single gesture no longer gets stuck on the wrong ScrollRect the way nested ScrollRects behave by default. diff --git a/Documentation~/Examples/ScrollSnaps.md b/Documentation~/Examples/ScrollSnaps.md new file mode 100644 index 00000000..393a727f --- /dev/null +++ b/Documentation~/Examples/ScrollSnaps.md @@ -0,0 +1,63 @@ +# Example: Scroll Snaps (Horizontal / Vertical / Infinite) + +## Overview + +This folder collects several scroll-snap demonstrations across multiple scenes, covering paged horizontal and vertical snapping, content-item snapping, infinite/looping snaps, pagination, and runtime page management. Use it when you need swipeable paged UI, carousels, or snapping lists with button- and pagination-driven navigation. + +## Controls Featured + +- [Horizontal Scroll Snap](/ugui/controls/horizontal-scroll-snap/) — paged horizontal snapping driven by swipes, buttons, and page jumps, including dynamic add/remove of pages. +- [Vertical Scroll Snap](/ugui/controls/vertical-scroll-snap/) — the vertical equivalent, with pages added, removed, and jumped to at runtime. +- [Content Scroll Snap Horizontal](/ugui/controls/content-scroll-snap-horizontal/) — snaps content items to the centre of the scroll rect rather than paging whole screens. +- [Infinite Scroll Snap](/ugui/controls/infinite-scroll-snap/) — endlessly looping scroll-snap content (deprecated for Unity 6, shown for legacy reference). + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/HSS-VSS-ScrollSnap/` into your project's `Assets/` folder. +2. Open one of the example scenes in that folder, for example `ContentSnapScrollExample`, `InfiniteScrollSnapExamples`, `FullScreenScrollSnap`, `PaginationManagerExample`, `ScrollSnapDynamic`, `InfiniteMagneticExample`, or `ScrollSnapManagedTests`. +3. Press **Play**. + +## What to Expect + +Each scene shows a different scroll-snap variant. Paged scenes let you swipe or use buttons to move between full-screen pages, and a pagination row of dots reflects and controls the current page. The content-snap scene snaps individual child items to the centre rather than moving whole screens. The dynamic/managed scenes demonstrate adding pages, removing the current or all pages, and jumping to a page entered into an input field at runtime; one scene also adds ten pages to a freshly instantiated scroll snap when you press the **K** key. Page-change, start, and end events are logged to the console as you navigate. + +## Key Code Patterns + +A pagination button routes a click straight to the scroll snap's `GoToScreen` to jump to a specific page: + +```csharp +public class PaginationScript : MonoBehaviour, IPointerClickHandler +{ + public HorizontalScrollSnap hss; + public int Page; + + public void OnPointerClick(PointerEventData eventData) + { + if (hss != null) + { + hss.GoToScreen(Page); + } + } +} +``` + +Pages can also be added, removed, or jumped to at runtime against either a horizontal or vertical snap: + +```csharp +public void AddButton() +{ + if (HSS) + { + var newHSSPage = GameObject.Instantiate(HorizontalPagePrefab); + HSS.AddChild(newHSSPage); + } + // ... +} + +public void JumpToPage() +{ + int jumpPage = int.Parse(JumpPage.text); + if (HSS) { HSS.GoToScreen(jumpPage); } + if (VSS) { VSS.GoToScreen(jumpPage); } +} +``` diff --git a/Documentation~/Examples/SelectionBox.md b/Documentation~/Examples/SelectionBox.md new file mode 100644 index 00000000..ca4e7e09 --- /dev/null +++ b/Documentation~/Examples/SelectionBox.md @@ -0,0 +1,19 @@ +# Example: Selection Box + +## Overview + +This scene demonstrates the Selection Box, an RTS-style rubber-band selection control that lets the user drag out a rectangle to select multiple objects at once. It shows selecting both screen-space UI content and world-space objects within a restricted selectable area. Use it when you need marquee/multi-select behaviour, such as selecting units in a strategy game. + +## Controls Featured + +- [Selection Box](/ugui/controls/selection-box/) — drag to draw a selection rectangle; objects inside the selection mask area are selected. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/SelectionBox/` into your project's `Assets/` folder. +2. Open the `Selection Box Test` example scene in that folder. +3. Press **Play**. + +## What to Expect + +Dragging the pointer across the canvas draws a selection box using the configured colour and background art. The scene includes both a screen-space selection canvas and world-space content (such as a cube and cylinder), demonstrating that 2D and 3D items can be selected. Selection is constrained to the assigned Selection Mask rect transform, so only objects within that area respond to the marquee. diff --git a/Documentation~/Examples/UICircleProgress.md b/Documentation~/Examples/UICircleProgress.md new file mode 100644 index 00000000..456d32b0 --- /dev/null +++ b/Documentation~/Examples/UICircleProgress.md @@ -0,0 +1,47 @@ +# Example: UI Circle Progress + +## Overview + +This scene demonstrates using the UI Circle primitive as an animated radial progress indicator. It shows driving the circle's progress value, recolouring both the base and progress portions of the arc, and changing the arc density (number of segments) at runtime. Use it for circular loading indicators, health/cooldown rings, or any progress display. + +## Controls Featured + +- [UI Circle](/ugui/controls/ui-circle/) — rendered as a hollow ring whose progress fill, colours, and segment count are updated live from UI sliders. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/UICircleProgress/` into your project's `Assets/` folder. +2. Open the `UICircleProgress` example scene in that folder. +3. Press **Play**. + +## What to Expect + +A circular progress ring is shown alongside controls that update it in real time. One slider drives the base (track) colour and another drives the progress colour, mapping a 0–1 value across the colour wheel. A density slider changes the number of arc segments and writes the current step count to an on-screen text field, so you can watch the ring go from coarse and faceted to smooth as the segment count rises. + +## Key Code Patterns + +Recolouring the base and progress portions of the circle: + +```csharp +public void UpdateBaseColor(float value) +{ + baseColor = SetFixedColor(value, baseColor.a); + TargetUICircle.GetComponent().color = baseColor; +} + +public void UpdateProgressColor(float value) +{ + progressColor = SetFixedColor(value, progressColor.a); + TargetUICircle.GetComponent().SetProgressColor(progressColor); +} +``` + +Changing the arc density (segment count) at runtime: + +```csharp +public void UpdateDensity(float value) +{ + _uiCircleComponent.SetArcSteps((int)value); + _densityOutput.text = value.ToString(); +} +``` diff --git a/Documentation~/Examples/UICircleSegmented.md b/Documentation~/Examples/UICircleSegmented.md new file mode 100644 index 00000000..56bdd61b --- /dev/null +++ b/Documentation~/Examples/UICircleSegmented.md @@ -0,0 +1,19 @@ +# Example: UI Circle Segmented + +## Overview + +This scene showcases the UI Circle Segmented graphic, a circle split into individually controllable slices. It demonstrates the various fill patterns, segment counts and gap/offset options you can use to build ring charts, pie charts and radial selection wheels. Use it when you need a segmented circular indicator rather than a single smooth arc. + +## Controls Featured + +- [UI Circle Segmented](/ugui/controls/ui-circle-segmented/) — the sample circle graphic that renders the configurable segments, fill amount and fill patterns. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/UICircleSegmented/` into your project's `Assets/` folder. +2. Open the `UICircleSegmented Samples` scene in that folder. +3. Press **Play**. + +## What to Expect + +The scene presents the segmented circle drawn from the included segment sprites. By adjusting the control's inspector values you can see how **Segments Count** changes the number of slices, how **Fill Amount** and **Invert Fill** drive progress, and how the **Fill Pattern** (Default, Handle, Handle Inverted) and **Fill Deep** (Floating, Per Vertex, Per Segment) options change the way the fill is applied. Border thickness, gradients and the global/segment degree offsets let you fine-tune the look. The graphic is GC-free and redraws as the properties change. diff --git a/Documentation~/Examples/UIKnob.md b/Documentation~/Examples/UIKnob.md new file mode 100644 index 00000000..cf186fe6 --- /dev/null +++ b/Documentation~/Examples/UIKnob.md @@ -0,0 +1,40 @@ +# Example: UI Knob + +## Overview + +This scene demonstrates the UI Knob, a rotary dial control that behaves like a knob on a stereo or amplifier. It shows reading the knob's live value, displaying it on screen, and driving the knob to a specific value from script. Use it when you need a rotational input rather than a linear slider. + +## Controls Featured + +- [UI Knob](/ugui/controls/ui-knob/) — the rotary knob the user drags to set a value, with its value read back and set programmatically. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/UIKnobExample/` into your project's `Assets/` folder. +2. Open the `UIKnobExample` scene in that folder. +3. Press **Play**. + +## What to Expect + +Drag the knob with the mouse (or touch) to rotate it. A text label continuously updates to show the knob's current `KnobValue`. An input field plus button let you type a target value and apply it; pressing the button rotates the knob to that value via `SetKnobValue`. The knob's range, direction, loops and snapping are configured on the `UI_Knob` component in the inspector. + +## Key Code Patterns + +```csharp +public class KnobManagement : MonoBehaviour +{ + public Text KnobValue; + public InputField SetKnobValue; + public UI_Knob Knob; + + public void UpdateKnobValue() + { + Knob.SetKnobValue(float.Parse(SetKnobValue.text)); + } + + void Update() + { + KnobValue.text = Knob.KnobValue.ToString(); + } +} +``` diff --git a/Documentation~/Examples/UILineRenderer.md b/Documentation~/Examples/UILineRenderer.md new file mode 100644 index 00000000..a1fafb86 --- /dev/null +++ b/Documentation~/Examples/UILineRenderer.md @@ -0,0 +1,40 @@ +# Example: UI Line Renderer + +## Overview + +This folder collects several scenes that demonstrate drawing lines on a Canvas with the UI Line Renderer family of controls. They cover free-hand line drawing from pointer input, adding/clearing points at runtime, and animating an orbit path, using both the array-based `UILineRenderer` and the list-based `UILineRendererList`. Use these when you need to draw polylines, charts or dynamic paths in UI space. + +## Controls Featured + +- [UI Line Renderer](/ugui/controls/ui-line-renderer/) — the `LineDrawing` and `UILineRendererDemo` scenes draw and animate lines by setting its `Points` array. +- [UI Line Renderer (List)](/ugui/controls/ui-line-renderer-list/) — the `UILineRendererListDemo` scene builds the same effects using its `AddPoint`/`ClearPoints` list API. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/UILineRenderer/` into your project's `Assets/` folder. +2. Open one of the example scenes in that folder: `LineDrawing`, `UILineRendererDemo`, or `UILineRendererListDemo`. +3. Press **Play**. + +## What to Expect + +In `LineDrawing` you draw lines directly with the mouse. The `DrawLine` script supports two modes: **Drag and Draw**, where dragging rubber-bands a line between the start and release points, and **Click and Draw**, where each click extends a continuous line that follows the cursor until you right-click or press **Escape**. The demo scenes also show an animated orbit where a `UILineRenderer`/`UILineRendererList` traces a circle (driven by the `LineRendererOrbit`/`LineRendererOrbitList` scripts) and a small UI object travels around that path. Input fields with a button let you add new points by X/Y value or clear the line entirely. Remember the line renderer's RectTransform should sit at (0,0,0) for correct results. + +## Key Code Patterns + +```csharp +// UILineRenderer: replace the whole Points array +public void AddNewPoint() +{ + var point = new Vector2() { x = float.Parse(XValue.text), y = float.Parse(YValue.text) }; + var pointlist = new List(LineRenderer.Points); + pointlist.Add(point); + LineRenderer.Points = pointlist.ToArray(); +} + +// UILineRendererList: append/clear via the list API +public void AddNewPoint() +{ + var point = new Vector2() { x = float.Parse(XValue.text), y = float.Parse(YValue.text) }; + LineRenderer.AddPoint(point); +} +``` diff --git a/Documentation~/Examples/UIParticleSystem.md b/Documentation~/Examples/UIParticleSystem.md new file mode 100644 index 00000000..8feff5c1 --- /dev/null +++ b/Documentation~/Examples/UIParticleSystem.md @@ -0,0 +1,39 @@ +# Example: UI Particle System + +## Overview + +This scene demonstrates rendering a native Unity particle system inside the uGUI canvas with the UI Particle System control. A small runtime control window lets you play, pause and stop the emitter and watch its live state. Use it when you want particle effects that live in your UI layer rather than in 3D world space. + +## Controls Featured + +- [UI Particle System](/ugui/controls/ui-particle-system/) — renders the attached Unity particle system in UI space so the effect draws correctly within the canvas. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/UIParticleSystem/` into your project's `Assets/` folder. +2. Open the `UIParticleSystem` scene in that folder. +3. Press **Play**. + +## What to Expect + +The particle effect renders within the UI canvas. A draggable on-screen control window (drawn with IMGUI by the `ParticleSystemControllerWindow` script) shows read-only toggles for the system's Playing, Emitting and Paused states, plus buttons to **Play**, **Pause**, **Stop Emitting**, and **Stop & Clear**. An "Include Children" toggle controls whether those calls cascade to child systems, and labels report the current time and live particle count. + +## Key Code Patterns + +```csharp +void DrawWindowContents(int windowId) +{ + if (system) + { + if (GUILayout.Button("Play")) + system.Play(includeChildren); + if (GUILayout.Button("Pause")) + system.Pause(includeChildren); + if (GUILayout.Button("Stop Emitting")) + system.Stop(includeChildren, ParticleSystemStopBehavior.StopEmitting); + if (GUILayout.Button("Stop & Clear")) + system.Stop(includeChildren, ParticleSystemStopBehavior.StopEmittingAndClear); + } + GUI.DragWindow(); +} +``` diff --git a/Documentation~/Examples/UIVerticalScroller.md b/Documentation~/Examples/UIVerticalScroller.md new file mode 100644 index 00000000..d9d8f56b --- /dev/null +++ b/Documentation~/Examples/UIVerticalScroller.md @@ -0,0 +1,34 @@ +# Example: UI Vertical Scroller + +## Overview + +This scene builds a date picker from three UI Vertical Scrollers, one each for days, months and years. Each scroller scales its elements by distance from a centre point so the focused entry is zoomed and selectable. Use it when you want a wheel-style picker where the centred item is the current selection. + +## Controls Featured + +- [UI Vertical Scroller](/ugui/controls/ui-vertical-scroller/) — three instances act as the day, month and year wheels; the centred element is read back as the selected value. + +## Scene Setup + +1. Add the **UI Extensions Samples** sample to your project (open the package in the Unity Package Manager and import **UI Extensions Samples**), or copy `Examples~/UIVerticalScrollerDemo/` into your project's `Assets/` folder. +2. Open the `VerticalCalendar` scene in that folder. +3. Press **Play**. + +## What to Expect + +Three vertical wheels appear: days (1-31), months (Jan-Dec) and years (1900 to the current year), each populated from a button prefab at startup. Scrolling a wheel zooms whichever item sits at its centre, and scroll up/down buttons step through entries. The currently focused values are combined into a formatted date string (with the correct ordinal suffix, e.g. "Jan 1st 1900"). Input fields plus a "set date" action snap all three wheels to a chosen day/month/year via `SnapToElement`. + +## Key Code Patterns + +```csharp +// Read the centred element of each scroller every frame and build the date +string dayString = daysVerticalScroller.Result; +string monthString = monthsVerticalScroller.Result; +string yearsString = yearsVerticalScroller.Result; +dateText.text = monthString + " " + dayString + " " + yearsString; + +// Jump all three wheels to a specific entry +daysVerticalScroller.SnapToElement(daysSet); +monthsVerticalScroller.SnapToElement(monthsSet); +yearsVerticalScroller.SnapToElement(yearsSet); +``` diff --git a/Documentation~/com.unity.uiextensions.md b/Documentation~/com.unity.uiextensions.md index 3cdec96f..be869fe6 100644 --- a/Documentation~/com.unity.uiextensions.md +++ b/Documentation~/com.unity.uiextensions.md @@ -20,7 +20,7 @@ To install this package, follow the instructions in the Package Manager document For more details on [Getting Started](https://unity-ui-extensions.github.io/GettingStarted) please checkout the [online documentation here](https://unity-ui-extensions.github.io/). -# Using Unity UI Extensions +## Using Unity UI Extensions The UI Extensions project provides many automated functions to add the various controls contained within the project commonly accessed via "***GameObject -> UI -> Extensions -> 'Control'***" from the editor menu. This will add the UI object and all the necessary components to make that control work in the scene in a default state. @@ -28,25 +28,28 @@ Some of the features are also available through the GameObject "Add Component" m For a full list of the controls and how they are used, please see the [online documentation](https://unity-ui-extensions.github.io/Controls.html) for the project. -# Technical details +## Technical details ## Requirements -This version of the Unity UI Extensions is compatible with the following versions of the Unity Editor: +This version of the Unity UI Extensions is compatible with Unity 6 and above. -- 2019 and above - the recommended path for 2019+ is to use the Unity Package Manager to get access to the package. Full details for installing via UPM can be [found here](https://unity-ui-extensions.github.io/UPMInstallation.html). +> Although, at this time there are some known issues with 6000.5 and above, which will be addressed in the next release. -> Alternatively, the Asset packages have been tested to work with 2019 as well if you prefer to install that way. - -- 2018 and below - for 2018 and use this package, you will have to import the asset package(s), either from the Asset Store or from the alternate download locations [listed here](https://unity-ui-extensions.github.io/Downloads). +The recommended path is to use the Unity Package Manager to get access to the package. Full details for installing via UPM can be [found here](https://unity-ui-extensions.github.io/UPMInstallation.html). ## [Release Notes](https://unity-ui-extensions.github.io/ReleaseNotes/RELEASENOTES) -## Release 2.3.2 - Rejuvenation - 2023/11/26 +## Release 3.0.0 - Unity 6, reimagined - 2026/06 + +The V3 relaunch brings **full Unity 6 support**, a refreshed brand, and the start of a two-package ecosystem — the proven uGUI library you know, now joined by a modern UI Toolkit companion. + +> **Two packages. One ecosystem.** These notes cover the **uGUI** package (`com.unity.uiextensions`). Meet its new companion: [UI Toolkit Extensions](https://github.com/Unity-UI-Extensions/com.unity.uitoolkitextensions). -2023 is certainly an interesting year to keep you on your toes, and finding time to keep managing all the requests and updates that come in are taking their toll, especially for a FREE project, but nonetheless, I still do it. +### Highlights -Mainly bugfixes for the end of year update, promoting some resolutions that have been verified and tested since the last release. +- **Full Unity 6 support** — the whole library verified and updated for Unity 6, with legacy dependencies cleared out and the examples refreshed. +- **Two-package ecosystem** — the new UI Toolkit Extensions package launches alongside under the shared 3.0 banner. To get up to speed with the Unity UI Extensions, check out the [Getting Started](https://unity-ui-extensions.github.io/GettingStarted.html) Page. @@ -57,41 +60,42 @@ To get up to speed with the Unity UI Extensions, check out the [Getting Started] > > Much easier that posting a question / issue on YouTube, Twitter or Facebook :D -## Breaking changes - -For customers upgrading from earlier versions of Unity to Unity 2020, please be aware of the Breaking change related to Text Based components. You will need to manually replace any UI using the older ```Text``` component and replace them with ```TextMeshPro``` versions. This is unavoidable due to Unity deprecating the Text component. - -> New users to 2022 are unaffected as all the Editor commands have been updated to use the newer TextMeshPro versions. - -For more details, see the [deprecation notice](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/discussions/428) on GitHub. - -## Added - -- Add CalculatePointOnCurve for uilinerenderer (@victornor) - -## Changed - -- fix: Fixed an null reference exception with the ResetSelectableHighlight (@FejZa) -- fix: Resolved an issue where the last line in a flow layout group would overflow the rect bounds. -- fix: GetPosition when Segments is null (@victornor) -- fix: Fix Bug! NicerOutline color.a Loss when m_UseGraphicAlpha is true (wanliyun) -- fix: Update to force Enumerated start for Accordion elements, Resolves: #455 -- Added argument to the UpdateLayout method for the HSS/VSS to move to a new starting page. -- Updated implementations to handle 2023 support, with 2023 moving in to public release. -- Added extra event on the AutoCompleteComboBox, to fire when an item in the list is selected, with its display name. -- FlowLayoutGroup components updated to latest (likely the last as the author has stopped development) - ## Deprecated - All deprecated Text based components now have "obsolete" tags, to avoid breaking code. Note, these do not function in 2022 and above, as Unity have "changed" things. For any affected component, I recommend updating to use TextMeshPro native features. - [UI Extensions Issue log](https://github.com/Unity-UI-Extensions/com.unity.uiextensions/issues) -## Upgrade Notes +### Added + +- New control: **GridRawImage** +- New control: **UI Knob 2** (`UI_Knob2`) +- New control: **UI Segmented Circle** / Segmented Control +- New control: **UI Graphic Selector** +- UILineConnector: the pivot can now be used as the reference point when drawing lines (#490) +- UILineConnector: new "close line" option to finish a line off and fill any gaps at the end +- BoxSlider: added `SetXWithoutNotify` and `SetYWithoutNotify` + +### Changed / Fixed + +- Reorderable List: fixed a null-reference exception, and resolved element-stacking when moving elements slightly +- Scroll Snap: resolved a race condition that could raise a NaN error when lerping; made rescaling and full-screen scroll snap more resilient +- HSS/VSS: guarded against a divide-by-zero when the scroll snap has a single page; `GetCurrentPage` made more resilient +- Infinite Scroll: resolved out-of-bounds issues +- Flow Layout Group: addressed layout issues and fixed the last line overflowing the rect bounds +- UI Particle System: new "CullingMode" option to resolve unscaled delta time (#486 / #487) +- Gradient2: optimised `ModifyMesh`; fixed radial triangle add order (#384) +- ScrollRect: force `ScrollRect.content` setup (#485) +- UILineConnector: improved point-array calculation (#495); refresh on global scale change +- Layout groups now rebuild on disable/enable +- General TMPro/Text compatibility housekeeping (#477) +- Compile-flag support for Unity 6 (#493) + +### Upgrade Notes We recommend using the UPM delivery method. If you are using the Unity asset, there should be no issues updating but if you have a problem, just deleted the old Unity-UI-Extensions folder and import the asset new. -# Document revision history +## Document revision history |Date|Details| |-|-| @@ -100,3 +104,5 @@ We recommend using the UPM delivery method. If you are using the Unity asset, th |August 8th, 2020|2019.4 (v2.2) released, New UPM Delivery.| |October 10th, 2020|2019.5 (v2.2) released, New UPM fast delivery| |February 7th, 2022|v2.3 released, New Home, UPM fast delivery via OpenUPM| +|June 20th, 2026|v3.0.0 released, Now part 1 of two packages, uGUI and UIToolkit, all refreshed for Unity 6. + diff --git a/README.md b/README.md index 690e92b3..aba4cf7a 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@

- 100+ controls · 21 example scenes · battle-tested since 2015 · 100% free · BSD-3-Clause + 100+ controls · 22 example scenes · battle-tested since 2015 · 100% free · BSD-3-Clause

diff --git a/Runtime/Scripts/Controls/GridRawImage/BitArray/BitArray256.cs b/Runtime/Scripts/Controls/GridRawImage/BitArray/BitArray256.cs index 734bdfbb..6bf2d8da 100644 --- a/Runtime/Scripts/Controls/GridRawImage/BitArray/BitArray256.cs +++ b/Runtime/Scripts/Controls/GridRawImage/BitArray/BitArray256.cs @@ -27,13 +27,21 @@ public struct BitArray256 : IBitArray [SerializeField] ulong data4; - ///

Number of elements in the bit array. + /// + /// Number of elements in the bit array. + /// public readonly uint Capacity => 256u; - /// True if all bits are 0. + /// + /// True if all bits are 0. + /// public readonly bool AllFalse => data1 == 0uL && data2 == 0uL && data3 == 0uL && data4 == 0uL; - /// True if all bits are 1. + /// + /// True if all bits are 1. + /// public readonly bool AllTrue => data1 == ulong.MaxValue && data2 == ulong.MaxValue && data3 == ulong.MaxValue && data4 == ulong.MaxValue; - /// Returns the bit array in a human readable form. + /// + /// Returns the bit array in a human readable form. + /// public readonly string HumanizedData => System.Text.RegularExpressions.Regex.Replace(String.Format("{0, " + 64u + "}", Convert.ToString((long)data4, 2)).Replace(' ', '0'), ".{8}", "$0.") + System.Text.RegularExpressions.Regex.Replace(String.Format("{0, " + 64u + "}", Convert.ToString((long)data3, 2)).Replace(' ', '0'), ".{8}", "$0.") diff --git a/Runtime/Scripts/Controls/GridRawImage/BitArray/BitArray8.cs b/Runtime/Scripts/Controls/GridRawImage/BitArray/BitArray8.cs index 1034203d..18c9650c 100644 --- a/Runtime/Scripts/Controls/GridRawImage/BitArray/BitArray8.cs +++ b/Runtime/Scripts/Controls/GridRawImage/BitArray/BitArray8.cs @@ -21,13 +21,21 @@ public struct BitArray8 : IBitArray [SerializeField] byte data; - /// Number of elements in the bit array. + /// + /// Number of elements in the bit array. + /// public uint Capacity => 8u; - /// True if all bits are 0. + /// + /// True if all bits are 0. + /// public bool AllFalse => data == 0u; - /// True if all bits are 1. + /// + /// True if all bits are 1. + /// public bool AllTrue => data == byte.MaxValue; - /// Returns the bit array in a human readable form. + /// + /// Returns the bit array in a human readable form. + /// public string HumanizedData => String.Format("{0, " + Capacity + "}", Convert.ToString(data, 2)).Replace(' ', '0'); /// diff --git a/Runtime/Scripts/Controls/GridRawImage/BitArray/IBitArray.cs b/Runtime/Scripts/Controls/GridRawImage/BitArray/IBitArray.cs index 4ff27659..df41b5b6 100644 --- a/Runtime/Scripts/Controls/GridRawImage/BitArray/IBitArray.cs +++ b/Runtime/Scripts/Controls/GridRawImage/BitArray/IBitArray.cs @@ -5,11 +5,17 @@ namespace UnityEngine.UI.Extensions { public interface IBitArray { - /// Number of elements in the bit array. + /// + /// Number of elements in the bit array. + /// uint Capacity { get; } - /// True if all bits are 0. + /// + /// True if all bits are 0. + /// bool AllFalse { get; } - /// True if all bits are 1. + /// + /// True if all bits are 1. + /// bool AllTrue { get; } /// /// Returns the state of the bit at a specific index. @@ -17,7 +23,9 @@ public interface IBitArray /// Index of the bit. /// State of the bit at the provided index. bool this[uint index] { get; set; } - /// Returns the bit array in a human readable form. + /// + /// Returns the bit array in a human readable form. + /// string HumanizedData { get; } /// diff --git a/Runtime/Scripts/Effects/UIParticleSystem.cs b/Runtime/Scripts/Effects/UIParticleSystem.cs index 68e5821a..81e5690c 100644 --- a/Runtime/Scripts/Effects/UIParticleSystem.cs +++ b/Runtime/Scripts/Effects/UIParticleSystem.cs @@ -14,13 +14,21 @@ namespace UnityEngine.UI.Extensions /// public enum UIParticleSystemCullingMode { - /// Default. Simulates continuously and clamps a catastrophic catch-up (e.g. returning from the background) to maxSimulationDeltaTime so it cannot freeze the app (issue #486). Mirrors Unity's default culling mode. + /// + /// Default. Simulates continuously and clamps a catastrophic catch-up (e.g. returning from the background) to maxSimulationDeltaTime so it cannot freeze the app (issue #486). Mirrors Unity's default culling mode. + /// Automatic, - /// Clamp the simulation step (see maxSimulationDeltaTime); behaves the same as Automatic for this manual simulation. + /// + /// Clamp the simulation step (see maxSimulationDeltaTime); behaves the same as Automatic for this manual simulation. + /// Pause, - /// Replay the full elapsed time on the next frame. Original behaviour - can freeze the app after a long pause (issue #486). + /// + /// Replay the full elapsed time on the next frame. Original behaviour - can freeze the app after a long pause (issue #486). + /// PauseAndCatchup, - /// Replay the full elapsed time; behaves the same as PauseAndCatchup for this manual simulation. + /// + /// Replay the full elapsed time; behaves the same as PauseAndCatchup for this manual simulation. + /// AlwaysSimulate }