JPExtendedAPI

JPExtendedAPI

Adds new functions to the default ShiVa APIs
Version: 5.0
Price: $30
v5.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

v4.0
New functions:
- nMin = math.min ( nValue0, nValue1, nValue2, ... )
- nMax = math.max ( nValue0, nValue1, nValue2, ... )
- nIndex = table.findFirst ( tTable, vValue, nOptStartIndex )
- hud.setComponentScreenSpaceSize ( hComponent, nSizeX, nSizeY, bUseScreenWidthIfComponentInvariant )
- nSizeX, nSizeY = hud.getComponentScreenSpaceSize ( hComponent )
- nRatio = user.getViewportRatio ( hUser )
Fixed a conflict with JPAnimation 4.4
Fixed a bug with hud.setComponentContainer with bKeepGlobalTransform set to true and component with independant aspect ratio

v3.8
- Fixed a bug with table.implode

v3.7
Added the following functions:
- x, y = hud.getComponentScreenSpaceBottomCenter ( hComponent )
- x, y = hud.getComponentScreenSpaceLeftCenter ( hComponent )
- x, y = hud.getComponentScreenSpaceRightCenter ( hComponent )
- x, y = hud.getComponentScreenSpaceTopCenter ( hComponent )
- hud.setComponentScreenSpaceBottomCenter ( hComponent, nPositionX, nPositionY )
- hud.setComponentScreenSpaceLeftCenter ( hComponent, nPositionX, nPositionY )
- hud.setComponentScreenSpaceRightCenter ( hComponent, nPositionX, nPositionY )
- hud.setComponentScreenSpaceTopCenter ( hComponent, nPositionX, nPositionY )
- hUser = hud.getComponentUser ( hComponent )
- bYes = hud.isEqualTo ( hComponent, hOtherComponent )

v3.6
- string.implode renamed table.implode
- string.queryString renamed hashtable.queryString
- hud.setComponentStrechableBackground now takes 4 additional and optional parameters: nOptSpriteUVX, nOptSpriteUVY, nOptSpriteUVSX, nOptSpriteUVSY. If you want to use a strechable sprite, you can define its location in the texture using these parameters.
- New function:
object.lookAtObject ( hObject, hOtherObject, nOptFactor, nOptOffsetY )

v3.5
New functions:
- sTag = object.getTag ( hObject )
- object.setTranslation ( hObject, nOptTX, nOptTY, nOptTZ, kSpace )
- object.setRotation ( hObject, nOptRX, nOptRY, nOptRZ, kSpace )
- hud.setComponentPosition ( hComponent, nOptX, nOptY )
- sString = string.queryString ( params )
- metatable = hashtable.toMetatable ( htHashtable )
- htHashtable = hashtable.fromMetatable ( metatable )

Bugfix:
- fixed a bug with the getRay functions
- fixed a bug with string.implode

v3.4
Sound related functions moved to a new 'JPSound' pack with tons of new features :)

v3.3
You can now set default values to a new table instance:
- tTable = table.newInstance ( v0, v1, v2, ... )

v3.2
Optimized for ShiVa 1.9.2
New function:
- bYes, nAngle = object.isLookingAtPoint ( hObject, nPointX, nPointY, nPointZ, kSpace, nMaxAllowedAngle )

v3.1
New functions:
- application.setMinFrameRate ( nFrameRate )
- application.setMaxFrameRate ( nFrameRate )
- hud.translate ( hComponent, nTx, nTy )
- sUnixTimestamp = system.getUnixTimestampStringForDate ( nYear, nOptMonth, nOptDay, nOptHours, nOptMinutes, nOptSeconds )
- bYes = system.isYearBissextile ( nYear )

Bugfix on hud.getSpinnerRotation, last rotation was 360 instead of 0.

v3.0
New functions:
- nVolume = sound.getVolume ( hObject, nSoundIndex )
- nCoef = application.getGlobalSoundsVolumeCoef ( )
- application.setGlobalSoundsVolumeCoef ( nCoef )
- hud.setComponentBackgroundImageContainerSpaceUVOffset ( hComponent, nOffsetU, nOffsetV )
- hud.setComponentBackgroundImageContainerSpaceUVScale ( hComponent, nScaleU, nScaleV )
- hud.setComponentBackgroundImageScreenSpaceUVOffset ( hComponent, nOffsetU, nOffsetV )
- hud.setComponentBackgroundImageScreenSpaceUVScale ( hComponent, nScaleU, nScaleV )

