Ramses

The main class. One (and only one) instance globally available (Ramses is a singleton), by calling Ramses.instance().

Static Methods

Method	Arguments	Description
instance ▹ Ramses		Returns the Ramses unique instance.
version ▹ string		The current version of this API

Static Attributes

Attribute	Type	Default	Description
apiReferenceUrl	string	This page URL	A link to this API documentation
addonsHelpUrl	string	The URL to this page	A link to the Ramses add-ons documentation
generalHelpUrl	string	The URL to this documentation	A link to the Ramses documentation

Attributes

Read the section entitled Events and Handlers below (and see the Examples) for more information about the methods you can add to these lists.

Attribute	Type	Default	Description
importScripts	list	[]	A list of functions to be triggered when Ramses.instance().importItem() is called. If you’re using one of the provided Add-ons, you can add your own handlers to this list so they’re run when the user asks to import an item. Note: official Ramses Add-ons will add an item to this list to provide a default implementation. If you’re extending an existing add-on, you can reset the list or insert/append your own methods to keep the default behavior.
openScripts	list	[]	A list of functions to be triggered when Ramses.instance().openFile() is called. If you’re using one of the provided Add-ons, you can add your own handlers to this list so they’re run when the user opens an item in the host application. Note: official Ramses Add-ons will add an item to this list to provide a default implementation. If you’re extending an existing add-on, you can reset the list or insert/append your own methods to keep the default behavior.
publishScripts	list	[]	A list of functions to be triggered when Ramses.instance().publish() is called. If you’re using one of the provided Add-ons, you can add your own handlers to this list so they’re run when the user publishes the current file from the host application. Note: official Ramses Add-ons will add an item to this list to provide a default implementation. If you’re extending an existing add-on, you can reset the list or insert/append your own methods to keep the default behavior.
replaceScripts	list	[]	A list of functions to be triggered when Ramses.instance().replaceItem() is called. If you’re using one of the provided Add-ons, you can add your own handlers to this list so they’re run when the user asks to import an item. Note: official Ramses Add-ons will add an item to this list to provide a default implementation. If you’re extending an existing add-on, you can reset the list or insert/append your own methods to keep the default behavior.
saveAsScripts	list	[]	A list of functions to be triggered when Ramses.instance().saveFileAs() is called. If you’re using one of the provided Add-ons, you can add your own handlers to this list so they’re run when the user saves the current file in the host application. Note: official Ramses Add-ons will add an item to this list to provide a default implementation. If you’re extending an existing add-on, you can reset the list or insert/append your own methods to keep the default behavior
saveScripts	list	[]	A list of functions to be triggered when Ramses.instance().saveFile() is called. If you’re using one of the provided Add-ons, you can add your own handlers to this list so they’re run when the user saves the current file in the host application. Note: official Ramses Add-ons will add an item to this list to provide a default implementation. If you’re extending an existing add-on, you can reset the list or insert/append your own methods to keep the default behavior
saveTemplateScripts	list	[]	A list of functions to be triggered when Ramses.instance().savTemplate() is called. If you’re using one of the provided Add-ons, you can add your own handlers to this list so they’re run when the user saves the current file as a new template in the host application. Note: official Ramses Add-ons will add an item to this list to provide a default implementation. If you’re extending an existing add-on, you can reset the list or insert/append your own methods to keep the default behavior.
statusScripts	list	[]	A list of functions to be triggered when Ramses.instance().updateStatus() is called. If you’re using one of the provided Add-ons, you can add your own handlers to this list so they’re run when the user changes the current status of an asset / shot from the host application.
userScripts	dict or object	{}	This dict or object is here for your convenience, to make it easy to register and call any method from anywhere you’ve imported Ramses without having to import the file containing the method. Just register with Ramses.instance().userScripts["TheFunctionName"] = aFunction and call the method with Ramses.instance().userScripts["TheFunctionName"](some, args).

Methods

