Twin Sync Studio
User Manual

To install Twin Sync Studio, you will need an access key, available seats on that key, and an active subscription which may be purchased at our website.

Access keys are purchased with a seat count, and seats are allocated per machine. That means that once you install the software on one machine, that machine is now using a seat for that access key/account. If you need to move one of your seats from one machine to another, contact support. In the future, there will be a button in the application to deactivate the seat allocation of the current machine. You may only reallocate a seat allocation to another machine once per day.

To use Twin Sync Studio, you will need at least:

• Windows 10 or 11. If you need another operating system, please contact support.
• 16GB of CPU RAM

To use Twin Sync Studio-generated content for Unreal Engine, you will need:

• Unreal Engine 5.0-5.5 installed
• to meet or exceed Unreal Engine's system requirements
  The more Graphics RAM you have in your GPU, the larger scenes you'll be able to handle.
• Microsoft Visual Studio or just the Build Tools for visual Studio
  You can develop on the latest supported version of Unreal Engine (5.5 as of writing) without Visual Studio until you package your project, since we ship the necessary 5.5 windows-editor binaries for the editor, but you must build the packaged version of the plugin yourself for your desired platforms.

To install Twin Sync Studio, you will need:

• The downloaded installer
• An access key for an active subscription with at least one available seat

Both of the above should be delivered promptly to your registered email (within 1 business day) after payment is processed.

Once you have both, on Windows:

1. Double click the downloaded installer
2. If you are greeted by a blue "Windows protected your PC" window, hit the "more info" link and then the "run anyway" button.
   Since Graphl Technologies LLC is a new company with a new code signing certificate, (April 2025), you may see this screen until the application has been downloaded many times. See this link for more details.
   Regardless, always check that the installer was signed by Graphl Technologies LLC, as indicated by Windows as you run it.
3. Read through the End-User-License-Agreement, terms and conditions, and privacy policy.
4. Press "accept and continue" if you agree and are ready to proceed.
5. Type or paste your access key into the text input, and press "submit".
6. If your license is valid (you have installed on this machine before or have unused installations on your license), then Twin Sync Studio should open! Of course, if it doesn't work, please contact support with the given error message.

As of today, application updates are announced on our LinkedIn pageand subscription holders will be notified of major updates and their changes via the email with which they subscribed. Installing an update currently is not automatic, and requires opting in by downloading the latest installer and running it. It will not delete your project data.

1. From the File and view menus, you can go back to the main menu or change which file you're inspecting at any time.
2. Open the export creation interface for a local file
3. Open the iModel selection interface, where you can select an iModel from your Bentley account, such as a Synchro 4D project iModel, and then download it as a local file and open it
4. Logout of your Bentley account and purge any credentials saved in your computer's secure password storage
5. Click a project name here to open the corresponding recently opened project
6. Follow a quick link to learn more about some of the technologies in use

1. Quick Export button. Brings up the quick export dialog
2. Enable the Graphical complexity visualization overlay. This will color elements by how many vertices there are. Red elements are the densest in the scene, green are the least dense. Due to limitations of the iTwin viewer, it is inaccurate if one element contains multiple instances ("parts"), but otherwise is helpful to find problematic elements
   You can disable the complexity view by clicking the Clear ... Emphasized button that appears next to it once the mode is enabled
3. View manipulation tools. Use the 3D cube, fit to view, pan, zoom, and other tool buttons to navigate the view
4. Schedule playback bar. Play through and inspect the schedule in your iTwin. Only the first schedule found is shown
5. Tree view. A common iTwin viewer component, you can inspect the model hierarchy and categories, and manipulate the visibility of their geometry in the viewport
6. Widget tabs. Select between viewing the scripting interface, geometry analyzer, and table manager tabs.
7. Connection status. Shows whether you have the latest synced changes to the iTwin and if you're connected to the iTwin services
8. Choose the selection scope, if you want to select whole assemblies at a time instead of the default of individual elements

The quick export allows you to perform an export with some basic settings, completely ignoring the scripting interface. Hover over each option to see an explanation, reproduced here with more details.

1. Output visibility tracks to level sequence. In the level sequence driven animation mode, (which is not the default so you can probably ignore this setting), this outputs visibility tracks for all created actors to the level sequence. Many non-trivial scenes generate so many actors that this often makes the level sequence unusable and should be avoided. Prefer to leave this off and use the schedule manager driven animation modeor at least set the AffectRealVisibilityOfBatchedActors property of the ScheduleManager to true.

2. Cluster merging strategy. Decide which iTwin scene elements to merge into a single actor in Unreal. Merging meshes means less draw calls which means faster real-time rendering (vroom vroom). Construction geometry however can be very heavy and repeat instance meshes, so you may reach Unreal Engine's 2GB static mesh size limit if you merge too much. This can usually be avoided by just not merging instanced meshes since those will take less memory as a single static mesh placed multiples time across multiple static mesh actors. That is why the default merging strategy is "Uninstanced elements within each element". So all pieces of an element get merged, except anything that has multiple instances. You may also try merging "All uninstanced meshes" or "Uninstanced meshes within each animation batch" for less draw calls.

   In the scripting interface, you can assign meshes to merged clusters however you want, by just finding a number (such as the category id to merge by category) for each mesh.

3. Filter by viewport visibility. Do not export any elements, categories, models, etc, that have been hidden or isolated out in the viewport. This is a simple but effective way of filtering what you export without using the visual scripting ignore feature.
4. Decimation tolerance. The distance in meters at which to merge vertices in the mesh. This can seriously lower the quality of meshes with hard edges as normals are not preserved. Can be useful to reduce the complexity of dense, smooth meshes, or easily remove very small features or duplicate vertices.
5. Angle tolerance. Max angle difference in radians for approximated face. For example, a primitive representing a circle would have its 2 radians circumference divided by an angular tolerance of 0.25 radians, yeilding a mesh "circle" of 8 vertices, an octogon.
   See the iTwin documentation for this.
6. Level sequence FPS. For use in the level sequence driven animation mode(which is not the default and most users shouldn't need). Change the resolution and framerate (FPS) of the generated level sequence from your animation data.

7. .udatasmith file name. Set the name to use for the generated .udatasmith file and _Assets folder. So a name of "myproject" would yield the file myproject.udatasmith and folder myproject_Assets.

   This is done because the scripting interface allows you to export to multiple separate datasmith files with different names, should you need it.

The geometry analyzer shows a table sorting elements by vertex density. In the presence of multiple instances ("parts") within one element, it may be slightly inaccurate, but this is a rare case.

1. Hovering over an element will list similar geometry properties to those in the table, but for that specific hovered element.
   Each element in the table and the hover panel show the amount of undecimated triangles it would produce during export, and how many instances there are of this particular mesh in the scene. Elements with more than one instance often should not be clustered for maximum performance.
2. Click on the search icon in the Find column to zoom to an element. If you've enabled the graphical complexity view, the densest elements at the top of the table will be in red.
3. Click on the select icon in the Select column to add the element to your selection.

The table manager allows you to create tables for access in the scripting interface. Currently, the main use of tables is for creating a material mapping table for metadata in your iModel. You can also copy cells from most spreadsheet editors (for example, Excel), and paste them into this table view. It saves automatically each time you edit it and the data will be present if you close and reopen the project.

For more information on this workflow, see the corresponding tutorial.

1. Click on the selected table's name to edit the name. You may delete a table with the x button, and switch to an unselected table by clicking on it.
2. Press the + button to add a new table
3. Select a cell with the left mouse button and then use the arrow keys or start typing to fill in table cells.
4. Right click a cell for help entering special values. Currently supported are helpers to get material asset paths from your Unreal Engine project.
   You can either input the "default" animated material from the plugin for that cell. Or you can select any material from your Unreal project by using the file browser.
5. You can see, for example, the property panel here, where you can inspect data in the iTwin coming through Synchro, Revit, or from wherever the data was synchronized. These properties can be accessed in the scripting interface to decide which table row to select a material from.

Twin Sync Studio's scripting interface is built on top of the Graphl scripting language, developed by Graphl Technologies. Note that Graphl is in alpha. Please report any encountered issues!

With Graphl, you can access all the data in your iTwin, using a convenient visual scripting interface, and even dropping down to JavaScript if you need it.

Graphl is designed to be familiar for users of other visual scripting tools, like Unreal Engine or Blender material and geometry nodes. If you would like a particular feature, please vote for it or add a feature request.

In Twin Sync Studio, you are given a function processInstance which you may implement as you see fit. Given some inputs about an instance of the a geometric mesh in the scene, tell the exporter:

• which datasmith file to send it to
• which cluster to merge it into, where a cluster is identified by any non-negative number (the type is called u64)
• which material to assign it, the unreal engine asset path of said material
• or whether to just ignore it entirely while exporting

Here is some information to help get you oriented:

• The logic starts flowing from the "Enter" node, which also has all the inputs
• All paths must end in a "return" node for your visual code to be valid
• You can use the if node to change what path is taken
• Flow pins (the ones with arrows in them) control the "flow" of the code, and say which node to go to next
• If you have not seen them before, you may want to learn about integer, floating-point, and boolean types, which you may know from Unreal Engine's blueprint system and other programming languages

You can take the following actions to manipulate the node graph.

• left click and drag on a node to move it around
• left click and drag on the graph background to pan around the graph
• left click on a node to select only it
• hold down control and left click on a node to add it to the current selection
• left click and drag on a selected node to move the whole selection around
• use control-C to copy some nodes and their links to the clipboard
• use control-X to cut some nodes to the clipboard, deleting them after the copy
• use control-V to paste some nodes and their links from the clipboard
• right click a node for some options, such as to delete it or the whole selection
• right click the background to open the "add node menu". Then type to search for a node. Or use the arrow keys, tab, and enter to select a node type to spawn. Nodes are organized into categories
• click and drag from one colored input or output "pin" of a node to another node's pin to create a link between them
• click and drag from one colored input or output "pin" of a node and "drop" the dragged link to open the "add node menu" with a filter on the type of node you are trying to connect. Creating a node this way will autoconnect it to the first compatible argument
• control-click a pin to delete all of its connected links

1. Help menu. You can open a quick help dialog here or submit any issues you find while using the graphl interface
2. File menu. You can use the "Save" and "Open" options to save your current script to a file or load an existing saved script
3. Export menu. You can run the scripted export by choosing the export option
4. Plugin menu. You can open the "install plugin" file dialog where you must select your Unreal project's .uproject file for the app to install the plugin for you.
5. Add function button. For repetitive logic, you can add a function, this will add a new node that you can then reuse multiple times to execute that logic.
6. Edit function button. If you have multiple functions, the selected one is highlighted in blue. You may open the other ones to edit them.
7. Add local variable button. You may add local variables to hold local state, and set their name and type here.
8. Parameters and results. You can only edit these for functions you created yourself. processInstance just lists the uneditable input types it is providing you and output types it is expecting here.
9. The enter node. This is where the flow of the script starts.
10. A NoClusterId node. This node says use the special cluster id that means the instance should not be merged into any cluster
11. A return node. This ends the script, outputting the inputs you specified
12. Literal inputs. Some types you can just provide a value right in the node itself if you don't connect a node. This is called a "literal" value.
    For example, booleans have a checkbox, strings and numbers can be typed in directly.
13. The Add node menu. You may right click the background to open the "add node menu". Then type to search for a node. Or use the arrow keys, tab, and enter to select a node type to spawn. Nodes are organized into categories.

The default animation mode is the ScheduleManager-driven animation mode. This means you must use the properties of the ScheduleManager to control the animation. The properties attempt to be as close as possible to those of a Level Sequence Actor. They are the following:

To use this mode, make sure the Associated Sequence property of the ScheduleManager is empty. It is empty by default. To control the animation, you may modify these properties at runtime or call functions like Play, Pause, and SetScheduleDateTime. This is probably better shown than told, so check out the blueprint API basics part of the tutorial, or the schedule UI tutorial.

The non-default and now not-recommended animation mode is the Level Sequence-driven animation mode. This animation mode is not recommended, especially for non-trivial scenes, as it has some limitations. That said, it allows you to synchronize to a level sequence more directly which can be useful when using Unreal's Movie Render Queue. Future versions of Twin Sync Studio will probably make this animation mode completely obsolete.

To use this mode, simply spawn a level sequence actor of any level sequence; an empty one, or the one generated by your Datasmith import, found in its Animations folder. If there is no such level sequence generated, you will have to make an empty level sequence. Then in the ScheduleManager properties (shown above), set the AssociatedSequence to the newly spawned LevelSequenceActor instance.

Search "Twin Sync Studio" in the blueprint context menu to see the list of applicable nodes provided by the Twin Sync Studio plugin, and to read their descriptions. You may also inspect the C++ source files in the installed plugin.