v2.7
Parameters changed for function:
hud.sizeComponentToFitText ( hComponent )

v2.6
New functions:
- sRes = string.implode ( tStringsToImplode, sDelimiter )
- hud.setComponentBackgroundImageMiddleUVOffset ( hComponent, nUVX, nUVY )
- hud.sizeComponentToFitText ( hComponent, sText, nComponentHeightForOneLine )
- nMaxLineCount = hud.getComponentMaxVisibleLineCount ( hComponent )
- nTextHeight = hud.getComponentTextHeightToMatchLineCount ( hComponent, nLineCount )
- hud.setComponentTextWithVariableTextHeight ( hComponent, sText, nNormalTextHeight, nMinTextHeight )

Fixed a bug with the pack constants, that sometimes became nil in ShiVa Editor only.
Fixed a bug with lists and hud_setComponentText.

Input related funtions splitted to create JPInput.

v2.5
New functions:
- nRayPntX, nRayPntY, nRayPntZ, nRayDirX, nRayDirY, nRayDirZ = input.getCursorRay ( hUser )
- nRayPntX, nRayPntY, nRayPntZ, nRayDirX, nRayDirY, nRayDirZ = input.getPointRay ( x, y )
- nRayPntX, nRayPntY, nRayPntZ, nRayDirX, nRayDirY, nRayDirZ = hud.getCursorRay ( hUser )
- nRayPntX, nRayPntY, nRayPntZ, nRayDirX, nRayDirY, nRayDirZ = hud.getPointRay ( x, y )
- nHours, nMinutes, nSeconds = system.getClock ( )
- nHoursAngle, nMinutesAngle, nSecondsAngle = system.getClockAngles ( nOptHours, nOptMinutes, nOptSeconds )

v2.4
New functions:
- sString = string.setByte ( sString, nIndex, nByte ) --Set the byte at the specified index.
- bOK, kLoadDetails = application.loadCurrentUserEnvironmentCompliant ( sName )
- bOK, kSaveDetails = application.saveCurrentUserEnvironmentCompliant ( bOverride )

New constants:
- JPExtendedAPI.kLoadSuccess
- JPExtendedAPI.kLoadErrorLocalStorageNotFound
- JPExtendedAPI.kLoadErrorCurrentUserEnvironmentDoesNotExist
- JPExtendedAPI.kLoadErrorCurrentUserEnvironmentCorrupted
- JPExtendedAPI.kLoadErrorUnknown

- JPExtendedAPI.kSaveSuccess
- JPExtendedAPI.kSaveErrorNoLocalStorageDevice
- JPExtendedAPI.kSaveErrorNoLocalStorageWriteAccess
- JPExtendedAPI.kSaveErrorNoLocalStorageSpaceAndCanOpenStorageManager
- JPExtendedAPI.kSaveErrorNoLocalStorageSpaceAndCannotOpenStorageManager
- JPExtendedAPI.kSaveErrorLocalStorageDeviceChanged
- JPExtendedAPI.kSaveErrorLocalStorageDeviceRemoved
- JPExtendedAPI.kSaveErrorUnknown

v2.3
- Event functions moved to a new pack: JPEvent
- New functions:
bFound = system.findFilesMatching ( tResult, sDirectory, sMatching )
bFound = system.findDirectoriesMatching ( tResult, sDirectory, sMatching )
bFound, tIndexes = table.find ( tTable, vValue )
table.sort ( tTable, bOptSortStringNumbersLikeNumbers )

v2.2
- The xml.getElementFirstChildWithNameAndAttributes, xml.getElementFirstChildWithNameAndAttributesAndAttribute and xml.getElementFirstChildWithNameAndAttributesAndAttributeAndAttribute have been merged into a single function:
hChild = xml.getElementFirstChildWithNameAndAttributes ( hXMLElement, sOptElementName, sOptAttributeName0, sOptAttributeValue0, sOptAttributeName1, sOptAttributeValue1, sOptAttributeName2, sOptAttributeValue2 )

