Assembling SWTOR Game Areas via the SWTOR Area Assembler Addon for Blender OLD VERSION

Notice: this Add-on's tools are also available in the ZG SWTOR Tools Add-on, with some improvements including auto-texturing (which soon will be backported to this one).

---

The SWTOR Area Assembler Addon for Blender, written by ZeroGravitas and Crunch, assembles SWTOR's in-game areas based on the information produced by Jedipedia.net's World Viewer and File Reader online tools. Those tools are able to export lists of objects in an human-readable-ish .json format, which the Area Assembler Blender Addon uses to import the objects and position them correctly.

In this guide we will show you how to use Jedipedia's tools to find and download the game location data in .json format, how to feed it to the addon, and the possibilities and limitations of the addon.

(This addon will import the objects but it won't auto-texture them. For that, we recommend the ZG SWTOR Tools Addon's Process Named Materials tool)

• Required Tools.
• Locating Area IDs, and Downloading Area JSONs.
• Configuring the Area Assembler Addon.
• Using the Area Assembler Addon.
  • How Automatic Lighting Works.
  • Adding Terrain.
  • General information about Objects Types and Empties.
• Importing options.
  • Options for reducing Blender's lag when importing MASSIVE Areas.
• Texturing the objects.
• Known Limitations.
• To Do.

---

Required Tools.

• A full assets extraction produced with Slicers GUI's 'Full' preset (a 'Static' preset-based one might work, too, but that hasn't been thoroughly verified yet).
• The free Blender 3D Software, version 3.1 or above.
• The latest .gr2 Importer addon for Blender.
• The SWTOR Area Assembler addon for Blender.
• The ZeroGravitas' SWTOR Tools addon for Blender.
• Visiting Jedipedia.net's World Viewer webpage.
• Visiting Jedipedia.net's File Reader webpage.

---

Locating Area IDs, and Downloading Area JSONs.

The first step of importing an area is knowing what area you want to import. For the sake of this tutorial we're going to be focusing on the Sith Warrior's 'Fury' player ship. The steps for this area will apply to all other areas as well.

1. Navigate to Jedipedia's World Viewer and locate in the Player ships category the Fury (Sith Warrior) entry. Simply click on this to populate the AreaID in the textbox below the 1. Choose an area heading as seen below. Copy this Area ID to the clipboard or a text document for use in the next step. We're not done with the World Viewer!

2. Navigate to Jedipedia's File Reader (the link is available at the top left corner of the World Viewer page, too) and click the Add Assets button, then navigate to your SWTOR game files' Assets Directory and select all the .tor files within this folder, then open them. Loading can take between 10-60 seconds (there are progress indicators), so perfect time to check your phone.
   • Steam Install Location: C:\Program Files (86)\Steam\steamapps\common\Star Wars – The Old Republic\Assets
   • SWTOR Launcher Install Location: C:\Program Files (x86)\Electronic Arts\BioWare\Star Wars - The Old Republic\Assets

3. Once all the .tor files have loaded into the File Reader, switch to the 'Files' tab on the top left, and then, in the input search box, paste or type in the AreaID we found earlier. In this case, the AreaID is 4611686051284477081. Doing that will narrow the displayed files to a handful, all relating to the spc_ps_sith_warrior area: these are the .dat files, commonly referred to as area.dats.

4. Whilst you could go through each individual area.dat and download them all, in most cases it's quicker and easier to import a whole area unless you know you'll only need a certain section, and are willing to spend the time working out which area.dat is the one you require. For this tutorial, we will be importing the entire Sith Warrior's Fury. Continently, the .dat file of any area is called area.dat, and will encapsulate all subareas such as ps_sith_exterior.dat, ps_sith_int_barracks.dat, ps_sith_int_captain_room.dat, etc.

5. Select area.dat from the search list and scroll down until you see a heading labeled Assets with a large button labeled Extract as zipped JSON. Download and save the ZIP file generated by this button to somewhere easily accessable, and unzip the included directory which contains the .json files we'll require for the final step in Blender.

6. Congratulations, you've completed your first steps. Continue onto the next section to download and install the SWTOR Area Assembler Addon.

---

Configuring the Area Assembler Addon.

It is recommended to use the latest version of Blender (or, at the very least, Blender 3.1 or higher), as there are no guarantees of a perfect operation of the addon with older ones.

1. Download the latest version of the Area Assembler Addon by clicking here which is packed in a ZIP Folder. DON'T UNZIP IT! Blender handles that automatically when we install the Addon.

2. Open Blender and Select from the top Menu Bar Edit > Preferences... > Add-ons > Install... which will open a file import navigation window. From this window locate the SWTOR Area Assembler zip file that we downloaded in the step above (NOT the Area.dat ZIP we downloaded in the previous section), select it, and then click Install Add-on.

3. After a second or two Blender will reload the Add-on's list, and present you with the newly installed Addon. Click in the empty checkbox to enable the Addon, but stay on the page as you will need to populate some information. If Blender doesn't automatically show you the SWTOR: Area Assembler Addon as the only result and instead you see the full list of Addons, use the search bar on the top right of the Preferences window to narrow your results until you find it (type, for example, 'sw', and it should pop up immediately).

4. After enabling the Addon and expanding its information box by pressing the small down arrow, you will see a Preferences section with a text input box labeled SWTOR Resources. In this field you will need to enter the full path to your Slicers GUI or similar SWTOR extraction tool, up to and including the resources folder you ought to find in there. It should be something like C:\Users\YOU\Documents\resources or whatever path you specified when doing your extraction in this guide.

5. Once you've set your path, you can close the Preferences Window. It shouldn't be necessary to close and relaunch Blender. You can make sure that the add-on is correctly installed by checking that Blender shows it as File > Import > SWTOR (area .json).

6. If it does, congratulations, you're done with another section and can proceed to the final one! If it appears but it is greyed out, check that the path to the resources folder is set correctly, and/or that there is a modern .gr2 importer addon installed, too (this Area Assembler addon isn't compatible with the Legacy version).

---

Using the Area Assembler Addon.

1. The very first step of importing an area is remembering where you downloaded the Area.zip file to, once you've located it, extract its entire contents so the containing .json files are accessible in their own directory. If you downloaded a Area.json file directly, then you can skip this step as there's nothing to unzip.

2. Moving back to Blender, navigate to Window > Toggle System Console for Windows Users. This step is technically optional, but highly recommended so you can see your imports progress when we begin, and will also provide some useful debugging and status information as it goes. Opening the system console will open a black text-based window which can be repositioned and resized where ever you want.

3. Once you've opened (or not) the System Console, navigate to File > Import > SWTOR (area .json) and this time select the SWTOR (area .json) option, which will open a navigation window. Whilst here, take note of the import options on the right hand side, which will allow you toggle on/off various quality of life features which have been added. Hovering over the item name with your cursor will display a tool tip giving a brief explanation of its purpose. For now, leave the defaults set.

4. Navigate to where ever your area.json files have been saved, which will be in the directory you created when unzipping the area.zip file in Step 1 of this section. Here you can select as many, or as few of the .json files as you like. The importer will process whatever you tell it to, however the more files you import, the longer the process will take. We recommend that the first time you try the addon you import a single, big .json file, to get a sense of how fast it runs on your PC.

   For this guide, we will select everything by pressing A, or manually highlight all the displayed .json files used by the Sith Warrior's Fury. With these files selected, click the Import Area .json button, and wait.

5. Continue waiting. If you opened the system console you'll likely be able to see a flurry of activity as it sets about importing and processing each .gr2 file. If you didn't open the system console, your Blender has likely gone 'non-responsive' and 'frozen'. Don't be alarmed, its still working in the background. If importing takes more than 10-20 minutes you may want to consider starting again, however - This time open your Blender System Console as per Step 2 in this Section.

   The progress of the importing that the console shows goes through these stages:

   1. A fairly quick one where all the .json files' information is being gathered.
   2. The actual importing of the objects with some additional diagnostic data: imports, duplications, discardings…
   3. A parenting pass where child objects are parented to parent objects, inheriting their positions, rotations and sizes accordingly. Some failure warnings are expected here, as the area data doesn't include certain animated objects that could act as parents. See the Known Limitations and To Do sections at the end of this guide.
   4. A final object renaming pass.

6. When the Addon has finished processing the files, you should see the untextured model of the Fury, ready for you to apply your own Uber Shaders. This process is outside of the scope of this guide, however for a quick and easy solution, please refer to ZeroGravitas' ZG SWTOR Tools which has a one-click materials application process, or to this guide to get a more thorough comprehension of this process.

7. Congratulations, you've assembled your first area. Now go forth, recreate the game in Blender and enjoy your lag!

How Automatic Lighting Works.

The area data exported in the .json files contains references to light sources' positions and rotations, but nothing else about them (so far). As that information might be useful when lighting the locations in Blender, the addon produces generic point lights out of that data as a reference (this can be disabled via the importing options'checkboxes).

At this moment, things are set so that all the lights in a "room" (a .json file) share settings (light data block) such as type, intensity, color, etc., so, changing them for a light will change them for all the lights in the room. They can always be individualized by using the Object > Relations > Make Single User > Object + Data > Selected Object (or All if you need that) option.

Adding Terrain.

We have preliminary support for processing heightmap-based terrain objects reference data. The Add-on imports terrain objects exported as .obj files and placed in a new folder at resources\world\heightmaps by a Windows command line tool still in development by fellow Slicer UltimaKaosXIII: SWTOR Terrain Extractor. The tool is able to process all the terrains in the game in one go in a few minutes, the results occupying some 8.3 GB.

There are some caveats, such as gaps between some terrain patches and the lack of UV information to apply textures correctly.

General information about Objects Types and Empties.

Similar to the case of lights, many objects are linked duplicates sharing mesh data blocks, as that accelerates importing a whole lot. We are looking at the possibility of making them unlinked and see how that affects importing speed and Blender's responsiveness afterwwards. Meanwhile, any linked duplicate can be turned into a fully independent object through the usual means.

To facilitate debugging, the objects have some Custom Properties keeping some data from the .json files such as object ID, parent's object ID, the name of the .json file it came from, and some positional data that Jedipedia pre-calculated to check against. Those properties can be found in the Custom Properties section of both the 3D Viewport Editor sidebar's Item tab and the Properties editor's Object Properties tab.

Importing options.

• Apply Final Rotation (default=on): disable to skip final rotation. All objects will need to be rotated in the X Axis 90 Degrees by the user.

  This is more of a diagnostic tool than anything else. Due to Blender's Z-is-up coordinate system being at odds with SWTOR's Y-is-up one, which is a source of complications when using SWTOR objects transformation data and chaining those transformations when parenting objects, we delay the final 90º rotation to the very last moment. Un-ticking this checkbox will bypass that rotation.

• Apply Scene Scale (default=off): automatically scale the entire scene after import by 10x to better match Blender Units.

  SWTOR uses decimeters as coordinate units, so, objects are internally sized as their real world size divided by 10. As many advanced operations in Blender (physics simulations, automatic weighting, etc.) depend on objects having real world sizes, this option will resize the imported areas x10 for us if we need it.

• Skip dbo Objects (default=on): Don't import design blockout (DBO) objects such as blockers, portals, etc.

  Those are game engine objects, invisible during gameplay, used by the level designers to set barriers to movement, mob spawning points, etc. Normally, such objects are just a nuisance for the purpose of assembling a game location in Blender, so, the default setting is on.

  However: we aren't fully sure yet about whether some of those objects determine the position, rotation and/or scale values of any visible objects in the scene (that is, they act as their parent objects) or not. Because of that, at the moment we are replacing them with Blender's Empties, which are a nuisance of their own but at least they aren't rendered in the scene. Once we determine they are safe to remove, we'll have this setting do so.

• Create Scene Lights (default=off): automatically create basic scene lighting based on in-game lighting nodes (if their numbers exceed 100, they will be set as excluded from view for Blender responsiveness reasons).

• Separate Object Types in SubCollections (default=off): if checked, the areas' objects are further arranged in Area sub-Collections. For each area (.json file), we get this Collection hierarchy:

  Area name
  > Area name - Lights (if Create Scene Lights is on)
  > Area name - Terrains (if any)
  > Area name - Objects

