Skip to content

Make packaging more solid #557

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
freezy merged 55 commits into from
Jun 26, 2026
Merged

Make packaging more solid #557

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
55 commits
Select commit Hold shift + click to select a range
467d908
export: Fix .vpe export.
freezy Apr 19, 2026
723e071
packaging: Add table metadata.
freezy Apr 19, 2026
8178549
packaging: Fix runtime package loading.
freezy Apr 19, 2026
08e6b12
packaging: Add abstraction layer to material export.
freezy Apr 20, 2026
c663c45
fix: Normal map encoding when loading during runtime.
freezy Apr 25, 2026
af4ee96
Move runtime HDRP conversion code to HDRP repo.
freezy Apr 25, 2026
44f7d8d
export: First migration toward a coherent GLB-based format.
freezy Apr 25, 2026
ceba272
packaging: Pack sidecar textures into single BLOB for faster loading.
freezy Apr 25, 2026
62a59be
packaging: Add some diagnostics.
freezy Apr 25, 2026
7362372
packaging: Disables MIPS for linear textures.
freezy Apr 25, 2026
8aeea8a
packaging: More cleanup.
freezy Apr 26, 2026
fed7efc
doc: Add first part of packaging documentation.
freezy Apr 26, 2026
371bdb4
doc: Update materials contract with HDRP documentation links.
freezy Apr 26, 2026
cb526dd
packaging: Make loading async with progress indicator.
freezy Apr 26, 2026
f2f07cc
packaging: Add various missing material and light props to the .vpe f…
freezy May 10, 2026
eb52415
packaging: Extend shader support with rubber, metal and dmd.
freezy May 13, 2026
4699c4f
doc: Align packaging doc.
freezy May 13, 2026
0e96788
packaging: Add compress options.
freezy May 13, 2026
2233a05
packaging: Add missing packables.
freezy May 14, 2026
60d749f
packaging: Add screenshot generator.
freezy May 16, 2026
dc082ff
packaging: More screenshot tweaks.
freezy May 16, 2026
5c194bd
packaging: Remove transparent background code.
freezy May 16, 2026
0ad6faf
packaging: Simplify screenshot generator.
freezy May 17, 2026
abf9431
packaging: Generate 3 screenshots.
freezy May 17, 2026
b105f82
packaging: Fix bulb rendering.
freezy May 17, 2026
0372f6a
packaging: Pick correct lights when screenshotting.
freezy May 17, 2026
79dd2a4
packaging: Deactivate bulb GameObjects for off-shot screenshots.
freezy May 29, 2026
6b9e027
light: Fix editor on/off toggle leaving bulbs dark
freezy May 29, 2026
a8059ef
packaging: Drive bulbs via LightComponent.Enabled in screenshots
freezy May 29, 2026
595dd89
packaging: Let HDRP settle lamp state between screenshot shots
freezy May 29, 2026
2cb6b17
packaging: Bundle screenshots and add cabinet/backbox markers
freezy May 29, 2026
077e4e9
packaging: Add table crop-bounds sidecar to screenshots
freezy May 29, 2026
678868f
packaging: Bundle backglass image and switch screenshots to jpg.
freezy Jun 12, 2026
ac25241
packaging: Ship cooked GPU textures and parallelize package load
freezy Jun 12, 2026
27c2680
packaging: Switch to lossless source textures with local player cook
freezy Jun 12, 2026
b85497e
packaging: Add materials-only import and tune progress weights
freezy Jun 12, 2026
24cbe45
packaging: Formalize .vpe format with manifest and node IDs.
freezy Jun 12, 2026
b65b4cc
packaging: Drop GPU normal repack shader, AG-pack on CPU
freezy Jun 13, 2026
79e1676
packaging: GPU compute repack for normal maps during cook.
freezy Jun 13, 2026
5a1925a
packaging: Add optional zstd compression to texture cache.
freezy Jun 13, 2026
3abfe4a
packaging: Async export with cancelable progress bar
freezy Jun 13, 2026
286cf9b
packaging: Drop libvips per-call lock, rely on main-thread init
freezy Jun 13, 2026
5b6ce73
packaging: Expose screenshot aspect ratio in table metadata
freezy Jun 14, 2026
5a9325d
input: Allow host app to override native input bindings.
freezy Jun 14, 2026
290103a
packaging: Note glTF 2.1 uid as future replacement for vpeId
freezy Jun 14, 2026
f81bdfd
simulation: Drop input events while paused to keep menu exclusive
freezy Jun 14, 2026
30b7932
simulation: Drop native input events while app window isn't focused
freezy Jun 14, 2026
0c4a2a8
rendering: Add VpeGraphics bridge for runtime SRP settings.
freezy Jun 14, 2026
6ec8192
light: Access shadowRadius/shadowAngle via reflection for SRP compat
freezy Jun 14, 2026
a7eea4b
packaging: Add fabric/silk material profile and HDRP hint fields.
freezy Jun 15, 2026
db37def
packaging: Filter expected glTF shader-missing warnings at runtime.
freezy Jun 15, 2026
aec3e9c
doc: Document shader variant capture for HDRP player builds.
freezy Jun 15, 2026
0223170
doc: Update packaging guide for source textures and cook cache.
freezy Jun 15, 2026
5ad8bb1
packaging: Pack invisible primitive collider meshes separately.
freezy Jun 15, 2026
03e35b1
unity: Upgrade to v6.5
freezy Jun 26, 2026
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
167 changes: 84 additions & 83 deletions CHANGELOG.md
View file
Open in desktop

