IC Python API:Loading PFX
- Main article: RL Python Samples.
This article will show you how to load PopcornFX assets into the scene from the template and custom library paths. This lesson is applicable for other asset types such as Avatars, Props, Terrains, and more; as long as you know where the asset file directories are located.
Necessary Modules
Besides the rudimentary Reallusion Python module, we'll also need the os module to read from the windows file system.
import RLPy
import os
Load PopcornFX Method
Let's create a handy load function that can be reused multiple times. This is useful if you are loading several PopcornFX files in one go. We do this by search the template and custom file directories for the PopcornFX file by name. Once it is found, we load the asset file into the scene and return the object that was instantiated.
def LoadPopcornFX(name, case_sensitive=True, template_first=True):
'''
Load a PopcornFX file by it's name (without the extension).
Args:
name (String): The name of the PFX file without the extension.
case_sensitive (Bool): Whether or not to use case sensitive search.
template_first (Bool): Changes the search priority between Template and Custom paths
Returns:
RIObject: A reference to the PFX object loaded into the scene.
'''
template_data_path = RLPy.RApplication.GetTemplateDataPath()
template_data_path += '\\iClone Template\\Particle\\'
custom_data_path = RLPy.RApplication.GetCustomDataPath()
custom_data_path += '\\Particle\\'
for directory in [template_data_path, custom_data_path] if template_first else [custom_data_path, template_data_path]:
for root, dirs, files in os.walk(directory):
for f in files:
if f == name+".iPkfx" if case_sensitive else f.lower() == name.lower()+".ipkfx":
popcornfx_file_path = os.path.join(root, f)
load_object = RLPy.RFileIO.LoadObject(popcornfx_file_path)
return load_object
Notice that some useful arguments have been included to assist in the search. They are optional arguments because we have provided the logical default values.
File Not Found Messaging
Next, we should tell the user if the file has not been found. This is done with a simple modal message window.
# No matching file was found -notify the user
RLPy.RUi.ShowMessageBox(
"PFX File Not Found",
'''No matching Popcorn ParticleFX file was found!
Please check the file name for errors
and capitalization for case-sensitive search.''',
RLPy.EMsgButton_Ok)
This segment of code is final part of the LoadPopcornFX method.
Example Usage
Now that we have a handy reusable method, we can call it multiple times to load various PopcornFX assets. After loading the PFX files, you should playback to view the particles effects in action.
LoadPopcornFX("DOF Kidneys")
explosion_fx = LoadPopcornFX("Explosion")
text_fx_01 = LoadPopcornFX("LED Text")
text_fx_02 = LoadPopcornFX("LED Text")
error_fx = LoadPopcornFX("Non-existing PFX")
Notice that assigning a loaded asset does not need to be assigned to a variable -the returned value is simply discarded. Also the same particle file can be called multiple times for multiple instantiations.
Everything Put Together
You can copy and paste the following code into a PY file and load it into iClone via Script > Load Python.
import RLPy
import os
def LoadPopcornFX(name, case_sensitive=True, template_first=True):
'''
Load a PopcornFX file by it's name (without the extension).
Args:
name (String): The name of the PFX file without the extension.
case_sensitive (Bool): Whether or not to use case sensitive search.
template_first (Bool): Changes the search priority between Template and Custom paths
Returns:
RIObject: A reference to the PFX object loaded into the scene.
'''
template_data_path = RLPy.RApplication.GetTemplateDataPath()
template_data_path += '\\iClone Template\\Particle\\'
custom_data_path = RLPy.RApplication.GetCustomDataPath()
custom_data_path += '\\Particle\\'
for directory in [template_data_path, custom_data_path] if template_first else [custom_data_path, template_data_path]:
for root, dirs, files in os.walk(directory):
for f in files:
if f == name+".iPkfx" if case_sensitive else f.lower() == name.lower()+".ipkfx":
popcornfx_file_path = os.path.join(root, f)
load_object = RLPy.RFileIO.LoadObject(popcornfx_file_path)
return load_object
# No matching file was found -notify the user
RLPy.RUi.ShowMessageBox(
"PFX File Not Found",
'''No matching Popcorn Particle FX file was found!
Please check the file name for errors
and capitalization for case-sensitive search.''',
RLPy.EMsgButton_Ok)
LoadPopcornFX("DOF Kidneys")
explosion_fx = LoadPopcornFX("Explosion")
text_fx_01 = LoadPopcornFX("LED Text")
text_fx_02 = LoadPopcornFX("LED Text")
error_fx = LoadPopcornFX("Non-existing PFX")
APIs Used
You can research the following references for the APIs deployed in this code.
