cutscene.h File Reference

Detailed Description

Design Philosophy

A cutscene takes the data in the cutscene_t data structure and renders it to the display. Using cutscene should feel similar in some ways to using menuMegaRenderer, and it handles all its own memory management. You shouldn't need to malloc/calloc any of the structs found in cutscene.h. The cutscenes also make sounds as you press A to progress, or mash the arrow keys to jam out. Many default midi values are internally set up for you to quickly get testing. Although a musically inclined ear would do well to tactfully assign certain instruments and effects to characters and set pitches that can work nicely with background music.

Usage

Start with initCutscene(), then add any number of styles with addCutsceneStyle(). Generally think of a style as a character. It has its name, various poses, and a certain sound. Styles can also be used in other clever ways such as an incoming transmission, or getting a new ability!

Consider calling setMidiParams() in a way that meshes with other background music. You can call it again when the BGM changes, and all the parameters will be overwritten. But this function is completely optional. Midi sounds will be populated with some kind of noise by default.

Add any number of dialogue lines with addCutsceneLine(). A list will be internally shifted as each line is disposed with the A press. At any point later in your game, simply add a bunch of other dialogue lines to do yet another cutscene.

Add updateCutscene() to your own update loop. And add drawCutscene() to your own draw loop.

When you are all done with cutscenes, typically on Mode Exit, you must call deinitCutscene().

Example

See megaPulseEx.c and mgCutscenes.c and to see how cutscenes were used in the 2026 Mega Pulse X platformer.

Go to the source code of this file.

Data Structures
struct	cutsceneLine_t
	The underlying data for a cutscene line. More...
struct	cutsceneStyle_t
	Style specifications to draw, and sound a cutsceneLine such as text color, character sprite, and midi notes. More...
struct	cutscene_t
	The underlying data for a cutscene. A cutscene is fundamentally made of a list of cutsceneLine_t. With other variables that can be stored in one place here. More...

Typedefs
typedef void(*	cutsceneCb) ()
	A callback which is called when this cutscene concludes. Use it to unpause your game loop.

Functions
cutscene_t *	initCutscene (cutsceneCb cbFunc, cnfsFileIdx_t nextIconIdx, uint8_t soundBank)
	Required to begin a cutscene.
void	removeAllStyles (cutscene_t *cutscene)
	Removes all styles. Unlikely to be used by anybody else since you add all your styles at the start of the game.
void	addCutsceneStyle (cutscene_t *cutscene, paletteColor_t color, cnfsFileIdx_t spriteIdx, cnfsFileIdx_t textBoxIdx, char *title, uint8_t numPoseVariations, bool stageLeft, bool drawSprite, bool drawTextbox)
	Adds a cutscene style to an internally managed list.
void	setMidiParams (cutscene_t *cutscene, uint8_t styleIdx, uint8_t instrument, int8_t octaveOvset, uint16_t noteLength, bool slowAttack)
	Set the Midi Params object.
void	setSongPitches (cutscene_t *cutscene, int16_t songPitches[8])
	Set the Song Pitches object.
void	addCutsceneLine (cutscene_t *cutscene, uint8_t styleIdx, char *body, bool flipHorizontal, int8_t spriteVariation, cutsceneCb cbFunc)
	Adds a dialogue line to the cutscene.
void	updateCutscene (cutscene_t *cutscene, int16_t btnState)
	The update function of the cutscene must be called regularly from your game loop.
void	drawCutscene (cutscene_t *cutscene, font_t *font)
	The draw function of the cutscene must be called regularly from your draw loop. Update should typically be called before draw.
void	deinitCutscene (cutscene_t *cutscene)
	Frees data. Required to call where your mode exits or when done with cutscene_t. Remember you may recycle one cutscene_t for many cutscenes and deinit during Mode Exit.

---

Data Structure Documentation

cutsceneLine_t

struct cutsceneLine_t

Data Fields
char *	body	The spoken text displayed on screen.
uint8_t	styleIdx	Index into the list of lineStyle_t.
int8_t	spriteVariation	A number that is added to the spriteIdx to display various character poses.
bool	flipHorizontal	Draw the character sprite flipped.
cutsceneCb	cbFunc	A callback to fire at the end of this line. Usually used for BackGround Music change.

cutsceneStyle_t

struct cutsceneStyle_t

Data Fields
char *	title	The speaker's name displayed on screen.
paletteColor_t	textColor	The color of the text.
cnfsFileIdx_t	spriteIdx	The file index of the character sprite.
cnfsFileIdx_t	textBoxIdx	The file index of the textbox sprite.
uint8_t	numSpriteVariations	A random number in range of this will be rolled and added to the spriteIdx. Provide 1 for no variation;
bool	stageLeft	If true, then the sprite enters and leaves the left side of the screen. If false, then the right side.
bool	drawSprite	Set false to draw no sprite.
bool	drawTextBox	Set false to draw no textbox.
uint8_t	instrument	Program# of the instrument when A is pressed.
int8_t	octaveOvset	How many octaves to transpose this character's sound up or down. Zero for no effect.
uint16_t	noteLength	Increase to have the note decay slower. 250 sounds fairly natural.
bool	slowAttack	True to make the note have a slow attack.

cutscene_t

struct cutscene_t

