ResonitePackage: Difference between revisions

From Resonite Wiki
No edit summary
No edit summary
 
(12 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{UnreleasedFeature}}
{{Note|ResonitePackage files are not supported by Unity! This is not an intended application of this feature.|information}}


'''ResonitePackage''' is an upcoming package format allowing users to share and import pre-setup avatars and objects easily<ref>Frooxius' comment on the package format on GitHub: https://github.com/Yellow-Dog-Man/Resonite-Issues/issues/950#issuecomment-2153588542</ref>.
'''ResonitePackage''' is a package format allowing users to share and import pre-setup avatars and objects easily<ref>Frooxius' comment on the package format on GitHub: https://github.com/Yellow-Dog-Man/Resonite-Issues/issues/950#issuecomment-2153588542</ref>.


== Goals ==
== Goals ==
Line 7: Line 7:
* Allow creators to share creations outside of Resonite
* Allow creators to share creations outside of Resonite
** For example an avatar creator adding a ResonitePackage version of their avatar
** For example an avatar creator adding a ResonitePackage version of their avatar
* Backup your content locally
** The package includes all the necessary assets for exported item without relying on the Resonite Cloud, making this a good option if you want to create local backups of your items


== Non-Goals ==
== Non-Goals ==
Line 14: Line 16:
* Compatibility with other VR Platforms
* Compatibility with other VR Platforms
** ResonitePackage files will not be suppoted by other VR Platforms
** ResonitePackage files will not be suppoted by other VR Platforms
* Offline Editing
** This is theoretically possible, but '''not''' one of the goals of this feature.
* Export from 3rd party tools
** While possible, the ResonitePackage contains Resonite's internal data formats, which are subject to change at any moment.
** The format is not designed to be easily built from scratch using 3rd party tools, so building those might prove challenging, since it'll require re-implementing a lot of Resonite's internal formats
** Best approach for this would be Unity SDK which is on our list of things to do: https://github.com/Yellow-Dog-Man/Resonite-Issues/issues/6
*** ResonitePackage could become part of the Unity SDK flow, where the SDK is used to build out and convert content to Resonite and then export it as ResonitePackage file
*** This is currently NOT implemented. We recommend upvoting the issue, which will allow us to prioritize it sooner.
== How to export ==
Exporting any item as .ResonitePackage is very easy!
# On the dash, click the "Files" tab
# Navigate to the directory you want to export your package to
# Grab and hold the item you want to export in world (grabbing a slot reference from inspector also works)
# While holding the item, click the green plus button in the Files tab (you can click it with your other hand)
# Export dialog will show up
# Select one of the "Resonite Package" options in the export dialog
# (optional) name the file in the Export dialog
# Click "Export"
The export might take some time depending on the size of the item. Once it's done, the dialog will disappear.


== Contents ==
== Contents ==
Line 22: Line 46:
** Meshes
** Meshes
** Videos
** Videos
** Fonts
** And others...
* Slot Hierarchies
* Slot Hierarchies
** Including Bones
** Including Bones
Line 29: Line 55:
All assets will be included explicitly, as a file within the package.
All assets will be included explicitly, as a file within the package.


== Variants ==
=== Variants ===
 
You can also optionally, export a ResonitePackage with all [[Asset_Variant|asset variants]] by selecting the (+variants) option during export.
 
This will result in a larger file size, but the object will load much more quickly when users import it. If the package is exported without variants, the user will compute the variants on their end after the package is imported, which can be CPU intensive.
 
== Permissions ==
As exporting a ResonitePackage is treated the same as exporting any other file, any regular export restrictions still work. This includes:
* Restricting certain roles from exporting in a world
* [[Component:SimpleAvatarProtection|SimpleAvatarProtection]] blocking export for objects you do not own.
 
=== Simple Avatar Protection handling ===
 
{{Note|It is recommended to review the <code>ReassignUserOnPackageImport</code> property on any important assets to make sure it is set correctly. It defaults to <code>True</code>
|danger}}
 
ResonitePackages have some custom handling for [[Component:SimpleAvatarProtection|SimpleAvatarProtection]].


You can also optionally, export a ResonitePackage with all [[Asset_Variant|asset variants]]. This will result in a larger file size though.
On '''import''':
# Resonite will notify each copy of [[Component:SimpleAvatarProtection|SimpleAvatarProtection]] found within the package that it is part of a package import.
# If the <code>ReassignUserOnPackageImport</code> property on the [[Component:SimpleAvatarProtection|SimpleAvatarProtection]] is set to <code>true</code>
## The User assigned to the [[Component:SimpleAvatarProtection|SimpleAvatarProtection]] will be set to the user who imported the package.
# If the <code>ReassignUserOnPackageImport</code> property on the [[Component:SimpleAvatarProtection|SimpleAvatarProtection]] is set to <code>false</code>
## The User assignment will be left alone.


== Naming ==
== Naming ==
The name was chosen as it was the most explicit (following in the steps of the Unity engine having the UnityPackage format), and as a way to advertise the platform<ref>Shifty's comment on the name: https://github.com/Yellow-Dog-Man/Resonite-Issues/issues/950#issuecomment-2148464652</ref><ref>Frooxius' comment on the name: https://github.com/Yellow-Dog-Man/Resonite-Issues/issues/950#issuecomment-2148476139</ref>.
The name was chosen as it was the most explicit (following in the steps of the Unity engine having the UnityPackage format), and as a way to advertise the platform<ref>Shifty's comment on the name: https://github.com/Yellow-Dog-Man/Resonite-Issues/issues/950#issuecomment-2148464652</ref><ref>Frooxius' comment on the name: https://github.com/Yellow-Dog-Man/Resonite-Issues/issues/950#issuecomment-2148476139</ref>.
== Tutorials ==
<youtube>rpsyT-FPTCg</youtube>
== Internals ==
ResonitePackage file is essentially a ZIP archive, containing a number of files:
* R-Main.record
** This contains the main asset (typically the object or main world that should be loaded)
** Contains various metadata about the object - name, description, tags
** Also contains manifest of assets that this record and main object represents and needs
** This is the same record that's used in Resonite's local and cloud storage to represent items, objects and worlds
* *.record files
** Any additional records that the item from the main world might be referencing.
** This generally only applies to worlds that reference other worlds (which themselves will each have their own record)
* Assets folder
** This contains all the assets needed by the records in the ResonitePackage
** These are the raw original versions of those assets
** Each one is named based on its own hash
* Variants folder
** This contains any variants (compressed/processed versions) of the assets for specific platforms
** This is optional - it speeds up importing of the package.
** Without those included, the client will need to compute these variants on its own, which can take some time
* Metadata folder
** This contains metadata for the included assets
** This is also optional - including this speeds up importing of the package, but it will also work without it
== Development Content ==
There were several previews of this feature uploaded to Frooxius' YouTube Channel:
* [https://youtu.be/LzONdReyxNU Testing Import]


== Sources ==
== Sources ==


[[Category:Features]]
[[Category:Features]]

Latest revision as of 00:27, 22 October 2024

ResonitePackage files are not supported by Unity! This is not an intended application of this feature.

ResonitePackage is a package format allowing users to share and import pre-setup avatars and objects easily[1].

Goals

The goals of the ResonitePackage format are to:

  • Allow creators to share creations outside of Resonite
    • For example an avatar creator adding a ResonitePackage version of their avatar
  • Backup your content locally
    • The package includes all the necessary assets for exported item without relying on the Resonite Cloud, making this a good option if you want to create local backups of your items

Non-Goals

  • Compatibility with Unity/Unitypackage
    • Unitypackage is a proprietary format, that we cannot support/emulate
    • Therefore Unity will not support ResonitePackage.
  • Compatibility with other VR Platforms
    • ResonitePackage files will not be suppoted by other VR Platforms
  • Offline Editing
    • This is theoretically possible, but not one of the goals of this feature.
  • Export from 3rd party tools
    • While possible, the ResonitePackage contains Resonite's internal data formats, which are subject to change at any moment.
    • The format is not designed to be easily built from scratch using 3rd party tools, so building those might prove challenging, since it'll require re-implementing a lot of Resonite's internal formats
    • Best approach for this would be Unity SDK which is on our list of things to do: https://github.com/Yellow-Dog-Man/Resonite-Issues/issues/6
      • ResonitePackage could become part of the Unity SDK flow, where the SDK is used to build out and convert content to Resonite and then export it as ResonitePackage file
      • This is currently NOT implemented. We recommend upvoting the issue, which will allow us to prioritize it sooner.

How to export

Exporting any item as .ResonitePackage is very easy!

  1. On the dash, click the "Files" tab
  2. Navigate to the directory you want to export your package to
  3. Grab and hold the item you want to export in world (grabbing a slot reference from inspector also works)
  4. While holding the item, click the green plus button in the Files tab (you can click it with your other hand)
  5. Export dialog will show up
  6. Select one of the "Resonite Package" options in the export dialog
  7. (optional) name the file in the Export dialog
  8. Click "Export"

The export might take some time depending on the size of the item. Once it's done, the dialog will disappear.

Contents

ResonitePackages will include everything needed to re-create an object inside Resonite when re-imported. Including:

  • All Assets
    • Images
    • Sounds
    • Meshes
    • Videos
    • Fonts
    • And others...
  • Slot Hierarchies
    • Including Bones
    • Including all components
    • ProtoFlux

All assets will be included explicitly, as a file within the package.

Variants

You can also optionally, export a ResonitePackage with all asset variants by selecting the (+variants) option during export.

This will result in a larger file size, but the object will load much more quickly when users import it. If the package is exported without variants, the user will compute the variants on their end after the package is imported, which can be CPU intensive.

Permissions

As exporting a ResonitePackage is treated the same as exporting any other file, any regular export restrictions still work. This includes:

  • Restricting certain roles from exporting in a world
  • SimpleAvatarProtection blocking export for objects you do not own.

Simple Avatar Protection handling

It is recommended to review the ReassignUserOnPackageImport property on any important assets to make sure it is set correctly. It defaults to True

ResonitePackages have some custom handling for SimpleAvatarProtection.

On import:

  1. Resonite will notify each copy of SimpleAvatarProtection found within the package that it is part of a package import.
  2. If the ReassignUserOnPackageImport property on the SimpleAvatarProtection is set to true
    1. The User assigned to the SimpleAvatarProtection will be set to the user who imported the package.
  3. If the ReassignUserOnPackageImport property on the SimpleAvatarProtection is set to false
    1. The User assignment will be left alone.

Naming

The name was chosen as it was the most explicit (following in the steps of the Unity engine having the UnityPackage format), and as a way to advertise the platform[2][3].

Tutorials

Internals

ResonitePackage file is essentially a ZIP archive, containing a number of files:

  • R-Main.record
    • This contains the main asset (typically the object or main world that should be loaded)
    • Contains various metadata about the object - name, description, tags
    • Also contains manifest of assets that this record and main object represents and needs
    • This is the same record that's used in Resonite's local and cloud storage to represent items, objects and worlds
  • *.record files
    • Any additional records that the item from the main world might be referencing.
    • This generally only applies to worlds that reference other worlds (which themselves will each have their own record)
  • Assets folder
    • This contains all the assets needed by the records in the ResonitePackage
    • These are the raw original versions of those assets
    • Each one is named based on its own hash
  • Variants folder
    • This contains any variants (compressed/processed versions) of the assets for specific platforms
    • This is optional - it speeds up importing of the package.
    • Without those included, the client will need to compute these variants on its own, which can take some time
  • Metadata folder
    • This contains metadata for the included assets
    • This is also optional - including this speeds up importing of the package, but it will also work without it

Development Content

There were several previews of this feature uploaded to Frooxius' YouTube Channel:

Sources