Console Commands - Script

Script specific commands can be found here. Most of them are only meaningful if used as a part of a script.

The usual script is structured as follows:

#description This is my script
requiretexture
pushfunction
...
[some operations]
...
popfunction

This makes sure that the script only runs, if there is a target texture available. The previously selected function will be restored after the script completes (popfunction command).

Command List:

addborders, advmix, aviadd, avistart, avistop, beep, call, engage, execute, fderender, flushcon, resample, loop, noop, pushfunction, rem, renderstring, requirepoints, requiresource, requiretexture, run, select, shade, showmessage, starttimer, writeilf.

requiretexture

Usage: requiretexture

This command checks whether a texture windows is open and stops the script otherwise with an error message.

requiresource

Usage: requiresource

Stops the running script if no texture was set as Source Texture.

requirepoints

Usage: requirepoints

Checks if Surface Points (i.e. objects like rectangles etc.) are available on the texture form and breaks otherwise.

pushfunction

Usage: pushfunction

Saves currently selected function to a stack.

Hint: Use the popfunction command to restore the saved function.

select

Usage: select <functionidentifier>

Selects the Function <functionidentifier> and automatically loads its <custom> Preset. Function identifiers consist of the function's group (basic, color, generator, ...) and the function's name (solid, saturation, perlin noise, ...) separated by a / character. They are not case-sensitive.

Example: select basic/solid

run

Usage: run <functionidentifier>,<presetname>

This command switches to the Function <functionidentifier>, loads the Preset <presetname>, runs the function and returns to the previous function. All settings are restored afterwards. Internally the command is translated to this series:

pushfunction
select <functionidentifier>
pushconfig
loadpreset <presetname>
engage
popconfig
popfunction

Example: run color/invert,red

engage

Usage: engage [<texture>[,<function>[,<preset>]]]

Runs the currently selected function with the custom preset on the currently active texture, if no parameter was specified.

Hint: Some functions require a source texture or surface points. If you are using those kind of functions, verify with the requiresource and requirepoints at the beginning of the script whether the items are available.

loop

Usage: loop(<variable>,<startvalue>,<endvalue>)

The loop command is used to repeat a block of commands. The number of repetitions is the difference between the <endvalue> and the <startvalue> (+1). <endvalue> must be greater or equal to the <startvalue>. Both have to be fixed numbers, variables are currently not allowed. A temporal variable with the name <variable> is set at each iteration to the corresponding number between <startvalue> and <endvalue>.

Example:

loop(a,10,20)
  set amplify value=$a
  engage
endloop

Hint: Single line loops can be achieved quickly by a special notation, like e.g this line:

&100 set time offset=&; engage

This repeats the two statements 100 times. The & character is a placeholder for the current iteration number.

You can create dynamic line loops by using a variable as the iteration count:

compute a=100
&$a print &

These two lines print the numbers from 0 to 99 to the console.

call

Usage: call <scriptname>

Inserts the script <scriptname> as subroutine in your script. Verify that scripts don't call each other, because this will make the script run forever and crash the application. The parameter <scriptname> contains the script folder and the name of the script, separated by a / character.

Example: call textures/agate

showmessage

Usage: showmessage <message>

Shows a windows, which contains the text string <message>.

Example of usage in scripts:

resetquery
addquery stringA,Enter your string:,string=Hello World!
query
showmessage $stringA

rem

Usage: rem <text>

Outputs the comment string <text> to the console. This is useful for script debugging purposes.

Example: rem Now we render the stone wall!

noop

Usage: noop

Does nothing at all: no operation.

flushcon

Usage: flushcon

Clears the content of the console, just like the DOS command cls (which you can also use here).

starttimer

Usage: starttimer

Starts the stop timer. Useful for benchmarking.

Hint: Use the stoptimer command to stop the timer and show the measured span of time.

execute

Usage: execute <filename>

Runs the external file <filename>. For security reasons, the function always asks the user if he really wants to run that file to avoid malicious scripts. Use this command for example to view an AVI video file after you have it rendered via a script.

Example: execute C:\temp\test.avi

avistart

Usage: avistart <filename>[,<framerate>]

Creates a new AVI video file, which can be employed to store textures as frames. A Texture Form has to be available, which supplies the width and height data of the AVI video.

Example: avistart E:\temp\test.avi,25

Hint: Currently, only uncompressed 24-bit AVI files are createable with Texture Maker.

aviadd

Usage: aviadd

Adds the content of the currently active texture to the AVI file, that was initialized with the avistart command.

avistop

Usage: avistop

Closes the AVI file, which was created by the avistart command.

beep

Usage: beep

Beeps. You can use this e.g. to make noise after a long script has completed.

writeilf

Usage: writeilf <targetfile>,<imagefile>,<imagecount>

Creates a standard ILF file (image list file). The <targetfile> parameter defines the name of the file, that the list is written to.

Use the <imagefile> parameter to adjust the prefix name (e.g. MyImage). You can include the image filename extensions in the <image file> parameter (e.g. MyImage.jpg) to have them used instead of the standard BMP extension.

The value <imagecount> defines the number of image filename that are stored in the file. For example <imagecount>=100 makes 100 lines with number from 0 to 99.

Example: writeilf C:\myilf,myimages.tga,5
Creates the ILF file C:\myilf.ilf that contains:
myimage0.tga
myimage1.tga
myimage2.tga
myimage3.tga
myimage4.tga

addborders

Usage: addborders

Creates a new textures from the active one with borders added. Use the configuration variables border left, border right, border top and border bottom to set the border dimensions. The background color is defined by the variable secondary color.

Example: set border left = 10; addborders

renderstring

Usage: renderstring <text>

Renders the string <text> to a new texture with the font settings and colors like set in the Render Text dialog. The new texture will be named Text.

Example: renderstring "Hello World!"

advmix

Usage: advmix

Calls the Multi-Texture Mixer to render a new texture with the current mixer settings and to terminate after that. The new texture will have the name Mixer.

shade

Usage: shade

Calls the Shader, which will render a new texture with the current shader settings and close after that. The new texture will be named Shader..

fderender

Usage: fderender

Launches the First Day Engine to render a landscape image to a new texture. After the rendering, the FDE will close. The new texture will be named FirstDay.

resample

Usage: reample

Launches the Reampler to have it automatically render a seamless texture from the active texture's content.