-
Notifications
You must be signed in to change notification settings - Fork 17
Asset Types
G-Engine (both the original and the recreation hosted in this repo) is a data-driven engine that supports a variety of asset types. This page summarizes the different types of assets supported and how they relate to one another. This info can be useful for modding GK3 or developing entirely new content.
In addition to the data on this page, you may also be interested in this related blog post: GK3 Asset Types
These are low-level engine assets that are used by most other assets in the game or don't make sense elsewhere.
GK3 doesn't ship all its assets as loose files. Instead, all the assets are packed into giant binary asset archives called "barns". Loading individual assets from monolithic binary archive files has some benefits for security and performance.
All other engine asset types discussed here are contained within barn files. However, it is possible to extract assets from barn files, and it's even possible to override barn file assets (if you want to provide your own customized version, for example).
An image/texture file. Three types of BMP files are supported:
- Uncompressed RGB 24 or 32 bits-per-pixel BMP images with a single color plane.
- Uncompressed palettized 8 bits-per-pixel BMP images with a single color plane.
- A proprietary(?) compressed image format.
Usually, uncompressed 24-bit RGB BMPs are used for UI elements. Uncompressed palettized 8-bit BMPs are used for some esoteric cases, such as walkable areas for different scenes. The compressed image format is used for 3D model and scene textures.
These assets are used to define and render the 3D content in the game.
A 3D model used to render characters and dynamic props in-game. These are usually used for 3D objects that need to move around or animate, or that need to be dynamically lit, but they can also be used for static 3D objects.
A 3D model consists of meshes and sub-meshes. Each sub-mesh can have a unique texture (BMP) asset assigned to it, to specify texture mapping for that part of the model.
Unfortunately, GK3 was released shortly before games started using skeletal animations for 3D models. As a result, GK3 models do not contain any skeletal data - only 3D vertex data. This means animations are achieved by moving each vertex individually. Overall, this is less efficient and a lot more difficult to author and maintain for the developers. For example, it means that if a 3D model is modified (vertices are added or removed), all animations for the 3D model also need to be modified to match. That is VERY inconvenient for 3D models with hundreds of animations.
Similar to other 3D games from the 90s like Quake or Half-Life, GK3 uses BSP (binary space partition) files to represent the 3D geometry of the scenes/maps/levels that are used throughout the game.
The file format used in GK3 isn't exactly the same as other BSP formats (every game had slightly different needs), but the general idea is the same: a tree of nodes that is traversed to determine what is in front of the camera and should be rendered.
BSP ultimately consists of 3D polygons that are textured by referencing image files (similar to 3D models). However, BSP meshes are static (they cannot animate or move). Lighting is also applied when the scene loads and is static after that point.
Lighting is applied to BSP by taking textures that may represent shadows or light colors and multiplying those textures with the scene textures (hence, the "MUL" extension). The effect of multiplying one texture with another is to tint the resulting texture. For example, if a gray lightmap texture is multiplied with a scene texture, that scene texture will look like it is in a shadow. Or, if a yellow/orange lightmap texture is multiplied with a scene texture, that scene texture will look like it is being illuminated by a yellow/orange light source.
Having scene lightmaps be separate from the scene geometry is a nice/clever optimization that allows the same BSP scene geometry to be used for locations at different times of day. For example, the "R25" BSP is used for the "Room 25" location in all timeblocks. However, there are different lightmaps applied for morning, afternoon, evening, and night.
This asset is really just a series of BMP texture assets that are stored within a single binary file. At runtime, it's expected that the surface count in the BSP asset matches the texture count in the lightmap asset. Each surface in the BSP then uses the corresponding texture in the MUL asset (e.g. surface index 0 in the BSP uses lightmap texture 0 in the MUL asset).
This is a strange little "glue" asset that appears to be exported alongside the BSP asset. It mainly lists the names of objects that exist in the BSP geometry, and also provides a list of lights and fairly detailed info about each light (such as position, direction, color, intensity, etc).
It can also specify the textures that are used for the scene's skybox, but this data is also sometimes defined in Scene Init Files (SIFs).
My guess is that perhaps these were intended to enable complex lighting, but the tech was not there to make it playable. Still, perhaps the lighting data that exists here can be used for something, someday...
These assets are used to animate various objects in the game.
These are text files that act as the entry to the entire game's animation system. You usually specify one of these files to play an animation. These files specify the timing of the animation and coordinate various types of animation actions, such as:
- Playing a 3D model animation (ACT)
- Playing a sound effect or music (WAV or STK)
- Toggling 3D model or BSP geometry visibility on or off.
- Changing the texture assigned to a 3D model or BSP geometry.
These are very similar to Animation (ANM) assets. In fact, the syntax seems to be identical. It's possible that MOM animations have more features or behave differently under-the-hood in the original game. But in the recreated engine, they are essentially identical to ANM assets.
These are binary files that contain 3D model vertex animation data. Animation data consists of defining the positions of vertices at various keyframes during the animation. At runtime, the 3D model vertices are interpolated between those keyframes.
The animation data can either be uncompressed or compressed. The majority of assets in the game are compressed. The compression technique is to store a delta from the previous keyframe as opposed to storing each keyframe's full vertex data.
Each ACT file is associated with a particular 3D Model (MOD) file via a naming convention. For example, the GAB_GABDINPOUR.ACT vertex animation asset is meant to be played on the GAB.MOD 3D model.
Specified either sets of textures (BMP) or animations (ANM) to play in sequence.
One example of this is on the timeblock screens, where the text animates in over a few frames. This is actually a series of textures that are shown in sequence.
But overall, this asset type is used very infrequently. I haven't yet seen an in-game use of the animation sequences. It's possible these assets were created, but never used.
These assets are used to define the game's gameplay behavior and logic.
A Sheep Script is a file that contains instructions in the engine's proprietary Sheep scripting language. This allows designers, scripters, and modders to create or change game logic without recompiling the entire engine.
The engine supports either pre-compiled or text-based scripts. If a text-based script is loaded, it is simply compiled on-the-fly before being executed.
The functions in a Sheep Script are typically called in response to in-game actions or events. There is a fairly exhaustive API that allows functions to perform complex logic and scripted sequences in-game (e.g. play animations, play sounds, add score, change locations, add inventory items, etc).
NVC files define the core of the game logic in an adventure game like GK3. These text files consist of a series of lines where each line specifies:
- An object in the scene that you can interact with (i.e. the Noun).
- An action that you can perform on the object (i.e. the Verb).
- The conditions under which this verb can be performed on this noun (i.e. the Case).
- The script to execute when the player chooses to perform the verb on the noun.
Both the case and the associated script are Sheep Script (SHP), so fairly complex conditions and actions can be defined. For example, if the player clicks on the PUDDING object, allow the EAT verb only if the player has already eaten their meat (as determined by checking game flags in the case script). If the player chooses the EAT verb on the PUDDING, run a script that walks the player character over to the pudding in the 3D scene and plays an "eat pudding" animation.
These text files blur the line between game logic and animation. These are essentially a very simple list of instructions that allow you to script the behavior of an object in the scene. A limited set of keywords are supported to enable looping animations, randomly picking an animation from a list, walking between a set of positions in the current scene, etc.
These are often used to script fairly simple idle animations and behaviors. For example, characters typically have GAS scripts defined to specify their idle animations when doing nothing, when talking to someone, and when listening to someone talk. Animated props in the scene (such as a ceiling fan) may also have a GAS script to tell it to loop its animation indefinitely.
Though GAS scripts allow some basic animation and movement related logic, anything more complex should probably use a Sheep Script (SHP).
Scene Init Files are text files that are used to load scenes in an intelligent way based on the current state of the game. This involves taking into account the current timeblock and other game progress flags and indicators.
For example, when loading the "R25" location in GK3, the exact set of data that should be loaded depends on a variety of factors. The SIF files for the R25 location determine exactly what should be loaded based on the state of the game:
- If it is a night timeblock, load use the nighttime BSP lightmaps (MUL) instead of the daytime ones.
- If this is a timeblock in which you play as Grace, use a different soundtrack.
- If the internal tracking variable shows that the closet was left open, initialize it in the open state.
- Show or hide various models depending on the current timeblock or whether the player has already taken certain items.
SIF files are the "point of entry" for any scene that is loaded in GK3. They tie together a lot of other assets:
- The SIF specifies which Scene asset (SCN) to use, which in turn dictates the BSP and BSP lightmap to use.
- The SIF specifies walk and camera boundaries.
- The SIF decides which 3D models will be loaded or visible, and what Noun to associate with each for NVC usage.
- The SIF decides which NVC files to load, which in turn drive the logic for what's clickable in the scene and what verbs are available.
Each location has a "general SIF" that is always used when that location is loaded. For example, the "R25" location has a corresponding R25.SIF asset. However, the game also conditionally loads certain SIFs to customize game logic based on timeblock. For example, if the timeblock is Day 1 12PM, the game would also try to load R25_112P.SIF as well.
These assets all relate to playing audio in the game.
An audio file. The engine only recognizes files with the ".WAV" extension as audio files, but two types of audio data are supported:
- Uncompressed PCM data.
- Compressed MP3 data.
Uncompressed PCM data is typically used for short sound effects and voice audio. Compressed MP3 data is used for longer music files, to save space.
GK3 contains a large number of files that appear to be randomly named. The docs sometimes refer to these as "license plates", I presume because they resemble license plate numbers.
These files are actually WAV audio files. Even though the extension is wrong, renaming it shows it to be a simple WAV.
All these files represent dialogue and voice over WAV files. I have no idea why they are named this way, but I imagine that whatever pipeline was in place for getting VO assets from the audio recording studio and ready for in-game use would generate these files.
A text file that controls the playback of one or more audio (WAV) files to dynamically generate longer music tracks. A lot of music in GK3 is not made up of single large tracks - instead, smaller musical riffs are used and pieced together using the logic in these soundtrack assets.
Soundtrack files have functionality to randomly select from a set of audio files, to fade in or fade out, to wait some time until playing the next piece of audio, etc.
A text file the correlates voice over audio files with in-game subtitles. The file syntax is nearly identical to Animation (ANM) assets, and they ultimately use the same system internally.
One thing to note is that the first letter of the YAK's filename indicates what language it is for (E for English). The remaining letters in the filename correspond to the license plate for the associated VO audio file.
These assets are used to implement UI in the game.
This is a text file that contains the definition for a font, such as the characters that exist in the font and what texture asset (BMP) is used to render the font. If no texture asset is specified, it is assumed that the texture has the same name as the font.
A font texture should consist of sequences of font glyphs in one or more rows. The glyphs in the texture must match the list of characters specified in the font asset. At runtime, the glyph to display is calculated by finding the index of the glyph in the font asset and correlating that to a portion of the font texture.
Defines a mouse cursor asset. This includes the appearance by specifying a texture (BMP) asset. Other properties include the cursor's hotspot position, opacity, and animation parameters. That's right - cursors can be static or animated. Animated cursors consist of multiple images baked into a single texture.
When search results are viewed in the in-game Sidney computer system, the articles for each search result are actually defined in valid HTML pages that can be opened and read in a normal web browser.
The engine isn't able to render any and all HTML tags, but it does support the basics: head, body, paragraph, links, fonts and font sizes.
Throughout GK3, you can hover the mouse over iconographic UI elements and see a tooltip explaining what the icon means. These tooltip style assets define how a tooltip should look - things like the font to use, background color, how quickly it fades in and out, etc.
GK3 also uses a variety of miscellaneous files to store configurations. Configurations are usually stored as INI format files.
Configs are text based files (in INI format) that provide some data used by the engine at runtime. There are only three used by the game.
| File | Description |
|---|---|
| GAME.CFG | Global game engine config options. Notably, defines the max score and 3D volume parameters. |
| DISCMAP.CFG | Specifies which disk video files are located on, if using a CD drive. |
| HARDWARE.CFG | Various video configs to overcome 90s graphics card bugs. |
Text files, mostly in INI format, used to describe the behavior of various mechanisms in the game.
| File | Description |
|---|---|
| BINOCS.TXT | INI that defines where you can use the binoculars and what happens when you do. |
| GPS.TXT | Defines the UI elements of the GPS system. Also defines where the GPS can be used and when it triggers in-game events. |
| PENDULUM.TXT | Defines behavior of the stupid swinging pendulum puzzle near the end of the game. |
Text files, mostly in INI format, used to define characters and describe their behavior.
| File | Description |
|---|---|
| CHARACTERS.TXT | Defines each character in the game and important data for them to function. |
| FACES.TXT | Defines character face parameters, such as eye colors, blink frequency, etc. |
| FLOORMAP.TXT | Maps specific floor texture (BMP) names to certain categories of floor (carpet, tile, grass, etc) |
| FONTCOLOR.TXT | Maps character names to the font color used for their subtitles. |
| FOOTSTEPS.TXT | Defines what sounds (WAV) should be used for footsteps based on shoe type and floor type. |
| FOOTSCUFFS.TXT | Similar to FOOTSTEPS.TXT. |
Text files, mostly in INI format, used to define how various UI screens work.
| File | Description |
|---|---|
| ESIDNEY.TXT | Sidney computer system English localizations. |
| ESIDNEYEMAIL.TXT | Sidney computer system English localizations for emails. |
| ESTRINGS.TXT | English localizations. |
| HELPSCREEN.TXT | Defines layout of the help screen UIs. |
| INVENTORYSPRITES.TXT | Maps inventory item names to the UI sprites (BMP) that represent them. |
| KEYBOARD.TXT | Maps keyboard keys to their display names. |
| MSGBOX.TXT | Defines layout of reusable message box. |
| PATHDATA.TXT | Defines the paths between locations on the driving screen; used to show driving blips in correct spots. |
| RC_LAYOUT.TXT | Defines layout of the in-game options UI. |
| SIDNEYDIALOG.TXT | Defines conditions where visiting certain Sidney search results will cause in-game dialogue to play. |
| SIDSEARCH.TXT | Maps search terms to specific Sidney results (HTML) pages. |
| VERBS.TXT | Maps in-game verbs to the UI sprites (BMP) that represent them. |