JPSprite

JPSprite

Atlases, sprites and animated sprites manager
Version: 4.0
Price: Lite / $50
v4.0
- Now compatible with ShiVa 2.0.
- Plugin API compiled for Mac and Linux in addition to Windows : it will provide API completion in the Script module in ShiVa Editor for each of these operating systems.
- Now uses a user token instead of an email to activate

v3.3
- New function JPSprite.computeAnimation ( ), allowing to detect animations having sprites in different atlasses.
- Animations are not computed in the JPSprite.setupAtlas function anymore.
- When kResizeModeNone is set, the component "aspect ratio invariant" property is not updated anymore.

v3.2
- Half of the features of the pack are now available for free! This is everything that is not related to sprites animation, such as atlas setup, static sprites loading etc.
The paid version adds support for sprite animation engine and enables the optimisation features.

A tutorial about JPSprite and Texture packer <a href="/tutorial?v=jpsprite_and_texturepacker" target="_blank" rel="noopener"><b>is now available.</b></a>

A new sample is available for JPSprite. It shows the core features of JPSprite and its optimisation system.
<a href="/samples" target="_blank" rel="noopener"><b>JPSpriteSample</b></a>

New function:
- tIndexesToUpdate, nUpdateCoef = JPSprite.helpMeUpdateMySprites ( nSpriteCount )

v3.1
- Fixed a few bugs related to the previous major update related to sprites scale
- When not set, default scale option is now always JPSprite.kResizeModeFull

v3.0
New functions, added scale support for objects and additional scale options for both objects and HUD components:
- JPSprite.setObjectScale ( hObject, nSubset, nEffectMap, nScale )
- nScale = JPSprite.getObjectScale ( hObject, nSubset, nEffectMap )
- nScale = JPSprite.getObjectScaleOverall ( hObject, nSubset, nEffectMap )
- JPSprite.setGlobalComponentsScale ( nScale )
- JPSprite.setGlobalObjectsScale ( nScale )
- nScale = JPSprite.getGlobalComponentsScale ( )
- nScale = JPSprite.getGlobalObjectsScale ( )

New constants:
- JPSprite.kResizeModeNone
- JPSprite.kResizeModeFull
- JPSprite.kResizeModeRatioBasedOnHeight
- JPSprite.kResizeModeRatioBasedOnWidth

Fixes:
- Fixed an issue with bFlipX for function JPSprite.setObjectSprite ( hObject, sSprite, bFlipX, bFlipY, kResizeMode )

v2.3
- Fixed an issue on Android with the function JPSprite.setObjectSprite

v2.2
- Optimized for ShiVa 1.9.2

v2.1
- Fixed a bug with animation (the last frame was not displayed)

v2.0
- The following functions where not referenced into the extension plugin:
JPSprite.setDefaultFrameRate ( nFrameRate )
JPSprite.setObjectAnimationFrame ( hObject, nSubset, nEffectMap, nFrame, bAddRandomDelay )

- You can now define a delegate for a hud component or object animation. It currently allows you to know when an animation has finished. See API page for more details.

- Fixed a bug with JPSprite.getComponentScale and JPSprite.getObjectScale, were not returning the right value.

- The functions getComponentScale, getComponentAnimationSpeed, and getObjectAnimationSpeed now return the value specific to the object/component. To get the real values (including global speed/scale, components specific speed/scale, etc), new functions have been created:
nSpeedCoef = JPSprite.getComponentAnimationSpeedOverall ( hComponent )
nScale = JPSprite.getComponentScaleOverall ( hComponent )
nSpeedCoef = JPSprite.getObjectAnimationSpeedOverall ( hObject, nSubset, nEffectMap )

- Fixed some wrong error messages

v1.5
- Internal modifications to prevent eventual conflicts between packs.

v1.4
- Added the missing function JPSprite.setObjectAnimationSpeed ( hObject, nSubset, nEffectMap, nSpeedCoef )
- There was a compatibility issue with the latest betas of ShiVa, animated sprites on objects were sometimes not displayed. A workaround has been integrated in the pack.

v1.3
- Fixed a random issue blocking the activation of the pack

v1.2
- New nOptScale parameter for the JPSprite.setupAtlas function
- New function: JPSprite.setAtlasScale ( sAtlasName, nScale )

v1.1
- Error messages now are easier to understand.

API

--JPSprite API JPSprite.activate ( sUserToken, sActivationKey ) --Atlases and sprites JPSprite.setAtlasScale ( sAtlasName, nScale ) JPSprite.setupAtlas ( sAtlasName, nOptScale ) sTexture, nUVX, nUVY, nUVSX, nUVSY = JPSprite.getSpriteProperties ( sSprite, bFlipX, bFlipY ) nRatio = JPSprite.getSpriteRatio ( sSprite ) --General - FrameRate nFrameRate = JPSprite.getDefaultFrameRate ( ) JPSprite.setDefaultFrameRate ( nFrameRate ) --General - Speed nSpeedCoef = JPSprite.getGlobalSpeed ( ) nSpeedCoef = JPSprite.getGlobalComponentsSpeed ( ) nSpeedCoef = JPSprite.getGlobalObjectsSpeed ( ) JPSprite.setGlobalSpeed ( nSpeedCoef ) JPSprite.setGlobalComponentsSpeed ( nSpeedCoef ) JPSprite.setGlobalObjectsSpeed ( nSpeedCoef ) --General - Scale nScale = JPSprite.getGlobalScale ( ) nScale = JPSprite.getGlobalComponentsScale ( ) nScale = JPSprite.getGlobalObjectsScale ( ) JPSprite.setGlobalScale ( nScale ) JPSprite.setGlobalComponentsScale ( nScale ) JPSprite.setGlobalObjectsScale ( nScale ) --Animations JPSprite.computeAnimation ( ) nDuration = JPSprite.getAnimationDuration ( sAnimation ) nCount = JPSprite.getAnimationFrameCount ( sAnimation ) nFrameRate = JPSprite.getAnimationFrameRate ( sAnimation ) JPSprite.setAnimationFrameRate ( sAnimation, nFrameRate ) --Delegates for components --Events are: --onComponentSpriteAnimationEnded ( sComponent, sAnimation ) JPSprite.setComponentDelegate ( hComponent, hObjectHandle_OR_nUserID_Delegate, sOptAIModel ) --Delegates for objects --Events are: --onObjectSpriteAnimationEnded ( hObject, sAnimation, nSubset, nEffectMap ) JPSprite.setObjectDelegate ( hObject, hObjectHandle_OR_nUserID_Delegate, sOptAIModel ) --HUD components nDuration = JPSprite.getComponentAnimationDuration ( hComponent ) nFrame = JPSprite.getComponentAnimationFrame ( hComponent ) nFrameRate = JPSprite.getComponentAnimationFrameRate ( hComponent ) nSpeedCoef = JPSprite.getComponentAnimationSpeed ( hComponent ) nSpeedCoef = JPSprite.getComponentAnimationSpeedOverall ( hComponent ) nScale = JPSprite.getComponentScale ( hComponent ) nScale = JPSprite.getComponentScaleOverall ( hComponent ) bEnded = JPSprite.isComponentAnimationEnded ( hComponent ) bPaused = JPSprite.isComponentAnimationPaused ( hComponent ) JPSprite.setComponentAnimation ( hComponent, sAnimation, bOptLoop, bOptFlipX, bOptFlipY, bOptAddRandomDelay, kResizeMode ) JPSprite.setComponentAnimationFrame ( hComponent, nFrame, bOptAddRandomDelay ) JPSprite.setComponentAnimationPaused ( hComponent, bPaused ) JPSprite.setComponentAnimationSpeed ( hComponent, nSpeedCoef ) JPSprite.setComponentScale ( hComponent, nScale ) JPSprite.setComponentSprite ( hComponent, sSprite, bOptFlipX, bOptFlipY, kResizeMode ) JPSprite.stopComponentAnimation ( hComponent ) --Objects, Simple ( Subset used = 0, effect map used = 0 ) nDuration = JPSprite.getObjectAnimationDuration ( hObject ) nFrame = JPSprite.getObjectAnimationFrame ( hObject ) nFrameRate = JPSprite.getObjectAnimationFrameRate ( hObject ) nSpeedCoef = JPSprite.getObjectAnimationSpeed ( hObject ) nSpeedCoef = JPSprite.getObjectAnimationSpeedOverall ( hObject ) nScale = JPSprite.getObjectScale ( hObject ) nScale = JPSprite.getObjectScaleOverall ( hObject ) bEnded = JPSprite.isObjectAnimationEnded ( hObject ) bPaused = JPSprite.isObjectAnimationPaused ( hObject ) JPSprite.setObjectAnimation ( hObject, sAnimation, bOptLoop, bOptFlipX, bOptFlipY, bOptAddRandomDelay, kResizeMode ) JPSprite.setObjectAnimationFrame ( hObject, nFrame, bOptAddRandomDelay ) JPSprite.setObjectAnimationPaused ( hObject, bPaused ) JPSprite.setObjectScale ( hObject, nScale ) JPSprite.setObjectSprite ( hObject, sSprite, bOptFlipX, bOptFlipY, kResizeMode ) JPSprite.stopObjectAnimation ( hObject ) --Objects, Advanced ( define the subset and effect map ) nDuration = JPSprite.getObjectAnimationDuration ( hObject, nSubset, nEffectMap ) nFrame = JPSprite.getObjectAnimationFrame ( hObject, nSubset, nEffectMap ) nFrameRate = JPSprite.getObjectAnimationFrameRate ( hObject, nSubset, nEffectMap ) nSpeedCoef = JPSprite.getObjectAnimationSpeed ( hObject, nSubset, nEffectMap ) nSpeedCoef = JPSprite.getObjectAnimationSpeedOverall ( hObject, nSubset, nEffectMap ) nScale = JPSprite.getObjectScale ( hObject, nSubset, nEffectMap ) nScale = JPSprite.getObjectScaleOverall ( hObject, nSubset, nEffectMap ) bEnded = JPSprite.isObjectAnimationEnded ( hObject, nSubset, nEffectMap ) bPaused = JPSprite.isObjectAnimationPaused ( hObject, nSubset, nEffectMap ) JPSprite.setObjectAnimation ( hObject, nSubset, nEffectMap, sAnimation, bLoop, bFlipX, bFlipY, bAddRandomDelay ) JPSprite.setObjectAnimationFrame ( hObject, nSubset, nEffectMap, nFrame, bAddRandomDelay ) JPSprite.setObjectAnimationPaused ( hObject, nSubset, nEffectMap, bPaused ) JPSprite.setObjectAnimationSpeed ( hObject, nSubset, nEffectMap, nSpeedCoef ) JPSprite.setObjectScale ( hObject, nSubset, nEffectMap, nScale ) JPSprite.setObjectSprite ( hObject, nSubset, nEffectMap, sSprite, bFlipX, bFlipY ) JPSprite.stopObjectAnimation ( hObject, nSubset, nEffectMap ) --Optimization system JPSprite.setOptimizationSystemEnabled ( bEnabled ) JPSprite.setOptimizationSystemParameters ( nOptMaxLevel, nOptStartLevel, nOptTimeBetweenLevelChange, nOptFpsRangeMin, nOptFpsRangeMax, bOptTypeExp ) tIndexesToUpdate, nUpdateCoef = JPSprite.helpMeUpdateMySprites ( nSpriteCount ) --Constants JPSprite.kResizeModeNone JPSprite.kResizeModeFull JPSprite.kResizeModeRatioBasedOnHeight JPSprite.kResizeModeRatioBasedOnWidth

Description

JPSprite is a pack for atlases, sprites and animated sprites management.

All the best games use an atlas system because it is the best solution to optimize your game: improved performance because the sprites are using the same texture (less draw calls) and reduced memory consumption (a lot of wasted space if each sprite had its own texture).

JPSprite is based on TexturePackerGUI which is a software for atlases creation, which generates a texture containing the sprites and an xml to describe the UV coordinates for each of them.

Once your atlas and its xml file are generated by TexturePackerGUI, import and reference them in your ShiVa game.

Give to JPSprite a HUD component and the name of a sprite and it will apply the correct texture to your component and the corresponding UV coordinates.

It also embeds an animation system. If your atlas contains a serie of sprites ending with consecutive index (starting from 0), JPSprite will consider it as an animation. There are many options, such as the ability to choose the frame rate of the animation, change its scale, and much more.

JPSprite is also equipped with a formidable optimization system. If you decide to enable it, this system will adjust the performances of JPSprite depending on the state of your game. If your game frame rate is low at some time, JPSprite will automatically reduce its own working speed to maximize the resources available for the rest of your game, without any visible impact on the animated sprites.

--Load the atlas. JPSprite will detect the sprites and animations JPSprite.setupAtlas ( "Avatar" ) --Set the animation named "Talking" to the HUD component, with loop mode enabled JPSprite.setComponentAnimation ( "ScreenRoot.Avatar", "Talking", true ) --If needed, enable the optimization system JPSprite.setOptimizationSystemEnabled ( true )

As an example, the game Babel Rising: Cataclysm which can be found in my portfolio uses a similar sprite and optimization system, and the game can display several hundreds of animated sprites at once, keeping a good framerate.

What contains the lite version ?
It contains everything that is not related to the animations:
- Atlas loading.
- Static sprite display for HUD components and objects materials.

What contains the paid version ?
It adds support for animated sprites and contains a very powerful and smart optimisation system.

TexturePacker comes with a profile name 'ShiVa3D (+ JPSprite extension)' that sets all the options for you. All you have to do is to drag and drop your sprites into the TexturePacker UI.

Here is a complete tutorial that explains how to use JPSprite and TexturePacker.