Script headers and shortcuts

Forums: Script headers and shortcuts
Forum for OctaneRender Lua scripting examples, discussion and support.

Script headers and shortcuts

Postby stratified » Mon Dec 30, 2013 1:24 am

stratified Mon Dec 30, 2013 1:24 am
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.

script_menu.png
shortcuts appearing in the script menu
script_menu.png (17.1 KiB) Viewed 1956 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
User avatar
stratified
OctaneRender Team
OctaneRender Team
 
Posts: 945
Joined: Wed Aug 15, 2012 6:32 am
Location: Auckland, New Zealand

Re: Script headers and shortcuts

Postby grimm » Mon Dec 30, 2013 1:40 am

grimm Mon Dec 30, 2013 1:40 am
Excellent, thanks Thomas. Can I add more authors to the @author line or do you put in multiple @author lines?
Linux Mint 19 x64 | Nvidia GTX 980 4GB (displays) RTX 2070 8GB| Intel I7 5820K 3.8 Ghz | 32Gb Memory | Nvidia Driver 440.31
User avatar
grimm
Licensed Customer
Licensed Customer
 
Posts: 1149
Joined: Wed Jan 27, 2010 8:11 pm
Location: Spokane, Washington, USA

Re: Script headers and shortcuts

Postby grimm » Mon Dec 30, 2013 1:43 am

grimm Mon Dec 30, 2013 1:43 am
Sorry for more questions. If the script has multiple files should they all have the same header?
Linux Mint 19 x64 | Nvidia GTX 980 4GB (displays) RTX 2070 8GB| Intel I7 5820K 3.8 Ghz | 32Gb Memory | Nvidia Driver 440.31
User avatar
grimm
Licensed Customer
Licensed Customer
 
Posts: 1149
Joined: Wed Jan 27, 2010 8:11 pm
Location: Spokane, Washington, USA

Re: Script headers and shortcuts

Postby stratified » Mon Dec 30, 2013 1:51 am

stratified Mon Dec 30, 2013 1:51 am
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
User avatar
stratified
OctaneRender Team
OctaneRender Team
 
Posts: 945
Joined: Wed Aug 15, 2012 6:32 am
Location: Auckland, New Zealand

Re: Script headers and shortcuts

Postby grimm » Mon Dec 30, 2013 1:54 am

grimm Mon Dec 30, 2013 1:54 am
Perfect, I already have the files in a sub-directory so I will add the header to the main script. Thanks,

Jason
Linux Mint 19 x64 | Nvidia GTX 980 4GB (displays) RTX 2070 8GB| Intel I7 5820K 3.8 Ghz | 32Gb Memory | Nvidia Driver 440.31
User avatar
grimm
Licensed Customer
Licensed Customer
 
Posts: 1149
Joined: Wed Jan 27, 2010 8:11 pm
Location: Spokane, Washington, USA

Return to Lua Scripting


Who is online

Users browsing this forum: No registered users and 1 guest

Mon Nov 18, 2019 6:14 am [ UTC ]