Viewing "SciFi Gun" by mrfetch@sketchfab in the live PigletViewer demo.
PigletViewer is a Unity application which uses the Piglet glTF Importer to load and view 3D models from glTF files (.gltf
, .glb
, or .zip
)1. It is designed to run on multiple platforms and currently supports builds for Windows, macOS, Android, iOS, and WebGL (see Build Instructions).
PigletViewer is provided as an example application for customers of the Piglet glTF Importer. As such, building the application requires purchasing and installing Piglet from the Unity Asset Store. For new users of Piglet, I recommend watching the Runtime Import Tutorial video and/or reading the Runtime Import Tutorial section of the manual before exploring the PigletViewer code, as the tutorial provides a much quicker and simpler introduction to the API.
A live demo for the WebGL version of PigletViewer is available at: https://awesomesaucelabs.github.io/piglet-webgl-demo/. I have tested the demo in Firefox and Google Chrome2, on Windows 10 64-bit.
Drag-and-drop functionality does not work on MacOS or Linux. The
ability to drag-and-drop .gltf/.glb/.zip files into the PigletViewer
window only works on Windows, because I implemented that feature using
UnityWindowsFileDragAndDrop. On
MacOS or Linux, you will instead need to use the --import
option
(see command line options) to choose which
glTF file(s) are loaded on application startup.
To set up the Unity project for PigletViewer, I recommend the following steps:
.unitypackage
for PigletViewer from the releases page, then unpack the .unitypackage
into your project from Assets -> Import Package -> Custom Package...
in the Unity menu. I recommend installing from the .unitypackage
rather than doing a git clone
because the project in this repo is tied to Unity version 2018.4.20f1, whereas the .unitypackage
will also work with newer versions of Unity.
You can build PigletViewer for Windows/Mac/Linux using the following steps:
Assets/PigletViewer/Scenes/MainScene.unity
to make it the current scene.File -> Build Settings...
in the Unity menu.PC, Mac & Linux Standalone
on the left sidebar of the Build Settings
dialog.PC, Mac & Linux Standalone
by clicking Switch Platform
. The Switch Platform
button will be grayed out if PC, Mac & Linux Standalone
is already the active build target.Build And Run
.OK
to start the build.Once the build has completed, PigletViewer will open on your Windows/Mac/Linux desktop. If you are using Windows, you can drag-and-drop .gltf
/.glb
/.zip
files onto the PigletViewer window to view them. If you are using Mac or Linux, you will instead need to launch PigletViewer from the command line and use the --import
option to specify which glTF file(s) to load at startup (see command line options).
Before you can build Android apps with Unity, you will first need to install Android Build Support via Unity Hub. See Android environment setup from the Unity documentation for instructions.
You will also need to enable USB debugging on your Android phone/tablet. See Configure on-device developer options from the Android documentation for instructions.
Once you have completed the above steps, you can build and run PigletViewer on Android using the following steps:
Assets/PigletViewer/Scenes/MainScene.unity
to make it the current scene.File -> Build Settings...
in the Unity menu.Android
on the left sidebar of the Build Settings
dialog.Android
by clicking Switch Platform
. The Switch Platform
button will be grayed out if Android
is already the active build target.Build and Run
..apk
file and click OK
to start the build.Unity will automatically upload and run the .apk
file on your Android phone/tablet once the build has completed. (You may need to wake/unlock your Android device before the PigletViewer app will start.)
You can open glTF files in the PigletViewer app by opening .glb
/.zip
files from a file browser app and choosing PigletViewer as the target application3.
In comparison to other platforms (e.g. Windows, Android), building for iOS has a lot of additional steps and requirements. Most importantly:
Even if you use Unity Cloud Build for iOS builds, you will still need to pay the yearly Apple Developer fee in order to generate the required iOS app-signing certificate, as described below.
Once you have obtained a Mac computer and bought an Apple Developer subscription, the next steps are:
Whew. Generating those certificate files was long and confusing process, wasn't it? Don't worry, you're almost done now.
Next you need configure iOS app-signing in Unity, as depicted in the screenshot below.
Screenshot of Unity settings for signing iOS apps.
In detail:
Edit -> Project Settings... -> Player -> iOS tab -> Other Settings -> Identification
from the Unity menu.Bundle Identifier
to a name that matches the certificate from the Apple Developer website, as shown under Certificates, IDs & Profiles -> Identifiers
. For example, for my own Apple Developer account, I have a certificate named "awesomesauce" that is associated with the pattern "com.awesomesauce.*". So "com.awesomesauce.piglet" would be a valid value for the Bundle Identifier
field.Signing Team ID
to your Apple Developer team ID. This is the alphanumeric ID shown in the top right corner of your Apple Developer account page, after you select Certificates, IDs & Profiles
. A hypothetical example is "AB123C45DE".Automatically Sign
checkbox.Finally (!), you can build and run PigletViewer on your iOS device using the following steps:
Assets/PigletViewer/Scenes/MainScene.unity
to make it the current scene.File -> Build Settings...
in the Unity menu.iOS
on the left sidebar of the Build Settings
dialog.iOS
by clicking Switch Platform
. The Switch Platform
button will be grayed out if iOS
is already the active build target.Build and Run
..app
folder and click OK
to start the build.Xcode will automatically upload and run the app on your iPhone/iPad once the build has completed. If you have installed your Apple Developer certificate correctly (see Building for iOS), Xcode will prompt for your Mac login password to sign the app. You may also need to wake/unlock your iPhone/iPad before the PigletViewer app will start running.
Once the app is installed on your iPhone/iPad, you can open a .glb
or .zip
file in the app by either:
iPhone
/iPad
in the left sidebar and then selecting the Files
tab (see screenshot below).
Dragging-and-dropping a glTF file onto the PigletViewer iOS app in Finder.
Before you can build WebGL apps with Unity, you will need to install WebGL Build Support via Unity Hub. See Add modules from the Unity Hub documentation for instructions.
Once you have installed WebGL Build Support, you can build and run PigletViewer in a web browser using the following steps:
Edit => Project Settings... => Player => WebGL settings tab => Resolution and Presentation => WebGL Template
. For Unity 2018 or Unity 2019, use the Piglet2018
template. For Unity 2020 or newer, use the Piglet2020
template4.Assets/PigletViewer/Scenes/MainScene.unity
to make it the current scene.File => Build Settings...
in the Unity menu.WebGL
on the left sidebar of the Build Settings
dialog.WebGL
by clicking Switch Platform
. The Switch Platform
button will be grayed out if WebGL
is already the active build target.Build and Run
in the bottom right corner.OK
.Once the build has completed, PigletViewer will open in your default web browser.
PigletViewer can be run with command-line options to automatically
import glTF file(s) and perform other actions. For example, the
following command would start the Windows standalone exe, import
model1.glb
, sleep for 2 seconds, import model2.glb
, sleep for 2
seconds (again), then quit.
PigletViewer.exe -- --import model1.glb --sleep 2 --import model2.glb --sleep 2 --quit
:warning: Notice the bare --
in the example command above. Options
that precede the --
are standard Unity Standalone Player command
line
arguments,
whereas options after the --
are PigletViewer-specific options (as
listed below).
:warning: Your Windows standalone exe may be named something different
than PigletViewer.exe
. The name of the executable is determined by the value of
Product Name
under Edit -> Project Settings... -> Player -> Product Name
in the Unity menu.
The full list of the PigletViewer options is:
Usage: PigletViewer.exe <UNITY_OPTIONS> -- <PIGLET_VIEWER_OPTIONS>
Options:
-b, --button=LABEL Show button with LABEL and continue when user clicks it
-e, --ensure-quaternion-continuity Call AnimationClip.EnsureQuaternionContinuity() after
importing each animation clip.
-i, --import=URI Import glTF file from URI (file path or HTTP URL)
-I, --import-streaming-asset=PATH Import glTF file from PATH, where PATH is relative
to the StreamingAssets folder. This option is useful
because the StreamingAssets folder can be located in
different places depending on the target platform.
For example, on Android the StreamingAssets
folder is located inside the .apk file!
-m, --log-message=MESSAGE Print message to Unity log
-M, --mipmaps Create mipmaps during texture loading [disabled]
-p, --profile Enable performance profiling [disabled]. When
enabled, this writes some profiling data
to the Unity log after each glTF import.
-q, --quit Quit application after performing all command line
actions [disabled].
-s, --sleep=SECONDS Sleep for SECONDS seconds. The option is
order-dependent and can be placed between
--import options to introduce a delay between
glTF imports.
:warning: I would love to add a --help
option that prints the above message on STDOUT, but
so far I can't figure out how to do it!
On Android/iOS/WebGL, specifying command line options is either
awkward or impossible. On these platforms, you can still use command
line options by putting them in a file named
StreamingAssets/piglet-viewer-args.txt
inside your Unity project.
The options are split on whitespace and can be specified across
multiple lines.
Here is an example of a valid StreamingAssets/piglet-viewer-args.txt
file:
--import https://awesomesaucelabs.github.io/piglet-webgl-demo/StreamingAssets/piggleston.glb
--sleep 2
--import https://awesomesaucelabs.github.io/piglet-webgl-demo/StreamingAssets/dragon_celebration.zip
--sleep 2
--quit
:warning: Currently, PigletViewer does naive splitting on whitespace
when parsing StreamingAssets/piglet-viewer-args.txt
, so quoted arguments
and arguments with spaces are not possible.
On platforms that support it (e.g. Windows, macOS), it is still
possible to use ordinary command line options when there is
StreamingAssets/piglet-viewer-args.txt
file in your project.
Options specified on the command line are appended to the options
specified in StreamingAssets/piglet-viewer-args.txt
.
The best starting point for understanding the PigletViewer code is the GameManager
class in Assets/PigletViewer/Scripts/GameManager.cs
. This class is responsible for starting glTF import tasks and for setting up callbacks that track import progress, handle import errors, and handle successful completion of a glTF import. GameManager
also handles running scripts that implement platform-specific behaviour (e.g. WindowsGameManager
). Depending on the target platform of your game/application, it may be useful to look at those classes as well.
The PigletViewer code in this repo is released under an MIT license.
This repo includes the code for UnityWindowsFileDragAndDrop under Assets/PigletViewer/Dependencies/UnityWindowsFileDragDrop
, which also has an MIT license.
Building PigletViewer requires purchasing and installing the Piglet glTF Importer source code separately from the Unity Asset Store. Piglet is licensed under the Unity Asset Store End User License Agreement (EULA). Briefly, this means that you are free use Piglet in your applications and games (commercial or otherwise), but you are not allowed to redistribute the source code.
The "Sir Piggleston" model included at Assets/StreamingAssets/piggleston.glb
is a trademark for the Piglet glTF Importer. Please contact awesomesaucelabs
at gmail for licensing terms.
This repo includes several sample glTF models under Assets/StreamingAssets
, which have been published by various artists on Sketchfab under the CC Attribution License:
Name of Work | Author | License | File Path |
---|---|---|---|
"Morpher Animated Face - Military Cartoon Hartman" | skudgee@sketchfab | CC Attribution License | Assets/StreamingAssets/cartoon_hartman.zip |
"Skull Salazar" | jvitorsouzadesign@sketchfab | CC Attribution License | Assets/StreamingAssets/skull_salazar.zip |
"Dragon (Celebration)" | kand8998@sketchfab | CC Attribution License | Assets/StreamingAssets/dragon_celebration.zip |
1. The WebGL build can only load models from .glb
and .zip
files (not .gltf
files). The main issue with loading .gltf
files in a web browser is that they typically reference other files on the user's hard drive (e.g. PNG files for textures), and web browsers aren't allowed to load arbitrary files from the user's hard drive, for security reasons. There is a similar issue for opening .gltf
files on Android3.
2. Performance of PigletViewer in Google Chrome can be greatly improved by enabling hardware acceleration (i.e. GPU acceleration) in the browser settings. (This option is currently disabled by default in Chrome.)
3. Opening .gltf
files from file browser apps does not work on Android. The main problem is that the file browser apps send PigletViewer an opaque content URI for the input .gltf
file, rather than a file path. This means that PigletViewer cannot resolve relative file paths used inside the .gltf
file (e.g. paths to PNG files). There is a similar issue for opening .gltf
files in the WebGL build1.
4. There are substantial changes to WebGL builds in Unity 2020, which require using a different WebGL template (Piglet2020
). For a detailed discussion of WebGL-related changes in Unity 2020, see: https://forum.unity.com/threads/changes-to-the-webgl-loader-and-templates-introduced-in-unity-2020-1.817698/