Introduction to Adding Objects - Kizari/Flagrum GitHub Wiki

Solheim Statue near Galdin Quay

• Introduction
• Finding a Model
• Calculating Location
• Editing the Script
• Applying Edits to Game
• Caveats

One of first techniques to learn while familiarizing yourself with ebex & prefab scripts involve manipulating where and what objects load into the world with rest of the environment. Using Flagrum, we are able to find objects and place them with precision where we want using information we find in Blender.

Though not required to fully understand, it is recommended you at least read Introduction to Script Editing to have a better understanding on the structure of scripts and nodes.

This guide will also make use of Flagrum's Environment Exporter both to help you find base level scripts that reference a model you may want to add, and for finding position information while placing your object. Review the guide Importing Environments into Blender for tips utilizing this tool.

NOTE: For help finding certain models and props, use the FFXV Game File List. The file list also includes a section for finding particular environments and notable elements contained within.

After deciding on what model you want to add to the game:

1. Load an environment file that you have exported with the Environment Exporter the contains the model you would like to use. In this example, we have exported map_du_d17_a_plan.ebex.

2. Find the model you want and while hovering the mouse over Scene Collection press the . key to highlight and expand the collection the model is in for this environment. The name of the collection represents the script file that references the model directly. In this case d17_mgm.prefab directly references d17_pr_mgm_1A.gmdl. And map_du_d17_a_plan references the prefab.

3. Looking at the script file back in our editor, we can search for d17_mgm to find the source path for the prefab. Looking at both, we can see that all transforms (position, scale and rotation) are defined in map_du_d17_a_plan, with a node type of "SQEX.Ebony.Framework.Entity.EntityPackageReference". The Package reference will allow us to also place other elements packed with our model instead of referencing each element individually. We will be referencing this later, but for now we are ready to load our next environment.

NOTE: When a structure is a collection of models instead of just one, you can reference the entire collection instead of each individual model

4. It is recommended when adding an object, to find an environment that already loads objects into the same area. This will help ensure the models you are adding load when expected, as well as prevents the game from loading the models unnecessarily. It is suggested, but not required to also use the same script you are editing as the environment you import into Blender to save yourself some math.

5. In this example, we have exported map_ld_gq_a_env. By exporting and editing the same file, all transforms will be identical in game as they are in Blender. If we had exported either area_leide or group_galdin however, we would need to find any transforms applied between the exported script and the edited script. In this case, we would have to adjust position by [-2842,0,2651].

NOTE: Rotations can differ in game than you see in Blender and may need manual adjustments.

6. FFXV uses Maya coordinates in-game. This means Y is up. In practice, [X,Y,Z] in Blender is switched to [X,Z,-Y] in game, where Y is swapped with Z and inverted in value. If you are ever unsure how the numbers are translated. Select a model that already existed in both the environment and script and compare location information.

7. Using either an imported model, or simply by using Blender's cursor [Shift Spacebar + Spacebar], find the exact location you would like your model to load.

Example comparing Blender and Game Coordinates.

8. Open back up the script you are adding to, in this example map_ld_gq_a_env.ebex, and transfer the EntityPackageReference we got from our source script.

9. We need an unused objectIndex number that our models can use. For us, the first free index is objectIndex="98". As discussed in Introduction to Script Editing, we will also adjust the ownerPath, path, ownerIndex, and owner to align with the container that will reference our model. And we can leave type, name and original_type the same, though as long as name matches the reference name, that can also be changed if desired. In this example, we will add a reference to our model in objectIndex="0". Since most of the models in this script do the same, we can refer to similar objects in the script to see how they are formatted if we are ever uncertain about declaring an object's attributes.

Original

<object objectIndex="1895" ownerPath="entities_" checked="True" type="SQEX.Ebony.Framework.Entity.EntityPackageReference" path="entities_.room07_ALL.entities_.d17_mgm" name="d17_mgm" ownerIndex="1826" owner="entities_.room07_ALL" original_type="Black.Entity.Prefab.Prefab">

Adjusted

<object objectIndex="98" ownerPath="entities_" checked="True" type="SQEX.Ebony.Framework.Entity.EntityPackageReference" path="entities_.d17_mgm" name="d17_mgm" ownerIndex="0" owner="" original_type="Black.Entity.Prefab.Prefab">

10. Similarly, we will need to adjust the position of the model with the new position we found in blender. The position in the original file was [55.87231,-281.8423,-65.15832,1]. In Blender, we wanted to change the position to X="-200", Y="-457.76758" and Z="-40". As discussed in Step 6, the Blender coordinates when being used for the game will need to be written out as <position_ type="float4">-200,-40,457.76758,1</position_>, once again noting the Y and Z values are swapped, and the value of Y became positive.

11. The game frequently uses relative paths i.e(../../environment/) when referencing data outside of the script. Though in this case the relative path would still work for us, changing the path to its absolute path will ensure the game references the correct set of data.

<sourcePath_ type="string">environment/dungeon/d17/prefab/d17_mgm.prefab</sourcePath_>

12. The last edit we need is to add a new line back in objectIndex="0" referencing your new object's index number and path. Without this, our new object will be ignored by the game. Save your file, and open up Flagrum.

Note: All objects need to be referenced in a container with the correct index numbers and paths.

13. Finally, open Flagrum and navigate to Mod Manager. Select the Create Mod button at the top-right to open a New EARC Mod page and select Replace Asset. Navigate to the environment script you edited, select the new version, and you are ready to save the mod!

Transforms
Some models have transforms such as position, rotation and scale declared in multiple places. If you are referencing a .prefab for example, verify the prefab sets the position to [0,0,0,1], or adjust your coordinates accordingly. Rotational transforms may occasionally produce different results than intended, even if no additional transforms are declared. If that is the case, you may need to manually adjust rotations to get the desired angle.

**Note: When comparing locations from a top-level environment like area_duscae to a environment that is transformed multiple times, it may be helpful to set up an excel sheet if you intend to be placing more than a couple objects in this manner. You can setup the excel sheet to both convert to and from game positions and blender positions.

Static and Skeletal Model Entities
Though the same principles can be used for most object types, this guide was designed for basic Static and Skeletal Model Entities, as well as environment scripts that reference them. You can extrapolate by observing how other object types are referenced and expand the scope to include those objects as well. For example, item locations, enemy spawn boundaries, climate boxes, safe areas etc...

Location Accuracy
Blender will sometimes display rounded location values to the nearest centimeter, you can usually click within the location field within to expand and view the full location.