feat(api): generate package entity accessor fns

crates/wasm/src/client/implementation/unused.rs

@@ -154,7 +154,7 @@ impl wit::server_http::Host for Bindings {
     }
 }
 #[async_trait::async_trait]
-impl wit::package_::Host for Bindings {
+impl wit::ambient_package::Host for Bindings {
     async fn get_entity_for_package_id(
         &mut self,
         _package_id: String,

crates/wasm/src/server/implementation/specific.rs

@@ -151,7 +151,7 @@ impl shared::wit::server_http::Host for Bindings {
 }
 
 #[async_trait::async_trait]
-impl shared::wit::package_::Host for Bindings {
+impl shared::wit::ambient_package::Host for Bindings {
     async fn get_entity_for_package_id(
         &mut self,
         package_id: String,

crates/wasm/src/shared/bindings.rs

@@ -21,7 +21,7 @@ pub trait BindingsBound:
     + super::wit::entity::Host
     + super::wit::message::Host
     + super::wit::player::Host
-    + super::wit::package_::Host
+    + super::wit::ambient_package::Host
     // Client
     + super::wit::client_message::Host
     + super::wit::client_player::Host

crates/wasm/wit/package_.wit → crates/wasm/wit/ambient-package.wit

@@ -1,4 +1,4 @@
-interface package_ {
+interface ambient-package {
     use types.{entity-id}
 
     get-entity-for-package-id: func(package-id: string) -> option<entity-id>

crates/wasm/wit/bindings.wit

@@ -8,7 +8,7 @@ world bindings {
     import entity
     import message
     import player
-    import package_
+    import ambient-package
 
     import client-message
     import client-player

docs/src/reference/package.md

@@ -306,3 +306,32 @@ the_basics = { path = "../basics" }
 [components]
 my_component = { type = "the_basics::BasicEnum" }
 ```
+
+### Runtime access to packages
+
+Packages are represented as entities within the ECS, with their metadata being stored as components. This means that you can access the metadata of a package at runtime. To do so, you can use the `entity()` function inside the generated Rust code for the package:
+
+```rust
+use ambient_api::prelude::*;
+
+#[main]
+fn main() {
+    dbg!(entity::get_all_components(packages::this::entity()));
+}
+```
+
+Or by querying for entities that have the `is_package` component:
+
+```rust
+use ambient_api::{
+    core::package::components::{is_package, name},
+    prelude::*,
+};
+
+#[main]
+fn main() {
+    let q = query((is_package(), name())).build();
+    // List all packages and their names.
+    dbg!(q.evaluate());
+}
+```

guest/rust/api_core/src/package.rs

@@ -4,6 +4,6 @@ use crate::{
 };
 
 #[doc(hidden)]
-pub fn get_entity_for_package_id(package_id: String) -> Option<EntityId> {
-    internal::wit::package_::get_entity_for_package_id(&package_id).from_bindgen()
+pub fn get_entity_for_package_id(package_id: &str) -> Option<EntityId> {
+    internal::wit::ambient_package::get_entity_for_package_id(package_id).from_bindgen()
 }

shared_crates/package_macro_common/src/lib.rs

@@ -1,7 +1,7 @@
 extern crate proc_macro;
 
 pub use ambient_package_semantic::RetrievableFile;
-use ambient_package_semantic::{Item, ItemId, ItemMap, Scope, Semantic, Type, TypeInner};
+use ambient_package_semantic::{Item, ItemId, ItemMap, Package, Scope, Semantic, Type, TypeInner};
 use proc_macro2::TokenStream;
 use quote::{quote, ToTokens};
 use std::collections::HashMap;
@@ -48,21 +48,7 @@ pub async fn generate_code(
     let outputs = semantic
         .packages
         .values()
-        .map(|&package_id| {
-            let package = items.get(package_id);
-            let generate_from_scope = &*items.get(package.scope_id);
-
-            let generated_output = generate(context, items, &type_printer, generate_from_scope)?;
-            let components_init = components::generate_init(context, items, generate_from_scope)?;
-
-            let id = make_path(package.data.id.as_str());
-            anyhow::Ok(quote! {
-                pub mod #id {
-                    #generated_output
-                    #components_init
-                }
-            })
-        })
+        .map(|id| generate_package(context, items, &type_printer, *id))
         .collect::<Result<Vec<_>, _>>()?;
 
     let imports = if let Some(package_id) = package_id {
@@ -113,7 +99,44 @@ pub async fn generate_code(
     Ok(output)
 }
 
-fn generate(
+fn generate_package(
+    context: context::Context,
+    items: &ItemMap,
+    type_printer: &TypePrinter,
+    package_id: ItemId<Package>,
+) -> anyhow::Result<TokenStream> {
+    let package = items.get(package_id);
+    let generate_from_scope = &*items.get(package.scope_id);
+
+    let entity = match context {
+        Context::GuestUser => {
+            let package_ambient_id = package.data().id.to_string();
+            quote! {
+                pub fn entity() -> ambient_api::global::EntityId {
+                    use ambient_api::once_cell::sync::Lazy;
+                    static ENTITY: Lazy<ambient_api::global::EntityId> = Lazy::new(|| {
+                        ambient_api::package::get_entity_for_package_id(#package_ambient_id).expect("Failed to get package entity - was it despawned?")
+                    });
+                    *ENTITY
+                }
+            }
+        }
+        _ => TokenStream::new(),
+    };
+    let generated_output = generate_scope(context, items, &type_printer, generate_from_scope)?;
+    let components_init = components::generate_init(context, items, generate_from_scope)?;
+
+    let id = make_path(package.data.id.as_str());
+    anyhow::Ok(quote! {
+        pub mod #id {
+            #entity
+            #generated_output
+            #components_init
+        }
+    })
+}
+
+fn generate_scope(
     context: context::Context,
     items: &ItemMap,
     type_printer: &TypePrinter,
@@ -129,7 +152,7 @@ fn generate(
             }
 
             let id = make_path(scope.data.id.as_str());
-            let inner = generate(context, items, type_printer, &scope)?;
+            let inner = generate_scope(context, items, type_printer, &scope)?;
             if inner.is_empty() {
                 return Ok(quote! {});
             }