Spriter Plugin

Spriter Plugin v.1.3.5
KanaX

Introduction
Allows user to utilize Spriter Pro save files and sprite parts for Skeletal Animations

Features

• Using Spriter, it is easy to create functional, fluid, expressive animations with sprite parts, without needing to create large numbers of sprite sheets.
• Additionally, Spriter Plugin allows you to manipulate your new Spriter sprites and give them special functions like:
  • Moving sprite in slow-mo, or fast-forward.
  • Change the bitmaps of a sprite so that the same animation is done with a different visual character.
    Example: Change skin set from a man to a woman, doing the exact same movement.
    
  • Change/add new parts to your existing animation.
    Example: Add hat to character / Change hair of character.
  • Add sound effects according to the animation cycle.
    Example: Footstep, every time the character's foot lands their foot down.

Videos
Here's a little story created with Spriter Sprites (View in 720p and fullscreen for better experience):

Here's the same video with labels explaining what happened where:

Spoiler: Click Here

A display of Spriter Sprites:

Spoiler: Click Here

A display of Bones, the moving parts that sprite pieces "stick" on.

Spoiler: Click Here

The animation when it is in Spriter:

Spoiler: Click Here

How to Use

Spoiler: Click Here

Installation:

1. Paste js file in js/plugins/
2. Create path img/characters/Spriter/ and inside Spriter, a folder named Single Bitmaps.
3. Paste SpriterObjects.json in data/ or copy the one from the demo.
4. Create path data/animations/.
5. Enable the plugin from the Plugin Manager and assign a number for the variable which will store animation info.
   WARNING: Do not modify that variable after activating the plugin.
   
6. Have some ramen noodles, because you deserve them.

Regarding Spriter:

1. The plugin should work as expected in most regards (please check "Future Updates/Fixes" for more information).
2. The first 4 animations in a Spriter project will respond to the character's 4 directions. If you want your character to move without Direction Fix, you have to create at least 4 animations.
3. While you can change the pivot of your bitmaps when you have inserted them into your project, you must not edit pivot x and pivot y in Edit Image's Default Pivot
   
4. Spriter might face some problems with its documentation, so if something inexplicably does not work, try redoing the animation. If that does not fix your problem, feel free to contact the plugin creator.

Plugin Operation:

1. Paste Spriter Pro save file in data/animations/. The file name will be the skeleton,
2. Create a folder in img/character/Spriter/, named after the Skinset. The Skinset folder should have 4 folder which each taking the parts for each direction.
   
   Example:
   Folder_1: [head,torso,r_arm,_r_leg,_l_arm,l_leg],
   Folder_2: [head,torso,r_arm,_r_leg,_l_arm,l_leg],
   Folder_3: [head,torso,r_arm,_r_leg,_l_arm,l_leg],
   Folder_4: [head,torso,r_arm,_r_leg,_l_arm,l_leg]
   
   Note: If you use TexturePacker spritesheets, instead of creating folders for each direction, just place in the Skinset folder the .png spritesheet and the .json file. Make sure to name them the same as the Skinset folder. Step 3 is also null.
   
   
3. Inside the Skinset folder, create the folders with the bitmaps you used for the animation.
4. If you want certain Spriter Sprites to appear globally across the game (such as animated armor and weapons for actors) you need to create them in the SpriterObjects.json file in your data folder. (See more info about SpriterObjects.json in About SpriterObjects.json).
   
5. To create a Spriter Sprite for actors, go to Tools -> Database and write this on the actors' notes:
   <Spriter:{
   "_skeleton": The file name of the animation you want to choose from data/animations/,
   "_skin": The folder name of the Skinset you want to choose from img/characters/Spriter,
   Note: If you use TexturePacker spritesheets, add a "$" in front of the skin name.
   "_speed": Speed of animation,
   "_cellX": Width of the area the main animation takes part in (example: the standard MV character cell width is 48),
   "_cellY": Height of the area the main animation takes part in (example: the standard MV character cell height is 48),
   "_spriteMask": Determine if the sprite will have a mask around it. If true, you need to fill the tags below,
   "_spriteMaskX": X value of mask origin. 0, 0 is the top left corner of the cell,
   "_spriteMaskY": Y value of mask origin. 0, 0 is the top left corner of the cell,
   "_spriteMaskW": Width of the mask,
   "_spriteMaskH": Height of the mask
   }>
   
   Example:
   <Spriter:{
   "_skeleton": "female_running",
   "_skin": "female4",
   "_speed": 4,
   "_cellX": 48,
   "_cellY" : 48,
   "_spriteMask": true,
   "_spriteMaskX": 0,
   "_spriteMaskY": 0,
   "_spriteMaskW": 48,
   "_spriteMaskH": 48
   }>
   
   Screenshot Examples
   
   
   
   
6. To create a Spriter Sprite for an event create a comment in the active event page:
   <Spriter, skeleton, skinset, speed, cellX, cellY, false>
   or
   <Spriter, skeleton, skinset, speed, cellX, cellY, true, maskX, maskY, maskW, maskH>
   
   Example
   <Spriter, doggo, sheperd, 10, 48, 32, true, 0, 0, 48, 32>
   
   WARNING: 01/24/2018 THERE IS A PIXI.JS BUG IN v4.5.4 THAT MAKES MASKS NOT WORK IF THE MAP HAS TILES.
   
   
7. Animations play when 1) an actor/event has walking animation on and is moving, or 2) an actor/event has stepping animation on.
   
   
8. For animations that are supposed to loop (walking animations, rolling balls, etc.), you need to toggle the Repeat Playback button in the Spriter Pro timeline.

About SpriterObjects.json

Much like the MV Sprite_Character class, Spriter_Character class looks for data in the actor/event object in order to create/update a sprite. But what happens when we want our character to hold an animated sprite? A sprite whose animation is separate from the animation of its parent? Like a torch, or a magic aura. And what do we do when we want to keep these sprites for multiple maps?

That's why we create SpriterObjects!

In SpriterObjects we create faux game objects, with just the bare minimum data to satisfy the needs of the Spriter_Character class. You create a new object, you give it a name, skeleton, skin and then you can attach it to any character you want!
These objects are created as comments in the COMMON EVENT with the ID that you assigned on the Spriter Objects Common Event ID:

<objectName, skeleton, skin, speed, cellX, cellY>

Example:

Spoiler: Click Here

Plugin Commands:

1. eventSkeleton eventId data/animations/skeleton Spriter/skinsetName
   (Changes skeleton. Since skeleton changes, skinset needs to change as well.)
   Example: eventSkeleton 1 waving_hello male_1
   
   
2. eventSkin eventId Spriter/skinsetName
   (Changes Skinset. Needs to be compatible with skeleton.)
   Example: eventSkin 1 male_2
   Note: For TexturePacker spritesheets, add a "$" in front of "male_2"
   
   
3. eventStop eventId true/false
   (Stops Animation.)
   Example: eventStop 1 true
   
   
4. eventRecovery eventId ("snap"/"freeze")
   (Snap resets animation when movement stops. Freeze pauses animation.)
   Example: eventRecovery 1 freeze
   
   
5. eventSkinPart eventId imageName (Spriter/skinsetName)-or-(bitmap name from Single bitmaps) fullsprite?
   (Changes only a single image from that skinset to another, compatible one. fullsprite is set to true or false and determines if the new bitmap will be from a full spriteset or not. If it is set to true then the user will have to use the desired spriteset path. If it is set to false then the user will have to use the desired bitmap path from within the Single Bitmaps folder)
   Example1: eventSkinPart 1 hat Items/helmet true
   (helmet needs to be a folder with the same filename/location as the one of the previous bitmap)
   Example2: eventSkinPart 1 r_hand_weapon mace false
   (mace needs to be a bitmap inside the Single Bitmaps folder)
   
   Note: For TexturePacker spritesheets, add a "$" in front of "Items/helmet"/"mace"
   
   
6. eventRemoveSkinPart eventId imageName
   (Removes Spriter/skinsetName bitmap from imageName)
   Example: eventRemoveSkinPart 1 r_hand_weapon
   
   
7. eventChildSprite eventId imageName objectName
   (Assigns a sprite from data/SpriterObjects.json to imageName)
   Example: eventChildSpriter 1 r_hand_weapon glowing_mace
   (glowing_mace needs to be an object in SpriterObjects)
   
   
8. eventRemoveChildSprite eventId imageName objectName
   (Remove sprite object)
   Example: eventChildSpriter 1 r_hand_weapon glowing_mace
   
   
9. playerSkeleton data/animations/skeleton Spriter/skinsetName
   
10. playerSkin Spriter/skinsetName
    
11. playerStop true/false
    
12. playerRecovery ("snap"/"freeze")
    
13. playerSkinPart imageName Spriter/skinsetName
    
14. playerRemoveSkinPart imageName
    
15. playerChildSprite imageName objectName
16. playerRemoveChildSprite imageName objectName
17. followerSkeleton followerId data/animations/skeleton Spriter/skinsetName
18. followerSkin followerId Spriter/skinsetName
19. followerStop followerId true/false
20. followerRecovery followerId ("snap"/"freeze")
21. followerSkinPart followerId imageName Spriter/skinsetName
22. followerRemoveSkinPart followerId imageName
23. followerChildSprite followerId imageName objectName
24. followerRemoveChildSprite followerId imageName objectName

Script Calls:

1. $gameMap._events[1].resetAnimation = true;
   (Resets animation)
   $gamePlayer.resetAnimation = true;
   $gamePlayer.followers()[1].resetAnimation = true;
2. $gameMap._events[1].hasActiveTag("tagName");
   (Checks if character has an active tag for this frame)
   
   
3. $gameMap._events[1]._spriter.var.variableName
   (Returns value for variableName for this Frame)

Tag Commands: (Place tags on Spriter with the following labels for special effects)

