DynRPG  v0.14a
RM2k3 Plugin SDK
Functions
Callbacks

Functions

bool __cdecl onStartup (char *pluginName)
 Called when the plugin was loaded.
void __cdecl onInitFinished ()
 Called after the RPG objects were initialized.
void __cdecl onInitTitleScreen ()
 Called before the title screen is initialized.
void __cdecl onNewGame ()
 Called before the player starts a new game.
void __cdecl onLoadGame (int id, char *data, int length)
 Called before the player loads a game from a savestate.
void __cdecl onSaveGame (int id, void __cdecl(*savePluginData)(char *data, int length))
 Called before the player saves a game.
void __cdecl onExit ()
 Called before the game exits.
void __cdecl onFrame (RPG::Scene scene)
 Called every frame, before the screen is refreshed (see details!)
bool __cdecl onSetVariable (int id, int value)
 Called before an in-game variable is set.
bool __cdecl onSetSwitch (int id, bool value)
 Called before an in-game switch is set.
bool __cdecl onEventCommand (RPG::EventScriptLine *scriptLine, RPG::EventScriptData *scriptData, int eventId, int pageId, int lineId, int *nextLineId)
 Called before an event command is executed.
bool __cdecl 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 __cdecl onDrawScreen ()
 Called when the screen is drawn on the game window.
bool __cdecl onDrawPicture (RPG::Picture *picture)
 Called before a picture is drawn.
bool __cdecl onPictureDrawn (RPG::Picture *picture)
 Called after a picture was drawn (or was supposed to be drawn)
bool __cdecl onCheckEventVisibility (RPG::Character *character)
 Called every frame to check whether an event should be drawn even though it is out of sight.
bool __cdecl onDrawEvent (RPG::Character *character, bool isHero)
 Called before an event or the hero is drawn.
bool __cdecl onEventDrawn (RPG::Character *character, bool isHero)
 Called after an event or the hero was drawn (or was supposed to be drawn)
bool __cdecl onDrawBattler (RPG::Battler *battler, bool isMonster, int id)
 Called before a battler is drawn.
bool __cdecl onBattlerDrawn (RPG::Battler *battler, bool isMonster, int id)
 Called after a battler was drawn (or supposed to be drawn)
bool __cdecl onDrawBattleStatusWindow (int x, int selection, bool selActive, bool isTargetSelection, bool isVisible)
 Called before the battle status window is drawn.
bool __cdecl 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 __cdecl onDrawBattleActionWindow (int *x, int *y, int selection, bool selActive, bool isVisible)
 Called before the battle action window is drawn.
bool __cdecl onDoBattlerAction (RPG::Battler *battler)
 Called before a battler's action is executed.
bool __cdecl onBattlerActionDone (RPG::Battler *battler, bool success)
 Called after a battler's action is executed.
bool __cdecl onSystemBackgroundDrawn (RECT *rect)
 Called after the system background was drawn.

Function Documentation

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

Called after a battler's action is executed.

Parameters:
battlerThe battler which is executing its action
successtrue 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.
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
bool __cdecl 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:
battlerThe battler which was drawn (or supposed to be drawn)
isMonstertrue if the battler is a monster
idZero-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
bool __cdecl 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:
xThe current X coordinate of the left side of the window
selectionThe zero-based party member ID of the currently selecter actor
selActivetrue if the selection parameter contains a valid value and a choice bar is drawn
isTargetSelectiontrue if it is the target selection window, false if it is the "normal" status window
isVisibletrue 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
bool __cdecl 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:
characterThe 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
bool __cdecl 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:
textThe comment's content as simple text
parsedDataThe already parsed data
nextScriptLineThe next event script line after the comment
scriptDataPointer to the RPG::EventScriptData object of the current event script
eventIdThe ID of the current event (negative for common events, zero for battle events)
pageIdThe ID of the current event page (zero for common and battle events - sorry, no battle event page ID yet)
lineIdThe zero-based line number
nextLineIdPointer 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
bool __cdecl onDoBattlerAction ( RPG::Battler battler)

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:
battlerThe battler which is executing its action
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
bool __cdecl 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:
xPointer to the X coordinate of the upper-left corner of the window
yPointer to the Y coordinate of the upper-right corner of the window
selectionZero-based index of the current selection
selActivetrue if the selection parameter contains a valid value and a choice bar is drawn
isVisibletrue 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
bool __cdecl 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:
battlerThe battler which is about to be drawn
isMonstertrue if the battler is a monster
idZero-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
bool __cdecl 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:
xThe current X coordinate of the left side of the window
selectionThe zero-based party member ID of the currently selected actor
selActivetrue if the selection parameter contains a valid value and a choice bar is drawn
isTargetSelectiontrue if it is the target selection window, false if it is the "normal" status window
isVisibletrue 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
bool __cdecl 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:
characterThe character which is about to be drawn (can also be the hero)
isHerotrue 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
bool __cdecl 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:
pictureThe 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
void __cdecl 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
bool __cdecl 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:
scriptLineThe event script line which is about to be executed
scriptDataPointer to the RPG::EventScriptData object of the current event script
eventIdThe ID of the current event (negative for common events, zero for battle events)
pageIdThe ID of the current event page (zero for common and battle events - sorry, no battle event page ID yet)
lineIdThe zero-based line number
nextLineIdPointer 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 \c 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
bool __cdecl 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:
characterThe character which was drawn or supposed to be drawn (can also be the hero)
isHerotrue 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
void __cdecl 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).
void __cdecl 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:
sceneGame 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
void __cdecl onInitFinished ( )

Called after the RPG objects were initialized.

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

See also:
onStartup
void __cdecl onInitTitleScreen ( )

Called before the title screen is initialized.

This function is called before the title screen fades in.

void __cdecl 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:
idSavestate ID
dataPointer to plugin data
lengthLength of plugin data
Note:
data may be 0 if there is no data.
See also:
onLoadGame
void __cdecl onNewGame ( )

Called before the player starts a new game.

bool __cdecl 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:
pictureThe 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
void __cdecl onSaveGame ( int  id,
void __cdecl(*)(char *data, int length)  savePluginData 
)

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:
idSavestate ID
savePluginDataCall 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
bool __cdecl 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:
idID of the switch to be changed
valueValue 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
bool __cdecl 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:
idID of the variable to be changed
valueValue 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
bool __cdecl 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:
pluginNameThe 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
bool __cdecl 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:
rectArea which has been (re)drawn
Note:
In the save/load menu, there is only the smart part at the top drawn, in the other menus, the whole screen is painted. Pay attention to the rect parameter.
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator