3Space/Research on KQ8

Here is research on King's Quest 8: Mask of Eternity, imported from the ResidualVM wiki. As KQ8 uses the 3Space engine, this info was imported under the 3Space namespace.

.cs files

The .cs file format is line-based, with # serving as a line comment. Every file needs to be invoked with a number of parameters named $1, $2, .... The $2 parameter defines an operation, it is one of "Init", "Load", "NewWorld", "RestoreWorld", "UnloadWorld", or "Die".

There are some singleton objects, such as KQGame and KQWorld. Accessing a member of these objects takes the form $KQWorld::Name, but a set does not take a $. Methods can be called as Object::method <argument>....

Currently seen primitives:

• test: takes an expression (for example $2 == Load) and returns a boolean
• lockResource <filename> [<bool>]: lock the resource into memory? If number is not given, lock. If it is 0, unlock.
• purgeresources: Free up memory?
• deleteObject <objectID>: call a destructor, maybe?
• echo <argument>...: Prints its arguments.
• set <variable> <value>: Set a variable to a value.
• set <variable>: Remove a variable.
• setcat <variable> <argument>...: Sets variable to the concatenation of its arguments. (setcat example one / two is the same as set example "one/two")
• loadPalettes <number>: No idea.
• loadKQ <filename>: loads a .kq file.
• blackout: Black out the screen?
• newSky <argument>: Set a sky texture?
• newStars: Set a night sky texture?
• allowShadows <bool>: No idea.
• resetHazeColor <red> <green> <blue>: A comment states this must be called after a loadPalette call.
• setHaze <number>: No idea.
• sendEvent <objectID> <field?> <event> <argument>...: Send an event to the specified object.
• setLoadProgress <bool>: No idea.
• loadAnim <filename.kqs> <objectID?> <???> <???> <???> <x> <y> <z> <xrot> <yrot> <zrot>: Load an object?
• setThirdPerson: No idea.
• handsOff <bool>: Cutscene mode?
• move <objectID> <???> <x> <y> <z> <xrot> <yrot> <zrot>: Move and/or rotate an object.
• setConnorFlag <flagname> <bool>: No idea.
• doPopup <number>: Popup with a text ID?
• checkSave: No idea.
• checkDistance <objectID> <objectID> <distance?>: Sets $Console::Return depending on distance.
• preloadShape <filename.kqs>: No idea.
• getLoc <object>: Returns a location+rotation in $KQObject::loc , location in $KQObject::locOnly.
• random <min> <max>: Returns a random number in $Console::Return.
• conClickItem <objectID>: No idea.
• getConInventory: Sets some values in $ConInv (::Long and ::Short)
• alias <name> <string>: For the console.
• activatePersistMgr <boolean>: No idea.
• addMapIcon <filename.bmp> <x?> <y?>: No idea.
• teleportersEarned: Returns a boolean in $Console::Return
• onTeleport: No idea.
• offTeleport: No idea.

.kq files

Simple INI-based format. Most important is the classType field, which contains a class name.

.vol files

Packs of files, organized per world. This StackOverflow question seems to contain basic extraction code.