GrimE

GrimE
Engine developer	aquadran, botje, giucam, klusark, somaen, chkr, ender
Companies that used it	LucasArts
Games that use it	Grim Fandango, Escape from Monkey Island
Date added to ScummVM	2020-10-09
First release containing it	2.5.0

GrimE is an engine originally developed for Grim Fandango, and later used for Escape from Monkey Island.

Support for Escape from Monkey Island was improved by the students Akz and JoseJX as part of the GSoC 2014.

General overview

GrimE is a 2.5D engine, that is, a mix of 2D and 3D objects. The backgrounds and many objects are prerendered bitmaps, while the characters are 3D models.

Structure

Scripting - Lua

GrimE uses a modified version of Lua 3.1 alpha as script engine. It interacts with the engine through a set of global C functions defined in the grim/lua*.cpp files, which can be called by the scripts.

The main difference with the original version is multi-tasking support. The function start_script, callable by the scripts, create a new lua state, which lives together with the original one. The function lua_runtasks() updates all the states. The states are managed by the functions start_script, stop_script, (un)pause_script, find_script.

The function lua_Save is invoked when saving a game and it writes the entire Lua state to disk. This information is restored by lua_Restore upon game load.

The management of user objects in Lua is different from the upstream version. Instead of the pointer to the object itself Lua stores an unique id for the object (see Grim::PoolObject), which is later used to get the object from a pool. So the objects are now not saved into a TaggedString anymore, but with this new struct into the "Value" union, in lua/lobject.h:

typedef struct UserData {
	int32 id;
	int32 tag;
} UserData;

Sound - iMuse

GrimE uses the good old iMuse for playing music and sound effects.

iMuse is controlled by the scripts through the use of these functions, defined in lua_v1_sound.cpp:

• ImStartSound();
• ImStopSound();
• ImStopAllSounds();
• ImPause();
• ImResume();
• ImSetVoiceEffect();
• ImSetMusicVol();
• ImGetMusicVol();
• ImSetVoiceVol();
• ImGetVoiceVol();
• ImSetSfxVol();
• ImGetSfxVol();
• ImSetParam();
• ImGetParam();
• ImFadeParam();
• ImSetState();
• ImSetSequence();
• SaveIMuse();
• RestoreIMuse();
• SetSoundPosition();
• IsSoundPlaying();
• PlaySoundAt();

iMuse loads *.wav and *.snd files, decoded in the VIMA format.

Movies

Smush

TODO

The sets

A set is a game room, a space where the actors can walk into, An example is Manny's office, or Blue Casket's kitchen. Sets informations are saved up in the .set files.

A list of sets in Grim Fandango can be found in the Grim Sets page.

Sectors

A set has a number of sectors, that is, polygons defining a certain piece of a plane. A sector can be or not be walkable, or can be a hot sector, which is used to swap between sets.

Setups

A setup is a particular view of the camera. A set has usually more than one setup, and they are swapped depending on Manny's position. E.g, in Manny's office there are four setups:

• the one when using the computer;
• the one when reading the work order;
• the one when picking up the card deck
• the one when exiting to the hall.

Every setup defines a pre-rendered background bitmap, in the .bm format and a zbitmap, depth information on the background that defines if an actor should be drawn above or behind the background for each pixel, in the .zbm format.

Object states

An object state is a 2D object above the background, which may be interactive. E.g. the mail tube in Manny's office. It is essentially a bitmap and can be drawn above the 3D objects. It may also have a zbitmap. Usually they are animated, like the flag, if the bitmap contains more that one image.

The object states can be animated by running a Costume chore, using a function like PlayActorChore.

Engine allows to start from specific sets. Grim Fandango sets can be found in the Grim Sets page.

The Actors

An actor is what the name suggests, an actor on screen. It can be a 3D object, like Manny, or a 2D object, an object state.

Costumes

Every actor has one or more costume. A costume is a set of components and chores. Each component represents an on-screen object, like an object state, a 3D mesh, a material, or a keyframe animation, or a sound effect; each chore, diminutive for choreography, gives a set of instructions for how to move, change state or activate or deactivate each component at certain times.
All these information are saved into .cos or .cosb files.