In HScript, you can assign strings to variables with the set command:

A variable name must begin with letter or an underscore (_), followed by any number of letters, numbers or underscores.

To use a variable in a command, prefix its name with a dollar sign ($):

> set foo = "bar"
> echo $foo
bar

You can optionally enclose the name of the variable in curly braces ({}) to prevent the variable name from running into surrounding text:

> echo ${foo}baz
barbaz

In addition, when you use curly braces HScript will expand variable references in the name before looking up its value. This lets you simulate simplistic arrays:

set foo1 = Padma
set foo2 = Mohammed
for i = 1 to 2 echo ${foo$i} end
Padma
Mohammed

In HScript, variables can be local or global (sometimes called system variables).

Local variables are local to the script being run. When the script is finished, the variable disappears. Local variables cannot be used outside the script in which they're defined. To create or set a local variable, use set. The variables created by the for and foreach loops are always local.

Global variables are available to all scripts and to any programs started by Houdini. To create or set a global variable, use setenv or set -g.

> set afile = /home/matt/bin/foo.bar
> echo $afile:e
bar
> echo ${afile:e}
bar

> echo ${afile:h}
/home/matt/bin

> echo ${afile:t}
foo.bar

> echo ${afile:e}
bar

> echo ${afile:r}
/home/matt/bin/foo

> echo ${afile:s}/foo/baz/
/home/matt/bin/baz.bar

> set str = Hello There
> echo ${str:u}
HELLO THERE

> set str = Hello There
> echo ${str:l}
hello there

set A = "foo1 foo2 foo3 foofoo4"

$A:u == "Foo1 foo2 foo3 foofoo4"
$A:u:u == "FOo1 foo2 foo3 foofoo4"
$A:gu == "Foo1 Foo2 Foo3 Foofoo4"
$A:gu:u == "FOo1 Foo2 Foo3 Foofoo4"
$A:au == "FOO1 FOO2 FOO3 FOOFOO4"

$A:s/foo/bar/ == "bar1 foo2 foo3 foofoo4"
$A:s/foo/bar/:s/foo/bar/ == "bar1 bar2 foo3 foofoo4"
$A:gs/foo/bar/ == "bar1 bar2 bar3 barfoo4"
$A:as/foo/bar/ == "bar1 bar2 bar3 barbar4"

Unlike expression functions, HScript commands are not functions and do not have return values. They just print output to the textport. If you try to assign the result of a command to a variable, as in:

set objects = opls /obj

…you’ll just get the string "opls /obj" in the $objects variable. However, you can capture the output of a command as a string and put it in a variable to achieve the same effect. To capture the output of a command, put it inside a run expression function and then use backquotes to evaluate the expression in HScript. Essentially, you're calling HScript inside an expression (to get a return value) inside HScript.

set objects = `run("opsls /obj")`
echo $objects
model ambient1 light1 light2 light3 cam1

To redirect the output of an HScript command to a file, use >filename in the command. To append to the file instead of overwriting it, use >>filename. To redirect the error output and the standard output of a command, use >&filename.

When using the unix command to launch an external process, you may want to do redirection in the external shell instead of in the textport. Enclose the argument in single quotes to prevent the Houdini command interpreter from acting on the redirection before the external shell can see it.

unix myscript.pl '>output.txt'

You can use these operators in the if and while structures:

You can enclose HScript expressions in parentheses for clarity, but it is not necessary:

for i = 1 to 10
...
end

for (i = 1 to 10)
...
end