• Merge Multi-Objects (default=off): joins single .gr2 file-originated multi-meshes into single objects.

  Some of SWTOR's .gr2 objects contain several meshes at once. For example, there is an open crate object that has a separate lid and several tools spreaded around it, plus some invisible blocking object to keep a player from walking across it. These are the objects that slow down the importing process the most, despite some attempts at optimizing it. Then again, those are great objects for kitbashing if we keep their sub-meshes separate.

  Still, if one doesn't care for that, this option would just merge the sub-meshes into a single object, easier to pick and move around in Blender. This might marginally speed up the importing process if there are duplicates of this object listed in the .json files.

• Show Full Report In Terminal (default=off): by default, the addon will show the progress of each of the importing job's stages in a concise manner: as single lines (it simply makes the cursor go backwards one line after each line) except for those that have some error report. Ticking this checkbox will show all the progress information, instead. Given the tremendous amount of lines a whole world import can mean, we recommend increasing the console app's (or the one in a debugging environment such as VSCode's) buffer settings to some ludicrous size: we are talking about 500 lines per expected .json file or so. This option doesn't make much sense otherwise, as the full report's first half or more would easily get truncated out without an ample buffer size.

Options for reducing Blender's lag when importing MASSIVE Areas.

After importing massive amounts of objects, such as a whole planet's set of .json area files, it's typical that Blender's responsiveness to operations such as a Select All or to launch a material processing on such a selection lags terribly. We are talking half minutes or worse just to respond to our cursor hovering over a button if this button has to do a check for a selection of objects before making itself clickable. Even just moving through an Outliner overloaded with thousands of objects will lag considerably.

The following options mitigate or fully eliminate that problem by hiding the objects in two manners that keep Blender from getting choked, and give us a chance to save the project and organize things a little before unhiding them.

• Hide Objects After Importing (default=off): imported Area objects are hidden in the 3D Viewport (as when turning their 'eye' icon off in Outliner or using the h shortcut) to keep Blender more responsive when having massive amounts of objects per individual Collections.

  Recommended for dealing with single .json files weighting in the MegaByte range.

  Lag could persist, as the Outliner still has to list the objects, but it should be fairly tolerable.

• Exclude Collections After Importing (default=off): imported per area (per .json file) Collections are excluded from the View Layer (as when unticking their checkboxes in the Outliner or using the e shortcut') to keep Blender fully responsive and be able to manage them without any lag at all.

  Recommended when importing a massive number of areas, such as whole worlds.

  Excluded Collections won't list their objects in the Outliner, as usual, which immediately alleviates the Outliner's workload and makes Blender brisky. The idea is to activate the specific area Collection or Collections we want to tinker with and deactivate them to move on to others instead of having it all active and crush both poor Blender and our patience.

Excluding Collections resets the hide/show state of the Collections' contents. That means that, if we enable both options, Hide Objects After Importing won't produce any effect.

Texturing the objects.

In order to texture the imported objects, we recommend the use of the ZG SWTOR Tools Addon's Process Named Materials tool (instructions in the addon's page's wiki). We are considering transplanting it to this addon to simplify things.

Known Limitations.

We can't do successive imports inside a same Blender project: due to coordinate system issues, we do a final 90º rotation of the scene at the end of each import, and that would tumble any previously imported objects. We are seeing about some better way to solve this.

We just added support for "placeables" (holoprojectors, spaceship cockpits' seats, GTN Booths, etc), but it is incomplete, as some types such as FXspec objects are difficult to position in the scene adequately. We are seeing about making them present at the very least, leaving its correct placement to the user.

To Do.

• Addon-side:

  • Store Preferences at the Blender settings' level, not at the addon's one, so that they survive addon updates.
  • See if any standard Python module such as NumPy can be applied somehow to accelerate processing.
  • Check the implications of making the duplicates of imported objects unlinked (each having their own mesh data) on processing speed and Blender responsiveness.
  • imported objects may have Bone Bounds properties. Their duplicates don't, at the moment. Investigate (it might have to do with armature-driven elements such as doors) and see what else duplicates might be missing and how to solve it.
  • See if we can entirely disregard the Empties replacing DBOs.
  • Maybe transplant a materials processor from other addons, with little area-oriented utilities such as an emisive values changer, some Collection management tools, etc.

• Materials-processing addons:

  • There are lots of little materials that we need to cover: animated holograms, vegetation, glass and water…