KageDesu/aabsz_ext_level_up_animation.md

## aabsz_ext_level_up_animation.md

      
    Raw
  

              aabsz_ext_level_up_animation.md
            
          
    Custom Level Up Animation (AABSZ Extension)

This extension plugin requires Alpha ABS Z to work.
⚠️ Information valid for version 0.11 and above

🎯 Overview

This guide will help you implement a custom level-up animation using the AABSZ extension. Follow the steps below to create a unique and engaging experience for your players.
The Custom Level Up Animation extension allows you to create sophisticated level-up effects that trigger when a player character gains a level. You can combine multiple types of visual and audio feedback including database animations, image sequence animations, sound effects, popup text, common events, and custom script actions.

📋 Table of Contents


Installation
Configuration Overview
Animation Types
PopUp Text Configuration
Advanced Features
Examples
Troubleshooting


🔧 Installation


Ensure you have Alpha ABS Z plugin installed and properly configured
Place the Alpha_ABSZ_Ext_LevelUpAnimation plugin after the Alpha ABS Z plugin in your plugin list
Configure the plugin parameters according to your needs (detailed below)


⚙️ Configuration Overview

The plugin uses a single configuration structure called Visual Settings which contains all customization options:
Main Configuration Structure

{
    databaseAnimationId: 0,           // RPG Maker animation ID
    imageSeqAnimationName: "",        // Image sequence animation file
    imageSeqAnimationMargins: {x: 0, y: 0}, // Animation position offset
    extraSE: "",                      // Sound effect file
    isShowPopUp: true,                // Enable/disable popup text
    popUpText: "Level %1!",          // Popup text template
    popUpStyle: {...},               // Popup visual styling
    commonEvent: 0,                  // Common event ID to trigger
    scriptAction: ""                 // Custom script to execute
}

🎬 Animation Types

1. Database Animation

Parameter: databaseAnimationId

Type: Number (Animation ID)
Default: 0 (no animation)
Description: Plays a standard RPG Maker MZ animation from the database

Usage:

Create an animation in the database (Animations tab)
Note the animation ID number
Enter the ID in the databaseAnimationId field

2. Image Sequence Animation

Parameter: imageSeqAnimationName

Type: String (filename)
Directory: img/pictures/
Naming Rule: filename(frames,delay).png
Description: Plays a custom sprite sheet animation

File Naming Examples:

levelup(8,4).png - 8 frames with 4-frame delay between each
explosion(12,2).png - 12 frames with 2-frame delay
sparkle(6,6).png - 6 frames with 6-frame delay

Margins: Use imageSeqAnimationMargins to adjust the animation position:
imageSeqAnimationMargins: {
    x: 10,  // Horizontal offset in pixels
    y: -20  // Vertical offset in pixels (negative = up)
}
3. Sound Effect

Parameter: extraSE

Type: String (filename)
Directory: audio/se/
Description: Plays a sound effect when leveling up

Usage:

Enter the filename without extension (e.g., levelup_sound for levelup_sound.ogg)
Leave empty for no sound effect


💬 PopUp Text Configuration

Basic PopUp Settings

Enable PopUp: isShowPopUp

Set to true to show popup text
Set to false to disable popup text

PopUp Text: popUpText

Template string for the popup message
Use %1 as placeholder for the new level number
Example: "Level %1!" becomes "Level 5!" when reaching level 5

PopUp Style Configuration

The popUpStyle parameter controls the visual appearance:
popUpStyle: {
    id: "levelUp",           // Unique identifier
    randDX: 0,              // Random horizontal variance
    randDY: 10,             // Random vertical variance
    stayTime: 12,           // How long popup stays (frames)
    noFlyUp: false,         // Disable upward movement
    noFadeOut: false,       // Disable fade out effect
    changeFontSize: 16,     // Font size modifier
    text: {
        visible: true,
        size: {w: 60, h: 20},
        margins: {x: 0, y: 0},
        alignment: "center",    // "left", "center", "right"
        outline: {
            color: null,        // Outline color (CSS format)
            width: 2           // Outline width in pixels
        },
        font: {
            face: "AABS_3",    // Font family name
            size: 12,          // Font size
            italic: false      // Italic style
        },
        textColor: "#deb521"   // Text color (CSS format)
    },
    image: null                // Optional background image
}
PopUp Animation Parameters


randDX/randDY: Adds random positioning variance (0-100 recommended)
stayTime: Duration in frames (60 frames = 1 second)
noFlyUp: When true, popup stays in place instead of floating upward
noFadeOut: When true, popup disappears instantly instead of fading

Text Styling Options


alignment: Controls text alignment within the popup area
outline: Adds text outline for better readability
font.face: Use system fonts or custom fonts loaded in your project
textColor: Supports hex colors (#FF0000), RGB, or CSS color names


🔧 Advanced Features

Common Events

Parameter: commonEvent

Type: Number (Common Event ID)
Description: Triggers a common event when leveling up
Use Cases:

Custom dialogue
Additional visual effects
Game state changes
Achievement unlocks


Script Actions

Parameter: scriptAction

Type: String (JavaScript code)
Description: Executes custom JavaScript code
Context: The character object is available for manipulation

Example Script Actions:
// Flash the screen
"$gameScreen.startFlash([255, 255, 255, 128], 30)"

// Play a custom animation with specific timing
"this.setMoveSpeed(1); this.jump(0, 0)"

// Show a custom message
"$gameMessage.add('Congratulations on reaching level ' + this._level + '!')"

📖 Examples

Example 1: Simple Level Up Effect

{
    databaseAnimationId: 15,      // Use animation #15 from database
    extraSE: "levelup",           // Play levelup.ogg sound
    isShowPopUp: true,
    popUpText: "LEVEL UP!",
    commonEvent: 0,
    scriptAction: ""
}
Example 2: Advanced Visual Effect

{
    databaseAnimationId: 0,
    imageSeqAnimationName: "levelup_sparkles(10,3)",
    imageSeqAnimationMargins: {x: 0, y: -30},
    extraSE: "magic_chime",
    isShowPopUp: true,
    popUpText: "Level %1 Achieved!",
    popUpStyle: {
        randDY: 15,
        stayTime: 90,
        changeFontSize: 20,
        text: {
            textColor: "#FFD700",
            font: {face: "Arial", size: 16, italic: true},
            outline: {color: "#000000", width: 3}
        }
    },
    commonEvent: 5,
    scriptAction: "$gameScreen.startFlash([255, 215, 0, 100], 60)"
}
Example 3: Minimal Setup

{
    databaseAnimationId: 0,
    imageSeqAnimationName: "",
    extraSE: "",
    isShowPopUp: true,
    popUpText: "+1 Level!",
    popUpStyle: {
        text: {
            textColor: "#00FF00",
            alignment: "center"
        }
    },
    commonEvent: 0,
    scriptAction: ""
}

🎨 Creating Image Sequence Animations

Step 1: Create Your Sprite Sheet


Design your animation frames horizontally in a single PNG file
Each frame should be the same width and height
Arrange frames from left to right

Step 2: Name Your File

Follow the naming convention: filename(frames,delay).png

frames: Number of animation frames in the sprite sheet
delay: Number of game frames between each animation frame

Step 3: Place in Correct Directory

Save the file in your project's img/pictures/ folder
Example Sprite Sheets


8-frame explosion: explosion(8,4).png

8 frames total, 4-frame delay = smooth animation


12-frame sparkle: sparkle(12,2).png

12 frames total, 2-frame delay = fast animation


🛠️ Troubleshooting

Animation Not Playing


Check plugin order: Ensure this plugin is loaded after Alpha ABS Z
Verify animation ID: Make sure the database animation ID exists
Check file names: Ensure image sequence files follow the correct naming format
File location: Confirm files are in the correct directories

PopUp Not Appearing


Enable setting: Ensure isShowPopUp is set to true
Text content: Make sure popUpText is not empty
Style configuration: Check that popUpStyle is properly configured

Sound Effects Not Playing


File format: Use supported audio formats (OGG, M4A, WAV)
File location: Ensure sound files are in audio/se/ directory
File naming: Use filename without extension in the parameter

Performance Issues


Animation optimization: Use fewer frames or increase delay for complex animations
PopUp limits: Avoid very long stayTime values
Script actions: Keep custom scripts simple and efficient

Common Event Not Triggering


Event ID: Verify the common event ID exists and is greater than 0
Event content: Ensure the common event has valid commands
Plugin conflicts: Check for conflicts with other event-related plugins


📝 Notes


All animation types can be used simultaneously for layered effects
The %1 placeholder in popup text is automatically replaced with the new level number
Random variance (randDX, randDY) adds natural variation to popup positioning
Custom fonts must be properly loaded in your project to display correctly
Script actions have access to the character object and standard RPG Maker globals


Happy game developing! 🎮
No results found