Text inside single quotes (') is not expanded.

Text inside double quotes (") has variables expanded.

A double-quoted string is considered one argument.

A backslash character (\\) escapes the next character. For example, to use double-quotes in a string: "I had a \\"great\\" time.".

When a string doesn’t require variable expansion, use single quotes to speed up evaluation.

If you have two quoted strings next to each other with no spaces, they are considered a single argument.

For example:

set foo = "Hello world"
echo '$foo='"$foo"
$foo=Hello world

…the echo command has one argument: '$foo=Hello world'.

HScript evaluates backquotes with a higher priority than double quotes. If a double-quoted argument encloses a back-quoted string, the back-quoted string may contain double quotes without terminating the initial double quote delimiter.

For example, the string:

foo`ch("/obj/geo1/tx")`

…is considered a single argument.

As a general rule, do not include spaces between backquotes and what’s inside them. Houdini may not evaluate them if there are extra spaces.

Everything following a # character on a line is considered a comment. To use a literal # in an unquotes string without starting a comment, put a backslash (\\) in front of it.

Houdini splits input lines into words at space characters. The special characters ; < > ( ) = form separate words and Houdini will insert spaces around these characters in unquoted strings. HScript is very lax about arguments. Basically anything it doesn’t understand as a command or option, it will treat as a string. This can be useful when not having to put quotes around something makes multiple levels of quoting easier. However, it may insert extra spaces around special characters in unquoted strings.

As a general rule, you should put quotes around strings you don’t want HScript to alter.

The textport lets you input HScript commands and see the results. To open a new textport window, choose Windows > HScript textport. To put a textport in a pane, open the pane’s Pane menu and choose Textport.

• Quick copy and paste: select text, then click to immediately paste it into the command line.

• Quick help: type help command_name to print a text version of the command’s online help in the textport.

• Type ahead: you can start typing new commands before Houdini has finished executing the current command. Houdini will execute the "buffered" commands when it’s done.

• Scrolling: use Page up and Page down to scroll, or press to grab the contents of the window and drag.

• Continuation: if you press Enter in a command line that’s not finished (for example, in the middle of a for loop), the command line will continue until you finish the open block (with end).

• Command history

  Recall a previous command on the command line

  Press ↑ and ↓ to move through the history of previous commands. You can edit the text of the recalled command before executing it.

  Repeat the last command

  Type !! on the command line.

  Repeat a previous command

  Type !-num on the command line to execute the command from num entries ago. For example, type !-5 to repeat the fifth most recent command.

  Repeat the last command matching a pattern

  Type !string on the command line to execute the previous command containing string.

  View the command history

  Use the history command to print the command history.

• Create aliases of commonly used commands

  In HScript you can use the alias command to assign are frequently used command, often with arguments, to a new command name. For example, if you find you frequently need to list the names of the objects in the scene, you can assign the command to the shorter, easier to type alias objs.

  alias objs "opls /obj"
  

  Now typing objs on the command line will execute opls /obj.

  HScript’s alias expansion is not as sophisticated as csh. For example, there is no recursive alias expansion; the following sequence of commands will not produce the expected result:

  alias opcd opcf
  alias cd opcd
  

  The cd alias will result in an unknown command "opcd" message since the alias expansion terminates after the first expansion.

  Also, HScript’s alias expansion does not include the history meta-character substitution feature of csh.

The hscript application is in $HFS/bin. Running it on the system command line will give you a console similar to the textport in which you can run HScript commands and see the results.

The hscript application lets you write batch scripts that exercise the full power of Houdini without having to start up the entire graphical interface.

Use hscript -q on the command line to suppress the version information the utility normally prints when it starts up. This is useful when you're redirecting the output of the hscript standalone process.

You can encapsulate a group of commands in a script file so you can reuse its functionality. Simply create a text file containing the commands you want to run. In general, you’ll want to save the script file in the script path, for example in $HOME/houdiniversion/scripts.

In scripts, you can use the exit statement to exit the script prematurely. This exits all loops cleanly. HScript does not support setting an "exit status" like a UNIX shell, but you can use a global variable to achieve the same thing.

You can pass arguments to the script when you run it to customize its behavior. To use arguments in the script file, use $argn variables:

$arg0 is set to the name of the script as it was called.

$arg1, $arg2, $arg3, etc. are set to the arguments passed in to the script.

$argc is set to the number of arguments passed in to the script. For example, if the script is called with myscript first second third (three arguments), $argc is 3.

To do simple parsing of the command line, or to work with a variable number of arguments, you can use the shift command. The shift command removes the first argument and shifts all the remaining arguments down, so $arg1 is now what was $arg2. So, you can iterate through all the arguments by processing the value of $arg1, then calling shift to move the next argument into $arg1.

You can also read input from the user with the read command.

You can also take a look at the scripts included with Houdini for examples of real-world HScript.

# Script for a guessing game (guess.cmd)

# First, get a random seed

set foo = `system(date)`
set seed = `substr($foo, 14, 2)``substr($foo, 17, 2)`

# Then, pick a random number

set num = `int(rand($seed)*100)+1`

set guess = -1
echo Guess a random number between 1 and 100.

while ( "$guess" != "$num" )
    echo -n Enter guess (q to quit): "
    read guess

    if ( "$guess" == q || "$guess" == "") then
        break;
    endif

    # Convert to a number
    set iguess = `atof($guess)`

    if ( $iguess < $num ) then
        echo Too low
    else if ( $iguess > $num ) then
        echo Too high
    else
        echo Spot on!
    endif
end

echo The number was $num

defaultscene.cmd

Use the ucd and unix commands to start the language’s runtime as an external process.

Houdini passes any global HScript variables to the external process as environment variables, and sets the status variable to the exit code of the command.

Houdini includes dedicated HScript commands to call typical host system commands, such as uls to list the contents of a directory, urm to remove a file, and upwd to print the current directory. To make your code portable to non-UNIX systems such as Windows, use these HScript commands instead of explicitly calling the equivalent UNIX utility (ls, rm, pwd, etc.).

Viewers have names with the form "desk.pane.type", where:

• desk = The name of the desk containing the viewer pane.

• pane = The name of the viewer pane.

• type = "world", "particle", or "texture", depending on the contents of the pane.

To see a list of all viewers, use "viewls -n". For most viewer-related commands, you can specify more than one viewer at a time, and/or use wildcards in viewer names.

A viewer can be subdivided into up to four viewports (such as top, left, front, and perspective). Viewports have names with the form "desk.pane.type.viewport", where:

• desk = The name of the desk containing the viewer pane.

• pane = The name of the viewer pane.

• type = "world", "particle", or "texture", depending on the contents of the pane.

• viewport = The name of the viewport within the viewer pane. You can change the name of a viewport in the viewport’s display options editor. To list all viewports, use "viewls -n -v" (to show what viewer each viewport is in, just use "viewls -v").

For most viewport-related commands, you can specify more than one viewer at a time, and/or use wildcards in viewer names. You can also use the name of a viewer to refer to all viewports in the viewer. For example instead of "viewcamera -c cam1 Build.panetab1.world.persp1 Build.panetab1.world.top1 ...", you could do "viewcamera -c cam1 Build.panetab1.world.*" or just "viewcamera -c cam1 Build.panetab1.world".

Most viewport-related commands work on view-memories as well as viewports. View-memories have the format "desk.pane.type:memory", where memory is a number from 1-9 or a name. The first three components (desk name, pane name, type) can have wildcards. To list all view-memories, use viewls -n -l.

The viewlayout command controls the number and layout of viewports in a viewer pane.

• Use commandecho on to make Houdini print the HScript commands it executes internally in the textport.

• Maximum line length for a Houdini command is 8 KB after all expansions.

• Maximum number of arguments on a command line is 1024.

• Maximum number of number of nested if statements in a single source file is 128.

• Maximum number of source files is limited by the system limit on open files.

• No limit for nested loops.