Functions
bool	onStartup (char *pluginName)
	Called when the plugin was loaded.

void	onInitFinished ()
	Called after the RPG objects were initialized.

void	onInitTitleScreen ()
	Called before the title screen is initialized.

void	onLoadGame (int id, char *data, int length)
	Called before the player loads a game from a savestate.

void	onSaveGame (int id, void(savePluginData)(char data, int length))
	Called before the player saves a game.

void	onExit ()
	Called before the game exits.

void	onFrame (RPG::Scene scene)
	Called every frame, before the screen is refreshed (see details!)

bool	onSetVariable (int id, int value)
	Called before an in-game variable is set.

bool	onSetSwitch (int id, bool value)
	Called before an in-game switch is set.

bool	onEventCommand (RPG::EventScriptLine scriptLine, RPG::EventScriptData scriptData, int eventId, int pageId, int lineId, int *nextLineId)
	Called before an event command is executed.

bool	onComment (const char text, const RPG::ParsedCommentData parsedData, RPG::EventScriptLine nextScriptLine, RPG::EventScriptData scriptData, int eventId, int pageId, int lineId, int *nextLineId)
	Called when a "Comment" event command is encountered.

void	onDrawScreen ()
	Called when the screen is drawn on the game window.

bool	onDrawPicture (RPG::Picture *picture)
	Called before a picture is drawn.

bool	onPictureDrawn (RPG::Picture *picture)
	Called after a picture was drawn (or was supposed to be drawn)

bool	onCheckEventVisibility (RPG::Character *character)
	Called every frame to check whether an event should be drawn even though it is out of sight.

bool	onDrawEvent (RPG::Character *character, bool isHero)
	Called before an event or the hero is drawn.

bool	onEventDrawn (RPG::Character *character, bool isHero)
	Called after an event or the hero was drawn (or was supposed to be drawn)

bool	onDrawBattler (RPG::Battler *battler, bool isMonster, int id)
	Called before a battler is drawn.

bool	onBattlerDrawn (RPG::Battler *battler, bool isMonster, int id)
	Called after a battler was drawn (or supposed to be drawn)

bool	onDrawBattleStatusWindow (int x, int selection, bool selActive, bool isTargetSelection, bool isVisible)
	Called before the battle status window is drawn.

bool	onBattleStatusWindowDrawn (int x, int selection, bool selActive, bool isTargetSelection, bool isVisible)
	Called after the battle status window was drawn (or supposed to be drawn)

bool	onDrawBattleActionWindow (int x, int y, int selection, bool selActive, bool isVisible)
	Called before the battle action window is drawn.

bool	onDoBattlerAction (RPG::Battler *battler, bool firstTry)
	Called before a battler's action is executed.

bool	onBattlerActionDone (RPG::Battler *battler, bool success)
	Called after a battler's action is executed.

bool	onSystemBackgroundDrawn (RECT *rect)
	Called after the system background was drawn.

Detailed Description

Function Documentation

◆ onBattlerActionDone()

bool onBattlerActionDone	(	RPG::Battler *	battler,
		bool	success )

Called after a battler's action is executed.

Parameters

battler	The battler which is executing its action
success	`true` if the action was successfully executed or `false` if the action couldn't be executed yet because another action or something else was active

Returns: false will prevent other plugins from receiving this notification, use true otherwise

Note: If success if false, the RPG Maker will repeatedly try again to execute the action, until it succeeds, at which point success will be true. Please note that this will also lead to multiple calls to onDoBattlerAction.

Warning: You must not modify the battler's action from this function, because it might not be fully completed. For example, "Attack" commands will immediately be finished although the attack animation and damage display haven't been done yet.

See also: onDoBattlerAction; RPG::Action

◆ onBattlerDrawn()

bool onBattlerDrawn	(	RPG::Battler *	battler,
		bool	isMonster,
		int	id )

Called after a battler was drawn (or supposed to be drawn)

You can use this function to draw something above a certain battler.

Parameters

battler	The battler which was drawn (or supposed to be drawn)
isMonster	`true` if the `battler` is a monster
id	Zero-based party member ID of the `battler`

Returns: false will prevent other plugins from receiving this notification, use true otherwise

Note: This function will be called regardless if a plugin returned false from its onDrawBattler handler for this event.

This function is not called for hidden monsters. For dead monsters it is only called while they are still partly visible (i.e. while they are fading out).

See also: onDrawBattler