1. se,seName,pan,pitch,volume,fade(, areaOfMaxVolume, areaOfTotalFade)
   (Plays SE sound. If fade is true, the sound fades away the further the player is from the source)
   Example1: se,step,0,100,60,true,3,10
   Example2: se,clock,0,80,100,false
   
   
2. SkinPart,imageName,(Spriter/skinsetName)-or-(bitmap name from Single bitmaps),fullsprite?
   (Works exactly like the plugin command. Useful for automatically spawning sprites with certain skinParts. Not so useful if those sprites change parts often.)
   Example1: SkinPart,hat,stink_lines,false
   Example2: SkinPart,torso,Items/tuxedo,true
   
   
3. RemoveSkinPart,imageName,(Spriter/skinsetName)-or-(bitmap name from Single bitmaps),fullsprite?
   Example: RemoveSkinPart,hat,stink_lines,false
   
   
4. ChildSprite,imageName,objectName
   (Works exactly like the plugin command.Useful for automatically spawning sprites with certain childSprites. Not so useful if those sprites change children often.)
   Example: ChildSprite,r_hand_tool,twinking_axe
   
   
5. RemoveChildSprite,imageName,objectName
   Example: ChildSprite,r_hand_tool,twinking_axe

Demo
[Click Here] The Autorun Story might not perform well on less powerful computers.

Tutorial
[Click Here] Please excuse the typos and timing.

Plugin
[Click Here]

Credit and Thanks

• Free for use in all projects.
• Please provide credits to KanaX.
• Feel free to let me know about your project, or any ideas regarding the plugin.
• Special Thanks to ivan.popelyshev (https://github.com/pixijs/pixi-display/tree/layers)

Future Updates/Fixes

• Fix reverse animations (this._speed < 0).
• Add ability to distort texture meshes.
• Make functional masks after dealing with a pixi.js bug.

Author's Notes

I hope this contributes to the community that helped me substantially with my growth!

It is my first official plugin so feel free to recommend any changes, fixes, suggestions, offer criticism, etc.

UPDATE: If you are interested in using Spriter Plugin in a battle scene, feel free to contribute in this poll.

02/22/2018: Fixed Subfolder Issue of RPGMV version 1.6
03/18/2018: Added:

1. Performance Boosters
2. Bezier Curve Tweening for Animations
3. Instant Tweening for Animations
4. TexturePacker Support

​

04/30/2018:

1. Fixed saving issue.
2. Replaced bitmaps with textures.
3. Tweaked the core of the plugin to work with up-coming Battle_Scene add-on.
4. With tagging certain sprites can automatically change their skin according to their equipment.

​

 

Are you kidding me.... cutscenes are going to be amazing using this. Do you think it’s possible to use an animation sequence with an action battle system?

 

I would guess that it's very possible. However, this plugin does not encompass battle scenes, partly because I have never created a battle scene in my life!
Nevertheless, with enough demand, I might just do it.

 

Might actually have a use for spriter that I bought a year ago and never use. Thanks for this.

 

In your video, the character pulls the sheet away and gets out of bed.

How did you make this animation play once in it's entirety, rather than looping?

Looping is obviously useful for run cycles and such, but what if I want a one time animation to play and not loop? eg. an explosion

 

Spriter Pro has a "repeat" button that allows looping on play. This info is documented in the save file and I use it to determine which animations are meant to loop or not.
I would like to thank you, however, I forgot to mention that.

 

Thank you . Awesome plugin btw! I've been praying for this since I got MV.
Hoping to use it to add effects to the world and screen (eg. an alien spaceship swooping down and beaming down a character).

 

That's pretty rad.

 

This is insane! @.@ You're amazing! I... i can't believe in my eyes

 

Hi @KanaX ,I have this error when starting new game

 

Well there is no property named toLowerCase on the plugin. After a bit of looking up, there seems to be an issue with a parameter you made. May I ask you to send me your project here? https://www.dropbox.com/request/YPgSPPLTJS7KjGqRl627

Edit: I has the dumb, the error was in an alias I made.

 

Thanks @KanaX
i have problem access Dropbox, so i will send you my project in GoogleDrive to your inbox, uploading now

Hi @KanaX, i uploaded my project on GoogleDrive and send the link (in txt file) to your dropbox

 

Congrats on getting it done! Now when will WSS be finished?

 

@Hudell when Orange Season leaves early access.

 

Amazing work, and a very pedagogical explanation on how it works.

 

Wow that is fantastic! I could make so many cut scenes with this. Forgive my scripting ignorance but would this work with a script for 8 directional movement/sprites?

also I keep getting an error in the demo :-( "reference error : arga is not defined"

 

@Alopexdog Oh my gosh, I'm so sorry. Made an error in the new fix I did a few hours ago. And I'm sorry I didn't see the reply sooner. Please download the new version of Spriter.js from github and replace the old one.

 

This is amazing. I just got Spriter and now I can do some cool stuff with it with the NPCs in the game! Thank you

 

Thanks KanaX It's a fantastic plugin.