Data Fields
cutsceneCb	cbFunc	A callback which is called when this cutscene concludes. Use it to unpause your game loop.
list_t *	styles	A list_t of lineStyle_t.
list_t *	lines	A list_t of cutsceneLine_t.
int8_t	blinkTimer	Increments and overflows to make the next graphic blink.
bool	a_down	True when the a button is held.
int16_t	xOffset	Decrements to slide the character portait in from below.
wsg_t *	sprite	The character sprite.
wsg_t *	textBox	The textbox rendered over the character sprite.
wsg_t *	nextIcon[4]	The nextIcon with a few animation frames.
int8_t	nextIconAnimationTimer	Increments and controls the next icon frame.
bool	isEnding	True as the character slides out of frame.
uint8_t	soundBank	2 for mega man sounds. https://adam.feinste.in/Super-2024-Swadge-FW/MIDI.html#general-midi-bank-0
midiTimbre_t	timbre	Lots of midi params for character sound playback.
int32_t	bgm_headroom	The volume of background music. Fades 33% lower during cutscenes.
int16_t	btnState_previousFrame	The btnState of the previous frame.
int16_t	songPitches[8]	Up to eight pitches and no less than four pitches that harmonize with a song. Any pitches in idx 4 thru 7 may be -1 to be unused.

Typedef Documentation

cutsceneCb

typedef void(* cutsceneCb) ()

A callback which is called when this cutscene concludes. Use it to unpause your game loop.

Function Documentation

initCutscene()

cutscene_t * initCutscene	(	cutsceneCb	cbFunc,
		cnfsFileIdx_t	nextIconIdx,
		uint8_t	soundBank )

Required to begin a cutscene.

Parameters

cbFunc	A callback which is called when this cutscene concludes. Use it to unpause your game loop.
nextIconIdx	The file index of the first of four frames of the nextIcon graphic.
soundBank	0 for general midi, 1 for MAGFest, 2 for MegaManX

Returns

cutscene_t*

removeAllStyles()

void removeAllStyles

(

cutscene_t *

cutscene

)

Removes all styles. Unlikely to be used by anybody else since you add all your styles at the start of the game.

Parameters

cutscene

Pointer to the cutscene_t

addCutsceneStyle()

void addCutsceneStyle	(	cutscene_t *	cutscene,
		paletteColor_t	textColor,
		cnfsFileIdx_t	spriteIdx,
		cnfsFileIdx_t	textBoxIdx,
		char *	title,
		uint8_t	numSpriteVariations,
		bool	stageLeft,
		bool	drawSprite,
		bool	drawTextbox )

Adds a cutscene style to an internally managed list.

Parameters

cutscene	Pointer to the cutscene_t
textColor	The color to draw text
spriteIdx	The file index of the first pose of a character
textBoxIdx	The file index of the textbox sprite
title	The text drawn for a character's name
numSpriteVariations	The number of sprites/poses of this character
stageLeft	If false then this character will slide on and off the right side of the screen. True for left side.
drawSprite	If true, then the character pose is drawn. Use false to draw nothing.
drawTextbox	If true, then the textbox sprite is drawn behind the text. Use false to draw just the text with no textbox.

setMidiParams()

void setMidiParams	(	cutscene_t *	cutscene,
		uint8_t	styleIdx,
		uint8_t	instrument,
		int8_t	octaveOvset,
		uint16_t	noteLength,
		bool	slowAttack )

Set the Midi Params object.

Parameters

cutscene	Pointer to the cutscene_t
styleIdx	An index into the styles list
instrument	An instrument program #
octaveOvset	The number of octaves to transpose the sounds up or down. Zero for no transposition.
noteLength	Vaguely the note length, but not precisely.
slowAttack	Set to true to make this character sound really loose. Set to false to sound snappy.

setSongPitches()

void setSongPitches	(	cutscene_t *	cutscene,
		int16_t	songPitches[8] )

Set the Song Pitches object.

Parameters

cutscene	Pointer to the cutscene_t
songPitches	No less than four midi pitches and no more than 8 that may play well against other background music. Any -1's will be ignored in the array.

addCutsceneLine()

void addCutsceneLine	(	cutscene_t *	cutscene,
		uint8_t	styleIdx,
		char *	body,
		bool	flipHorizontal,
		int8_t	spriteVariation,
		cutsceneCb	cbFunc )

Adds a dialogue line to the cutscene.

Parameters

cutscene	Pointer to the cutscene
styleIdx	Index into the styles list
body	The dialogue text to draw
flipHorizontal	true to flip the character pose horizontally
spriteVariation	The specific pose sprite, counted up from the main pose sprite.
cbFunc	A callback function to fire when A is pressed on this line. Leave NULL to fire nothing.

updateCutscene()

void updateCutscene	(	cutscene_t *	cutscene,
		int16_t	btnState )

The update function of the cutscene must be called regularly from your game loop.

Parameters

cutscene	Pointer to the cutscene_t
btnState	Button state

drawCutscene()

void drawCutscene	(	cutscene_t *	cutscene,
		font_t *	font )

The draw function of the cutscene must be called regularly from your draw loop. Update should typically be called before draw.

Parameters

cutscene	Pointer to the cutscene_t
font	Font to draw the character name and dialogue text

deinitCutscene()

void deinitCutscene

(

cutscene_t *

cutscene

)

Frees data. Required to call where your mode exits or when done with cutscene_t. Remember you may recycle one cutscene_t for many cutscenes and deinit during Mode Exit.

Parameters

cutscene