Method	Arguments	Description
addToRecentFiles	• string: filePath	Adds the file to the list of recently opened files, to be used in the DCC app to list these files to the user. The list of recent files is available as RamSettings.instance().recentFiles.
alternativeFolderPaths ▹ list of string		A list of alternative absolute paths to the main Ramses folder. Missing files will be looked for in these paths (and copied to the main path if available), and they will be used if the main path is not available.
backupFolderPath ▹ list of string		A copy of the main folder where all files are stored.
connect ▹ boolean		Checks Daemon availability and initiates the connection. Returns success.
currentProject ▹ RamProject or None		The current project.
currentUser ▹ RamUser or None		The current user.
daemonInterface ▹ RamDaemonInterface		The Daemon interface unique instance. Same as RamDaemonInterface.instance()
disconnect ▹ boolean		Gets back to offline mode (stops all communications with the Daemon).
folderPath ▹ string		The absolute path to main Ramses folder, containing projects by default, config files, user folders, admin files…
importItem	• string: currentFilePath • list of string: importFilePaths • RamItem or RamAsset or RamShot: item • RamStep: step=None • dict: importOptions=None • bool: showImportOptions=false	Runs the scripts in Ramses.instance().importScripts. Read the section entitled Events and Handlers below for more details. This method returns an error code: • -1: One of the event handlers interrupted the process. • 0: OK.
openFile	• string: filePath	Runs the scripts in Ramses.instance().openScripts. Read the section entitled Events and Handlers below for more details. This method returns an error code: • -1: One of the event handlers interrupted the process. • 0: OK.
project ▹ RamProject or None		(Try to) retrieve a project using its short name.
projects ▹ list of RamProject		The list of available projects.
projectsPath ▹ string		The path to the folder containing projects.
states ▹ list of RamState		The list of available states.
state ▹ RamState	• string: stateShortName=WIP	Gets a specific state.
online ▹ boolean		True if connected to the Daemon and the Daemon is responding.
publish	• string: filePath, • dict: publishOptions=None, • bool: showPublishOptions=false	Runs the scripts in Ramses.instance().publishScripts. Read the section entitled Events and Handlers below for more details. This method returns an error code: • -1: One of the event handlers interrupted the process. • 0: OK.
replaceItem	• string: currentFilePath • string: importFilePath • RamItem or RamAsset or RamShot: item • RamStep: step=None • dict: importOptions=None • bool: showImportOptions=false	Runs the scripts in Ramses.instance().replaceScripts. Read the section entitled Events and Handlers below for more details. This method returns an error code: • -1: One of the event handlers interrupted the process. • 0: OK.
saveFile ▹ int	• string: filePath • bool: incrementVersion=false • string: comment=None • string:newStateShortName:None	Runs the scripts in Ramses.instance().saveScripts. Read the section entitled Events and Handlers below for more details. This method returns an error code: • -1: One of the event handlers interrupted the process. • 0: OK. • 1: Malformed file name, can’t get the item from the file. The file was not saved. • 2: The file was a restored version, it’s been incremented then saved as a working file. • 3: The file was misplaced (in a reserved folder), and was incremented and saved in the right place. • 4: The file was too old (according to RamSettings.autoIncrementTimeout) and was incremented and saved.
saveFileAs ▹ int	• string: currentFilePath • string: fileExtension • RamItem or RamAsset or RamShot: item • RamStep: step • string: resource=""	Runs the scripts in Ramses.instance().saveAsScripts. Read the section entitled Events and Handlers below for more details. This method returns an error code: • -1: One of the event handlers interrupted the process. • 0: OK. • 1: Saved as a new version because the file already exists.
saveTemplate ▹ int	• string: fileExtension • RamStep: step • string: templateName="Template"	Runs the scripts in Ramses.instance().saveTemplateScripts. Read the section entitled Events and Handlers below for more details. This method returns an error code: • -1: One of the event handlers interrupted the process. • 0: OK.
showClient		Raises the Ramses Client window, launches the client if it is not already running.
setCurrentProject	• RamProject: project	Sets the current project.
settings ▹ RamSettings		The settings unique instance. Same as RamSettings.instance()
updateStatus	• RamItem or RamAsset or RamShot: item, • RamStatus: status, • RamStep: step=None	Runs the scripts in Ramses.instance().statusScripts. Read the section entitled Events and Handlers below for more details. This method returns an error code: • -1: One of the event handlers interrupted the process. • 0: OK.
usersPath ▹ string		The path to the folder containing users.

Events and Handlers

Some events are triggered by Ramses on specific actions, like opening a file in the host application or importing an asset. Handlers are functions to be run when these events are triggered. For each of these events, you can add your own handlers if you’re developping an add-on, and the end-user can also register script files containing handlers for these events.

• When developping the add-on: add the handler function to the corresponding list, like Ramses.openScripts or Ramses.importScripts for example.
• Adding a user script: add script files to the settings (with the UI of the add-on if available, or programmatically with RamSettings.userScripts). These script files must define a function for the desired event(s) named after the event.

There are two types of handler functions per event:

• before_event handlers are run before the default methods of the add-on (before all methods stored in Ramses.eventScripts).
• on_event handlers are run after the default methods of the add-on.

Ramses will pass a few arguments depending on the context to these handler functions.

Handlers must return true or nothing to let the process continue, and can return false to stop the process (the event propagation) and the next registered handlers.

Event	Arguments	Description
before_import_item | on_import_item Trigger function: Ramses.importItem() Handler function list: Ramses.importScripts	• list of string: filePaths, • RamItem or RamAsset or RamShot: item, • RamStep: step=None, • dict: importOptions=None, • bool: showImportOptions=false	• filePaths is the list of absolute path to the files the user wants to import. This list can be empty! In this case, it means the add-on must automatically choose the right file from the publish folder of the item and step. • item is the item from which the user wants to import a file. • step is the step from which the user wants to import. • importOptions is a dictionnary (associative array) containing custom options you can use to import the item, automatically built from the pipeline configuration, if these options have been set. • showImportOptions tells the script to show a UI or not to edit the import options before importing.
before_open | on_open Trigger function: Ramses.openFile() Handler function list: Ramses.openScripts	• string: filePath, • RamItem or RamAsset or RamShot: item, • RamStep: step=None	• filePath is the absolute path of the file being opened. • item is the item the user has opened. • step is the step being opened.
before_publish | on_publish Trigger function: Ramses.publish() Handler function list: Ramses.publishScripts	• string: filePath • RamItem or RamAsset or RamShot: item • RamStep: step • dict: publishOptions=None • bool: showPublishOptions=false	• filePath is the path of the file currently being published. • item is the item from which the user wants to publish a file. • step is the step from which the user is publishing. • publishOptions is a dictionnary (associative array) containing custom options you can use to publish the item. • showPublishOptions tells the script to show a UI or not to edit the publish options before publishing.
before_replace_item | on_replace_item Trigger function: Ramses.replaceItem() Handler function list: Ramses.replaceScripts	• string: filePath, • RamItem or RamAsset or RamShot: item, • RamStep: step=None, • dict: importOptions=None, • bool: showImportOptions=false	• filePath is the absolute path to the file the user wants to import. • item is the item from which the user wants to import a file. • step is the step from which the user wants to import. • importOptions is a dictionnary (associative array) containing custom options you can use to import the item, automatically built from the pipeline configuration, if these options have been set. • showImportOptions tells the script to show a UI or not to edit the import options before importing. With this info, the method should replace selected objects with the imported items.
before_save | on_save Trigger function: Ramses.saveFile() Handler function list: Ramses.saveScripts ▹ bool	• string: filePath, • RamItem or RamAsset or RamShot: item, • RamStep: step, • int: version, • string: comment, • bool: incremented	• filePath is the absolute path of the file being saved. • item is the item the user has saved. • step is the step being saved. • version is the version number for the file being saved. • comment is the comment associated to this version of the file. • incremented is true if this is a new version.
before_save_as | on_save_as Trigger function: Ramses.saveFile() Handler function list: Ramses.saveScripts ▹ bool	• string: filePath • RamItem or RamAsset or RamShot: item • RamStep: step • string: resourceName	• filePath is the absolute path of the file being saved. • item is the item the user has saved. • step is the step being saved. • resourceName is the name of the resource, this can be an empty string for the main working file.
before_save_template | on_save_template Trigger function: Ramses.saveFile() Handler function list: Ramses.saveScripts ▹ bool	• string: filePath • RamItem: item • RamStep: step • string: templateName	• filePath is the absolute path of the file being saved. • item is the item the user has saved. • step is the step being saved. • templateName is the name of the template.
before_update_status | on_update_status Trigger function: Ramses.updateStatus() Handler function list: Ramses.statusScripts	• RamItem or RamAsset or RamShot: item, • RamStatus: status, • RamStep: step	• item is the item which is being updated. • status is the new status. • step is the step being updated.

Examples

Adding handlers with a user script file

Users can add their own handlers for specific events by just storing them in script file(s) and implementing a function named after the event(s).
This is a simple example of a file like this containing a few handlers.

