feat: interior places (cityshops.bin), an archive's materials, imports under a frame

README.md

@@ -297,7 +297,7 @@ only, no authorization - with its live status in the launcher's status bar. Poin
 with `claude mcp add --transport http illusion http://127.0.0.1:2010/mcp`; change the port with
 `McpPort` in settings.
 
-It serves 86 tools. The file tools all read through the same format layer the editor uses, so what
+It serves 92 tools. The file tools all read through the same format layer the editor uses, so what
 a model is told about a file is what the toolkit itself sees; the editor tools drive the running
 map editor itself.
 
@@ -306,14 +306,15 @@ map editor itself.
 | **Archives** | `list_sds_files`, `open_sds_file`, `get_sds_header`, `list_resources`, `get_resource_info`, `search_resources`, `extract_resource`, `get_sds_stats`, `close_sds_file` |
 | **Decoding** | `decode_resource` (extract + decode in one call), `decode_actors`, `decode_frame_resource`, `decode_itemdesc`, `decode_collisions` |
 | **Scripts** | `decompile_script_resource`, `decompile_lua` - the game's compiled Lua back to source |
-| **Materials** | `open_mtl_file`, `list_mtl_files`, `get_material_info`, `search_materials` |
+| **Materials** | `open_mtl_file`, `list_mtl_files`, `get_material_info`, `search_materials`, `archive_materials` |
 | **Textures** | `list_sds_textures`, `inspect_sds_texture`, `inspect_dds_file`, `inspect_dds_bytes` |
 | **Tables** | `list_tables`, `dump_rows`, `lookup_by_row` |
 | **Stream map** | `parse_stream_map`, `edit_stream_map` |
 | **Effects** | `parse_effects_file`, `parse_effects_from_bytes` |
 | **Utility** | `hash_fnv32`, `hash_fnv64`, `hash_batch`, `convert_number`, `detect_file_format`, `detect_format_from_bytes`, `list_game_files`, `get_configured_games`, `ping` |
 | **Editor** | `editor_status`, `editor_list_areas`, `editor_open_area`, `editor_save`, `editor_build`, `editor_mirror_winter`, `editor_undo`, `editor_redo`, `editor_notices` |
 | **Scene** | `scene_find`, `scene_select`, `scene_delete_selected`, `scene_duplicate_selected`, `object_move`, `object_properties`, `object_set_property`, `actor_import`, `object_import`, `mesh_hide_triangles`, `mesh_materials`, `collision_unused_hulls`, `crash_placements` |
+| **Interiors** | `shop_places`, `shop_place_add`, `shop_place_delete`, `shop_create`, `shop_delete` |
 | **Resource editor** | `editor_target`, `resource_list`, `resource_open`, `resource_status`, `car_tuning`, `car_tuning_set` |
 | **Cars** | `car_clone`, `car_substitute`, `car_export_m2o`, `archive_build` |
 | **Loading zones** | `zones_at`, `zones_map`, `zone_move_face`, `zone_create`, `zone_delete` |
@@ -350,6 +351,20 @@ district in the table or two - and inside one named `AREA902_FOOXBAR` he does no
 editor open the new zone is a step of its history; `zone_delete` takes an added zone out again (a
 zone the game ships with is refused). Zones are made in the base game's `city_univers` only.
 
+**Interiors.** The game stands a shop, a diner or a flat at a place through three things: a marker
+frame inside the interior's archive under `shops\`, a pair of box volumes in `city_univers` that
+load it and let it go, and rows of `missions\SHOPS\cityshops.bin`. `shop_places` lists the
+interiors and the places each stands at, `shop_place_add` stands one at another place and
+`shop_place_delete` takes a place out. `shop_create` makes a new interior as a copy of an existing
+one under its own name with its own row, and `shop_delete` removes it. A save is all or nothing.
+`object_import` takes a parent frame and, like `actor_import`, works on the archive open in the
+resource editor, which is how an interior is furnished and lit.
+
+`archive_materials` tells each material an archive is drawn with as the game's own, changed or
+added, with its definition in full and which of its textures the archive holds. The game's own are
+an embedded list of the materials it ships with, so the answer is the same on any install.
+`libraryTo` writes the added and changed ones as a material library of their own.
+
 **Cars.** `car_clone` makes a new car out of an existing one for single player: a copy of its
 archive (and the winter `_z` twin) with the root frame, name table, prefab entry, entity data and
 geometry buffers filed under the new model name, registered in the vehicle, paint, cover-point and

src/Illusion.Assets/Frames/FrameTransplant.cs

@@ -60,6 +60,10 @@ public sealed class TransplantedObject
         internal readonly Dictionary<FrameObjectBase, FrameObjectBase> Copies = new();   // source → copy
         internal FrameHeaderScene? Anchor;
 
+        /// <summary>The frame of the receiving scene the copy's root was hung under, when it was asked to be
+        /// someone's child; null for a root that stands in the scene by itself.</summary>
+        public FrameObjectBase? Under { get; internal set; }
+
         /// <summary>The copy's root — what an actor places, or the scenery object itself.</summary>
         public FrameObjectBase Root { get; internal set; } = null!;
 
@@ -206,7 +210,18 @@ public static bool CanTransplant(FrameObjectBase root, out string? reason) =>
     /// </summary>
     public static TransplantedObject? TryTransplant(ISceneDocument document, FrameResource source,
         FrameObjectBase root, string name, Standing standing, Matrix4x4 world, ImportGeometry? shared,
-        out string? skipReason)
+        out string? skipReason) =>
+        TryTransplant(document, source, root, name, standing, world, shared, under: null, out skipReason);
+
+    /// <summary>
+    /// The same, with the copy's root hung under <paramref name="under"/> — a frame of the receiving scene —
+    /// instead of standing in the scene by itself: the shape an interior's furniture ships in, every piece a child
+    /// of the frame that carries the interior to its place. <paramref name="world"/> is still where the copy
+    /// stands in the world; its own matrix is worked out against the parent's. Scenery only.
+    /// </summary>
+    public static TransplantedObject? TryTransplant(ISceneDocument document, FrameResource source,
+        FrameObjectBase root, string name, Standing standing, Matrix4x4 world, ImportGeometry? shared,
+        FrameObjectBase? under, out string? skipReason)
     {
         ArgumentNullException.ThrowIfNull(source);
         ArgumentNullException.ThrowIfNull(root);
@@ -223,6 +238,25 @@ public static bool CanTransplant(FrameObjectBase root, out string? reason) =>
             return null;
         }
         if (!CanTransplant(root, out skipReason)) return null;
+        Matrix4x4 underInverse = Matrix4x4.Identity;
+        if (under != null)
+        {
+            if (standing != Standing.Scenery)
+            {
+                skipReason = "only scenery can be hung under a frame — an actor places its own object";
+                return null;
+            }
+            if (!resource.FrameObjects.TryGetValue(under.RefID, out object? held) || !ReferenceEquals(held, under))
+            {
+                skipReason = "the parent is not a frame of the receiving scene";
+                return null;
+            }
+            if (!Matrix4x4.Invert(under.WorldTransform, out underInverse))
+            {
+                skipReason = $"'{under.Name}' has a matrix that cannot be undone — nothing can be placed under it";
+                return null;
+            }
+        }
         if (string.IsNullOrWhiteSpace(name) || resource.FrameObjects.Values.OfType<FrameObjectBase>()
                 .Any(o => string.Equals(o.Name.String, name, StringComparison.OrdinalIgnoreCase)))
         {
@@ -244,7 +278,17 @@ public static bool CanTransplant(FrameObjectBase root, out string? reason) =>
         var subtree = new List<FrameObjectBase>();
         Collect(root, subtree, new HashSet<FrameObjectBase>());
 
-        var result = new TransplantedObject { Resource = resource, Adapter = adapter, Anchor = anchor };
+        var result = new TransplantedObject { Resource = resource, Adapter = adapter, Anchor = anchor, Under = under };
+        // What a child of `under` records in its second slot: the top of the parent's chain hangs off it — an
+        // object, or the scene folder that holds that top; nothing when the chain ends at a rootless frame.
+        FrameEntry? underAnchor = null;
+        if (under != null)
+        {
+            FrameObjectBase top = under;
+            var climbed = new HashSet<FrameObjectBase> { top };
+            while (top.Parent is { } next && climbed.Add(next)) top = next;
+            underAnchor = top.Root as FrameEntry ?? resource.FrameScenes.Values.FirstOrDefault(folder => folder.Children.Contains(top));
+        }
         string unique = Guid.NewGuid().ToString("N")[..8];
         var reused = new HashSet<ulong>(); // source buffers this copy draws from without copying them
         if (!CopyBuffers(source, resource, subtree, name, unique, result, shared, reused,
@@ -295,20 +339,38 @@ public static bool CanTransplant(FrameObjectBase root, out string? reason) =>
             FrameObjectBase copy = result.Copies[original];
             if (ReferenceEquals(original, root))
             {
-                result.Parents[copy] = (null, anchor);
+                // Under a frame: the parent in the first slot and, in the second, what the parent's own chain
+                // hangs off — the way a shipped interior's pieces name both the frame that carries them and
+                // the scene that frame stands in.
+                result.Parents[copy] = under != null ? (under, underAnchor) : (null, anchor);
                 continue;
             }
             // Inside the subtree a link follows its target's copy. A second-slot link that pointed OUTSIDE it
             // named what the whole chain hangs off — the scene, or the top of the chain — and that is now
             // whatever the root hangs off, or the root itself when it hangs off nothing.
             FrameEntry? parent1 = Mapped(original.Parent, result.Copies);
             FrameEntry? parent2 = original.Refs.ContainsKey(FrameEntryRefTypes.Parent2)
-                ? Mapped(original.Root, result.Copies) ?? (FrameEntry?)anchor ?? result.Root
+                ? Mapped(original.Root, result.Copies) ?? (under != null ? underAnchor : anchor) ?? result.Root
                 : null;
             result.Parents[copy] = (parent1, parent2);
         }
 
-        if (standing == Standing.Scenery)
+        if (under != null)
+        {
+            // A child is found through its parent: not on the spawn list, and a matrix of its own that is told
+            // against the parent's. The anchored-mesh bit as the shipped files have it on a child: set when the
+            // second slot names an object (a door's leaf under its frame), clear when it names the scene (an
+            // interior's furniture under its holder) or nothing.
+            result.Root.IsOnFrameTable = false;
+            if (result.Root is FrameObjectSingleMesh childMesh)
+            {
+                childMesh.SingleMeshFlags = underAnchor is FrameObjectBase
+                    ? childMesh.SingleMeshFlags | SingleMeshFlags.ParentIndex2_Flag
+                    : childMesh.SingleMeshFlags & ~SingleMeshFlags.ParentIndex2_Flag;
+            }
+            result.Root.LocalTransform = world * underInverse;
+        }
+        else if (standing == Standing.Scenery)
         {
             // The stock drawable shape, as the bridge's object factory builds it: anchored through the
             // second slot, on the spawn list, normal-season flags, and the anchored-mesh bit a mesh in that
@@ -356,16 +418,89 @@ public static bool CanTransplant(FrameObjectBase root, out string? reason) =>
     /// shipped ones stand on it. Null when nothing in the subtree decodes.
     /// </para>
     /// </summary>
-    public static Vector3? BaseOf(FrameObjectBase root) =>
-        BoundsOf(root) is { } bounds
+    public static Vector3? BaseOf(FrameObjectBase root) => BaseOf(root, Quaternion.Identity);
+
+    // The same point with the root's space tilted first — the bottom of the object as it STANDS (see StandAt).
+    private static Vector3? BaseOf(FrameObjectBase root, Quaternion tilt) =>
+        BoundsOf(root, Matrix4x4.CreateFromQuaternion(tilt)) is { } bounds
             ? new Vector3((bounds.Min.X + bounds.Max.X) / 2f, (bounds.Min.Y + bounds.Max.Y) / 2f, bounds.Min.Z)
             : null;
 
+    /// <summary>
+    /// A rotation as two: the tilt that stands the object the way it stands, and after it the heading — its
+    /// turn about the vertical axis. <c>rotation = Quaternion.Concatenate(Tilt, heading)</c>.
+    /// <para>
+    /// An object that is upright in its own space has no tilt and its rotation IS its heading. One that is not
+    /// — the chairs of Francesca's flat are modelled with their height along the mesh's y, 0.56 × 0.91 × 0.50
+    /// in their own box, and stood up by a quarter turn in the frame's matrix — keeps that quarter turn in the
+    /// tilt, whichever way it faces.
+    /// </para>
+    /// </summary>
+    public static (Quaternion Tilt, float Heading) SplitHeading(Quaternion rotation)
+    {
+        // The part of the rotation that is a turn about z. None can be told for an object standing exactly
+        // on its head: there every heading is the same rotation about some horizontal axis.
+        float length = MathF.Sqrt((rotation.Z * rotation.Z) + (rotation.W * rotation.W));
+        if (length < 1e-6f) return (rotation, 0f);
+        var twist = new Quaternion(0f, 0f, rotation.Z / length, rotation.W / length);
+        float heading = 2f * MathF.Atan2(twist.Z, twist.W);
+        return (Quaternion.Normalize(Quaternion.Concatenate(rotation, Quaternion.Conjugate(twist))), heading);
+    }
+
+    /// <summary>A rotation with its heading replaced and its tilt kept: what an asked heading makes of the
+    /// rotation an object has in its own archive. For an upright object that is the heading itself.</summary>
+    public static Quaternion WithHeading(Quaternion rotation, float yawRadians) =>
+        Quaternion.Concatenate(SplitHeading(rotation).Tilt, Quaternion.CreateFromAxisAngle(Vector3.UnitZ, yawRadians));
+
+    /// <summary>
+    /// The matrix that STANDS a piece of scenery on a point: tilted and scaled as it is in its own archive
+    /// (<paramref name="sourceWorld"/>), turned about the vertical axis the way it is there or — when a heading
+    /// is asked for — to that heading, and moved so that the middle of the bottom of its geometry is on
+    /// <paramref name="at"/>.
+    /// <para>
+    /// The heading replaces the object's heading and nothing else. Replacing its whole rotation, as this once
+    /// did, laid on its side everything that is not upright in its own space (see
+    /// <see cref="SplitHeading"/>). The bottom is likewise the bottom of the object as it stands — its
+    /// geometry with the tilt applied — and not of the box of its own space, of which such an object's bottom
+    /// is a side.
+    /// </para>
+    /// </summary>
+    /// <param name="yawRadians">The heading to give it; null keeps the one it has.</param>
+    public static Matrix4x4 StandAt(FrameObjectBase root, Matrix4x4 sourceWorld, Vector3 at, float? yawRadians)
+    {
+        // A matrix that is not rotation and scale (sheared, flattened) has no tilt to keep: it is taken as it
+        // is, and an asked heading is then all the rotation the copy gets.
+        bool split = TransformMath.TryDecompose(sourceWorld, out Vector3 scale, out Quaternion rotation, out _);
+        (Quaternion tilt, float heading) = split ? SplitHeading(rotation) : (Quaternion.Identity, 0f);
+
+        Matrix4x4 world = sourceWorld;
+        // What follows the tilt: the turn about the vertical axis and the scale.
+        Matrix4x4 standing = sourceWorld;
+        if (yawRadians is { } yaw)
+        {
+            Quaternion turn = Quaternion.CreateFromAxisAngle(Vector3.UnitZ, yaw);
+            world = TransformMath.Compose(Quaternion.Concatenate(tilt, turn), scale, Vector3.Zero);
+            standing = TransformMath.Compose(turn, scale, Vector3.Zero);
+        }
+        else if (split)
+        {
+            standing = TransformMath.Compose(
+                Quaternion.CreateFromAxisAngle(Vector3.UnitZ, heading), scale, Vector3.Zero);
+        }
+
+        Vector3 standsOn = BaseOf(root, tilt) ?? Vector3.Zero;
+        world.Translation = at - Vector3.TransformNormal(standsOn, standing);
+        return world;
+    }
+
     /// <summary>The box everything the subtree draws fits in, in its root's own space. Null when nothing decodes.</summary>
-    public static (Vector3 Min, Vector3 Max)? BoundsOf(FrameObjectBase root)
+    public static (Vector3 Min, Vector3 Max)? BoundsOf(FrameObjectBase root) => BoundsOf(root, Matrix4x4.Identity);
+
+    private static (Vector3 Min, Vector3 Max)? BoundsOf(FrameObjectBase root, Matrix4x4 then)
     {
         ArgumentNullException.ThrowIfNull(root);
         if (!Matrix4x4.Invert(root.WorldTransform, out Matrix4x4 toRoot)) return null;
+        toRoot *= then;
         Vector3 min = new(float.MaxValue), max = new(float.MinValue);
         foreach ((Vector3[] positions, _) in TrianglesOf(root))
         {