Essentials Docs Wiki

This page shows how to control game events by script commands. This includes how to make an event move around (applying a move route), change their graphic and so on.

Simple script commands

The script section Overworld contains several functions for controlling events with scripts. For an example of their use, see the scripts used by the Duel mini-game in script section Minigame_Duel.


Waits for x frames, where one frame is 1/40 of a second. While waiting, processes the rest of the scene.

pbShake(power, speed, x)

Shakes the screen with a given power and speed for x frames, where one frame is 1/20 of a second. Returns immediately, so that other things can be made to happen during the shaking.

pbFlash(color, x)

Flashes the screen with a given colour for x frames, where one frame is 1/20 of a second.

pbToneChangeAll(tone, duration)

Sets the color tone for the screen and all graphics thereon. Fades the tone in for duration frames, where one frame is 1/20 of a second.

pbMoveRoute(event, commands)

Runs a move route on an event, the player, or a follower. To set the player's move route, use $game_player for the event parameter. To set the move route for an event on the current map, use $[X], where X is the event's ID. event can be nil; this method returns the whole move route regardless. commands is an array of move route commands, with each command followed by a set of parameters for that command. Here is an example of a move route defined for the player:

pbMoveRoute($game_player, [
  PBMoveRoute::ChangeSpeed, 2, 

Notice that the ChangeSpeed command is followed by a number specifying the speed. The Backward command has no parameters. Here is a list of possible commands, together with their required parameters:

  • Down, Left, Right, Upno parameters
  • LowerLeft, LowerRight, UpperLeft, UpperRightno parameters
  • Randomno parameters
  • TowardPlayer, AwayFromPlayerno parameters
  • Forward, Backwardno parameters
  • TurnDown, TurnLeft, TurnRight, TurnUpno parameters
  • TurnRight90, TurnLeft90, Turn180, TurnRightOrLeft90no parameters
  • TurnRandom, TurnTowardPlayer, TurnAwayFromPlayerno parameters
  • WalkAnimeOn, WalkAnimeOffno parameters
  • StepAnimeOn, StepAnimeOffno parameters
  • DirectionFixOn, DirectionFixOffno parameters
  • ThroughOn, ThroughOffno parameters
  • AlwaysOnTopOn, AlwaysOnTopOffno parameters
  • Jump - X offset; Y offset
  • Wait - Number of frames to wait (1/20 second)
  • SwitchOn - Switch number
  • SwitchOff - Switch number
  • ChangeSpeed - Desired movement speed (1-6)
  • ChangeFreq - Desired frequency (1-6)
  • Graphic - Filename; hue (0-359); direction (2=up, 4=left, 6=right, 8=up); pattern (0-3)
  • Opacity - New opacity (0-255)
  • Blending - New blend type (0=normal, 1=add, 2=subtract)
  • PlaySE - Name of the sound effect (SE) file to play
  • Script - Script to run
  • ScriptAsync - Script to run (the move route doesn't wait for its completion before continuing)

When using pbMoveRoute, it will always set ThroughOn at the beginning and ThroughOff at the end. This means the event can be made to move to places it wouldn't ordinarily be allowed to go (e.g. the player walking on water, an NPC moving over a tree). Be sure that nothing strange can happen because of this.

This function returns immediately, and doesn't wait for the move route to complete. This function's return value is the generated move route (RPG::MoveRoute).