cleanup

kiln-core/src/object_def.rs

@@ -54,13 +54,18 @@ pub struct ObjectDef {
     /// remove itself via `die()`). Set when a grab archetype (e.g. a gem) is
     /// expanded into an object. Defaults to `false`.
     pub grab: bool,
-    /// Name of the Rhai script in [`Board::scripts`] that drives this object.
-    /// `None` means this object has no script yet.
+    /// Compile-key of the Rhai script that drives this object: a name in
+    /// [`World::scripts`](crate::world::World::scripts) for a hand-authored object,
+    /// or a synthetic `BUILTIN_*` name set when a script-backed archetype is
+    /// expanded (see [`builtin_script`](ObjectDef::builtin_script)). `None` means
+    /// this object has no script yet.
     pub script_name: Option<String>,
     /// Embedded built-in script source, set when a script-backed archetype (e.g. a
-    /// `pusher_*`) is expanded into an object at load time (see
-    /// [`crate::builtin_scripts`]). Takes precedence over [`script_name`](ObjectDef::script_name)
-    /// and is not part of the map file (it is regenerated from the archetype on load).
+    /// `pusher_*` or `gem`) is expanded into an object at load time (see
+    /// [`crate::builtin_scripts`]). When set, this is the object's script *source*
+    /// (its compile-key is the synthetic `BUILTIN_*` [`script_name`](ObjectDef::script_name)
+    /// the same expansion assigns). Not part of the map file — it is regenerated
+    /// from the archetype on load.
     pub builtin_script: Option<&'static str>,
     /// Open-ended string labels for this object. Serialized as a TOML array;
     /// not subject to any rate limit — mutations take effect immediately after