MM1:Cutscenes

Cutscenes are cinematic moments in Mary's Magical Adventure that temporarily appear over gameplay when important moments are encountered. These are made up of pictures, voice acting, and sometimes video (which is a series of pictures). Cutscenes can be disabled in the Miscellaneous Options menu or by changing the CVAR  to 0.

Cutscenes appear at predictable moments: In some cases, cutscenes can occur during a level without warning.
 * Before boss battles, to set up the conflict responsible for the battle the player is about to engage in.
 * After boss battles. These show the boss's defeat, followed by Mary and Xane navigating to the next area.
 * Upon acquiring new weapons, due to the rarity of getting weapons in this game. Your character picks up and looks at their new weapon.

Behavior
When a cutscene is triggered, the screen fades out, then a purple background with a white framed area at the top fades in. After this is done, each picture or video appears here in sequence, with text appearing below it. After a second, can be pressed to advance to the next screen of text. When all screens are shown, this interface fades out, then gameplay fades back in.

In some cases, the player may be warped to another part of the level (and other scripted events) upon ending a cutscene.

Modding
Cutscenes are made up of multiple parts behind the scene, but with work, you can set up and play custom cutscenes in-game.

Images and Videos
Importing cutscene images and videos is easy. First, make sure all of your images and video frames are 569x320 pixels exactly.

For images: For videos:
 * Create a Graphics folder in your mod PK3, if one doesn't exist yet, then a cutscenes folder inside that for neatness.
 * Name them CUT_x, where 'x' is a positive number. This is the number you will reference when preparing the cutscene in with ACS scripting.
 * If you'd like to use higher-resolution images, create a HiRes folder in your mod's root directory and place the images inside using the exact same names.
 * Creating videos specifically for this is easy, provided your video editor supports exporting to a series of PNG images. When finishing the video, export it at 569x320 pixels, 15 FPS.
 * If any audio is generated to go with your video in your editor, like if extra sounds were dubbed in on different layers, export that as a WAV or OGG file to insert into the game separately.
 * Create a Graphics folder in your mod PK3, if one doesn't exist yet. Create a cutscenes folder for neatness, then a subfolder for your video.
 * Name each video frame CV-x_y, where 'x' is the video number and 'y' is the frame, which starts at 1. You can automate this after importing using SLADE by using rename (F2) then typing, which will give each image in the list from top to bottom its own number.
 * Add in the last image you'd like to see after the video plays and name it "CUT_-x", where 'x' is the video number. Most of the time, this is the final frame of the video, but you can cause a "hard cut" to another scene by placing the next scene picture here.

Dialogue/Text
Dialogue is handled through GZDoom's LANGUAGE lumps.
 * Create a LANGUAGE lump named something like "LANGUAGE.cut" then begin editing it.
 * Write something like  for the first line, which specifies it's an US English language file.
 * Each line of cutscene speech begins with "CUTSCENE_x", where 'x' is the ID of this line for reference later in ACS scripting. For example, a line may look like this:
 * Repeat this for each line you need in your cutscene.

Voice Acting and Video Audio
This goes hand-in-hand with the previous section about text. Voice acting is directly tied to each speech line in your LANGUAGE lump.
 * Create a Sounds folder if one doesn't already exist in the main folder of your mod. Create subfolders for cutscene dialogue to be neat.
 * Place your WAV or OGG voice acting into a folder. Rename it to, where 'x' is the text ID. When that text appears in-game, the voice acting will automatically play.

Displaying your cutscene
Now, with your assets imported and prepared, it's time to put it all together in-game! At the beginning of your level's ACS script, add these lines: These are the three main arrays that you'll be filling in to determine how the cutscene progresses. Next, create a new script (or add the next stuff to an existing script) then prepare to set up the arrays. As this is mostly up to the modder, not much info can be provided here.

Enter variable-setting commands into your script, setting different array indices to numbers corresponding to text IDs (cut_text) and image/video numbers (cut_image). In the latter case, negative numbers start videos while positive numbers display pictures. To end a cutscene, set a cut_text index to 0. cut_extra isn't fully implemented currently.

Example script lines:

As of v2.0, this shows pictures of Mary and the Commander with dialogue implying the Commander caught Mary in a trap.

The last step needed is for the cutscene-running script to execute. Use, where 'x' is the "ID" your cutscene will check before running. This is to prevent players from watching the same cutscene multiple times upon returning to a level. If you haven't seen the specified cutscene ID yet, your cutscene will play out when that script runs.

Last, to script things like teleporting players when a cutscene finishes, create a script named CutsceneReturn with one argument. When a cutscene finishes, this script will be executed with the first argument set to the cutscene ID. Use an if or switch statement to check for your cutscene's specific number to have things happen only when that particular cutscene ends.