Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion Directory.Build.props
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,6 @@
<Description>Advanced viewer and editor for Zipper Interactive's ZBD files</Description>
<RepositoryUrl>https://github.com/Vorta/zStudio</RepositoryUrl>
<RepositoryType>git</RepositoryType>
<Version>0.12.4</Version>
<Version>0.12.5</Version>
</PropertyGroup>
</Project>
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion blender/zstudio_recoil/blender_manifest.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
2 changes: 2 additions & 0 deletions docs/map-editor.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
13 changes: 8 additions & 5 deletions src/zStudio.Core/Sources/GltfNodeEdits.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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)
{
Expand Down Expand Up @@ -520,15 +520,18 @@ private static void SetExplicitZone(JsonObject engine, uint zone)
/// none). A malformed transform is refused as the reader refuses it (<see cref="GltfDocument.LocalTransform"/>).
/// </summary>
public static Matrix4x4 Local(JsonObject node) => GltfDocument.LocalTransform(node) ?? Matrix4x4.Identity;
/// <summary>Sets a node's local transform, as translation, rotation and scale when it decomposes, otherwise as a matrix.</summary>
public static void SetLocal(JsonObject node, Matrix4x4 m)
/// <summary>Sets a node's local transform, keeping an authored matrix; otherwise uses TRS when it decomposes.</summary>
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 =>
{
Expand Down
6 changes: 5 additions & 1 deletion src/zStudio.Core/Sources/SourceObjectEdits.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
12 changes: 5 additions & 7 deletions tests/zStudio.Desktop.Tests/SourceEditingMcpChecks.cs
Original file line number Diff line number Diff line change
Expand Up @@ -817,6 +817,10 @@ static System.Windows.Controls.TextBox PositionField(SceneInspectionCard card, s
.OfType<System.Windows.Controls.TextBox>().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<string>() == "tur_101")!;
Assert.Equal(16, Assert.IsType<JsonArray>(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!;
Expand Down Expand Up @@ -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");
}
Expand Down
78 changes: 78 additions & 0 deletions tests/zStudio.Tests/SourceMatrixPreservationTests.cs
Original file line number Diff line number Diff line change
@@ -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<string>() == "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<string>() == name)!;
Assert.Equal(16, Assert.IsType<JsonArray>(node["matrix"]).Count);
foreach (string field in new[] { "translation", "rotation", "scale" }) Assert.Null(node[field]);
}
}
}
3 changes: 3 additions & 0 deletions tests/zStudio.Tests/SourceTransformUpdateTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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<JsonArray>(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!;
Expand Down