- The xml.getElementNextSiblingWithNameAndAttributes, xml.getElementNextSiblingWithNameAndAttributesAndAttribute and xml.getElementNextSiblingWithNameAndAttributesAndAttributeAndAttribute have been merged into a single function:
hChild = xml.getElementNextSiblingWithNameAndAttributes ( hXMLElement, sOptElementName, sOptAttributeName0, sOptAttributeValue0, sOptAttributeName1, sOptAttributeValue1, sOptAttributeName2, sOptAttributeValue2 )

- New function to get the indexes and the count of children of an xml element with a specific name and with specific attributes:
nCount, tIndexes = xml.getElementChildCountWithNameAndAttributes ( hXMLElement, sOptElementName, sOptAttributeName0, sOptAttributeValue0, sOptAttributeName1, sOptAttributeValue1, sOptAttributeName2, sOptAttributeValue2 )

- New functions:
bFound = system.findFilesMatching ( tResult, sDirectory, sMatching ) --Work as the default system.findFiles, but allows to match a specific pattern.
bFound = system.findDirectoriesMatching ( tResult, sDirectory, sMatching ) --Work as the default system.findDirectories, but allows to match a specific pattern.

v2.1
- Internal modifications to prevent eventual conflicts between packs.

v2.0
Removed the following functions:
- object.cancelEvent
- user.cancelEvent

Added the following function for joypad sensors access:
- nPressure = input.getJoypadButtonPressure ( nJoypad, nButton )
- bState = input.getJoypadButtonState ( nJoypad, nButton )
- nPointX, nPointY, nDeltaX, nDeltaY, nRayPntX, nRayPntY, nRayPntZ, nRayDirX, nRayDirY, nRayDirZ = input.getJoypadIRPointerState ( nJoypad, nPointer )
- nX0, nY0, nS0, nX1, nY1, nS1, nX2, nY2, nS2, nX3, nY3, nS3 = input.getJoypadIRState ( nJoypad, nSensor )
- nAxisX, nAxisY, nAxisZ = input.getJoypadState ( nJoypad, nPart )
- nAxisX, nAxisY = input.getJoypadStickState ( nJoypad, nStick )

Added the following functions for events management:
- JPExtendedAPI.setCustomEventManagementEnabled ( bEnabled )

- application.cancelEvents ( sAIModelPatternToMatch, sHandlerPatternToMatch )
- application.cancelObjectEvents ( sAIModelPatternToMatch, sHandlerPatternToMatch )
- application.cancelUserEvents ( sAIModelPatternToMatch, sHandlerPatternToMatch )
- application.pauseEvents ( sAIModelPatternToMatch, sHandlerPatternToMatch )
- application.pauseObjectEvents ( sAIModelPatternToMatch, sHandlerPatternToMatch )
- application.pauseUserEvents ( sAIModelPatternToMatch, sHandlerPatternToMatch )
- application.resumeEvents ( sAIModelPatternToMatch, sHandlerPatternToMatch )
- application.resumeObjectEvents ( sAIModelPatternToMatch, sHandlerPatternToMatch )
- application.resumeUserEvents ( sAIModelPatternToMatch, sHandlerPatternToMatch )

- object.cancelEvents ( hObject, sAIModelPatternToMatch, sHandlerPatternToMatch )
- object.pauseEvents ( hObject, sAIModelPatternToMatch, sHandlerPatternToMatch )
- object.resumeEvents ( hObject, sAIModelPatternToMatch, sHandlerPatternToMatch )

- user.cancelEvents ( hUser, sAIModelPatternToMatch, sHandlerPatternToMatch )
- user.pauseEvents ( hUser, sAIModelPatternToMatch, sHandlerPatternToMatch )
- user.resumeEvents ( hUser, sAIModelPatternToMatch, sHandlerPatternToMatch )