# handlers.py

def on_open( file_path, item, step):
    """Triggered when an item is opened by the user"""

    if step.shortName() == "LIGHT":
        # Do Something here if it's a lighting step being opened
        doSomething(item)
        print("We've opened the Lighting step for" + item.name())
    else:
        print("Nothing to do for unknown steps...")

def on_publish(  file_path, item, step,import_options, show_import_options):
    """Triggered when an item is published"""

    if step.shortName() == "MOD":
        # Show options to the user
        if show_import_options:
            options_dialog = show_options_ui()
            import_options = options_dialog.getResult()
        # Do Something here if it's a modeling step being published
        doSomething(item, import_options)
        print("We've published the Modeling step for" + item.name())
    else:
        print("Nothing to do for unknown steps...")

// handlers.jsx

// Triggered when an item is opened by the user
function on_open( file_path, item, step) {

    if (step.shortName() == "LIGHT") {
        // Do Something here if it's a lighting step being opened
        doSomething(item);
        $.writeln("We've opened the Lighting step for" + item.name());
    }
    else {
        $.writeln("Nothing to do for unknown steps...");
    }
}

// Triggered when an item is published
function on_publish( file_path, item, step, import_options, show_import_options):

    if (step.shortName() == "MOD") {
        // Show options to the user
        if (show_import_options) {
            var options_dialog = show_options_ui();
            import_options = options_dialog.getResult();
        }
        // Do Something here if it's a modeling step being published
        doSomething(item, import_options);
        $.writeln("We've published the Modeling step for" + item.name());
    }
    else{
        $.writeln("Nothing to do for unknown steps...");
    }

These script files can be registered using the UI of the add-on or by adding them in the settings programmatically like this:

# Python

# import ramses
import ramses as ram
# Get the instance
ramses = ram.Ramses.instance()

# The script containing the handlers
script_file = "/path/to/my/handlers.py"
# Register
settings = ramses.settings()
settings.userScripts.append( script_file )
settings.save()

# All handlers in the script file are now registered and will be run automatically with corresponding events

// ExtendScript

// include the Ramses lib
#include ramses.jsxinc
// Get the instance
var ramses = Ramses.instance();

// The script containing the handlers
var scriptFile = "/path/to/my/handlers.py";
// Register
var settings = ramses.settings();
settings.userScripts.push( scriptFile );
settings.save();

// All handlers in the script file are now registered and will be run automatically with corresponding events

Adding handlers when implementing/extending an add-on

# Python

# import ramses
import ramses as ram
# Get the instance
ramses = ram.Ramses.instance()

# A simple method
def published(filePath, item, step):
    ram.log("Hello, I've been published!")

# Another one
def aFunction( arg1, arg2):
    ram.log("I'm doing something")

# Adds the method to the scripts which will be run when the add-on publishes a file
ramses.publishScripts.append( published )

# Let's store a function in the userScripts to make it available everywhere
ramses.userScripts["MyFunction"] = aFunction

# The provided Ramses add-ons for Blender, Maya, etc. automatically trigger these scripts.
# If you're developping another addon, you have to call Ramses.publish() to run them
ramses.publish(currentItem, 'a path', 'STEP')

# From anywhere in the app where the Ramses module has been imported, you can call 'aFunction' with
ramses.userScripts["MyFunction"](some, arg)

// ExtendScript

// include the Ramses lib
#include ramses.jsxinc
// Get the instance
var ramses = Ramses.instance();

// A simple method
function published(filePath, item, step)
{
    ram.log("Hello, I've been published!");
}

// Another one
function aFunction( arg1, arg2)
{
    ram.log("I'm doing something");
}

// Adds the method to the scripts which will be run when the add-on publishes a file
ramses.publishScripts.push( published );

// Let's store a function in the userScripts to make it available everywhere
ramses.userScripts["MyFunction"] = aFunction;

// The provided Ramses add-ons for Blender, Maya, etc. automatically trigger these scripts.
// If you're developping another addon, you have to call Ramses.publish() to run them
ramses.publish(currentItem, 'a path', 'STEP');

// From anywhere in the app, you can call 'aFunction' with
ramses.userScripts["MyFunction"](some, arg);

---

API Dev notes

Private attributes

Attribute	Type	Default	Description
defaultState	RamState		The state to use as default (“WIP”).