The File() constructor accepts a string that points to the location of
a disk file, and an optional mode string that states how to open the
file. Then the file command returns a File Object Agent.
sceneFile = File(“/temp.lws”,”w”);
The following list contains the File open modes, which are identical to those provided
r read (ascii)
a append (ascii)
b binary (i.e., “rb” would be read-binary)
+ with update (i.e., the file pointer can be moved arbitrarily)
For example, to open a file for random binary
read access, you specify “rb+” as the open mode for your
file. If you do not specify the optional open mode, then the file is
opened in read-ascii (r) mode by default.
The File Object Agent methods that deal with binary file modes now
accept an optional Boolean argument that indicates whether or not the
read numeric value should have its byte ordering swapped. By
default, byte ordering will remain as it was read in from the
file. Passing a Boolean true will cause the byte ordering to be
swapped before the value is returned.
LScript v2.7 provides hooks in its functionality for a rather interesting new feature: URL file
referencing. Currently, this functionality will be employed by LScript in cases where external
script components are referenced (Object Agents, include files, etc.).
In order to activate this functionality, you must first acquire the shared-library build for
your platform of the W3C code distribution called libwww.
Once you have these files (numbering approximately 26 *.dll files for the Windows distribution),
they must be placed in the "w3c" subdirectory of the LScripts/ installation directory. For
example, if you have installed LightWave in "C:\LightWave", then the libwww files must be
placed in "C:\LightWave\LScripts\W3C" in order to activate this dormant LScript functionality.
Once the W3C files are correctly located and loaded into LScript, your script can specify URL
references for script components instead of local filenames. For instance, a script could then
reference an Object Agent include file published on an HTTP server as:
Further, inside the referenced include file, the Object Agent declaration line would then utilize
a URL instead of a file path to bring down the actual Object Agent binary file from the HTTP
use "http://www.myobjectagents.com/cooloa.oal" as class CoolOA;
As with Web pages in your favorite brower, files retrieved from an HTTP server in this fashion are
cached locally on your machine (in the same folder as the W3C directory). Each time the files are
referenced by URL, the local file dates are checked with the HTTP server, and files with newer dates
are refreshed locally. In this way, the component publisher has only to update the files on their
HTTP server, and all people using them will receive the updates automatically the next time any
script referencing them is executed.
open(string, mode) opens a new file with a specified mode ("r"
for read or "w" for write). The newly opened file is assigned
to the existing File Object Agent.
IsOpen() returns a Boolean value indicating that the file is open and accessible.
reopen(mode) closes the currently open file, and reopens it in the specified
mode ("r" for read or "w" for write).
close()closes the currently open file.
eof() returns a Boolean value (true/false) indicating whether the file
has reached the EOF marker.
rewind() resets the file read/write point to the beginning of the file.
name() returns a string containing the name (and path, if it was originally
specified) of the currently open file.
write() places a series of one or more arguments to the file. writeln()
is identical to write() except that a newline character is appended to
the line. These commands are illegal when the file is opened in Binary
In ASCII mode, the writeByte(integer) function will write an integer
value into the text file as a character. In Binary mode, the provided
value is stored in the file as a single binary value of size unsigned
character.The value returned is the number of bytes written to the file.
Using writeData(), you can send the binary data in a block to a disc file.
This can be used to re-create binary files from the embedded binary data within
the script. For instance, a LightWave object file can be embedded in a script
and carried along with the script until needed:
output = File("ball.lwo","wb");
// important! the file must be closed to flush any
// remaining data to disc before the call to
070 079 082 077 000 000 039 064 076 087 079 050 084 065 071 083 000 000 000 010
069 121 101 000 073 114 105 115 000 000 076 065 089 082 000 000 000 018 000 000
000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 080 078 084 083
In ASCII mode, the writeInt(integer) function will write a numeric integer
value into the text file as a character. In Binary mode, a single binary
value of size integer is written to the file. The value returned is the
number of bytes written to the file.
In ASCII mode, the writeNumber(number) function will write a value into
the text file as a floating-point number in character format. In Binary
mode, a string is written to the file. The value returned is the number
of bytes written to the file.
writeDouble() will store a numeric value of double-size (usually eight bytes)
writeDouble() will store a numeric value of short-size (usually two bytes)
In ASCII mode, the writeString(string) function will write a value into
the text file as a string in character format. In Binary mode, a single
binary value of size double is written to the file. The value returned
is the number of bytes written to the file.
In ASCII mode, the writeVector(Vector) function will write a value into
the text file as three floating point numbers separated by spaces in
character format. In Binary mode, a triple binary value of size double
is written to the file. The value returned is the number of bytes
written to the file.
read()reads a text line from the file, returning it as a character
string. This function is illegal when the file is opened in Binary mode.
In ASCII mode, the readByte()function will return a single character from
the text file as an integer value. In Binary mode, a single binary value
of size unsigned char is read from the file and returned as an integer
In ASCII mode, the readInt() function will read a sequence of characters
from the text file and return an integer data type. In Binary mode, a
single binary value of size integer will be read from the file.
In ASCII mode, the readNumber() function reads a sequence of characters
from the file, converting them to a single numeric (floating-point) value.
In Binary mode, a single numeric value (of size double) is read from the
readDouble() will read a numeric value of double-size (usually eight bytes)
readShort() will read a numeric value of short-size (usually two bytes)
In ASCII mode, the readString() function reads a sequence of characters
from the file, converting them to a string value. In Binary mode, a single string is read from the
In ASCII mode, the readVector() function will read a sequence of characters
from the file, return them as a vector data type. The data in the file
should appear as space-separated, floating-point numbers. In Binary mode,
three numeric values each of size double will be read and returned as
parse(string) reads a line from the file, and returns a variable number
of elements representing the tokens of the line. These elements are stored
in a character array. Tokens are separated by one of the characters provided
in the character string argument. This function is illegal in Binary mode.
nl()writes a new line character to the file. This command is illegal in
When the file is opened in ASCII mode, the linecount() function returns
the number of text lines in the currently-open file. However, in Binary
mode, it returns the size, in bytes, of the file.
In ASCII mode, the line([integer])function returns the current line
number in the file when no argument is provided. When a integer value
is provided that falls within the range of text lines in the file, it
will move the file pointer to the line number indicated. It is illegal
in Binary mode.
Called without parameters, the offset([integer[,method]]) method will return
the current byte offset of the file. Providing an integer value will cause
the file pointer to be placed at the specified offset in the file, relative
to an offset method. This optional offset method can be one of the following:
position the file from the beginning (and is the default when no method
position from the end of the file;
that the provided offset value is relative to the current location of
// global values
= File(file,"r") || error("Cannot open file
Display some Method values.
Read and display the first line.
a valid LightWave Scene!");
Read and display the next line.
The filerename() command renames a file on disk. The first argument is
the file that already exists and the second argument is the new filename
that you want to apply.
The filedelete() command deletes a file on disk.
The filestat() function returns various system-related values associated
with the file on disk. When filestat() is passed a valid filename, it
returns (in order) the file’s last access time, creation time, and last
modification time, the file size, the number of links to the file (UNIX
or NTFS file systems only), the file owner’s user id (UNIX only), and
the file’s group id (UNIX only).
are integers, and the access, creation, and modification times can be
arguments for the time() and date() functions.
function takes a single path value (string), and returns a full path version
if the provided path is relative. If the path is already a full path,
then that value is returned.
path1 = fullpath(“test2.txt”);
path2 = fullpath(“c:\\test2.txt”);
// result: ”c:\test2.txt”
The getdir() command returns the working
value used by the application for any one of the following constants (string
(LW Install Dir.)
returns the executing script's directory
This points to the alternate Configs directory, a good place to store settings as a file for your plugins.
You might retrieve
one of these directory values in the following fashion:
install = getdir(“Install”);
plugins = getdir(PLUGINSDIR);
A getsep() function has been added that will return the platform-specific path separator
info(getsep()); // displays "\", "/" or ":" depending on the operating system
getfile() gives LScript an interface
for selecting files. When you need to let the user specify a disk file,
getfile() posts a fileselection dialog box, and returns the file name
(including path information) that the user selects. If the user cancels,
getfile() will return nil.
All of getfile()’s
parameters are optional. You can specify a title for the dialog box, a
file name mask, and even a default directory.
title -- String; dialogue box title
mask -- String; file mask to use, which can include * wildcards
dir -- String; start directory
reqtype -- Boolean; 0 = save, 1= open
This function is similar to getfile() except it only allows the user to select folders. It takes two optional parameters: the first is the title of the dialog (defaults to "Select A Folder"); the second is a starting path. Returns a string representing the path to the selected folder, or returns nil if the user cancelled.
title -- String; dialogue box title
dir -- String; start directory
getmultifile (LW 9.2 or above only)
This presents an open file dialog box that allows the user to selection one or more files for opening. The selected files are returned to the script as an array
title string; dialog box title
mask string; file mask to use (can include wildcards)
filefind() takes a file name (sans path information) and scans through
the directory paths in the application in order to locate the file. The
path to the file is returned.
if((where = filefind("lw.cfg")) != nil)
This function uses those paths that are available to the getdir() function in order to find the file.
A new function called filecrc() calculates the CRC-32 value of the contents of a file, and returns this integer value.
The Layout LScript Compiler provides a new mode for generating compiled
scripts. This new compiled type is a "library", and is intended to be a
collection of functions (potentially unrelated) that are not associated
with any single plug-in architecture. Once compiled, this "library"
script can be used by any LScript through the use of the library
Functions defined within the "library" file can be referenced from a script as though they were built into LScript.
// the 'functions.lsc' library contains the gimmeStringFrom() function
library "functions.lsc"; // no path, so file should be in \NewTek\LScripts
t = 104;
The matchfiles() command scans a directory for files and folders that match
a pattern. matchfiles() returns an array with files that match the given
path and search parameters.
path1 = matchfiles(“c:\\”, “*.txt”);
The matchdirs() command returns an array with folders that match the given search parameters.
path1 = matchdirs(“c:\\”,
chdir() is one of three functions for managing directories that LScript
offers to you. When you use this function, you can change the
“working” directory of an LScript from the directory where
the script was started. This command also returns a character string
with the current “working” directory as a full path.
The chdir() command can be handy for launching external processes that
must run from a specific directory. ScreamerNet is a perfect example of
such a process: ScreamerNet must be launched from the NewTek/Programs
directory so it can properly locate support files, such as
configuration files and images. However, your LScript may already be
running in an entirely different location. The following code snippet,
illustrates how chdir() solves this particular situation:
// change the “working” directory to one required
// by ScreamerNet
if((snDir = getenv(“LW3D”)) == nil)
// is it (properly) in the environment?
oldDir = chdir(“\\windows\\apps\\newtek\\programs”);
oldDir = chdir(snDir);
snID = spawn(“lwsn -2 “, getenv(“TMP”),” \\snii.job “,_
// move back to our start-up directory
If the chdir() function fails to set the working directory to the one specified, a value
of nil is returned.
mkdir() is another function for directory management. An LScript can use
mkdir to create a new file system directory. The function accepts a string
that specifies the directory (with optional path), and returns a result
code (0 means no error).
rmdir() can remove an existing directory. The directory to be removed must
be completely empty for this command to succeed. As with mkdir(), this
command accepts a string that specifies the directory (with optional path)
to be removed, and returns a result code.
Replace the current selected object layer with the layer chosen from the file.
Replace the current selected object layer with the file.
This allows you to set the file type for the RGB render file saver. You need to contain it in the Command Input style wrapper.