{"id":16322368,"url":"https://github.com/maxxfrazer/realityui","last_synced_at":"2025-04-04T20:10:47.516Z","repository":{"id":39747431,"uuid":"265939509","full_name":"maxxfrazer/RealityUI","owner":"maxxfrazer","description":"A Swift Package for creating familiar UI Elements and animations in RealityKit. For both Augmented Reality or Virtual Reality scenes. Now with visionOS support.","archived":false,"fork":false,"pushed_at":"2024-01-02T14:51:28.000Z","size":15639,"stargazers_count":665,"open_issues_count":2,"forks_count":36,"subscribers_count":14,"default_branch":"main","last_synced_at":"2024-12-06T21:36:49.258Z","etag":null,"topics":["3d-graphics","ar","arkit","augmented-interactions","augmented-reality","ios","macos","mixed-reality","realitykit","realitypro","swift","swift-package-manager","swiftpm","user-experience","user-interaction","user-interface","ux","virtual-reality","visionos"],"latest_commit_sha":null,"homepage":"https://maxxfrazer.github.io/RealityUI/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxxfrazer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-21T19:56:59.000Z","updated_at":"2024-11-04T13:14:10.000Z","dependencies_parsed_at":"2024-12-14T11:10:06.067Z","dependency_job_id":"cd57af47-8985-4949-afa6-1d481e909190","html_url":"https://github.com/maxxfrazer/RealityUI","commit_stats":{"total_commits":66,"total_committers":2,"mean_commits":33.0,"dds":"0.31818181818181823","last_synced_commit":"8873130eeec6828542012000b8b7f7e338804302"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxxfrazer%2FRealityUI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxxfrazer%2FRealityUI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxxfrazer%2FRealityUI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxxfrazer%2FRealityUI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxxfrazer","download_url":"https://codeload.github.com/maxxfrazer/RealityUI/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247242678,"owners_count":20907134,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-graphics","ar","arkit","augmented-interactions","augmented-reality","ios","macos","mixed-reality","realitykit","realitypro","swift","swift-package-manager","swiftpm","user-experience","user-interaction","user-interface","ux","virtual-reality","visionos"],"created_at":"2024-10-10T22:50:40.519Z","updated_at":"2025-04-04T20:10:47.494Z","avatar_url":"https://github.com/maxxfrazer.png","language":"Swift","readme":"# RealityUI\n\nRealityUI is a collection of utilities and UI objects for RealityKit.\nThe UI objects included in RealityUI aim to offer familiar User Interface standards, but in a 3D setting for Augmented and Virtual Reality through RealityKit.\n\nRealityUI also has a collection of components for interfacing with any Entity through touch or drag interactions.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://swiftpackageindex.com/maxxfrazer/RealityUI\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/release/maxxfrazer/RealityUI?color=F05138\u0026label=Package%20Version\u0026logo=Swift\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://swiftpackageindex.com/maxxfrazer/RealityUI/main/documentation/realityui\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Swift-Doc-DE5C43.svg?style=flat\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/github/maxxfrazer/RealityUI\" \u003e\n    \u003cimg src=\"https://codecov.io/github/maxxfrazer/RealityUI/graph/badge.svg?token=3PCDBMSCLL\"/\u003e\n  \u003c/a\u003e\n  \u003cbr/\u003e\n  \u003cimg src=\"https://github.com/maxxfrazer/RealityUI/workflows/build/badge.svg?branch=main\"/\u003e\n  \u003cimg src=\"https://github.com/maxxfrazer/RealityUI/workflows/Deploy%20DocC/badge.svg?branch=main\"/\u003e\n  \u003ca href=\"./LICENSE.md\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/maxxfrazer/RealityUI\"/\u003e\n  \u003c/a\u003e\n  \u003cbr/\u003e\n  \u003ca href=\"https://swiftpackageindex.com/maxxfrazer/RealityUI\"\u003e\n    \u003cimg src=\"https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fmaxxfrazer%2FRealityUI%2Fbadge%3Ftype%3Dplatforms\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://swiftpackageindex.com/maxxfrazer/RealityUI\"\u003e\n    \u003cimg src=\"https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fmaxxfrazer%2FRealityUI%2Fbadge%3Ftype%3Dswift-versions\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n![RealityUI Elements in a RealityKit VR space](https://github.com/maxxfrazer/RealityUI/blob/main/media/realityui_banner.gif?raw=true)\n\n## Requirements\n\n- iOS 13, macOS 10.15 or visionOS 1.0\n- Swift 5.8\n- Xcode 13\n\n## Content\n\n- [RealityUI](#realityui)\n  - [Requirements](#requirements)\n  - [Content](#content)\n  - [Installation](#installation)\n    - [Swift Package Manager](#swift-package-manager)\n  - [Usage](#usage)\n      - [Registering RealityUI Components](#registering-realityui-components)\n      - [Activating Gestures](#activating-gestures)\n        - [visionOS](#visionos)\n        - [iOS/macOS](#iosmacos)\n  - [Control Entities](#control-entities)\n    - [RUISwitch](#ruiswitch)\n    - [RUIStepper](#ruistepper)\n    - [RUISlider](#ruislider)\n    - [RUIButton](#ruibutton)\n  - [Gestures](#gestures)\n    - [Drag](#drag)\n    - [Turn](#turn)\n    - [Tap](#tap)\n  - [Animations](#animations)\n    - [Spin](#spin)\n    - [Shake](#shake)\n  - [Text](#text)\n  - [More](#more)\n\n## Installation\n\n### Swift Package Manager\n\nAdd the URL of this repository to your Xcode 11+ Project under `Project \u003e Swift Packages`.\n\n`https://github.com/maxxfrazer/RealityUI.git`\n\n## Usage\n\nAdd `import RealityUI` to the top of your swift file to start.\n\n#### Registering RealityUI Components\n\nAll components used in RealityUI must be registered before they are used, simply call `RealityUI.registerComponents()` anywhere in your app before any classes starting with `RUI` are initialised to avoid issues with that. For more information on what is meant by registering components [see Apple's documentation here](https://developer.apple.com/documentation/realitykit/component/3243766-registercomponent).\n\n#### Activating Gestures\n\n##### visionOS\n\nWith visionOS, gestures can be enabled on a RealityView using `View/addRUIDragGesture()` or `View/addRUITapGesture()` modifiers, or by adding the gestures directly with `.gesture(RUIDragGesture())` or `.gesture(RUITapGesture())`. The RealityView might look something like this:\n\n```swift\nRealityView { content in\n    let swtch = RUISwitch()\n    swtch.scale = .init(repeating: 0.1)\n    content.add(swtch)\n}.addRUIDragGesture()\n```\n\n\u003e The above snippet adds an interactive switch/toggle to the scene.\n\nThis gesture works for any entity with RUIDragComponent, for example:\n\n```swift\nRealityView { content in\n    let movable = try! await ModelEntity(named: \"toy_biplane\")\n    movable.generateCollisionShapes(recursive: false)\n\n    movable.components.set(RUIDragComponent(type: .move(nil)))\n    movable.components.set(InputTargetComponent())\n\n    content.add(movable)\n}.addRUIDragGesture()\n```\n\n![moving a biplane around in vision pro simulator](media/biplane_drag.gif)\n\n##### iOS/macOS\n\nEnabling RealityUI gestures can be doen by calling `RealityUI.enableGestures(.all, on: ARView)`, with `ARView` being your instance of an [ARView](https://developer.apple.com/documentation/realitykit/arview) object.\n\nRUISlider, RUISwitch, RUIStepper and RUIButton all use ``RUIDragComponent``, which requires `.ruiDrag`. If you are adding elements that use the component `RUITapComponent` you can use the gesture `.tap`.\nI would just recommend using `.all` when enabling gestures, as these will inevitably move around as RealityUI develops.\n\n`RealityUI.enableGestures(.all, on: arView)`\n\n---\n## Control Entities\n\nBy default all RealityUI Entities are quite large. This is used to standardize the sizes so that you always know what to expect. For example, all UI thumbs are spheres with a diameter of 1 meter, which is 1 unit in RealityKit, ± any padding adjustments. All RealityUI Entities face `[0, 0, -1]` by default. To have them point at the user camera, or `.zero`, you can use the [`.look(at:,from:,relativeTo:)`](https://developer.apple.com/documentation/realitykit/entity/3244094-look) method like so: `.look(at: .zero, from: [0, 0, 1])`. Or if you want it to turn around straight away if you've positioned it at `[0, 0, -1]`, set the orientation to `simd_quatf(angle: .pi, axis: [0, 1, 0])`. Using the [.look()](https://developer.apple.com/documentation/realitykit/entity/3244094-look) method works here by setting the `at:` value to the direction the button should be used from.\n\n### RUISwitch\n\nRUISwitch is a 3D toggle switch with an on and off state.\nDefault bounding box is 2x1x1m\n\n![RUISwitches with and without light responsiveness](https://github.com/maxxfrazer/RealityUI/blob/main/media/switches_combined.gif?raw=true)\n\n[More details](https://github.com/maxxfrazer/RealityUI/wiki/Control-Entities#ruiswitch)\n\n### RUIStepper\n\nRUIStepper is used to increment or decrement a value.\nDefault bounding box is 2x1x0.25m\n\n![RUIStepper with light responsiveness](https://github.com/maxxfrazer/RealityUI/blob/main/media/stepper_light.gif?raw=true)\n\n[More details](https://github.com/maxxfrazer/RealityUI/wiki/Control-Entities#ruistepper)\n\n### RUISlider\n\nAn interactive track to represent an interpolated value.\nDefault bounding box is 10x1x1m including thumb.\n\n![RUISlider with light responsiveness](https://github.com/maxxfrazer/RealityUI/blob/main/media/slider_light.gif?raw=true)\n\n[More details](https://github.com/maxxfrazer/RealityUI/wiki/Control-Entities#ruislider)\n\n### RUIButton\n\nRUIButton is used to initiate a specified action. The action here will only trigger if the gesture begins on a button, and also ends on the same button. This is similar to the [touchUpInside UIControl Event](https://developer.apple.com/documentation/uikit/uicontrol/event/1618236-touchupinside).\nDefault button bounding box before depressing the button into the base is `[1, 1, 0.3]`\n\n![RUIButton with light responsiveness](https://github.com/maxxfrazer/RealityUI/blob/main/media/button_light.gif?raw=true)\n\n\n[More details](https://github.com/maxxfrazer/RealityUI/wiki/Control-Entities#ruibutton)\n\n---\n## Gestures\n\nAll of the RealityUI Control Entities use custom gestures that aren't standard in RealityKit, but some of them have been isolated so anyone can use them to manipulate their own RealityKit scene.\n\n### Drag\n\nDrag objects anywhere in space with 3 degrees of freedom with [RUIDragComponent](https://maxxfrazer.github.io/RealityUI/documentation/realityui/RUIDragComponent), using the [.move](https://maxxfrazer.github.io/RealityUI/documentation/realityui/RUIDragComponent/move(_:)) type.\n\n![Dragging Cubes](media/RUIDrag_cubes.gif)\n\nThis type has an optional constraint, to fix the movement within certain criteria:\n\n1. **Box Constraint**: Restricts movement within a specified `BoundingBox`, providing a defined area where the entity can move.\n\n2. **Points Constraint**: Limits movement to a set of predefined points, represented as an array of `SIMD3\u003cFloat\u003e`.\n\n3. **Clamp Constraint**: Uses a custom clamping function to control the movement. This function takes a `SIMD3\u003cFloat\u003e` as input and returns a modified `SIMD3\u003cFloat\u003e` to determine the new position.\n\n### Turn\n\nUnlock the ability to rotate a RealityKit entity with just one finger.\n\n![Turning key](https://github.com/maxxfrazer/RealityUI/raw/e3cb908fa9051512671e01dd3fe01f59c45f0936/media/RealityUI_pivot_key.gif?raw=true)\n\n[More details](https://maxxfrazer.github.io/RealityUI/documentation/realityui/RUIDragComponent/DragComponentType/turn(axis:))\n\n### Tap\n\nCreate an object in your RealityKit scene with an action, and it will automatically be picked up whenever the user taps on it!\n\nNo Gif for this one, but check out [RUITapComponent](https://maxxfrazer.github.io/RealityUI/documentation/realityui/RUITapComponent) to see how to add this to an entity in your application.\n\nIf you instead wanted to use something similar to a \"touch up inside\" tap, you can use [RUIDragComponentType/click](https://maxxfrazer.github.io/RealityUI/documentation/realityui/RUIDragComponent/DragComponentType/click).\n\n![touch-up-inside example with a button](media/button_light.gif)\n\n---\n## Animations\n\nThere aren't many animations added by default to RealityKit, especially none that you can set to repeat. See the [wiki page](https://github.com/maxxfrazer/RealityUI/wiki/Animations) on how to use these animations.\n\n### Spin\nSpin an Entity around an axis easily using ruiSpin.\n\n![Spinning Star](https://github.com/maxxfrazer/RealityUI/blob/main/media/RUISpin_star_example.gif?raw=true)\n[More details](https://github.com/maxxfrazer/RealityUI/wiki/Animations#spin)\n\n### Shake\n\nShake an entity to attract attention, or signal something was incorrect.\n\n![Shaking Phone Icon](https://github.com/maxxfrazer/RealityUI/blob/main/media/RUIShake_phone_example.gif?raw=true)\n[More details](https://github.com/maxxfrazer/RealityUI/wiki/Animations#shake)\n\n---\n## Text\n\nIt's already possible to place text in RealityKit, but I felt it needed a little upgrade.\n\nWith RUIText you can easily create an Entity with the specified text placed with its bounding box centre at the middle of your entity.\n\n![Hello Text](https://github.com/maxxfrazer/RealityUI/blob/main/media/RUIText_hello_example.gif?raw=true)\n![Hello Text](https://github.com/maxxfrazer/RealityUI/blob/main/media/RUIText_symbols_example.gif?raw=true)\n[More details](https://github.com/maxxfrazer/RealityUI/wiki/Text)\n\n\n---\n## More\n\nMore information on everything provided in this Swift Package in the [documentation](https://maxxfrazer.github.io/RealityUI/documentation/realityui/).\n\nAlso see the [Example Project](https://github.com/maxxfrazer/RealityUI/tree/main/RealityUI%2BExamples) for iOS in this repository.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxxfrazer%2Frealityui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxxfrazer%2Frealityui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxxfrazer%2Frealityui/lists"}