{"id":3134,"date":"2025-02-18T17:25:32","date_gmt":"2025-02-18T22:25:32","guid":{"rendered":"https:\/\/stepinto.vision\/?p=3134"},"modified":"2025-04-01T12:49:20","modified_gmt":"2025-04-01T16:49:20","slug":"realitykit-basics-attachments","status":"publish","type":"post","link":"https:\/\/stepinto.vision\/example-code\/realitykit-basics-attachments\/","title":{"rendered":"RealityKit Basics: attachments"},"content":{"rendered":"\n

We can create 2D SwiftUI attachments and add them to 3D scenes as entities.<\/p>\n\n\n\n

Overview<\/h2>\n\n\n\n

Attachments in RealityKit are one of my favorite features. We can create SwiftUI views, then pass them into a RealityView as an attachment. When we retrieve them in the make or update closures, RealityKit transforms them into entities that we can use along with our other assets.<\/p>\n\n\n\n

Adding an attachment is always a two step process<\/p>\n\n\n\n

    \n
  1. Define an attachment with an id and a view<\/li>\n\n\n\n
  2. Retrieve the attachment by id and add it to the scene. We do this by calling attachments.entity(for: )<\/code>.<\/li>\n<\/ol>\n\n\n\n
    <\/path><\/path><\/svg><\/span>
    RealityView { content, attachments <\/span>in<\/span><\/span>\n    <\/span>if<\/span> <\/span>let<\/span> scene = <\/span>try<\/span>? <\/span>await<\/span> <\/span>Entity<\/span>(<\/span>named<\/span>: <\/span>"RKBasicsLoading"<\/span>, <\/span>in<\/span>: realityKitContentBundle) {<\/span><\/span>\n        content.<\/span>add<\/span>(scene)<\/span><\/span>\n        <\/span>if<\/span> <\/span>let<\/span> earth = scene.<\/span>findEntity<\/span>(<\/span>named<\/span>: <\/span>"Earth"<\/span>) {<\/span><\/span>\n            <\/span>\/\/ Step 2: Retrieve the attachment by id and add it to the scene<\/span><\/span>\n            <\/span>if<\/span> <\/span>let<\/span> earthPanel = attachments.<\/span>entity<\/span>(<\/span>for<\/span>: <\/span>"EarthPanel"<\/span>) {<\/span><\/span>\n                earth.<\/span>addChild<\/span>(earthPanel, <\/span>preservingWorldTransform<\/span>: <\/span>true<\/span>)<\/span><\/span>\n                earthPanel.<\/span>setPosition<\/span>([<\/span>0<\/span>, <\/span>-0.1<\/span>, <\/span>0.1<\/span>], <\/span>relativeTo<\/span>: earth)<\/span><\/span>\n            }<\/span><\/span>\n        }<\/span><\/span>\n    }<\/span><\/span>\n} update: { content, attachments <\/span>in<\/span><\/span>\n} attachments: {<\/span><\/span>\n    <\/span>\/\/ Step 1: Define an attachment with an id and a view<\/span><\/span>\n    <\/span>Attachment<\/span>(<\/span>id<\/span>: <\/span>"EarthPanel"<\/span>) {<\/span><\/span>\n        HStack {<\/span><\/span>\n            <\/span>Image<\/span>(<\/span>systemName<\/span>: <\/span>"globe.europe.africa"<\/span>)<\/span><\/span>\n            <\/span>Text<\/span>(<\/span>"Earth"<\/span>)<\/span><\/span>\n                .<\/span>font<\/span>(.<\/span>headline<\/span>)<\/span><\/span>\n        }<\/span><\/span>\n        .<\/span>padding<\/span>()<\/span><\/span>\n        .<\/span>glassBackgroundEffect<\/span>()<\/span><\/span>\n    }<\/span><\/span>\n}<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
    We can work with attachments in two main ways.<\/p>\n\n\n\n
      \n
    1. As child entities of other entities in our scene.<\/li>\n\n\n\n
    2. As standalone entities in our scene<\/li>\n<\/ol>\n\n\n\n
      We have examples of both here. This adds the earthPanel as a child of the earth entity.  <\/p>\n\n\n\n
      <\/path><\/path><\/svg><\/span>
      if<\/span> <\/span>let<\/span> earthPanel = attachments.<\/span>entity<\/span>(<\/span>for<\/span>: <\/span>"EarthPanel"<\/span>) {<\/span><\/span>\n    <\/span>\/\/ \u274c Don't add an attachment like this unless you want the SwiftUI content to scale with the entity<\/span><\/span>\n    <\/span>\/\/ earth.addChild(earthPanel)<\/span><\/span>\n    <\/span>\/\/ \u2705 Instead, use preservingWorldTransform to keep the attachment entity transform\/scale<\/span><\/span>\n    earth.<\/span>addChild<\/span>(earthPanel, <\/span>preservingWorldTransform<\/span>: <\/span>true<\/span>)<\/span><\/span>\n    earthPanel.<\/span>setPosition<\/span>([<\/span>0<\/span>, <\/span>-0.1<\/span>, <\/span>0.1<\/span>], <\/span>relativeTo<\/span>: earth)<\/span><\/span>\n}<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
      Notice that we use addChild(earthPanel, preservingWorldTransform: true)<\/code>. This will let us keep the intrinsic size and transform of the attachment entity, regardless of the parent. There are situations where you may want to scale the attachments with the parent though. For example, I do this for the text on the gravestones in Project Graveyard. In those cases, set preservingWorldTransform<\/code> to false or use addChild()<\/code>.<\/p>\n\n\n\n
      \"\"
      Attachments are scaled with the parent gravestone<\/figcaption><\/figure>\n\n\n\n
      We can also add attachments as standalone entities in the scene.<\/p>\n\n\n\n
      <\/path><\/path><\/svg><\/span>
      RealityView { content, attachments <\/span>in<\/span><\/span>\n    <\/span>if<\/span> <\/span>let<\/span> scene = <\/span>try<\/span>? <\/span>await<\/span> <\/span>Entity<\/span>(<\/span>named<\/span>: <\/span>"RKBasicsLoading"<\/span>, <\/span>in<\/span>: realityKitContentBundle) {<\/span><\/span>\n        content.<\/span>add<\/span>(scene)<\/span><\/span>\n        <\/span>\/\/ Get the attachment by id<\/span><\/span>\n        <\/span>if<\/span> <\/span>let<\/span> titlePanel = attachments.<\/span>entity<\/span>(<\/span>for<\/span>: <\/span>"TitlePanel"<\/span>) {<\/span><\/span>\n            <\/span>\/\/ add it to the content<\/span><\/span>\n            content.<\/span>add<\/span>(titlePanel)<\/span><\/span>\n            titlePanel.<\/span>setPosition<\/span>([<\/span>0<\/span>, <\/span>0.2<\/span>, <\/span>-0.2<\/span>], <\/span>relativeTo<\/span>: <\/span>nil<\/span>)<\/span><\/span>\n        }<\/span><\/span>\n    }<\/span><\/span>\n} update: { content, attachments <\/span>in<\/span><\/span>\n} attachments: {<\/span><\/span>\n    <\/span>Attachment<\/span>(<\/span>id<\/span>: <\/span>"TitlePanel"<\/span>) {<\/span><\/span>\n        VStack {<\/span><\/span>\n            <\/span>Text<\/span>(<\/span>"Earth & Moon"<\/span>)<\/span><\/span>\n                .<\/span>font<\/span>(.<\/span>largeTitle<\/span>)<\/span><\/span>\n            <\/span>Text<\/span>(<\/span>"Best of friends for 4.53 billion years"<\/span>)<\/span><\/span>\n                .<\/span>font<\/span>(.<\/span>caption<\/span>)<\/span><\/span>\n        }<\/span><\/span>\n        .<\/span>padding<\/span>()<\/span><\/span>\n        .<\/span>glassBackgroundEffect<\/span>(<\/span>in<\/span>: .<\/span>rect<\/span>(<\/span>cornerRadius<\/span>: <\/span>24<\/span>))<\/span><\/span>\n    }<\/span><\/span>\n}<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
      Attachments are an incredibly powerful feature. They can display simple bits of data or more complex UI. Be away that many SwiftUI controls that rely on the presentation API are not supported in attachments. Common controls like picker require some additional work.<\/p>\n\n\n\n
      Full Example Code<\/h2>\n\n\n\n
      <\/path><\/path><\/svg><\/span>
      struct<\/span> <\/span>Example050<\/span>: View {<\/span><\/span>\n    <\/span>var<\/span> body: some View {<\/span><\/span>\n        RealityView { content, attachments <\/span>in<\/span><\/span>\n<\/span>\n            <\/span>if<\/span> <\/span>let<\/span> scene = <\/span>try<\/span>? <\/span>await<\/span> <\/span>Entity<\/span>(<\/span>named<\/span>: <\/span>"RKBasicsLoading"<\/span>, <\/span>in<\/span>: realityKitContentBundle) {<\/span><\/span>\n                content.<\/span>add<\/span>(scene)<\/span><\/span>\n                scene.<\/span>position<\/span>.<\/span>y<\/span> = <\/span>-0.4<\/span><\/span>\n<\/span>\n                <\/span>if<\/span> <\/span>let<\/span> earth = scene.<\/span>findEntity<\/span>(<\/span>named<\/span>: <\/span>"Earth"<\/span>), <\/span>let<\/span> moon = scene.<\/span>findEntity<\/span>(<\/span>named<\/span>: <\/span>"Moon"<\/span>) {<\/span><\/span>\n<\/span>\n                    <\/span>if<\/span> <\/span>let<\/span> earthPanel = attachments.<\/span>entity<\/span>(<\/span>for<\/span>: <\/span>"EarthPanel"<\/span>) {<\/span><\/span>\n                        <\/span>\/\/ \u274c Don't add an attachment like this unless you want the SwiftUI content to scale with the entity<\/span><\/span>\n                        <\/span>\/\/ earth.addChild(earthPanel)<\/span><\/span>\n                        <\/span>\/\/ \u2705 Instead, use preservingWorldTransform to keep the attachment entity transform\/scale<\/span><\/span>\n                        earth.<\/span>addChild<\/span>(earthPanel, <\/span>preservingWorldTransform<\/span>: <\/span>true<\/span>)<\/span><\/span>\n                        earthPanel.<\/span>setPosition<\/span>([<\/span>0<\/span>, <\/span>-0.1<\/span>, <\/span>0.1<\/span>], <\/span>relativeTo<\/span>: earth)<\/span><\/span>\n                    }<\/span><\/span>\n<\/span>\n                    <\/span>if<\/span> <\/span>let<\/span> moonPanel = attachments.<\/span>entity<\/span>(<\/span>for<\/span>: <\/span>"MoonPanel"<\/span>) {<\/span><\/span>\n                        moon.<\/span>addChild<\/span>(moonPanel, <\/span>preservingWorldTransform<\/span>: <\/span>true<\/span>)<\/span><\/span>\n                        moonPanel.<\/span>setPosition<\/span>([<\/span>0<\/span>, <\/span>-0.05<\/span>, <\/span>0.15<\/span>], <\/span>relativeTo<\/span>: moon)<\/span><\/span>\n                    }<\/span><\/span>\n                }<\/span><\/span>\n<\/span>\n                <\/span>if<\/span> <\/span>let<\/span> titlePanel = attachments.<\/span>entity<\/span>(<\/span>for<\/span>: <\/span>"TitlePanel"<\/span>) {<\/span><\/span>\n                    content.<\/span>add<\/span>(titlePanel)<\/span><\/span>\n                    titlePanel.<\/span>setPosition<\/span>([<\/span>0<\/span>, <\/span>0.2<\/span>, <\/span>-0.2<\/span>], <\/span>relativeTo<\/span>: <\/span>nil<\/span>)<\/span><\/span>\n                }<\/span><\/span>\n<\/span>\n                <\/span><\/span>\n            }<\/span><\/span>\n<\/span>\n        } update: { content, attachments <\/span>in<\/span><\/span>\n<\/span>\n        } attachments: {<\/span><\/span>\n<\/span>\n            <\/span>Attachment<\/span>(<\/span>id<\/span>: <\/span>"EarthPanel"<\/span>) {<\/span><\/span>\n                HStack {<\/span><\/span>\n                    <\/span>Image<\/span>(<\/span>systemName<\/span>: <\/span>"globe.europe.africa"<\/span>)<\/span><\/span>\n                    <\/span>Text<\/span>(<\/span>"Earth"<\/span>)<\/span><\/span>\n                        .<\/span>font<\/span>(.<\/span>headline<\/span>)<\/span><\/span>\n                }<\/span><\/span>\n                .<\/span>padding<\/span>()<\/span><\/span>\n                .<\/span>glassBackgroundEffect<\/span>()<\/span><\/span>\n            }<\/span><\/span>\n<\/span>\n            <\/span>Attachment<\/span>(<\/span>id<\/span>: <\/span>"MoonPanel"<\/span>) {<\/span><\/span>\n                HStack {<\/span><\/span>\n                    <\/span>Image<\/span>(<\/span>systemName<\/span>: <\/span>"moon.circle.fill"<\/span>)<\/span><\/span>\n                    <\/span>Text<\/span>(<\/span>"Moon"<\/span>)<\/span><\/span>\n                        .<\/span>font<\/span>(.<\/span>headline<\/span>)<\/span><\/span>\n                }<\/span><\/span>\n                .<\/span>padding<\/span>()<\/span><\/span>\n                .<\/span>glassBackgroundEffect<\/span>()<\/span><\/span>\n            }<\/span><\/span>\n<\/span>\n            <\/span>Attachment<\/span>(<\/span>id<\/span>: <\/span>"TitlePanel"<\/span>) {<\/span><\/span>\n                VStack {<\/span><\/span>\n                    <\/span>Text<\/span>(<\/span>"Earth & Moon"<\/span>)<\/span><\/span>\n                        .<\/span>font<\/span>(.<\/span>largeTitle<\/span>)<\/span><\/span>\n                    <\/span>Text<\/span>(<\/span>"Best of friends for 4.53 billion years"<\/span>)<\/span><\/span>\n                        .<\/span>font<\/span>(.<\/span>caption<\/span>)<\/span><\/span>\n                }<\/span><\/span>\n                .<\/span>padding<\/span>()<\/span><\/span>\n                .<\/span>glassBackgroundEffect<\/span>(<\/span>in<\/span>: .<\/span>rect<\/span>(<\/span>cornerRadius<\/span>: <\/span>24<\/span>))<\/span><\/span>\n            }<\/span><\/span>\n        }<\/span><\/span>\n    }<\/span><\/span>\n}<\/span><\/span><\/code><\/pre><\/div>\n","protected":false},"excerpt":{"rendered":"
      We can create 2D SwiftUI attachments and add them to 3D scenes as entities.<\/p>\n","protected":false},"author":93705089,"featured_media":3135,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_kad_blocks_custom_css":"","_kad_blocks_head_custom_js":"","_kad_blocks_body_custom_js":"","_kad_blocks_footer_custom_js":"","advanced_seo_description":"","jetpack_seo_html_title":"","jetpack_seo_noindex":false,"_EventAllDay":false,"_EventTimezone":"","_EventStartDate":"","_EventEndDate":"","_EventStartDateUTC":"","_EventEndDateUTC":"","_EventShowMap":false,"_EventShowMapLink":false,"_EventURL":"","_EventCost":"","_EventCostDescription":"","_EventCurrencySymbol":"","_EventCurrencyCode":"","_EventCurrencyPosition":"","_EventDateTimeSeparator":"","_EventTimeRangeSeparator":"","_EventOrganizerID":[],"_EventVenueID":[],"_OrganizerEmail":"","_OrganizerPhone":"","_OrganizerWebsite":"","_VenueAddress":"","_VenueCity":"","_VenueCountry":"","_VenueProvince":"","_VenueState":"","_VenueZip":"","_VenuePhone":"","_VenueURL":"","_VenueStateProvince":"","_VenueLat":"","_VenueLng":"","_VenueShowMap":false,"_VenueShowMapLink":false,"_kadence_starter_templates_imported_post":false,"_kad_post_transparent":"","_kad_post_title":"","_kad_post_layout":"","_kad_post_sidebar_id":"","_kad_post_content_style":"","_kad_post_vertical_padding":"","_kad_post_feature":"","_kad_post_feature_position":"","_kad_post_header":false,"_kad_post_footer":false,"_kad_post_classname":"","_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":true,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","enabled":false},"version":2},"_wpas_customize_per_network":false,"jetpack_post_was_ever_published":false},"categories":[1365],"tags":[],"class_list":["post-3134","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-example-code"],"jetpack_publicize_connections":[],"taxonomy_info":{"category":[{"value":1365,"label":"Example Code"}]},"featured_image_src_large":["https:\/\/i0.wp.com\/stepinto.vision\/wp-content\/uploads\/2025\/02\/step-example-050-01.jpeg?fit=1024%2C768&ssl=1",1024,768,true],"author_info":{"display_name":"Joseph Simpson","author_link":"https:\/\/stepinto.vision\/author\/vrhermit\/"},"comment_info":0,"category_info":[{"term_id":1365,"name":"Example Code","slug":"example-code","term_group":0,"term_taxonomy_id":11,"taxonomy":"category","description":"Code snippets and examples of using common APIs throughout visionOS development","parent":0,"count":187,"filter":"raw","cat_ID":1365,"category_count":187,"category_description":"Code snippets and examples of using common APIs throughout visionOS development","cat_name":"Example Code","category_nicename":"example-code","category_parent":0}],"tag_info":false,"jetpack_featured_media_url":"https:\/\/i0.wp.com\/stepinto.vision\/wp-content\/uploads\/2025\/02\/step-example-050-01.jpeg?fit=2732%2C2048&ssl=1","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/stepinto.vision\/wp-json\/wp\/v2\/posts\/3134","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/stepinto.vision\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/stepinto.vision\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/stepinto.vision\/wp-json\/wp\/v2\/users\/93705089"}],"replies":[{"embeddable":true,"href":"https:\/\/stepinto.vision\/wp-json\/wp\/v2\/comments?post=3134"}],"version-history":[{"count":14,"href":"https:\/\/stepinto.vision\/wp-json\/wp\/v2\/posts\/3134\/revisions"}],"predecessor-version":[{"id":3896,"href":"https:\/\/stepinto.vision\/wp-json\/wp\/v2\/posts\/3134\/revisions\/3896"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/stepinto.vision\/wp-json\/wp\/v2\/media\/3135"}],"wp:attachment":[{"href":"https:\/\/stepinto.vision\/wp-json\/wp\/v2\/media?parent=3134"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/stepinto.vision\/wp-json\/wp\/v2\/categories?post=3134"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/stepinto.vision\/wp-json\/wp\/v2\/tags?post=3134"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}