|
|
QSDK 1.1 Documentation |
|
|
Click on the links below to go directly to the topic of interest.
QDS is a command line utility that enables you to view and edit the contents of one or more Q Database (.q) files. Common QDS tasks are listed in the contents.
QDS can be used in either interactive or automatic mode. In either mode, a script file may be supplied. The script file is executed before any other command.
In interactive mode, QDS displays a command prompt and processes commands one by one. When commands are passed in through a pipe (e.g. cat file | qds file.q or qds file.q < file), QDS will automatically exit after the supplied commands have been processed.
Q files contain not only the Q objects that you see in QStudio, but also data which describes the Q objects. No Q object can be stored in a Q file without this metadata. So the QSDK ships with class.q, a Q file containing nothing but the metadata. Class.q is the starting point for all QDS work. When you want to create a new Q file, take a copy of class.q as your starting point, and import new content into it.
qds [-s <scriptFileName>] [ -tp <texturePath>]
[-i] [-v]
([r | readonly | rw | readwrite | rwc | readwritecreate | newfile]) <qDataBaseName>
....
Execute the commands in a script file on startup. scriptFileName is mandatory and is the fully qualified path and name of the script file. The script file is a plain text file where each line is a valid QDS command with appropriate parameters. If running in interactive mode and the last command in the script file is quit, QDS will exit after executing the script. If the last command is not quit QDS will remain in interactive mode. A script file is typically used for batch processing Q Database files, e.g. in an automated build.
Specify a path to search for textures.
Enable interactive mode. This is the default if stdin and stdout are not redirected or piped. Interactive mode also enables verbose mode.
Enable verbose messages.
(<permissions>) <qDatabaseName> ...
Specify the Q files on which to operate. Each qDatabaseName must be a fully qualified Q file name. Each filename may be prefixed by a permissions string indicating how the file is to be opened. The permissions string can be:
- r or readonly. You can look at objects, but not modify, create or delete them. The file must exist.
- rw or readwrite. You can look at objects or modify them, but not create or delete them. The file must exist.
- rwc or readwritecreate. The default access mode. You can look at, change, create and delete objects. The file must exist.
- newfile. This is used to create class.q, and is not for public use. Users should create new Q files by copying class.q.
createTextureFrom <fileName> | <clipName>
Create a Texture object in the Q file from either a file containing a JPG, PNG, BMP or TGA image, or a previously imported image Clip.
When an image is imported, a Clip is first created for each mip level found. The Clip contains the raw data for the image. Importing a file called grass.jpg will create a Clip and a Texture, both called GRASS. A Texture is used to wrap a Clip to allow multiple mip levels to be created and used.
Note: Image Clip names are converted to upper case to avoid cross-platform naming issues. For more information about mip levels and mip-built textures, refer to the mipBuilder documentation.
import <fileName> [into <clipName>] [mimetype <mimetype>] [ <properties> ]
Create a Clip object in the Q file from a file containing a sound, image, QAM (Q Animation Machine) file, font (.ttf, .pfa, .pfb) or other verbatim content. There is a limit of 64MB on the size of the data imported.
If the Clip already exists it will be replaced with the new file contents. If you do not specify the mime type yourself, QDS will only accept the file if it is one of the supported filetypes. If you do specify the mime type yourself, then it is your application's responsibility to ensure that the data is of the appropriate format.
Examples:
Result in:
Properties allow the user to specialize the import. A property is a name followed by the symbol = and a value. The value is either a number or a string (between braces). For instance, mip=4 and color=(blue) are properties. The effects of properties depend on the type of data that gets imported. Here is a table that lists all properties for all data types:
| Font | |||||
|
NOTE: the use of QDS to import QGS (Q Game Schema) and QGP (Q Game Placement) files is deprecated. You are advised to use the compile command instead.
importXML <fileName>
importXML [overwrite | nooverwrite] <filename>
Create, modify, delete or rename assets in the Q file depending on the contents of the XML file read. This command is typically used to import items edited in QStudio.
The first form of the command is the same as importXML overwrite <filename>. The overwrite / nooverwrite qualification specifies whether or not existing objects will be modified or replaced by the data read from the XML file. Using nooverwrite ensures that existing objects are untouched.
compile <fileName>
Compile QGS (game schema) and QGP (game placement) files into Q data. This command is the equivalent of the importXML command for these file types. It reads a description text file and creates the Q objects described in it (Concepts and EntityInstances).
You should compile the Game Schema before compiling any Game Placement files that use it.
When you compile a Game Schema you must have a writable database attached into which the schema Concepts required for EntityInstance creation are exported. You do not need to have Q files containing referenced preload assets attached.
When you compile a Game Placement file you are advised to add the placement data to the Q file containing the scene graph for that Zone. This prevents the scene graph being split across multiple Q files. If you do split the scene graph across Q files and attach an incomplete set of Q files you can end up deleting part of the scene graph. You must have all referenced asset Q files attached (read-only permissions are advised in this case). You must also have the Q file containing the schema attached (read-only).
For example: if you have a scene file called scene.q, two asset files called asset1.q and asset2.q and a schema in schema.q then the following commands will result in the QGP file scene.qgp being compiled correctly:
qds r asset1.q r asset2.q r schema.q rwc scene.q
> compile scene.qgp
This command is normally used in conjunction with qdub. It creates Clump objects in the Q file that contain lists of all objects and knowledge required to transition between Zones, or to load up a given Zone.
quit | exit
Exit QDS.
Display a full list of the QDS commands on stdout.
List the Clips stored in the Q file, their size and their mime-type.
property <key> <attribute> <value>
Declare a property in the Q database. A property is a tuple (key, attribute, value) whose value is unique.
Example:
property cat color white
let <key> <attribute> <value>
Declare a relation in the Q database. A property is a tuple (key, attribute, value). There may be several values.
The command format is as follows:
Example:
let bob likes apple
let bob likes banana
|
|||
|
|
Qube Software Limited © 2000-2004
|
|