IC Python API:Loading PFX

From Reallusion Wiki!
Revision as of 03:46, 16 December 2019 by Chuck (RL) (Talk | contribs) (Example Usage)

Jump to: navigation, search
Main article: RL Python Samples.

This article will show you how to load Popcorn FX 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 Popcorn FX Method

Let's create a handy load function that can be reused multiple times. This is useful if you are loading several Popcorn FX files in one go. We do this by search the template and custom file directories for the Particle FX 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

Ic python api loading pfx 01.png

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 Particle FX 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

Ic python api loading pfx 02.png

Now that we have a handy reusable method, we can call it multiple times to load various Popcorn FX assets.

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")