◆ onBattleStatusWindowDrawn()

bool onBattleStatusWindowDrawn	(	int	x,
		int	selection,
		bool	selActive,
		bool	isTargetSelection,
		bool	isVisible )

Called after the battle status window was drawn (or supposed to be drawn)

You can use this function to draw something above the battle status window.

Parameters

x	The current X coordinate of the left side of the window
selection	The zero-based party member ID of the currently selecter actor
selActive	`true` if the `selection` parameter contains a valid value and a choice bar is drawn
isTargetSelection	`true` if it is the target selection window, `false` if it is the "normal" status window
isVisible	`true` if the window is visible

Returns: false will prevent other plugins from receiving this notification, use true otherwise

Note: This function will be called regardless if a plugin returned false from its onDrawBattleStatusWindow handler for this window.

This function is also called when the window is invisible. In this case, isVisible will be false.

Please see the onDrawBattleStatusWindow documentation to find out more about the isTargetSelection parameter!

See also: onDrawBattleStatusWindow

◆ onCheckEventVisibility()

bool onCheckEventVisibility ( RPG::Character * character )

Called every frame to check whether an event should be drawn even though it is out of sight.

Use this function in case you want to draw larger graphics instead of an event's normal graphic (using onDrawEvent). Normally, events which are out of sight are not drawn at all, thus neither onDrawEvent nor onEventDrawn would be called for this event. Return false from this function to force the drawing of the event.

Parameters

character The event to be drawn (can also be the hero)

Returns: false if the event should be drawn even though it is out of sight and also to prevent other plugins from receiving this notification, use true otherwise

Warning: Do not initiate any actions from this function, only check whether you need to draw this event or not. If a previous plugin returned false, your plugin won't receive this notification, even though it might receive the onDrawEvent and onEventDrawn notifications!

See also: onDrawEvent; onEventDrawn

◆ onComment()

bool onComment	(	const char *	text,
		const RPG::ParsedCommentData *	parsedData,
		RPG::EventScriptLine *	nextScriptLine,
		RPG::EventScriptData *	scriptData,
		int	eventId,
		int	pageId,
		int	lineId,
		int *	nextLineId )

Called when a "Comment" event command is encountered.

You can use this function to provide functions which are executed when a special event comment is encountered. Please stick to the Event comments guidelines! The parsedData parameter brings you the data already parsed according to the guidelines.

You will get all comment lines at once (separated by newline characters) in the text parameter. This way you don't need to do the parsing of the next event script lines (because internally, each comment line is a new event command).

You may use the comment function as "modifier" for event commands, thus there is the nextScriptLine parameter which allows you to modify the parameters of the next script line. For modifying event commands please also read the note at the onEventCommand documentation!

Parameters

text	The comment's content as simple text
parsedData	The already parsed data
nextScriptLine	The next event script line after the comment
scriptData	Pointer to the RPG::EventScriptData object of the current event script
eventId	The ID of the current event (negative for common events, zero for battle events)
pageId	The ID of the current event page (zero for common and battle events - sorry, no battle event page ID yet)
lineId	The zero-based line number
nextLineId	Pointer to the next executed line number (`-1` for default)

Returns: false will prevent other plugins from receiving this notification, use true otherwise

Note: For information how to use the nextLineId parameter, please refer to the onEventCommand documentation.

See also: onEventCommand

◆ onDoBattlerAction()

bool onDoBattlerAction	(	RPG::Battler *	battler,
		bool	firstTry )

Called before a battler's action is executed.

This function can be used to modify a battler's action before it is executed. For example, you might add a "random" skill which randomly executes certain skills and use this function to set the actual skill.

Parameters

battler	The battler which is executing its action
firstTry	`true` if this is the first attempt to execute this action. Make sure you include a check for this parameter to be `true` if you want your code to be run only once per action!

Note: If executing the action fails (due to another action being executed), the RPG Maker will repeatedly try again. You will then receive multiple calls to this callback, but only at the first call firstTry will be set to true.

Returns: false will prevent other plugins from receiving this notification, use true otherwise

Note: Using this function, you can also use targets for a skill (or the "Attack" and "Double Attack" functions) which are normally not possible.

To prevent an action completely, change it to the basic action RPG::BA_NONE. Do not use RPG::AK_NONE because this can cause errors later in the battle.

See also: onBattlerActionDone; RPG::Action

◆ onDrawBattleActionWindow()

bool onDrawBattleActionWindow	(	int *	x,
		int *	y,
		int	selection,
		bool	selActive,
		bool	isVisible )

Called before the battle action window is drawn.

You can use this function to draw below the battle action window, or to replace it entirely.

You can also use this function to move the window by modifying *x and *y.

Parameters

x	Pointer to the X coordinate of the upper-left corner of the window
y	Pointer to the Y coordinate of the upper-right corner of the window
selection	Zero-based index of the current selection
selActive	`true` if the `selection` parameter contains a valid value and a choice bar is drawn
isVisible	`true` if the window is visible

Returns: false will prevent the original window from being drawn and other plugins from receiving this notification, use true otherwise

Note: The selection parameter does not contain the database ID of the selected battle command, but only a zero-based index based on all choices which are displayed. Use the RPG::Actor object to find out which battle commands are available for an actor. You probably need to store the selection parameter from your onDrawBattleStatusWindow to find out which actor is currently selected. You can then use something like RPG::Actor::partyMember(battleStatusWindowSelection)->getBattleCommand(battleActionWindowSelection) to get the database ID of the currently selected battle command.

This function is also called when the window is invisible. In this case, isVisible will be false.

See also: onBattleStatusWindowDrawn

◆ onDrawBattler()

bool onDrawBattler	(	RPG::Battler *	battler,
		bool	isMonster,
		int	id )

Called before a battler is drawn.

You can use this function to draw something below a certain battler, or instead of the battler.

Parameters

battler	The battler which is about to be drawn
isMonster	`true` if the `battler` is a monster
id	Zero-based party member ID of the `battler`

Returns: false will prevent the original battler from being drawn and other plugins from receiving this notification, use true otherwise

Note: If you return false, the onBattlerDrawn handlers will still be called.

This function is not called for hidden monsters. For dead monsters it is only called while they are still partly visible (i.e. while they are fading out).

See also: onBattlerDrawn

◆ onDrawBattleStatusWindow()

bool onDrawBattleStatusWindow	(	int	x,
		int	selection,
		bool	selActive,
		bool	isTargetSelection,
		bool	isVisible )

Called before the battle status window is drawn.

You can use this function to draw below the battle status window, or to replace it entirely.

In the "Traditional" and "Alternative" battle layouts, there are two different status windows: One used as actual status window, one used as target selection window for actions with actors as targets. The latter is drawn above the skill/item selection window, while the former is drawn below it. Use the isTargetSelection parameter to find out which window you are dealing with.

You can also use this function (when isTargetSelection is false) to draw something above all battlers and below all windows.

Parameters

x	The current X coordinate of the left side of the window
selection	The zero-based party member ID of the currently selected actor
selActive	`true` if the `selection` parameter contains a valid value and a choice bar is drawn
isTargetSelection	`true` if it is the target selection window, `false` if it is the "normal" status window
isVisible	`true` if the window is visible

Returns: false will prevent the original window from being drawn and other plugins from receiving this notification, use true otherwise

Note: If you return false, the onBattleStatusWindowDrawn handlers will still be called. However, the "finger" cursor which points to the selected hero will not be drawn if you return false when the isTargetSelection parameter is true.

This function is also called when the window is invisible. In this case, isVisible will be false.

See also: onBattleStatusWindowDrawn

◆ onDrawEvent()

bool onDrawEvent	(	RPG::Character *	character,
		bool	isHero )

Called before an event or the hero is drawn.

You can use this function to draw something below a certain event, or instead of the event.

Parameters

character	The character which is about to be drawn (can also be the hero)
isHero	`true` if the `character` is the hero

Returns: false will prevent the original event from being drawn and other plugins from receiving this notification, use true otherwise

Note: If you return false, the onEventDrawn handlers will still be called.

Vehicles are not supported yet.

This function is only called when the event is in sight or an onCheckEventVisibility handler has returned false for this event.

See also: onEventDrawn

◆ onDrawPicture()

bool onDrawPicture ( RPG::Picture * picture )

Called before a picture is drawn.

You can use this function to draw something below a certain picture, or instead of the picture.

Parameters

picture The picture which is about to be drawn

Returns: false will prevent the original picture from being drawn and other plugins from receiving this notification, use true otherwise

Note: If you return false, the onPictureDrawn handlers will still be called.

See also: onPictureDrawn

◆ onDrawScreen()

void onDrawScreen ( )

Called when the screen is drawn on the game window.

Unlike onFrame, this function is called when the screen content is actually drawn on the game window. This means that if a section of the window is invalidated (for example because it was overlapped by another window or minimized), this function will be called again, even though the game screen itself didn't change.

Warning: The screen might already contain changes done by you in the onDrawScreen handler before. Also, it is possible that only a part of the screen is invalidated and redrawn. Thus, you should only use this callback if you need to draw something during certain screen transitions (where onFrame doesn't work).

See also: onFrame

◆ onEventCommand()

bool onEventCommand	(	RPG::EventScriptLine *	scriptLine,
		RPG::EventScriptData *	scriptData,
		int	eventId,
		int	pageId,
		int	lineId,
		int *	nextLineId )

Called before an event command is executed.

You can use this function to intercept event commands, use them for a different purpose or change their parameters.

By changing the nextLineId, you can decide which line in the script is to be executed next. By default, the value of *nextLineId is -1, which means that the default behavior is executed. You can change it to another line number to jump to a different line. Use *nextLineId = lineId; to repeat the command, this way you can create a "wait until done" behavior by initiating some action the first time and then repeatedly checking whether it is finished.

You can use the scriptData parameter to read other event commands in the current script.

Parameters

scriptLine	The event script line which is about to be executed
scriptData	Pointer to the RPG::EventScriptData object of the current event script
eventId	The ID of the current event (negative for common events, zero for battle events)
pageId	The ID of the current event page (zero for common and battle events - sorry, no battle event page ID yet)
lineId	The zero-based line number
nextLineId	Pointer to the next executed line number (`-1` for default)

Returns: false will prevent the event script line from being executed and other plugins from receiving this notification, use true otherwise

Note: You may change the scriptLine object if you want, so that it is executed with different parameters. After the line was executed, all changes will be undone automatically.

The "don't execute if you return false" feature works by setting bit 31 in the command member of the scriptLine so that it becomes an invalid (and thus ignored) command. DynRPG automatically clears this bit later.

Warning: Do not create loops which include several commands without a "Wait 0.0" (and also tell the user not to do so in case you provide an event command which jumps back in the script), otherwise the game will hang. If you loop to the same line using *nextLineId = lineId;, an automatic one-frame wait (equal to a "Wait 0.0") is inserted.

Do not use the nextLineId member if the current event command calls another event or ends the current event (e.g. when the command is RPG::EVCMD_STOP_EVENT).

See also: onComment

◆ onEventDrawn()

bool onEventDrawn	(	RPG::Character *	character,
		bool	isHero )

Called after an event or the hero was drawn (or was supposed to be drawn)

You can use this function to draw something above a certain event.

Parameters

character	The character which was drawn or supposed to be drawn (can also be the hero)
isHero	`true` if the `character` is the hero

Returns: false will prevent other plugins from receiving this notification, use true otherwise

Note: This function will be called regardless if a plugin returned false from its onDrawEvent handler for this event.

Vehicles are not supported yet.

This function is only called when the event is in sight or an onCheckEventVisibility handler has returned false for this event.

See also: onDrawEvent

◆ onExit()

void onExit ( )

Called before the game exits.

Note: It's recommended to wrap your code in a try..catch block because if the game exits after an error (before onInitFinished was called), the state of the memory is undefined. Also, if you want to save data, check whether there is anything to save before you do it. The RPG objects may or may not be initialized, depending on whether this function is called before (early exit) or after onInitFinished.

Warning: This handler may also be called while another callback handler is active, in case the other handler is pumping messages (for example, it is currently displaying a message box).

◆ onFrame()

void onFrame ( RPG::Scene scene )

Called every frame, before the screen is refreshed (see details!)

This function is called after every frame (see details below!), right after the current game scene was drawn, but before it becomes visible to the player. You may draw on the screen in this function and it will appear on top of the normal graphics.

You can even define your own scene and use this callback to draw it.

However: If the game is too slow, frames may be skipped. If this happens, the screen is not refreshed every frame, to save time. In this case, the onFrame handler is called only when the screen is refreshed. You can use RPG::System::frameCounter to find out how many frames were skipped (by comparing it with a value you saved at the last onFrame call), because when the scene is updated (even though the onFrame handler wasn't called), the RPG::System::frameCounter will still be incremented. This way, the game won't be "slower" than normal even when the framerate drops below 60.

Parameters

scene Game scene which was drawn

Note: The scene parameter does not necessarily equal to RPG::system->scene, e.g. when a transition from one scene to another is active.

See also: RPG::System::scene; RPG::System::frameCounter

◆ onInitFinished()

void onInitFinished ( )

Called after the RPG objects were initialized.

Unlike in onStartup, it is safe to access RPG objects from this function.

See also: onStartup

◆ onInitTitleScreen()

void onInitTitleScreen ( )

Called before the title screen is initialized.

This function is called before the title screen fades in.

◆ onLoadGame()

void onLoadGame	(	int	id,
		char *	data,
		int	length )

Called before the player loads a game from a savestate.

DynRPG loads plugin data which was previously saved in the onSaveGame function and passes it to this handler. See In-game data for details.

Parameters

id	Savestate ID
data	Pointer to plugin data
length	Length of plugin data

Note: data may be 0 if there is no data.

See also: onLoadGame

◆ onPictureDrawn()

bool onPictureDrawn ( RPG::Picture * picture )

Called after a picture was drawn (or was supposed to be drawn)

You can use this function to draw something above a certain picture.

Parameters

picture The picture which is was drawn (or was supposed to be drawn)

Returns: false will other plugins from receiving this notification, use true otherwise

Note: This function will be called regardless if a plugin returned false from its onDrawPicture handler for this picture.

See also: onDrawPicture

◆ onSaveGame()

void onSaveGame	(	int	id,
		void(*	savePluginData )(char *data, int length) )

Called before the player saves a game.

Use the function passed in the savePluginData parameter to save custom plugin data which will be passed back to the plugin when the player loads the same savestate. See In-game data for details.

Parameters

id	Savestate ID
savePluginData	Call this function to save custom plugin data

Note: If you call savePluginData more than once, only the last call will take effect.

See also: onLoadGame

◆ onSetSwitch()

bool onSetSwitch	(	int	id,
		bool	value )

Called before an in-game switch is set.

This function can be used to give "Change Switch" commands a special meaning.

Parameters

id	ID of the switch to be changed
value	Value to be assigned

Returns: false will prevent the switch from being changed and other plugins from receiving this notification, use true otherwise

Note: This callback is not only triggered by the "Change Switch" command, but by any action which writes to a switch.

See also: onSetVariable

◆ onSetVariable()

bool onSetVariable	(	int	id,
		int	value )

Called before an in-game variable is set.

This function can be used to give "Change Variable" commands a special meaning. This might be suitable for applications for which a full onComment implementation would be overkill, like a key check.

Parameters

id	ID of the variable to be changed
value	Value to be assigned

Returns: false will prevent the variable from being changed and other plugins from receiving this notification, use true otherwise

Note: This callback is not only triggered by the "Change Variable" command, but by any action which writes to a variable.

See also: onSetSwitch

◆ onStartup()

bool onStartup ( char * pluginName )

Called when the plugin was loaded.

This callback handler should be used to check for fatal problems, like missing files. You can abort the loading process from this function.

Parameters

pluginName The name of the plugin. This is the filename with the extension stripped. For its supposed usage, see Configuration.

Returns: true on success, false on failure. In the latter case, other plugins which were already loaded will receive the onExit call and be unloaded and the game will not be started.

Warning: Do not try to access RPG objects from this function, since the game hasn't been initialized yet.

See also: onInitFinished; onExit

◆ onSystemBackgroundDrawn()

bool onSystemBackgroundDrawn ( RECT * rect )

Called after the system background was drawn.

This function can be used to draw your custom background in the menu, etc.

Parameters

rect	Area which has been (re)drawn

Note: In the save/load menu, there is only the small part at the top drawn, in the other menus, the whole screen is painted. Pay attention to the rect parameter.

Functions

Detailed Description

Function Documentation

◆ onBattlerActionDone()

◆ onBattlerDrawn()

◆ onBattleStatusWindowDrawn()

◆ onCheckEventVisibility()

◆ onComment()

◆ onDoBattlerAction()

◆ onDrawBattleActionWindow()

◆ onDrawBattler()

◆ onDrawBattleStatusWindow()

◆ onDrawEvent()

◆ onDrawPicture()

◆ onDrawScreen()

◆ onEventCommand()

◆ onEventDrawn()

◆ onExit()

◆ onFrame()

◆ onInitFinished()

◆ onInitTitleScreen()

◆ onLoadGame()

◆ onPictureDrawn()

◆ onSaveGame()

◆ onSetSwitch()

◆ onSetVariable()

◆ onStartup()

◆ onSystemBackgroundDrawn()