Skip to content

Instantly share code, notes, and snippets.

@KageDesu

KageDesu/VPlayer_guide.md

Last active June 3, 2025 17:39
Show Gist options
  • Save KageDesu/35006f13cbdd3b6a590a240b134641be to your computer and use it in GitHub Desktop.
Save KageDesu/35006f13cbdd3b6a590a240b134641be to your computer and use it in GitHub Desktop.
Download ZIP
VPlayer RPG Maker plugin guide
Raw
VPlayer_guide.md

VPlayer plugin for RPG Maker MV and MZ

Table of Contents

  1. Introduction
  2. Script Calls
  3. Examples
  4. Advanced Controls
  5. Warnings
  6. Animated Battlers
  7. Battle Animations

Introduction

This document provides detailed instructions on using various script calls to add and control animated images in RPG Maker MV and MZ. The scripts allow you to display, move, scale, and manipulate animations in different scenes such as maps and battles.

Script Calls

General Usage

  • ShowVAnim(ID, FILE_NAME, X, Y, IS_LOOP)

    • Adds an animated image to any scene above all windows.
    • Parameters:
      • ID: Unique identifier for the animation.
      • FILE_NAME: Name of the .webm file (without extension) located in the movies folder.
      • X, Y: Coordinates in pixels.
      • IS_LOOP: true for looping the image, false otherwise.

  • DeleteVAnim(ID)

    • Removes the animated image with the specified ID.

  • DeleteAllVAnims()

    • Removes all animated images.

  • PreloadVAnim(FILE_NAME)

    • Preloads the specified .webm file for faster loading when used in animations.
    • Note: This should be called before using the animation.
    • Loads the animation into memory (it is not shown on the screen) and the sound for this animation is not played. When you call the usual method to display an animation with a given name, the previously loaded image from memory will be used. You can use this method a little in advance if you need to display a large animation file at a specific point in the game.

Map and Battle Scene

  • ShowVAnimOnSpriteset(ID, FILE_NAME, X, Y, IS_LOOP)

    • Adds an animated image to the Map or Battle Scene below windows.

  • ShowVAnimOnMap(ID, FILE_NAME, X, Y, IS_LOOP)

    • Adds an animated image to the Map like a character, below events.
    • Note: X, Y coordinates are in map cells.

  • ShowVAnimOnMapAboveEvents(ID, FILE_NAME, X, Y, IS_LOOP)

    • Adds an animated image to the Map like a character, above events.

  • ShowVAnimScreenBelowPictures(ID, FILE_NAME, X, Y, IS_LOOP)

    • Adds an animated image to the Screen below all pictures.

  • ShowVAnimWithCharacter(ID, FILENAME, EVENT_ID, DX, DY, IS_LOOP, IS_ABOVE)

    • Adds an animated image to the Map like a character, above or below the specified event.
    • Animation will move with the event.
    • Note: DX, DY are offsets in pixels.
    • Note: IS_ABOVE is true for above the event, false for below.
    • Note: EVENT_ID is the ID of the event. If 0 - the player.

Advanced Controls

  • MoveVAnim(ID, X, Y, DURATION)

    • Moves the animated image to the specified coordinates.
    • Note: DURATION is in frames.

  • ScaleVAnim(ID, SCALE_X, SCALE_Y, DURATION)

  • MirrorVAnim(ID, IS_MIRROR)

    • Mirrors the animated image horizontally.

  • ChangeOpacityVAnim(ID, OPACITY, DURATION)

  • SetAnchorForVAnim(ID, X, Y)

    • Sets the anchor point for the animated image.

  • SetVAnimPause(ID, IS_PAUSE)

  • SetEndScriptToVAnim(ID, SCRIPT, IS_ONCE)

    • Calls the script when the animation ends.
    • Note: IS_ONCE is true for a one-time call.

  • SetEndCommonEventToVAnim(ID, COMMON_EVENT_ID, IS_ONCE)

  • SetClickScriptToVAnim(ID, SCRIPT, IS_ONCE)

    • Calls the script when the animation is clicked.

  • SetClickCommonEventToVAnim(ID, COMMON_EVENT_ID, IS_DELETE)

    • Calls the common event when the animation is clicked.

  • SetVAnimCEOnTime(ID, TIME_IN_FRAMES, COMMON_EVENT_ID)

    • Calls the common event after the specified time.
    • Note: If you use looped animation, be sure that the TIME_IN_FRAMES is lower than the animation duration.

  • SetVAnimSCOnTime(ID, TIME_IN_FRAMES, SCRIPT)

    • Calls the script after the specified time.
    • Note: If you use looped animation, be sure that the TIME_IN_FRAMES is lower than the animation duration.

  • SetVAnimSoundOnTime(ID, TIME_IN_FRAMES, SE_FILENAME)

    • Plays the sound effect after the specified time.
    • Note: You can set many events and sounds for a single animation, even at the same time.
    • Note: If you use looped animation, be sure that the TIME_IN_FRAMES is lower than the animation duration.

  • SetVAnimCurrentPlayTime(ID, TIME_IN_SECONDS)

    • Sets the current play time of the animation.
    • Note: The animation will start/continue from the specified time.

  • GetVAnimCurrentPlayTime(ID)

    • Returns the current play time of the animation.

  • AdjustVAnimVolume(ID, VOLUME)

    • Adjusts the volume of the animation.

  • ChangeVAnimPlaySpeed(ID, SPEED)

    • Changes the play speed of the animation. From 0.1 to 10.
    • Note: 1 is the default speed.

  • AddOnInterruptScriptCall(ID, SCRIPT_TEXT)

    • Adds a script to call when the animation is interrupted (Scene is changed).

Battle

  • SetVAnimBattleBack(ID, X, Y)
    • Sets the animated image as a battle background.

Examples

  • Adding an animation:

    ShowVAnim(44, "test", 0, 0, true)

  • Adding an animation to the map:

    ShowVAnimOnMap(11, "fire", 4, 6, true)

  • Adding an animation to the map to character:

    ShowVAnimWithCharacter(555, "fire", 30, 0, 0, true, true)

  • Removing an animation:

    DeleteVAnim(44)

  • Moving an animation:

    MoveVAnim(44, 100, 100, 120)

  • Scaling an animation:

    ScaleVAnim(44, 0.4, 0.4, 60)

  • Mirroring an animation:

    MirrorVAnim(1, false)

  • Changing animation opacity:

    ChangeOpacityVAnim(1, 128, 60)

  • Setting an anchor point for animation:

    SetAnchorForVAnim(1, 0.5, 0.5)

  • Pausing and resuming an animation:

    SetVAnimPause(1, true)  // Pause
SetVAnimPause(1, false) // Resume

  • Setting a script to call at animation end:

    SetEndScriptToVAnim(44, "console.log('Hello')", false)

  • Setting a common event to call at animation end:

    SetEndCommonEventToVAnim(44, 11, false)

  • Setting a script to call on animation click:

    SetClickScriptToVAnim(1, "console.log('Clicked')", false)

  • Setting a common event to call on animation click:

    SetClickCommonEventToVAnim(1, 11, false)

  • Setting a common event to call after a specified time:

    SetVAnimCEOnTime(1, 120, 11)

  • Setting a script to call after a specified time:

    SetVAnimSCOnTime(1, 120, "console.log('Time is up')")

  • Setting a sound effect to play after a specified time:

    SetVAnimSoundOnTime(1, 120, "Fire1")

  • Setting the current play time of an animation:

    SetVAnimCurrentPlayTime("myAnim", 3.5)

  • Setting an animation as a battle background:

    SetVAnimBattleBack("battle", 0, 0)
SetVAnimBattleBack("") // Removes the battle background

  • Adjusting the volume of an animation:

    AdjustVAnimVolume("myAnim", 0.5) // 0.5 is 50%

  • Changing the play speed of an animation:

    ChangeVAnimPlaySpeed("myAnim", 2) // 2x speed

  • Adding a script to call when the animation is interrupted:

    AddOnInterruptScriptCall('1', "console.log('interrupted')");

Warnings

  • Persistent Animations: Not deleted map animation images with looping (IS_LOOP is true) will be saved with the game.

  • File Usage: Avoid using the same .webm file with different IDs in RPG Maker MZ.

Animated Battlers

  • Adding a GIF to an enemy:

    • Add <GIF:NAME> to the enemy's note field in the database where NAME is the .webm file name.
    • Example: <GIF:Slime>
    • Note: The .webm file should be located in the movies folder (movies/Slime.webm).

  • Using random GIF for enemy:

    • <GIF_RAND:NAME1,NAME2,...> sets a random animation from the list.
    • Example: <GIF_RAND:SlimeA,SlimeB,SlimeC>

  • Setting margins for animation:

    • <gifMargins:X,Y> sets extra margins for the animation.
    • Example: <gifMargins:0,-60>

  • Changing animation on hit or attack:

    • <onGotHitGIF:NAME> changes animation when the enemy is hit.
    • <onAttackGIF:NAME> changes animation when the enemy attacks.

  • Using skill-specific animations:

    • <onUseSkillGIF_ID:NAME> changes animation when the enemy uses a specific skill.
    • Example: <onUseSkillGIF_20:fireball>

  • Using action animation names as postfixes:

    • Add <GIFAsPostfix> to the enemy's note field to use action animation names as postfixes for the GIF.

Examples:

<GIF:slime>
<GIFAsPostfix>
<onGotHitGIF:hit> \\ will use `slime_hit.webm` for the hit animation.
<GIF_RAND:slimeA,slimeB,slimeC>
<GIFAsPostfix>
<onGotHitGIF:hit> \\ will use `slimeA_hit.webm` or `slimeB_hit.webm` or `slimeC_hit.webm` for the hit animation, depending on the random choice.

  • Forcing animation change in battle:

    ForceChangeEnemyVAnimByEnemyId(ENEMY_ID, NAME, SET_BACK_TIMER)
ForceChangeEnemyVAnimByTroopIndex(TROOP_INDEX, NAME, SET_BACK_TIMER)
    • Note: SET_BACK_TIMER - 0 (no need) or the time in frames when the animation returns to its initial state.

Battle Animations

Note: Only for RPG Maker MZ.

You can play GIF animations instead Effekseer Animation in battles.

  • Replacing Effekseer animation to GIF

    • Add :GIF to the animation name in the database. In the end, it should look like Fire1:GIF.

    • Note: The .webm file should be located in the movies folder (movies/Fire1.webm).

    • You can edit Scale, Speed, Offset X and Y in the animation settings. Rotation is not supported.

GIF for skills animations

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment