diff --git a/CHANGELOG.md b/CHANGELOG.md
index dbdc344b..4ddb634e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,10 @@
Version numbers follow `MAJOR.MINOR.PATCH`; the 0.x series is under active development. Release tags and downloadable archives use the same version.
+## 0.12.5 — 2026-11-14
+
+- Editing a matrix-authored object keeps its matrix instead of converting it to translation, rotation and scale. Moving it changes only the matrix's position, preserving its basis exactly; copies and reparenting also retain matrices.
+
## 0.12.4 — 2026-11-13
- Clicking a World tree row button after switching back to zStudio keeps the tree at its current scroll position.
diff --git a/Directory.Build.props b/Directory.Build.props
index 8a5297d6..87e472b6 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -18,6 +18,6 @@
Advanced viewer and editor for Zipper Interactive's ZBD files
https://github.com/Vorta/zStudio
git
- 0.12.4
+ 0.12.5
diff --git a/README.md b/README.md
index 788c811a..c5647df2 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@
zStudio is a Windows desktop application. It unpacks RECOIL's retail game files once into an editable source project (the developers' original `data\` and `gamegen\` tree: text resources, glTF models, PNG textures, WAV sounds and build scripts), lets you edit the maps in zStudio or in Blender, and exports new game files from the sources. AI agents can work in the same workspace through local MCP.
-Download **[zStudio v0.12.4](https://github.com/Vorta/zStudio/releases/tag/v0.12.4)** for Windows x64.
+Download **[zStudio v0.12.5](https://github.com/Vorta/zStudio/releases/tag/v0.12.5)** for Windows x64.
zStudio tells you when a newer release is out: **Update available** appears in the status bar; click it for the release page. zStudio asks GitHub's public release API at most once a day and sends nothing but its version; **Help → Check for updates** asks now, and **Help → Check for updates automatically** turns the daily check off. Running zStudio 0.9.6 or older on the same Windows account turns the daily check back on, because older versions drop settings they don't know.
diff --git a/blender/zstudio_recoil/blender_manifest.toml b/blender/zstudio_recoil/blender_manifest.toml
index b6858644..33a2614d 100644
--- a/blender/zstudio_recoil/blender_manifest.toml
+++ b/blender/zstudio_recoil/blender_manifest.toml
@@ -1,6 +1,6 @@
schema_version = "1.0.0"
id = "zstudio_recoil"
-version = "0.12.4"
+version = "0.12.5"
name = "zStudio RECOIL"
tagline = "Edit RECOIL glTF models, linked worlds, flags and zones"
maintainer = "Vorta"
diff --git a/docs/map-editor.md b/docs/map-editor.md
index b76a713f..ad651367 100644
--- a/docs/map-editor.md
+++ b/docs/map-editor.md
@@ -76,6 +76,8 @@ A selected object's fields are editable at once: **Name** and **Model** where th
Where an edit lands:
+An object authored with a glTF `matrix` keeps that representation when moved, rotated, scaled, copied or moved under another parent. A position-only move changes only the matrix's translation entries and keeps its basis exactly. Objects authored with translation, rotation and scale keep using those properties where they can express the placement.
+
| Object | What changes |
| --- | --- |
| A node of the mission database (`mN.gltf`) or its parts | the glTF node; a part's node changes in every copy of the part |
diff --git a/src/zStudio.Core/Sources/GltfNodeEdits.cs b/src/zStudio.Core/Sources/GltfNodeEdits.cs
index 8a9a0283..48c47eea 100644
--- a/src/zStudio.Core/Sources/GltfNodeEdits.cs
+++ b/src/zStudio.Core/Sources/GltfNodeEdits.cs
@@ -428,7 +428,7 @@ internal static void Reparent(Hierarchy hierarchy, int index, int? parent, uint?
throw new InvalidDataException("Under the new parent the node's scale would fall below 1e-6 of its parent's, which flattens it for later edits; choose another parent.");
CheckReparentedPosition(local.Translation);
JsonObject preparedLocal = new();
- SetLocal(preparedLocal, local);
+ SetLocal(preparedLocal, local, moved["matrix"] is JsonArray);
JsonObject? preparedExtras = null;
if (inheritedZone is uint keep)
{
@@ -520,15 +520,18 @@ private static void SetExplicitZone(JsonObject engine, uint zone)
/// none). A malformed transform is refused as the reader refuses it ().
///
public static Matrix4x4 Local(JsonObject node) => GltfDocument.LocalTransform(node) ?? Matrix4x4.Identity;
- /// Sets a node's local transform, as translation, rotation and scale when it decomposes, otherwise as a matrix.
- public static void SetLocal(JsonObject node, Matrix4x4 m)
+ /// Sets a node's local transform, keeping an authored matrix; otherwise uses TRS when it decomposes.
+ public static void SetLocal(JsonObject node, Matrix4x4 m) => SetLocal(node, m, node["matrix"] is JsonArray);
+
+ // Reparenting prepares the fields separately before committing; carry the original node's representation with them.
+ internal static void SetLocal(JsonObject node, Matrix4x4 m, bool preserveMatrix)
{
ObjectTransform.Finite(m);
node.Remove("matrix"); node.Remove("translation"); node.Remove("rotation"); node.Remove("scale");
- if (m.IsIdentity) return;
+ if (!preserveMatrix && m.IsIdentity) return;
// TRS only when it gives the matrix back, each axis within a fraction of its own length: Decompose replaces axes
// shorter than its epsilon, which an absolute comparison would let through as a turned object.
- if (Matrix4x4.Decompose(m, out var scale, out var rotation, out var translation)
+ if (!preserveMatrix && Matrix4x4.Decompose(m, out var scale, out var rotation, out var translation)
&& Matrix4x4.CreateScale(scale) * Matrix4x4.CreateFromQuaternion(rotation) * Matrix4x4.CreateTranslation(translation) is var recomposed
&& Enumerable.Range(0, 3).All(row =>
{
diff --git a/src/zStudio.Core/Sources/SourceObjectEdits.cs b/src/zStudio.Core/Sources/SourceObjectEdits.cs
index df96b294..dcc3a2ad 100644
--- a/src/zStudio.Core/Sources/SourceObjectEdits.cs
+++ b/src/zStudio.Core/Sources/SourceObjectEdits.cs
@@ -349,7 +349,11 @@ void Add(bool changes, string command, Vector3 value, Vector3 unset, Vector3? sh
if (gltfPosition) m.Translation = requested.Position;
ObjectTransform.Finite(m);
// A move keeps the authored basis as written; anything else writes the new transform.
- if (!rotation && !scale && node["matrix"] is not JsonArray) node["translation"] = Array(m.Translation.X, m.Translation.Y, m.Translation.Z);
+ if (!rotation && !scale && node["matrix"] is JsonArray matrix)
+ {
+ matrix[12] = m.Translation.X; matrix[13] = m.Translation.Y; matrix[14] = m.Translation.Z;
+ }
+ else if (!rotation && !scale) node["translation"] = Array(m.Translation.X, m.Translation.Y, m.Translation.Z);
else GltfNodeEdits.SetLocal(node, m);
}, token);
changes.AddRange(plan.Changes); notes.AddRange(plan.Notes); places.Add(plan.Target);
diff --git a/tests/zStudio.Desktop.Tests/SourceEditingMcpChecks.cs b/tests/zStudio.Desktop.Tests/SourceEditingMcpChecks.cs
index 0d2d5fef..df40b27f 100644
--- a/tests/zStudio.Desktop.Tests/SourceEditingMcpChecks.cs
+++ b/tests/zStudio.Desktop.Tests/SourceEditingMcpChecks.cs
@@ -817,6 +817,10 @@ static System.Windows.Controls.TextBox PositionField(SceneInspectionCard card, s
.OfType().Single(t => System.Windows.Automation.AutomationProperties.GetName(t) == "Position " + axis);
async Task AssertRetainedTurret(System.Numerics.Vector3 offset)
{
+ var sourceNode = JsonNode.Parse(workspace.Read("data/m2/models/m2.gltf", token)!)!["nodes"]!.AsArray()
+ .Single(n => n!["name"]?.GetValue() == "tur_101")!;
+ Assert.Equal(16, Assert.IsType(sourceNode["matrix"]).Count);
+ foreach (string key in new[] { "translation", "rotation", "scale" }) Assert.Null(sourceNode[key]);
await main.Dispatcher.InvokeAsync(() => { }, System.Windows.Threading.DispatcherPriority.Loaded, token);
main.UpdateLayout();
var currentCard = (SceneInspectionCard)turretViewport.InspectionContent!;
@@ -846,13 +850,7 @@ async Task AssertRetainedTurret(System.Numerics.Vector3 offset)
var expected = original * System.Numerics.Matrix4x4.CreateTranslation(offset);
var actual = parts[name];
Assert.Equal(expected.Translation, actual.Translation);
- // The shared glTF writer converts an authored matrix to TRS when it decomposes;
- // quaternion normalization on reload can change this 45-degree basis by two float ULPs.
- // Position and the affine column remain exact; tolerate only that tiny basis round trip.
- for (int row = 0; row < 3; row++)
- for (int column = 0; column < 3; column++)
- Assert.InRange(MathF.Abs(expected[row, column] - actual[row, column]), 0f, 1e-6f);
- for (int row = 0; row < 4; row++) Assert.Equal(expected[row, 3], actual[row, 3]);
+ Assert.Equal(expected, actual);
}
Assert.DoesNotContain(zStudio.Core.SceneBuilder.Assemble(turretViewport.Mission!.Scene).Placements, p => p.Name == "wreck");
}
diff --git a/tests/zStudio.Tests/SourceMatrixPreservationTests.cs b/tests/zStudio.Tests/SourceMatrixPreservationTests.cs
new file mode 100644
index 00000000..a0383822
--- /dev/null
+++ b/tests/zStudio.Tests/SourceMatrixPreservationTests.cs
@@ -0,0 +1,78 @@
+using System.Numerics;
+using System.Text.Json.Nodes;
+using zStudio.Core.Sources;
+using zStudio.Core.Worlds;
+using Xunit;
+
+namespace zStudio.Tests;
+
+// Data-integrity regression: editing a matrix must not silently change its source representation or basis.
+public sealed class SourceMatrixPreservationTests
+{
+ [Fact]
+ public async Task MatrixObjectsKeepTheirRepresentationThroughPlacementAndStructuralEdits()
+ {
+ var token = TestContext.Current.CancellationToken;
+ using SourceWorldFixture fixture = new(); fixture.WriteNestedDatabase();
+ const string file = "data/m1/models/m1.gltf";
+ var root = JsonNode.Parse(File.ReadAllBytes(fixture.Path(file)))!;
+ var crate = root["nodes"]!.AsArray().Single(n => n!["name"]!.GetValue() == "crate")!;
+ crate["matrix"] = JsonNode.Parse("[-1,0,0,0,0,0.60000000000000001,0.8,0,0,0.8,-0.6,0,10,2,-30,1]");
+ fixture.Write(file, root.ToJsonString());
+ SourceWorkspace workspace = new(fixture.Project);
+ var source = await SourceWorlds.LoadSceneAsync(fixture.Project, "m1", workspace.Overlay(), token);
+ int index = Target().Origin.ModelNode;
+ var before = root.DeepClone();
+ var current = ObjectTransform.Of(Target().Node);
+ await Apply(SourceObjectEdits.PlanTransform(workspace, "crate", Target().Origin, source.Executions,
+ current with { Position = new(15, 3, -20) }, token, "m1", current));
+ var expected = before.DeepClone();
+ var values = expected["nodes"]![index]!["matrix"]!.AsArray();
+ values[12] = 15; values[13] = 3; values[14] = -20;
+ Assert.True(JsonNode.DeepEquals(expected, JsonNode.Parse(workspace.Read(file, token)!)));
+ AssertMatrix("crate");
+
+ current = ObjectTransform.Of(Target().Node);
+ await Apply(SourceObjectEdits.PlanTransform(workspace, "crate", Target().Origin, source.Executions,
+ current with { RotationDegrees = new(10, 25, 5), Scale = new(2, 3, 4) }, token, "m1", current));
+ AssertMatrix("crate");
+ var placed = WorldUpdate.LocalMatrix(Target().Node)!.Value;
+ await Apply(SourceObjectEdits.PlanDuplicate(Target(), "crate_copy", ObjectTransform.Of(Target().Node) with { Position = new(50, 4, -10) }, token, keepBasis: true));
+ AssertMatrix("crate_copy");
+ Assert.Equal(placed with { Translation = new(50, 4, -10) }, WorldUpdate.LocalMatrix(source.World.Nodes.Single(n => n.Name == "crate_copy")));
+
+ var parent = source.World.Nodes.Single(n => n.Name == "ground");
+ await Apply(SourceObjectEdits.PlanReparent(Target(), parent, token));
+ AssertMatrix("crate");
+ Assert.Equal(placed, WorldUpdate.LocalMatrix(Target().Node));
+ await Apply(SourceObjectEdits.PlanPatch(Target(), new() { Reparent = true, Parent = null, Position = new(21, 5, -10) }, token));
+ AssertMatrix("crate");
+ Assert.Equal(placed with { Translation = new(21, 5, -10) }, WorldUpdate.LocalMatrix(Target().Node));
+
+ // Even an identity result keeps an explicitly authored matrix.
+ current = ObjectTransform.Of(Target().Node);
+ await Apply(SourceObjectEdits.PlanTransform(workspace, "crate", Target().Origin, source.Executions,
+ ObjectTransform.Identity, token, "m1", current));
+ AssertMatrix("crate");
+ Assert.Equal(Matrix4x4.Identity, GltfNodeEdits.Local((JsonObject)JsonNode.Parse(workspace.Read(file, token)!)!["nodes"]![index]!));
+ workspace.Undo(); workspace.Redo(); AssertMatrix("crate");
+ await workspace.SaveAsync(token);
+ AssertMatrix("crate");
+ var reopened = await SourceWorlds.LoadSceneAsync(fixture.Project, "m1", token: token);
+ Assert.Equal(GameZWriter.Write(source.World, token), GameZWriter.Write(reopened.World, token));
+
+ SourceObjectTarget Target() => new(workspace, "m1", source.World, source.World.Nodes.Single(n => n.Name == "crate"),
+ GameZWriter.NodeSlots(source.World, token).ToDictionary(p => p.Key, p => source.Provenance[p.Value]), source.Executions) { Write = source.WriteInstruction };
+ async Task Apply(SourceEditPlan plan)
+ {
+ workspace.Apply(plan.Label, plan.Changes.Select(c => (c.Relative, (byte[]?)c.Content)), token);
+ source = await SourceWorlds.LoadSceneAsync(fixture.Project, "m1", workspace.Overlay(), token);
+ }
+ void AssertMatrix(string name)
+ {
+ var node = JsonNode.Parse(workspace.Read(file, token)!)!["nodes"]!.AsArray().Single(n => n!["name"]!.GetValue() == name)!;
+ Assert.Equal(16, Assert.IsType(node["matrix"]).Count);
+ foreach (string field in new[] { "translation", "rotation", "scale" }) Assert.Null(node[field]);
+ }
+ }
+}
diff --git a/tests/zStudio.Tests/SourceTransformUpdateTests.cs b/tests/zStudio.Tests/SourceTransformUpdateTests.cs
index 1301bede..25eaf6df 100644
--- a/tests/zStudio.Tests/SourceTransformUpdateTests.cs
+++ b/tests/zStudio.Tests/SourceTransformUpdateTests.cs
@@ -155,6 +155,9 @@ public async Task ReferencedTurretTransformAndHistoryMatchFullEvaluationWithoutR
async Task Check()
{
+ var node = JsonNode.Parse(workspace.Read("data/m2/models/m2.gltf", token)!)!["nodes"]![source.Provenance[slot].ModelNode]!;
+ Assert.Equal(16, Assert.IsType(node["matrix"]).Count);
+ foreach (string field in new[] { "translation", "rotation", "scale" }) Assert.Null(node[field]);
var previous = source;
var incremental = SourceWorlds.TryUpdateTransforms(previous, workspace.Overlay(), out string reason, token);
Assert.True(incremental != null, reason); source = incremental!;