Script headers and shortcuts

[stratified]

Hi all,

In the upcoming 1.24 release Octane will analyze the script header and add the possibility to assign shortcuts to scripts. A script header is just a comment that appears on top of your script. Ideally you describe here what your script does, how to use it, the author, ... . The full header must appear in the first 50 lines of the script, we don't bother scanning the full script.

A typical header would look like this:

Code: Select all

-- Renders a turntable animation and saves it on disk. To use it, select the desired
-- render target and then run the script.
-- 
-- @description Renders a turntable animation and saves it on disk.
-- @author      Thomas Loockx
-- @shortcut    ctrl + 3
-- @version     0.1
--

Notice there are a few words starting with an @ character. These are special keywords that Octane recognizes. The syntax is @keyword some text that fits on a single line. The keywords that Octane knows are:

• @description short description of what the script does
• @author the guy who wrote the script
• @shortcut shortcut to run the script, in the format modifier + key. Allowed modifiers are (ctrl, alt, shift) and key is a single number, character or punctuation.
• version version number of the script

When you modify a script's header it's important to reload the scripts (menu > script > reload scripts). Octane only scans the scripts in the user directory on startup and reload.

shortcuts appearing in the script menu

script_menu.png (17.1 KiB) Viewed 4877 times

Special care needs to be taken when assigning shortcuts. When you would map your script to a shortcut that already exists in Octane, the Octane shortcut takes precedence. When mapping 2 scripts to the same shortcut, the script that's alphabetically first will receive the shortcut. For reference, these are the existing shortcuts in Octane:

• ctrl + n : New Project
• ctrl + o : Open Project
• ctrl + s : Save Project
• ctrl + q : Quit Octane
• ctrl + x : Cut Selected Items
• ctrl + c : Copy Selected Items
• ctrl + v : Paste Items
• cmd + , : Show Preferences (Apple Only)
• delete : Delete Selected Items
• m : Toggle Material Picking
• f : Toggle Focus Picking
• t : Toggle Target Picking
• F2 : Unfold Selected Items

For users planning on distributing their own scripts for fun and profit. Try to be diligent in writing a clear script header. Later, when we make scripts available via LiveDB, we require this header from script writers. When assigning a shortcut, clearly document it. Otherwise you could be overriding shortcuts used by other scripts.

If there are any questions, please ask. If there's need for extra @keywords, we're open for suggestions.


cheers,
Thomas

[grimm]

Excellent, thanks Thomas. Can I add more authors to the @author line or do you put in multiple @author lines?

[grimm]

Sorry for more questions. If the script has multiple files should they all have the same header?

[stratified]

There's only support for a single @keyword of each type. If you would add multiple @author keywords, only the last one is used (same goes for the other keywords). So multiple authors would go on a single line. We don't do anything special with this keyword, we treat it as a string. The only special one (for now) is @shortcut. Octane is not really interested in what is behind the keyword, except for the shortcut keyword

When spreading your script over multiple files, you should add the header in the file that "requires" the others. Ideally the other files go into a seperate directory under the script directory so that they're not picked up in the menu.

cheers,
Thomas

[grimm]

Perfect, I already have the files in a sub-directory so I will add the header to the main script. Thanks,

Jason