Skip to content

Add PlayCanvas SOG v2 import and runtime loading#40

Draft
andybak wants to merge 4 commits into
wuyize25:mainfrom
icosa-mirror:pr/sog-support
Draft

Add PlayCanvas SOG v2 import and runtime loading#40
andybak wants to merge 4 commits into
wuyize25:mainfrom
icosa-mirror:pr/sog-support

Conversation

@andybak

@andybak andybak commented Jul 16, 2026

Copy link
Copy Markdown

This PR adds support for PlayCanvas SOG v2 bundled .sog files. A supported file is
a ZIP bundle containing meta.json and lossless WebP property images. The loader
decodes the SOG properties into the package's existing Spark or Uncompressed asset
representations, so rendering uses the normal gsplat pipelines after loading.

SOG files can be imported by placing them in a Unity project's Assets directory.
They can also be loaded at runtime by creating GsplatAssetSog or
GsplatAssetSogUncompressed, calling LoadFromSog, and assigning the resulting asset
to a GsplatRenderer.

Main changes

  • Register .sog with GsplatImporter.
  • Add Spark and Uncompressed SOG asset implementations.
  • Parse SOG v2 metadata and property-image layout.
  • Decode lossless WebP images through unity.webp/libwebp.
  • Support SOG SH bands 0 through 3.
  • Apply the existing source-coordinate conversion options.
  • Add editor caching for packed SOG imports. The cache key includes file metadata,
    compression mode, source coordinates, and decoder version.
  • Add runtime loading using the same decode path.
  • Document editor and runtime usage.
  • Add com.netpyoung.webp version 0.3.22 as a package dependency.

Limitations and compatibility

  • Supports bundled SOG v2 ZIP files, not directory-style SOG datasets.
  • Runtime loading performs ZIP parsing, JSON parsing, WebP decoding, and splat packing
    on the device.
  • Runtime support depends on unity.webp providing a native libwebp plugin for the
    target platform. Android is included in the intended supported platforms.
  • SH degree 4 is not supported for SOG; supported bands are 0 through 3.

Suggested testing

  • Import representative SOG v2 bundles with SH bands 0, 1, 2, and 3.
  • Test Spark and Uncompressed import modes.
  • Compare bounds, colors, positions, scales, rotations, and SH appearance against a
    reference SOG renderer.
  • Reimport the same file and verify the editor cache path.
  • Change compression mode and source coordinates and verify cache invalidation.
  • Load a SOG bundle at runtime and assign it to a renderer.
  • Test malformed ZIPs, missing meta.json, missing property images, invalid metadata,
    and unsupported SOG versions.
  • Test each intended player platform, especially Android, to verify native WebP
    plugin availability.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant