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
20 changes: 14 additions & 6 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -39,10 +39,18 @@ jobs:
run: ./tools/publish.ps1
- name: Validate RECOIL Blender round trip
run: |
$archive = Join-Path $env:RUNNER_TEMP 'blender-5.2.2-windows-x64.zip'
Invoke-WebRequest 'https://download.blender.org/release/Blender5.2/blender-5.2.2-windows-x64.zip' -OutFile $archive
if ((Get-FileHash -LiteralPath $archive -Algorithm SHA256).Hash -ne '3849D17A682CBA006075AAA3F3597ECB5C9C30EC31035B2E092C53E40679B535') { throw 'Blender archive checksum mismatch' }
Expand-Archive -LiteralPath $archive -DestinationPath (Join-Path $env:RUNNER_TEMP 'blender')
$env:ZSTUDIO_BLENDER = Join-Path $env:RUNNER_TEMP 'blender/blender-5.2.2-windows-x64/blender.exe'
$env:ZSTUDIO_BLENDER_HELPER = Join-Path $env:GITHUB_WORKSPACE 'artifacts/zStudio-win-x64/zStudio.exe'
dotnet test tests/zStudio.Tests -c Release --no-build --filter 'FullyQualifiedName~BlenderGraphTests.InstalledBlenderRoundTrip'
$versions = @(
@{ Version = '5.2.2'; Series = '5.2'; SHA256 = '3849D17A682CBA006075AAA3F3597ECB5C9C30EC31035B2E092C53E40679B535' },
@{ Version = '5.3.0'; Series = '5.3'; SHA256 = '3AC567A63D59D9934F7B9213BFB27BA05760E1FB366F8F55C381573EC3EABFA8' }
)
foreach ($blender in $versions) {
$name = "blender-$($blender.Version)-windows-x64"
$archive = Join-Path $env:RUNNER_TEMP "$name.zip"
Invoke-WebRequest "https://download.blender.org/release/Blender$($blender.Series)/$name.zip" -OutFile $archive
if ((Get-FileHash -LiteralPath $archive -Algorithm SHA256).Hash -ne $blender.SHA256) { throw "Blender $($blender.Version) archive checksum mismatch" }
Expand-Archive -LiteralPath $archive -DestinationPath (Join-Path $env:RUNNER_TEMP 'blender')
$env:ZSTUDIO_BLENDER = Join-Path $env:RUNNER_TEMP "blender/$name/blender.exe"
dotnet test tests/zStudio.Tests -c Release --no-build --filter 'FullyQualifiedName~BlenderGraphTests.InstalledBlenderRoundTrip'
if ($LASTEXITCODE -ne 0) { throw "Blender $($blender.Version) round trip failed" }
}
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.3 — 2026-11-12

- The Blender extension now installs on Blender 5.3 and newer, retaining the 5.2 minimum without an upper version cutoff.

## 0.12.2 — 2026-11-11

