User Guide (Version 1.16)

Using Virtual File System with iOS

This feature is in preview release and is subject to change.

The Asset Processor can use the virtual file system (VFS) to serve assets to your iOS devices over a USB connection. This method offers the following benefits:

  • You can edit game content and data on your Mac and view changes immediately on the iOS device without needing to redeploy the game.

  • You can iterate much faster.

This topic demonstrates how to set up your Mac and iOS device to run the Samples Project using VFS.


Before you can use the VFS with iOS, you must do the following:

  • Download the usbmuxconnect package and save to a location on your Mac.

  • Build Lumberyard on your Mac or use a prebuilt version of Lumberyard.

To set up VFS and connect your game to the Asset Processor

  1. On your Mac, do the following:

    1. In the AssetProcessorPlatformConfig.ini file (located in the lumberyard_version\dev directory), uncomment (remove the semicolon) the ios=enabled line to enable asset processing for iOS:

      [Platforms] pc=enabled ;es3=enabled ios=enabled
    2. Start the Asset Processor (located in the lumberyard_version\dev\BinMac64 directory).

  2. On your PC, configure and start the shader compiler server (located in the lumberyard_version\dev\Tools\CrySShaderCompiler\x64\profile directory). The shader compiler must be on a PC and can be located anywhere on your network as long as it's accessible from your Mac. For example, you can use a single shader compiler that is located on a server for an entire project.


    To allow connections between a remote shader compiler and your Mac, you must add the IP range(s) of your Mac(s) to a whitelist file. For more information, see Creating a Whitelist for the Remote Shader Compiler.

  3. On your Mac, do the following:

    1. Edit the bootstrap.cfg file (located in the lumberyard_version\dev directory) to set the following:

      remote_filesystem=1 ios_connect_to_remote=0 ios_wait_for_connect=1
    2. Edit the system_ios_ios.cfg file (located in the lumberyard_version\dev directory):

      1. Set r_AssetProcessorShaderCompiler to 1.

      2. Set r_ShaderCompilerServer to the IP address of the PC running the shader compiler.

        The Mac that is connected to the iOS device must be able to connect to the PC running the shader compiler.

    3. In the Asset Processor, on the Connection tab, click Add Connection and then select the Auto Connect check box. The Asset Processor will attempt to connect to the iOS device through the local host.

To run the game

  1. On your Mac, build and launch your game for iOS with Xcode. For instructions, see Configuring and Building iOS Games and Deploying iOS Games.

  2. In a terminal window, navigate to the location where you saved the usbmuxconnect package and run the following command: itnl --iport 22229 --lport 22229


    If the device cannot be reached, stop the game, disconnect and then reconnect the device, and start again from step 1 of this procedure. Generally you can allow itnl, the Asset Processor, and the shader compiler server to continuously run on a PC. Then you can continuously run your game without restarting other apps or services.