- scene.cancelEvents ( hScene, sAIModelPatternToMatch, sHandlerPatternToMatch )
- scene.cancelObjectEvents ( hScene, sAIModelPatternToMatch, sHandlerPatternToMatch )
- scene.cancelUserEvents ( hScene, sAIModelPatternToMatch, sHandlerPatternToMatch )
- scene.pauseEvents ( hScene, sAIModelPatternToMatch, sHandlerPatternToMatch )
- scene.pauseObjectEvents ( hScene, sAIModelPatternToMatch, sHandlerPatternToMatch )
- scene.pauseUserEvents ( hScene, sAIModelPatternToMatch, sHandlerPatternToMatch )
- scene.resumeEvents ( hScene, sAIModelPatternToMatch, sHandlerPatternToMatch )
- scene.resumeObjectEvents ( hScene, sAIModelPatternToMatch, sHandlerPatternToMatch )
- scene.resumeUserEvents ( hScene, sAIModelPatternToMatch, sHandlerPatternToMatch )

v1.5
- Minor fix with hud.setLabelText ( hComponent, vValue )

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

v1.3
- New function: hud.setComponentText ( hComponent, vText, nOptListItem, nOptListColumn )
- Added support of any text type for hud.setButtonText, hud.setLabelText, hud.setCheckText, hud.setEditText and hud.setListItemTextAt.

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

v1.1
- New parameter: hud.setComponentOrigin ( hComponent, kOrigin, bKeepScreenSpacePosition )
- New functions:
hud.setContainerRotation ( hComponent, nRotation )
nResult = math.sum ( nValue0, nValue1, ... )
scene.close ( hScene )
application.closeCurrentUserScene ( )
user.cancelEvent ( hUser, sAIModel, sHandler )
object.cancelEvent ( hObject, sAIModel, sHandler )

API