- Starting several zStudio instances together no longer fails when WPF libraries are first extracted.
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.2</Version>
<Version>0.12.3</Version>
</PropertyGroup>
</Project>
4 changes: 2 additions & 2 deletions 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.2](https://github.com/Vorta/zStudio/releases/tag/v0.12.2)** for Windows x64.
Download **[zStudio v0.12.3](https://github.com/Vorta/zStudio/releases/tag/v0.12.3)** 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 Expand Up @@ -41,7 +41,7 @@ zStudio's **Help** menu opens these guides as they are for the installed version

## Blender

The download includes the **zStudio RECOIL** extension for Blender 5.2 LTS (`zStudio-Blender-extension-<version>.zip`, beside `zStudio.exe`). **Tools → Edit in Blender…** checks out a model with every file it references; **Tools → Update from Blender export…** applies the Blender export as one undoable edit. See the [extension guide](blender/zstudio_recoil/README.md).
The download includes the **zStudio RECOIL** extension for Blender 5.2 or newer (`zStudio-Blender-extension-<version>.zip`, beside `zStudio.exe`). **Tools → Edit in Blender…** checks out a model with every file it references; **Tools → Update from Blender export…** applies the Blender export as one undoable edit. See the [extension guide](blender/zstudio_recoil/README.md).

## AI agents (MCP)

Expand Down
4 changes: 2 additions & 2 deletions blender/zstudio_recoil/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

New glTF files use `extras.zstudio`. Core and the Blender extension also read legacy `extras.recoil`; when both keys are present, `zstudio` wins without merging. Import does not rewrite source files. Blender operator IDs, property handles, saved-state names and the extension ID remain unchanged.

This extension imports and exports zStudio source glTF graphs in **Blender 5.2 LTS on Windows x64**. It uses Blender's glTF importer and exporter and the zStudio format library through a windowless helper; it needs no zStudio window, MCP access or network connection.
This extension imports and exports zStudio source glTF graphs in **Blender 5.2 or newer on Windows x64**. It uses Blender's glTF importer and exporter and the zStudio format library through a windowless helper; it needs no zStudio window, MCP access or network connection.

Both RECOIL and MechWarrior 3 source projects use this workflow. MW3 world, mech and lab graphs retain their native node words, corner colours, material switches and cycles. The source game and library member are fixed identities; an existing base mech's named top-level root must stay available to AIV actors. Use fresh version-3 checkouts and the matching extension/helper (graph protocol 2); source glTF remains format 4. The existing RECOIL menu and property names refer to these shared tools.

Expand Down Expand Up @@ -56,7 +56,7 @@ MCP: `zstudio_source_blender_checkout`, `zstudio_source_blender_checkouts`, `zst

- To continue editing an export in a new Blender session, import its root glTF from the complete generation folder; keep the dependencies and `recoil-export.json` together. This starts a fresh import, without inheriting the previous session's update history.
- Ordinary translation-only edits retain the original matrix or TRS representation and untouched transform values. Blender still computes edits with float precision: an inverse move is not guaranteed to restore every source number at every coordinate, particularly small fractional coordinates after a large move.
- Blender 5.2.x, `.gltf` files with external PNG textures, and the zStudio source format's rules for materials, names, transforms and model sizes. Give new surfaces a material with Metallic set to zero.
- Blender 5.2 or newer (no upper version limit), `.gltf` files with external PNG textures, and the zStudio source format's rules for materials, names, transforms and model sizes. Give new surfaces a material with Metallic set to zero.
- Missing images show as magenta checkers and never become source textures; replace one with an actual image to export it.
- A graph holds at most 4,096 files and 512 MiB of source data; cyclic or escaping references are refused.
- Blender's view is an editing view, not the game's collision, crater or zone queries. A pickup's collision volume (`bvol`) is hidden by its material, so it still counts in framing and shows in wireframe; keep it, because the game registers a pickup only when its model has one.
Expand Down
3 changes: 1 addition & 2 deletions blender/zstudio_recoil/blender_manifest.toml
Original file line number Diff line number Diff line change
@@ -1,14 +1,13 @@
schema_version = "1.0.0"
id = "zstudio_recoil"
version = "0.12.2"
version = "0.12.3"
name = "zStudio RECOIL"
tagline = "Edit RECOIL glTF models, linked worlds, flags and zones"
maintainer = "Vorta"
type = "add-on"
website = "https://github.com/Vorta/zStudio"
tags = ["Import-Export"]
blender_version_min = "5.2.0"
blender_version_max = "5.3.0"
license = ["SPDX:MIT"]
platforms = ["windows-x64"]
[permissions]
Expand Down
2 changes: 1 addition & 1 deletion docs/agents/sources.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,7 +170,7 @@ Models are glTF 2.0 with external PNG textures; engine attributes live in `extra

## Blender extension

- The bundled **zStudio RECOIL** extension (Blender 5.2 LTS, Windows x64) supports both source games through a windowless format helper (no MCP). **Tools → Edit in Blender…** checks out a model or master map's complete reference graph from the current workspace into `.zstudio/export`; **Export RECOIL glTF** writes a completed generation into the outbox; **Tools → Update from Blender export…** (`zstudio_source_blender_update`) validates the generation and hashes, remaps placement profiles and applies one undoable transaction. Checkout version 3 and graph protocol 2 bind each physical file's game and native library member; changing those identities is refused. Physical file identities, relative references, flags, zones, face assignments, load-root values and engine properties stay embedded in glTF. Native corner colours and node metadata remain part of the same graph.
- The bundled **zStudio RECOIL** extension (Blender 5.2 or newer, Windows x64) supports both source games through a windowless format helper (no MCP). **Tools → Edit in Blender…** checks out a model or master map's complete reference graph from the current workspace into `.zstudio/export`; **Export RECOIL glTF** writes a completed generation into the outbox; **Tools → Update from Blender export…** (`zstudio_source_blender_update`) validates the generation and hashes, remaps placement profiles and applies one undoable transaction. Checkout version 3 and graph protocol 2 bind each physical file's game and native library member; changing those identities is refused. Physical file identities, relative references, flags, zones, face assignments, load-root values and engine properties stay embedded in glTF. Native corner colours and node metadata remain part of the same graph.
- Consent is required for source edits since checkout and shared texture conflicts; it cannot force invalid metadata. An update may replace earlier updates' results only when its export descends from them (same import, the same `.blend`'s recorded generations); otherwise it is a conflict or refused. Ordinary Blender glTF exports and flattened checkouts are not accepted. Edited polygons keep boundaries only where surface, normals, UVs, morphs and placement zones survive; a split face takes the nearest assigned face's placement zones. Do not promise ordinary Blender import/export preserves the hierarchy.

## Compare worlds
Expand Down
2 changes: 1 addition & 1 deletion docs/agents/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Tests that need data return early unless their variable is set, so the plain sui
| `ZSTUDIO_DEMO_CORPUS` | a RECOIL demo's `zbd` folder (July or August 1998, version-13 worlds) | every version-13 world reads without diagnostics and every rebuilt node box gives back the stored corners |
| `ZSTUDIO_MW3_SOURCE_PROJECT` | a reconstructed MW3 source project, read only | retail C1 valve startup/range, manual reaction and timer proof |
| `ZSTUDIO_SOURCE_PROJECT` | a reconstructed project (read only; `data` and `gamegen` are copied to a temporary folder) | the terrain conversion corpus test without reconstructing first |
| `ZSTUDIO_BLENDER` | Blender 5.2.x executable | `BlenderGraphTests`: installs the packaged extension in a factory-startup background Blender with a fresh user-resource folder, round-trips shared references, flags, zones and geometry, saves and reopens a `.blend` with its baseline cache missing; never touches the user's Blender preferences or windows |
| `ZSTUDIO_BLENDER` | Blender 5.2 or newer executable (CI uses 5.2.2 and 5.3.0) | `BlenderGraphTests`: installs the packaged extension in a factory-startup background Blender with a fresh user-resource folder, round-trips shared references, flags, zones and geometry, saves and reopens a `.blend` with its baseline cache missing; never touches the user's Blender preferences or windows |
| `ZSTUDIO_BLENDER_HELPER` | the package's `zStudio.exe`, with `zStudio-Blender-extension-<version>.zip` beside it (required with `ZSTUDIO_BLENDER`); locally an extracted copy, not `artifacts/zStudio-win-x64` | the helper the extension calls; run after packaging |
| `ZSTUDIO_BLENDER_SOURCE` | any value | `tools/blender-roundtrip.py` loads the extension from `blender/` instead of the packaged ZIP |
| `ZSTUDIO_INSPECTION_CAPTURE` | an output folder | screenshots from the Desktop inspection checks |
Expand Down
Loading