gistfile1.md

RGB: ScriptManager

About

'ScriptManager' gives both Maya users & developers a simple and standardized workflow for the installation and removal of 3rd-party Maya scripts. Files are stored and maintained in an organized fashion, doing away with the process of hand-copying files into their intended Maya folders.

Usage

A) Installing 'ScriptManager'

Ironically, you must first install this installer. We hope this is the last time you need to manually install any maya script/plugin :P

1. Open Maya
2. Open Script Editor Window
3. Click menu item File > "Source Script"
4. Find and choose the file scriptManager/install.py from your downloads
5. The installer will then prompt you to located the same directory (w)

B) Install a 3rd-party script

1. Run scriptManager

   import RGB.scriptManager
   installer = RGB.scriptManager.ScriptManager()

2. Choose "Locate a Script to Install"

3. ScriptManager will then prompt you to choose the directory of the script to be installed.

4. Click "Install Script"

5. When complete, the user will be informed that the script has been installed and is ready to use. (If the installation found any issues, additional options or a message will be presented to the user.)

C) List and Edit Installed Scripts With ScriptManager UI

1. Run ScriptManager

   import RGB.scriptManager
   installer = RGB.scriptManager.ScriptManager()

2. The ScriptManager UI should list all installed scripts, with

Developers

Developers have easy control over the installation of their scripts and other supporting files by including a json-formatted file named 'install.json'. This file will be used to install all specified files and also be used to allow the user to easily update or uninstall the currently installed script/tool in the future.

For the lazy developers out there, future releases of ScriptManager will try to detect certain filetypes and directories provided and guess their appropriate installation locations. This feature should help with all the scripts in the world that haven't yet supported 'scriptManager'. Stay tuned.

Using 'install.json'

Required Data

title [string] : A unique name for the script/tool to be installed as. This defines the directory name in which all installed files will be stored within. The title should stay consistent with future updates, to allow 'scriptManager' to keep the user's preferences clean and tidy.

version [number] : Provide a version number to visually show the user what they have installed, and allow future versions of 'scriptManager' to provide options to update the script, when one is available.

files [dict]>[array]>[string] : To install files into their respective places, this defines which user path each file or directory should be placed. The keys of this dictionary should mirror Maya's 'internalVar' flags to insure installation respects the user's current settings. Define an array of relative paths of both files and directories to be copied to their respective locations. (see examples below)

* Optional Data

container [string] : This defines a parent directory to store all script related files. If defined, the directory defined in the title will be a child of this container directory. This will often be a developer's name, a company name or some other common (see examples below)

description [string] : Describe your script for the user to easily view with the ScriptManager UI

shelfButtons [array]>[dict]>[...] : Install needed shelf buttons with ease. Defined the most commonly used options with ease. (see examples below)

Example JSON Files

A) Typical Usage

This is a very simple example of a script installation.

install.json

{
    "title" : "My_Awesome_Script",
    "version" : 0.1,
    "files" : {
        "userScriptDir" : [
            "scripts/",
            "README.txt"
            ],
        "userBitmapsDir" : [
            "icons/"
            ]
    }
}

Example File Activity

.../downloads/myAwesomeScript/install.json           --> _ignored_
.../downloads/myAwesomeScript/README.txt             --> userScriptDir/My_Awesome_Script/README.txt
.../downloads/myAwesomeScript/scripts/__init__.py    --> userScriptDir/My_Awesome_Script/__init__.py
.../downloads/myAwesomeScript/scripts/mainScript.py  --> userScriptDir/My_Awesome_Script/mainScript.py
.../downloads/myAwesomeScript/icons/shelfbutton.png  --> userBitmapsDir/My_Awesome_Script/shelfbutton.png

B) Using a Container and Description

Group your scripts within a common directory and offer the user a description of your script.

install.json

{
    "title" : "My_Awesome_Script",
    "version" : 0.1,
    "description" : "This script was made by Joe Doe of ACME Studios.",
    "container" : "John_Doe",
    "files" : {
        "userScriptDir" : [
            "scripts/",
            "README.txt"
            ],
        "userBitmapsDir" : [
            "icons/",
            "johndoe_logo.png"
            ]
    }
}

Example File Activity

.../downloads/myAwesomeScript/install.json           --> _ignored_
.../downloads/myAwesomeScript/README.txt             --> userScriptDir/John_Doe/My_Awesome_Script/README.txt
.../downloads/myAwesomeScript/scripts/__init__.py    --> userScriptDir/John_Doe/My_Awesome_Script/__init__.py
.../downloads/myAwesomeScript/scripts/mainScript.py  --> userScriptDir/John_Doe/My_Awesome_Script/mainScript.py
.../downloads/myAwesomeScript/icons/shelfbutton.png  --> userBitmapsDir/John_Doe/My_Awesome_Script/shelfbutton.png
.../downloads/myAwesomeScript/johndoe_logo.png       --> userBitmapsDir/John_Doe/My_Awesome_Script/johndoe_logo.png

C) Installing Three Shelf Buttons

This shows how to install 3 shelf buttons. The first is installed in the current shelf, because "parent" was not defined. All keys correspond to the command shelfButton's available flags. (only those options below are currently supported)

install.json

{
    "title" : "My_Awesome_Script",
    "version" : 0.1,

    ...

    "shelfButtons" : [
        {
            "imageOverlayLabel" : "toolB",
            "sourceType" : "python",
            "command" : "print('hello A')"
        },
        {
            "parent" : "Animation",
            "imageOverlayLabel" : "toolB",
            "sourceType" : "python",
            "command" : "print('hello A')",
            "image1" : "shelfbuttonA.png"
        },
        {
            "parent" : "Rigging",
            "imageOverlayLabel" : "toolB",
            "annotation" : "This is tool B",
            "sourceType" : "python",
            "command" : "print('hello B')",
            "commandRepeatable" : false,
            "image1" : "shelfbuttonB.png"
        }
    ]
}

Future Plans

• auto-detect and install files without install.json
• add 'installer' to defined an existing installation script (for those who already have a install.py or install.mel)
• support installation of menus, shelves, marking menus and hotkeys
• install.json options
  • add 'author'
  • add 'contact'
    • support email and URLs
  • add 'readme' (if user prefers, prompt user with readme content)
    • support files and URLs
  • add 'history' (if user prefers, prompt user with history content)
    • support files and URLs
  • add 'license' (if developer prefers, prompt user to view / agree to license agreement)
    • support files and URLs
  • add 'dependencies'
    • not sure if this practical or posssible, but it sounds good :P
• userSetup.mel/py support
• install.json file generator
• compatibility options: OS, Maya Version, etc.

More Info

script : "ScriptManager"

author : Eriks Vitolins

contact : eriks@rgbnotes.com

website : https://rgbnotes.com