--JPExtendedAPI JPExtendedAPI.activate ( sUserToken, sActivationKey ) --NEW API FUNCTIONS: Note that you can use these function using both api.function ( ) or JPExtendedAPI.api_function ( ). Only the second case will have code completion. --animation animation.setCurrentAnimation ( hObject, nBlendLayer, sAnimation ) --application application.closeCurrentUserScene ( ) bOK, kLoadDetails = application.loadCurrentUserEnvironmentCompliant ( sName ) JPExtendedAPI.kLoadSuccess JPExtendedAPI.kLoadErrorLocalStorageNotFound JPExtendedAPI.kLoadErrorCurrentUserEnvironmentDoesNotExist JPExtendedAPI.kLoadErrorCurrentUserEnvironmentCorrupted JPExtendedAPI.kLoadErrorUnknown bOK, kSaveDetails = application.saveCurrentUserEnvironmentCompliant ( bOverride ) JPExtendedAPI.kSaveSuccess JPExtendedAPI.kSaveErrorNoLocalStorageDevice JPExtendedAPI.kSaveErrorNoLocalStorageWriteAccess JPExtendedAPI.kSaveErrorNoLocalStorageSpaceAndCanOpenStorageManager JPExtendedAPI.kSaveErrorNoLocalStorageSpaceAndCannotOpenStorageManager JPExtendedAPI.kSaveErrorLocalStorageDeviceChanged JPExtendedAPI.kSaveErrorLocalStorageDeviceRemoved JPExtendedAPI.kSaveErrorUnknown application.setMinFrameRate ( nFrameRate ) application.setMaxFrameRate ( nFrameRate ) --hashtable hashtable.push ( htHashtable, sKey, vValue ) metatable = hashtable.toMetatable ( htHashtable ) htHashtable = hashtable.fromMetatable ( metatable ) sString = hashtable.queryString ( htParams ) --hud hud.setButtonText ( hComponent, vText ) hud.setCheckText ( hComponent, vText ) hud.setEditText ( hComponent, vText ) hud.setLabelText ( hComponent, vText ) hud.setListItemTextAt ( hComponent, vText, nItem, nColumn ) hud.setComponentText ( hComponent, vText, nOptListItem, nOptListColumn ) hud.setComponentTextWithVariableTextHeight ( hComponent, vText, nNormalTextHeight, nMinTextHeight ) bYes = hud.getComponentIntersectsComponent ( hComponent0, hComponent1, bOptPermissive ) nMaxLineCount = hud.getComponentMaxVisibleLineCount ( hComponent ) nTextHeight = hud.getComponentTextHeightToMatchLineCount ( hComponent, nLineCount ) nRatio = hud.getComponentRatio ( hComponent ) nSizeX, nSizeY = hud.getComponentSizeInvariant ( hComponent ) nSizeX, nSizeY = hud.getComponentSizeVariant ( hComponent ) hUser = hud.getComponentUser ( hComponent ) nRayPntX, nRayPntY, nRayPntZ, nRayDirX, nRayDirY, nRayDirZ = hud.getCursorRay ( hUser ) nRayPntX, nRayPntY, nRayPntZ, nRayDirX, nRayDirY, nRayDirZ = hud.getPointRay ( x, y ) nAngle = hud.getSpinnerRotation ( nRotationBySecond, nAngleCount ) bYes = hud.isComponentAtPoint ( hComponent, x, y ) bYes = hud.isComponentUnderCursor ( hComponent ) bYes = hud.isEqualTo ( hComponent, hOtherComponent ) hud.postCallAction ( hUser, nDelay, sAction, vParam0, vParam1, vParam2, vParam3 ) hud.setComponentBackgroundImageMiddleUVOffset ( hComponent, nUVX, nUVY ) hud.setComponentBackgroundImageContainerSpaceUVOffset ( hComponent, nOffsetU, nOffsetV ) hud.setComponentBackgroundImageContainerSpaceUVScale ( hComponent, nScaleU, nScaleV ) hud.setComponentBackgroundImageScreenSpaceUVOffset ( hComponent, nOffsetU, nOffsetV ) hud.setComponentBackgroundImageScreenSpaceUVScale ( hComponent, nScaleU, nScaleV ) hud.setComponentOrigin ( hComponent, kOrigin, bKeepScreenSpacePosition ) hud.setComponentPosition ( hComponent, nOptX, nOptY ) hud.setComponentStrechableBackground ( hComponent, sTexture, nStrechUVX, nStrechUVY, nStrechCoefSizeX, nStrechCoefSizeY, nOptSpriteUVX, nOptSpriteUVY, nOptSpriteUVSX, nOptSpriteUVSY ) hud.setContainerRotation ( hComponent, nRotation ) hud.sizeComponentToFitText ( hComponent ) x, y = hud.transformPointFromInput ( x, y ) hud.translate ( hComponent, nTx, nTy ) --hud (screen space related functions) x, y = hud.getComponentScreenSpaceBottomCenter ( hComponent ) x, y = hud.getComponentScreenSpaceLeftCenter ( hComponent ) x, y = hud.getComponentScreenSpaceRightCenter ( hComponent ) x, y = hud.getComponentScreenSpaceTopCenter ( hComponent ) nSizeX, nSizeY = hud.getComponentScreenSpaceSize ( hComponent ) hud.setComponentScreenSpaceBottomLeftCorner ( hComponent, nPositionX, nPositionY ) hud.setComponentScreenSpaceBottomRightCorner ( hComponent, nPositionX, nPositionY ) hud.setComponentScreenSpaceCenter ( hComponent, nPositionX, nPositionY ) hud.setComponentScreenSpaceTopLeftCorner ( hComponent, nPositionX, nPositionY ) hud.setComponentScreenSpaceTopRightCorner ( hComponent, nPositionX, nPositionY ) hud.setComponentScreenSpaceBottomCenter ( hComponent, nPositionX, nPositionY ) hud.setComponentScreenSpaceLeftCenter ( hComponent, nPositionX, nPositionY ) hud.setComponentScreenSpaceRightCenter ( hComponent, nPositionX, nPositionY ) hud.setComponentScreenSpaceTopCenter ( hComponent, nPositionX, nPositionY ) hud.setComponentScreenSpaceSize ( hComponent, nSizeX, nSizeY ) --input nRayPntX, nRayPntY, nRayPntZ, nRayDirX, nRayDirY, nRayDirZ = input.getCursorRay ( hUser ) nRayPntX, nRayPntY, nRayPntZ, nRayDirX, nRayDirY, nRayDirZ = input.getPointRay ( x, y ) x, y = input.transformPointFromHud ( x, y ) --math nMin = math.min ( nValue0, nValue1, nValue2, ... ) nMax = math.max ( nValue0, nValue1, nValue2, ... ) nResult = math.sum ( nValue0, nValue1, ... ) --object object.destroy ( hObject ) sTag = object.getTag ( hObject ) bYes, nAngle = object.isLookingAtPoint ( hObject, nPointX, nPointY, nPointZ, kSpace, nMaxAllowedAngle ) object.lookAtObject ( hObject, hOtherObject, nOptFactor, nOptOffsetY ) object.setRotation ( hObject, nOptRX, nOptRY, nOptRZ, kSpace ) object.setTag ( hObject, sTag ) object.setTranslation ( hObject, nOptTX, nOptTY, nOptTZ, kSpace ) --scene scene.close ( hScene ) sCollisionType, vHitObject, nHitDist, nHitID, x, y, z, i, j, k = scene.getFirstHit ( hScene, nRayPosX, nRayPosY, nRayPosZ, nRayDirX, nRayDirY, nRayDirZ, nRayLength ) --string sFolder, sFile, sExtension, sParameters = string.explodePath ( sPath ) sChar = string.getAt ( sString, nIndex ) sChar = string.getFirst ( sString ) sChar = string.getLast ( sString ) sSubString = string.getSubStringWithDelimiter ( sString, sDelimiter, nPosition ) sString = string.setByte ( sString, nIndex, nByte ) --system bFound = system.findFilesMatching ( tResult, sDirectory, sMatching ) bFound = system.findDirectoriesMatching ( tResult, sDirectory, sMatching ) nHours, nMinutes, nSeconds = system.getClock ( ) nHoursAngle, nMinutesAngle, nSecondsAngle = system.getClockAngles ( nOptHours, nOptMinutes, nOptSeconds ) sUnixTimestamp = system.getUnixTimestampStringForDate ( nYear, nOptMonth, nOptDay, nOptHours, nOptMinutes, nOptSeconds ) bYes = system.isYearBissextile ( nYear ) --table bFound, tIndexes = table.find ( tTable, vValue ) nIndex = table.findFirst ( tTable, vValue, nOptStartIndex ) sRes = table.implode ( tStringsToImplode, sDelimiter ) table.insert ( tTable, vValue ) tTable = table.newInstance ( v0, v1, v2, ... ) table.pushAt ( tTable, nIndex, vValue ) table.sort ( tTable, bOptSortStringNumbersLikeNumbers ) --user nRatio = user.getViewportRatio ( hUser ) --xml nCount, tIndexes = xml.getElementChildCountWithNameAndAttributes ( hXMLElement, sOptElementName, sOptAttributeName0, sOptAttributeValue0, sOptAttributeName1, sOptAttributeValue1, sOptAttributeName2, sOptAttributeValue2 ) hChild = xml.getElementFirstChildWithNameAndAttributes ( hXMLElement, sOptElementName, sOptAttributeName0, sOptAttributeValue0, sOptAttributeName1, sOptAttributeValue1, sOptAttributeName2, sOptAttributeValue2 ) hChild = xml.getElementNextSiblingWithNameAndAttributes ( hXMLElement, sOptElementName, sOptAttributeName0, sOptAttributeValue0, sOptAttributeName1, sOptAttributeValue1, sOptAttributeName2, sOptAttributeValue2 )

Description

JPExtendedAPI is a very nice pack. Its particularity is that it does not create a new API, but it improves the existing ones by adding new functions very useful when creating your game.

A good example is the ability to know at any time if a key is pressed or not. This feature seems elementary, but is not present in the API offered by ShiVa, and therefore it was necessary to track by yourself the events for each of the keys you were interested in and store its state using a boolean variable, which is very boring... Now, thanks to JPExtendedAPI you have the input.isKeyboardKeyDown ( kKeyCode ) function that can be called from anywhere in the code, without having to manage the keyboard events by yourself.

Below some features offered by JPExtendedAPI:

hashtable.push ( htHashtable, sKey, vValue ) hud.setContainerRotation ( hComponent, nRotation ) hud.sizeComponentToFitText ( hComponent ) sRes = table.implode ( tStringsToImplode, sDelimiter ) table.sort ( tTable, bOptSortStringNumbersLikeNumbers )

These functions represent a small part of what JPExtendedAPI offers, to know all of them, go to API page by following the link below.