Ramses is still under active development, and this documentation is still being written.
For now, the only Add-on available for testing is the Autodesk Maya Add-On, others will follow in the upcoming weeks and months.
This specific page of the documentation is just a draft, sorry!
Ramses comes with some add-ons to be used in your creative applications (Blender, Maya, After Effects…). They are basic add-ons to demonstrate some capabilities of Ramses for file versionning and asset management, and can be used as templates to develop your own add-ons working with Ramses.
They will be developed one at a time, and you’re welcome to contribute with your own!
Here are some guidelines and descriptions about how these add-ons should work. We’re trying to apply the same guidelines to all host applications for a unified experience. These add-ons should use the provided Scripting API available at first in Python and Adobe ExtendsScript.
Although the add-ons are primarily meant to be used in conjunction with the Ramses Client Application (which in turn may be connected to the Ramses Server), they can also be used on their own. In which case not all functionnalities will be available; the differences are mentionned in this documentation.
All commands except open Ramses and Settings should first:
- If the add-on is not set to offline by the user (in the settings):
- If the path to the Client executable file is invalid: warn the user and stop.
- If the user is not connected, warn the user and stop
Open and import
Shows a selector to quickly open or import a file from the Ramses Tree.
Allows the user to select either a shot, asset or template.
The user can then select the shot or asset, and then the step, to open a file.
To make shot and asset selection easier, they can be filtered by group or sequence, and a search field is available.
Optionnaly, the user can select a specific version of the file.
When importing a file, the way it is imported and managed depends on the host application. Some options may be shown before importing.
If the file is not a working file, but a version coming from the ramses_version subfolder (named
restore-vXX), runs Save new version instead of Save.
- If the file is in the _versions folder or if its resource name contains restore-vXX.
- Increments the existing WIP file, saves over it, and increments again.
- Saves the current file.
- Backs up the file in the _versions subfolder. Version is automatically incremented if the auto-increment timeout has expired (defined in the settings).
- If online
- Send the new status of the asset/shot for this step (version, date, state, comment, completion ratio) to the Ramses Client.
Save new version & Publish
- If the file is in the ramses_version folder or if its resource name contains restore-vXX.
- Copies the current working file into the version folder, appending the state got from the Ramses client if available, or else just “v”, and the incremented version number.
- Saves the current file as the working file (in the working folder, and removing restore-XX from the resource name)
- Removes the current file (version file, keeps only the new working file) if it was a restored version
- Saves the current file.
- Copies the current file to the _versions subfolder, appending the current state and the incremented version number.
- If the file is published
- Copies the current file to the _published subfolder.
- If the client is available: sends the update command to the client, with the date, state and version of the current asset/shot, and publish information.
- Gets a specific version back from the ramses_versions subfolder.
- Copies the file to the asset/shot folder, adds
restore-vXXto the resource name, where
XXis the restored version number.
- Opens it.
It is only when the file will be saved that this new copied file will be removed and the working file will be overwritten to a new version.
Publish as template
- Saves the file in the corresponding step folder (in a “templates” subfolder), using a specific naming:
- (asks for overwrite if the file exists)
- Saves the file in a temp folder (to never overwrite a template when Ctrl+S)
- Lists the available templates
- Opens the selected one
- Saves it in a temp folder
- Lists the available templates
- Imports the selected one
- Opens the settings editor of the Add-on.
- Opens the Ramses Client if available.
- Try to connect to the Daemon.
- Warns the user if not available/cannot connect to the Daemon.
- If the Daemon is available, sets the mode to “online”. If not, sets to “offline”.
UI / UX
Depending on the host application, the implementation and User Interface / User Experience of the add-ons may vary, but they should follow these guidelines as closely as possible.
When possible, the commands should be integrated as seamlessly as possible in the host application, e.g. by adding or even replacing menu items for saving files, saving as., etc.
Especially for the save command, the default save shortcut (generally
[Ctrl] + [S]) should be replaced by the save command for Ramses. Other save command shortcuts should be added, preferably the same for all add-ons:
[Ctrl] + [S]
- Save new version:
[Ctrl] + [Alt] + [S]
[Ctrl] + [Shift] + [P]
These shortcuts have been chosen to avoid conflicts in most host applications but can be changed to something else if they’re still conflicting with something important.
If possible, each Ramses Add-on should provide a UI panel integrated into the host software, but organized similarly in all add-ons, with specific variations to respect the host software UI guidelines.
The panel must display buttons for all available commands.
The panel must also provide a way to quickly set the current Project and Step, and show the opened asset or shot information: state, version, date, comment, completion ratio… This information is retrieved from the client application if available, or from the Ramses Tree if not. The panel and this information must be updated as soon as the opened file changes, or at least when the user interacts with it.
Information available in the panel:
- Current user (online only)
- Current project
- Current shot or asset
- Containing asset group or sequence (sequence available only if online)
- Date of latest version (read only)
- Current state
- Current resource name
- Current version (read only)
- Completion ratio
- Is template (read only)
If the client application is not available, the Project and Step information is displayed but cannot be changed. Comment is not available.
If the host application provides a way to display the settings of its add-ons, the settings should be located there (and the settings command should open this location if possible). If it does not, the Add-on must provide a dialog or a panel to let the user change the settings.
These settings are:
- Location of the Ramses Client executable file (.exe on Windows, .app on MacOS, .appimage or binary on Linux)
- Listening port of the Ramses Daemon
Note: the settings are saved in a shared location (user documents folder ?) between all add-ons so that they’re configured only once. They’re in an easy-to-edit JSON text file.