Large diffs are not rendered by default.

90 changes: 45 additions & 45 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,45 @@
# How to Contribute
You want to contribute to VPE? Awesome! Here are a few things you should know.
## Submitting Changes
We rarely commit to master directly. Instead, we open [pull requests](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/about-pull-requests)
and let our peers review the code before it gets merged.
- We [rebase](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) our commits to master, so the commit history stays linear.
- When a PR is about user-facing changes, we [update the documentation](https://github.com/freezy/VisualPinball.Engine/wiki/Documentation#bigger-changes-or-new-content).
- If a PR contains notable changes, we also update the [changelog](CHANGELOG.md). Add your entry to the top of the appropriate section.
- We try to prefix our commit messages with a word that quickly tells the reader where the change happened. Examples are `editor`, `doc`, `<component-name>`, etc.
- Changes that touch the core project should be unit-tested.
### Unity License Setup For Automated Testing
It's preferred to make the automated tests run when creating your PR. Since Unity needs a license key (which can be obtained with a free account), you'll need to configure your fork to use the correct secrets. You will need to use a Personal license and request a key on behalf of GitHub:
1. Run the `License` workflow by clicking the `Run workflow` button in the `Actions` tab. When the workflow completes, download and unzip the `Unity_v2021.3.0f1.alf` artifact.
2. Visit [license.unity3d.com](https://license.unity3d.com), sign in, and upload the `Unity_v2021.3.0f1.alf` file.
3. You should now receive your license file (`Unity_v2021.x.ulf`) as a download.
4. Open `Github` > `<Your repository>` > `Settings` > `Secrets`
- Create the following secret:
- `UNITY_LICENSE` - (Copy the contents of the `Unity_v2021.x.ulf` license file here)
5. Delete the `License` workflow run by selecting `Delete workflow run` in the `...` menu.
## Code Style
We aren't too picky about code style. Just start reading our code and you'll get the hang of it. There
are a few rules though:
- We mostly use [C#'s naming conventions](https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/naming-guidelines).
That said, for `MonoBehaviours` we sometimes also use [Unity's style](https://github.com/raywenderlich/c-sharp-style-guide)
that puts field names in camel case.
- For the Unity projects, we use one namespace per project. For the core project, it's a namespace per folder.
- We use tabs for indentation.
- This is open source software. Consider the people who will read your code, and make it look nice for them. It's sort of like
driving a car: Perhaps you love doing donuts when you're alone, but with passengers the goal is to make the ride as smooth
as possible.
## Talk to us!
Have a look at the [VPF thread](https://www.vpforums.org/index.php?showtopic=43651) if you have any question. We also have a Discord
server for internal discussion.
# How to Contribute

You want to contribute to VPE? Awesome! Here are a few things you should know.

## Submitting Changes

We rarely commit to master directly. Instead, we open [pull requests](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/about-pull-requests)
and let our peers review the code before it gets merged.

- We [rebase](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) our commits to master, so the commit history stays linear.
- When a PR is about user-facing changes, we [update the documentation](https://github.com/freezy/VisualPinball.Engine/wiki/Documentation#bigger-changes-or-new-content).
- If a PR contains notable changes, we also update the [changelog](CHANGELOG.md). Add your entry to the top of the appropriate section.
- We try to prefix our commit messages with a word that quickly tells the reader where the change happened. Examples are `editor`, `doc`, `<component-name>`, etc.
- Changes that touch the core project should be unit-tested.

### Unity License Setup For Automated Testing

It's preferred to make the automated tests run when creating your PR. Since Unity needs a license key (which can be obtained with a free account), you'll need to configure your fork to use the correct secrets. You will need to use a Personal license and request a key on behalf of GitHub:

1. Run the `License` workflow by clicking the `Run workflow` button in the `Actions` tab. When the workflow completes, download and unzip the `Unity_v6000.5.0f1.alf` artifact.
2. Visit [license.unity3d.com](https://license.unity3d.com), sign in, and upload the `Unity_v6000.5.0f1.alf` file.
3. You should now receive your license file (`Unity_v6000.x.ulf`) as a download.
4. Open `Github` > `<Your repository>` > `Settings` > `Secrets`
- Create the following secret:
- `UNITY_LICENSE` - (Copy the contents of the `Unity_v6000.x.ulf` license file here)
5. Delete the `License` workflow run by selecting `Delete workflow run` in the `...` menu.

## Code Style

We aren't too picky about code style. Just start reading our code and you'll get the hang of it. There
are a few rules though:

- We mostly use [C#'s naming conventions](https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/naming-guidelines).
That said, for `MonoBehaviours` we sometimes also use [Unity's style](https://github.com/raywenderlich/c-sharp-style-guide)
that puts field names in camel case.
- For the Unity projects, we use one namespace per project. For the core project, it's a namespace per folder.
- We use tabs for indentation.
- This is open source software. Consider the people who will read your code, and make it look nice for them. It's sort of like
driving a car: Perhaps you love doing donuts when you're alone, but with passengers the goal is to make the ride as smooth
as possible.

## Talk to us!

Have a look at the [VPF thread](https://www.vpforums.org/index.php?showtopic=43651) if you have any question. We also have a Discord
server for internal discussion.
110 changes: 58 additions & 52 deletions VisualPinball.Engine/VisualPinball.Engine.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<PropertyGroup>
<TargetFramework>netstandard2.1</TargetFramework>
<!-- https://github.com/dotnet/sdk/issues/747#issuecomment-518156718 -->
<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
Expand All @@ -12,11 +12,11 @@
<InformationalVersion>0.1.0.0</InformationalVersion>
<LangVersion>9.0</LangVersion>
<AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
<PackageProjectUrl>https://visualpinball.org</PackageProjectUrl>
<PackageIcon>icon.png</PackageIcon>
<PackageLicenseFile>LICENSE</PackageLicenseFile>
<VisualPinballNativeInputVersion>0.0.4</VisualPinballNativeInputVersion>
</PropertyGroup>
<PackageProjectUrl>https://visualpinball.org</PackageProjectUrl>
<PackageIcon>icon.png</PackageIcon>
<PackageLicenseFile>LICENSE</PackageLicenseFile>
<VisualPinballNativeInputVersion>0.0.4</VisualPinballNativeInputVersion>
</PropertyGroup>
<!-- Give an initial value based on the operating system where it's currently running on -->
<PropertyGroup Condition="'$(RuntimeIdentifier)' == ''">
<RuntimeIdentifier Condition="$([MSBuild]::IsOSPlatform('Windows')) And '$(PlatformTarget)' != 'x86'">win-x64</RuntimeIdentifier>
Expand All @@ -28,18 +28,22 @@
<None Remove="**/*.meta" Visible="false" />
<None Remove="obj\**" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="NLog" Version="4.7.15" />
<PackageReference Include="SharpZipLib" Version="1.4.2" />
<PackageReference Include="OpenMcdf" Version="2.4.1" />
<PackageReference Include="OpenMcdf.Extensions" Version="2.4.0" />
<PackageReference Include="NetMiniZ" Version="1.4.0-preview.2" />
<PackageReference Include="NetMiniZ.Native" Version="1.4.0" />
<PackageReference Include="NetVips" Version="2.1.0" />
<PackageReference Include="NetVips.Native" Version="8.12.2" />
<!-- NativeInput is consumed exclusively through NuGet (not from a checked-out native source tree). -->
<PackageReference Include="VisualPinball.NativeInput" Version="$(VisualPinballNativeInputVersion)" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="NLog" Version="4.7.15" />
<PackageReference Include="SharpZipLib" Version="1.4.2" />
<PackageReference Include="OpenMcdf" Version="2.4.1" />
<PackageReference Include="OpenMcdf.Extensions" Version="2.4.0" />
<PackageReference Include="NetMiniZ" Version="1.4.0-preview.2" />
<PackageReference Include="NetMiniZ.Native" Version="1.4.0" />
<PackageReference Include="NetVips" Version="2.1.0" />
<PackageReference Include="NetVips.Native" Version="8.12.2" />
<!-- Off-main-thread image decoding for the runtime texture cook. -->
<PackageReference Include="StbImageSharp" Version="2.30.15" />
<!-- NativeInput is consumed exclusively through NuGet (not from a checked-out native source tree). -->
<PackageReference Include="VisualPinball.NativeInput" Version="$(VisualPinballNativeInputVersion)" />
<!-- Managed zstd (pure C#, no native dep) for optional texture-cache compression. -->
<PackageReference Include="ZstdSharp.Port" Version="0.8.8" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\VisualPinball.Resources\VisualPinball.Resources.csproj" />
</ItemGroup>
Expand All @@ -49,16 +53,16 @@
<ItemGroup>
<EmbeddedResource Remove="obj\**" />
</ItemGroup>
<ItemGroup>
<None Include="..\LICENSE">
<PackagePath></PackagePath>
<Pack>true</Pack>
</None>
<None Include="..\nuget\icon.png">
<PackagePath></PackagePath>
<Pack>true</Pack>
</None>
</ItemGroup>
<ItemGroup>
<None Include="..\LICENSE">
<PackagePath></PackagePath>
<Pack>true</Pack>
</None>
<None Include="..\nuget\icon.png">
<PackagePath></PackagePath>
<Pack>true</Pack>
</None>
</ItemGroup>
<Target Name="PluginsDeploy" AfterTargets="AfterBuild">
<ItemGroup>
<Plugins Include="$(OutDir)NLog.dll" />
Expand All @@ -67,34 +71,36 @@
<Plugins Include="$(OutDir)NetMiniZ.dll" />
<Plugins Include="$(OutDir)NetVips.dll" />
<Plugins Include="$(OutDir)ICSharpCode.SharpZipLib.dll" />
<Plugins Include="$(OutDir)StbImageSharp.dll" />
<Plugins Include="$(OutDir)ZstdSharp.dll" />
<Plugins Include="$(OutDir)System.Buffers.dll" />
</ItemGroup>
<ItemGroup Condition="'$(RuntimeIdentifier)' == 'win-x64' Or '$(RuntimeIdentifier)' == 'win-x86' Or '$(RuntimeIdentifier)' == 'osx' Or '$(RuntimeIdentifier)' == 'linux-x64'">
<Plugins Include="$(NuGetPackageRoot)\netminiz.native.$(RuntimeIdentifier)\1.4.0\runtimes\$(RuntimeIdentifier)\native\*" />
</ItemGroup>
<ItemGroup Condition="'$(RuntimeIdentifier)' == 'win-x64' Or '$(RuntimeIdentifier)' == 'win-x86' Or '$(RuntimeIdentifier)' == 'linux-x64'">
<Plugins Include="$(NuGetPackageRoot)\netvips.native.$(RuntimeIdentifier)\8.12.2\runtimes\$(RuntimeIdentifier)\native\*" />
</ItemGroup>
<ItemGroup Condition="'$(RuntimeIdentifier)' == 'win-x64' Or '$(RuntimeIdentifier)' == 'win-x86'">
<!-- Pull native binaries from the restored NuGet package and deploy into Unity Plugins. -->
<Plugins Include="$(NuGetPackageRoot)\visualpinball.nativeinput\$(VisualPinballNativeInputVersion)\runtimes\$(RuntimeIdentifier)\native\VisualPinball.NativeInput.dll" />
</ItemGroup>
<ItemGroup Condition="'$(RuntimeIdentifier)' == 'linux-x64'">
<Plugins Include="$(NuGetPackageRoot)\visualpinball.nativeinput\$(VisualPinballNativeInputVersion)\runtimes\linux-x64\native\libVisualPinball.NativeInput.so" />
</ItemGroup>
<Message Text="PluginsDeploy: @(Plugins)" />
<Copy SourceFiles="@(Plugins)" DestinationFolder="..\VisualPinball.Unity\Plugins\$(RuntimeIdentifier)\" SkipUnchangedFiles="true" />
</Target>
<ItemGroup Condition="'$(RuntimeIdentifier)' == 'win-x64' Or '$(RuntimeIdentifier)' == 'win-x86' Or '$(RuntimeIdentifier)' == 'linux-x64'">
<Plugins Include="$(NuGetPackageRoot)\netvips.native.$(RuntimeIdentifier)\8.12.2\runtimes\$(RuntimeIdentifier)\native\*" />
</ItemGroup>
<ItemGroup Condition="'$(RuntimeIdentifier)' == 'win-x64' Or '$(RuntimeIdentifier)' == 'win-x86'">
<!-- Pull native binaries from the restored NuGet package and deploy into Unity Plugins. -->
<Plugins Include="$(NuGetPackageRoot)\visualpinball.nativeinput\$(VisualPinballNativeInputVersion)\runtimes\$(RuntimeIdentifier)\native\VisualPinball.NativeInput.dll" />
</ItemGroup>
<ItemGroup Condition="'$(RuntimeIdentifier)' == 'linux-x64'">
<Plugins Include="$(NuGetPackageRoot)\visualpinball.nativeinput\$(VisualPinballNativeInputVersion)\runtimes\linux-x64\native\libVisualPinball.NativeInput.so" />
</ItemGroup>
<Message Text="PluginsDeploy: @(Plugins)" />
<Copy SourceFiles="@(Plugins)" DestinationFolder="..\VisualPinball.Unity\Plugins\$(RuntimeIdentifier)\" SkipUnchangedFiles="true" />
</Target>
<!-- NetVips does not have dual architecture binaries for osx -->
<Target Name="PluginsDeploy_osx" AfterTargets="PluginsDeploy" Condition="'$(RuntimeIdentifier)' == 'osx'">
<ItemGroup>
<Plugins_x64 Include="$(NuGetPackageRoot)\netvips.native.osx-x64\8.12.2\runtimes\osx-x64\native\*" />
<Plugins_arm64 Include="$(NuGetPackageRoot)\netvips.native.osx-arm64\8.12.2\runtimes\osx-arm64\native\*" />
<Plugins_x64 Include="$(NuGetPackageRoot)\visualpinball.nativeinput\$(VisualPinballNativeInputVersion)\runtimes\osx-x64\native\libVisualPinball.NativeInput.dylib" />
<Plugins_arm64 Include="$(NuGetPackageRoot)\visualpinball.nativeinput\$(VisualPinballNativeInputVersion)\runtimes\osx-arm64\native\libVisualPinball.NativeInput.dylib" />
</ItemGroup>
<Message Text="PluginsDeploy_osx: @(Plugins_x64) @(Plugins_arm64)" />
<Copy SourceFiles="@(Plugins_x64)" DestinationFolder="..\VisualPinball.Unity\Plugins\osx\x64\" SkipUnchangedFiles="true" />
<Copy SourceFiles="@(Plugins_arm64)" DestinationFolder="..\VisualPinball.Unity\Plugins\osx\arm64\" SkipUnchangedFiles="true" />
</Target>
</Project>
<ItemGroup>
<Plugins_x64 Include="$(NuGetPackageRoot)\netvips.native.osx-x64\8.12.2\runtimes\osx-x64\native\*" />
<Plugins_arm64 Include="$(NuGetPackageRoot)\netvips.native.osx-arm64\8.12.2\runtimes\osx-arm64\native\*" />
<Plugins_x64 Include="$(NuGetPackageRoot)\visualpinball.nativeinput\$(VisualPinballNativeInputVersion)\runtimes\osx-x64\native\libVisualPinball.NativeInput.dylib" />
<Plugins_arm64 Include="$(NuGetPackageRoot)\visualpinball.nativeinput\$(VisualPinballNativeInputVersion)\runtimes\osx-arm64\native\libVisualPinball.NativeInput.dylib" />
</ItemGroup>
<Message Text="PluginsDeploy_osx: @(Plugins_x64) @(Plugins_arm64)" />
<Copy SourceFiles="@(Plugins_x64)" DestinationFolder="..\VisualPinball.Unity\Plugins\osx\x64\" SkipUnchangedFiles="true" />
<Copy SourceFiles="@(Plugins_arm64)" DestinationFolder="..\VisualPinball.Unity\Plugins\osx\arm64\" SkipUnchangedFiles="true" />
</Target>
</Project>
Loading
Loading