A story is not a story until you share it with someone. In this case, you can package up the story you have put together, along with the assets needed to run it, and deliver it to a device that a viewer can use to enter the world you created.
If you are looking for existing published Spotlight Stories, see our YouTube channel.
Building the Story
Building your story involves baking the assets and story graph into a package that can play in a viewer. The viewer can be the Preview Viewer, the Story Viewer, or the Spotlight Stories app installed on a phone or other device.
To build the story, use one of the commands under the Play menu:
- Build Story: This command builds the story and places a file on disk in your story folder. You can then use one of the play commands to preview the story. Running the command again will overwrite this file. Note that this does not create an APK that you can install on a device; instructions for building an APK are below.
- Play on Device: If you have a device attached to your computer, with the Spotlight Stories application installed, you can build the story and have it made available directly in the application. A zip file is placed on the device, which will unzip the first time you try to run it, and then be available to play.
- Build and Play: This command opens a window allowing you to control more options in your build process. It also allows you to automatically play the story in a viewer as soon as the build process completes. The Use Device for Playback checkbox options are described in detail below.
When you build your story, you can watch the progress of the build in the Job Manager window. You will also see a red button in that window which you can use to cancel the build process.
Previewing the Story
Before you share your story, you will want to take a look at it yourself. You can preview your story in either the Preview Viewer or the Story Viewer (which provides more functions for you). For more information on viewing your story, see Story Viewer.
Command Line Options
When previewing a story there are a number of options that can be set in the Command Line field of the Build and Play dialog. Many of these work both on device and in a desktop environment. For the playblast options it is recommended to use the Preview Viewer instead of Story Viewer.
- -msaa: Enables multisample anti-aliasing on platforms that support it.
- -record filename: Records camera orientation information to a csv file.
- -replay filename: Can play back camera information previously written with the record flag.
- -res width height: Set the width and height of the window when using the Preview Viewer on desktop.
- -stats on: Writes out stat csv files to the build directory. This is useful when optimizing a show.
- -vr: Starts the show in cardboard mode.
- -hqoffline filepath: Use the offline high quality anti-aliasing settings and write to the given file path (Windows Only).
- -aasharpness amount: Settings for high quality anti-aliasing. 0.35 was found to be a good default value (Windoes Only).
- -playblast filepath: Export images to the given filepath without using high quality anti aliasing.
- -fixedtimestep ms: Play back with a fixed timestamp in milliseconds instead of trying for realtime playback.
- -latlong cubesize width height: Write out a latlong 360 images directly from the player.
Along with previewing a story interactively we may also want to create a 360 latlong video of a story. To do this you can use the Command Line parameter and set a series of options like the following example that will create images for a 30fps 1920x1080 latlong video.
-hqoffline path -aasharpness 0.35 -latlong 1024 1920 1080 -fixedtimestep 33.33333 -res 1024 1024
Creating an APK Package for a Device
If you are ready to create a package, or APK, that can be run on a device rather than just in a preview window, there are a few steps you need to follow. We have an introductory video that will walk you through one version of these steps.
The APK is actually an executable file which runs on a phone or other device, installing the story in the Spotlight Stories application.
To create the APK, use the Tools > Create Device Package menu in the Story Editor. The Create Device Package window opens allowing you to choose a name and target platform for the package.
You can also set different device package options, which are described below.
When you click Ok, a build process starts and creates a file with the name you provided, and a ".apk" file extension. Once the build is complete and the file has been created, you can install it on your device. There are different methods available to install the file; here is one we recommend:
- Copy the saved .apk file into your account on Google Drive.
- Download the .apk from Google Drive onto your device.
- Run the .apk file as an executable. It installs the story into the Spotlight Stories application. Note that, before the first time you run the .apk, you must set your device to allow .apk files from "unknown sources" or you will get an error.
- In Spotlight Stories, click on the story to unzip it. Afterward, it will be available to play.
> adb install -r (path)
Where path points to the .apk file and the "-r" flag replaces a previous version of the file.
When you build your story, you can select these options which can affect the performance of your story, or provide debug information that you might find helpful while it is playing. You can set these options either by clicking on the Options button on the Create Device Package window, or by clicking on the button next to the Use Device for Playback checkbox on the Extract, Build and Play window.
- Use Development Build: The default build is called a candidate build. It is built for performance. Check this box to build a debug version instead. This also unlocks the rest of the debug options below.
- Show Camera Overlay: Show information on variables and broadcast events.
- Show Audio Emitters: Show the position, names, and a representation of the falloff for any audio emitters in the story.
- Show Triggers: Show the trigger shapes in the story.
- Disable Checkpoints: If a story is set to use checkpoints, this will disable them so that the show will run normally on subsequent views without having to delete the checkpoints.
- Debug Text Size/Color: Change the size and color of the debug information that appears on screen. This is particularly useful if the story has a background that makes the default text hard to read.
- Capture FPS Stats: Enable this option to create a CSV file that includes a running capture of the current, average, minimum, and maximum frame rate for the story. Enter a path and filename in the Stats File Name field to specify where the file should be saved.
Below are some recommendations for current low-end devices (generally used for testing purposes) and high-end devices (for better performance).
Android low-end devices:
- Samsung Galaxy S4 [Model GT-I9505]
- Samsung Galaxy S4 [Model GT-I9506]
- Moto X Generation 1 [Model XT1058]
- Moto G Generation 2 [Model XT1068]
iOS Low-end devices:
- iPhone 5S [Model example: ME298LL/A]
- iPad Mini 2
- Android Version: 4.4.2+ for 64 Bit
- GL Version: OpenGL ES 3.0+
- RAM Android Minimum: 1GB+
- RAM iOS Minimum: 512GB+
- CPU Core Amt: 2+ (for best performance)
- Sensors: Gyro (required)
- GPU: Adreno 320 >=, Mali 600 >=, PowerVR 544 >=
This list is based on currently available models. As newer models are released, they will likely improve performance.
Android high-end devices:
- Samsung S7 (edge)
- Samsung S6 Edge Plus
- Samsung Note 5
- Nexus 6P
- Nexus 5X
- Moto Pure
iOS high-end devices:
- iPhone 6S or newer
- iPad Air 2 or newer