Core

Entity

An Entity in JackyJS is basically a high level object that many classes (Background, Dialog, Particle, Sprite, Text) inherit properties, methods, and events from. Not all classes support all properties, methods, and events of the Entity object though. Throughout this document you will see it denoted when only a specific class supports a specific property, method, or event. Please refer to the following legend:

TIP: for the purpose of this document, you can safely assume that if NO legend abbreviation is specified, then that means ALL the above classes support that particular property, method, or event.

Properties (read-only)

Name Type Description
idNumberthe id of the object in the current Room.
instanceIDNumberthe instance id of the object in the current Room.
assetOrigObjecta reference to the original asset object.
nameStringthe name of this instance. Usually assigned when creating an entity.

NOTE: when naming instances, use ONLY the following: letters, numbers, underscores, hyphens.
nameInstanceStringan auto-generated instance name, based on name and instanceID.
parentStringthe name of the parent entity, if this instance is a child.
instanceOfStringthe name of the entity this one is an instance of.
typeStringthe type of entity:

  • 'background'
  • 'dialog'
  • 'sprite'
  • 'text'
  • 'ps-particle'
  • 'ps-emitter'
  • 'ps-system'
existsBooleanis FALSE if instance has been destroyed.
xStartNumberthe x coordinate at creation.
yStartNumberthe y coordinate at creation.
draggable[S][T]BooleanTRUE if can be dragged. This is a special property that can be set when initializing and/or instantiating entities. When set to TRUE, JackyJS automatically converts the entity into a draggable object. (default: FALSE)
draggableOrigin[S][T]BooleanTRUE if dragging snaps to originX and originY values; otherwise will drag from exact point clicked. This is a special property that can be set when initializing and/or instantiating entities. (default: FALSE)
tile[B][S]BooleanTRUE if entity is tileable. This is a special property that can be set when initializing and/or instantiating entities. (default: FALSE)

Properties

Name Type Description
assetObjectthe asset object, which can be swapped at any time. To swap an asset in real-time, do this:

	player.onUpdate(function(obj){
		if (obj.vars.IDLE){
			obj.asset = GAME.Assets.Sprites['jackyStanding'];	
		} else {
			obj.asset = GAME.Assets.Sprites['jackyWalking'];	
		}
	});


NOTE: swapping the asset in real-time does not actually change the width and height of entity object.
consObjectcustom object for your entity-specific constants.
varsObjectcustom object for your entity-specific variables.
funcsObjectcustom object for your entity-specific functions.
activeBooleanif set to FALSE, will not render any updates. (default: TRUE)
persistent[B][P][S][T]Booleanif set to TRUE, will persist between Rooms. This means that the instance is created ONCE and will not be destroyed until its destroy method is called. (default: FALSE)
foregroundBooleanif set to TRUE, will appear in front of other entities. If entity is a Background, will appear in front of all Sprites as well as other backgrounds that are foregrounds. If entity is a Sprite, will appear in front of EVERYTHING, even backgrounds that are foregrounds! NOTE: the layer order depends on the order that the objects are instantiated. (default: FALSE)
solid[S]Booleanif set to TRUE, the space the entity occupies is not considered to be free, when checking for collisions; ie, via the placeFree method. (default: FALSE)
classStringa comma-separated string of attributes (no spaces); eg, 'green,fast'
widthNumberwidth of entity. If a Sprite, and width is wider than its asset width, will tile. NOTE: this only works on non-animated sprites. (default: 32)
heightNumberheight of entity. If a Sprite, and height is taller than its asset height, will tile. NOTE: this only works on non-animated sprites. (default: 32)
xNumberthe x coordinate in game.
yNumberthe y coordinate in game.
bbox[P][S][T]Objectfour coordinates that represent the bounding box, for collisions. The four properties are: x1, y1, x2, y2
originXNumberthe x registration point. Between 0 and 1, with 0 being left, and 1 being right. (default: 0)
originYNumberthe y registration point. Between 0 and 1, with 0 being top, and 1 being bottom. (default: 0)
scaleX[B][P][S][T]Numberthe x scale factor; ie, a factor of 2 means twice as wide. (default: 1)
scaleY[B][P][S][T]Numberthe y scale factor; ie, a factor of 2 means twice as tall. (default: 1)
alphaNumberthe alpha transparency value; with 0 being completely transparent, and 1 being completely opaque.
visibleBooleanif set to FALSE, will be invisible. NOTE: this actually alters the alpha property. (default: TRUE)
tintStringa hex value for tinting. Tinting is not a color matrix transformation; currently only works on images that have grey tones. (default: '#ffffff')
blendStringadjusts the color blending. See Global Constants. (default: GAME.cons.BLEND.NORMAL)
hspeedNumberthe horizontal speed. Negative values move left, positive values move right. (default: 0)
vspeedNumberthe vertical speed. Negative values move up, positive values move down. (default: 0)
speedNumberthe speed to move in a direction by. (default: NULL)
directionNumberthe direction to move by a speed. (default: NULL)
gravityNumberthe acceleration due to gravity. The default value is derived from GAME.vars.GRAVITY, which can be changed at any time. (default: 0.5)
gravityDirectionNumberthe direction of gravity. 0 is right, 90 is up, 180 is left, 270 is down. You can also use the Global Constants instead. The default value is derived from GAME.vars.GRAVITY_DIRECTION, which can be changed at any time. (default: 270)
frictionNumberthe deceleration due to friction. The default value is derived from GAME.vars.FRICTION, which can be changed at any time. (default: 0.15)
angle[B][P][S][T] Numberthe degree of rotation, clockwise; ie, an angle of 90 will rotate entity 90 degrees clockwise (pointing to the right).
angleAuto[B][P][S][T] Booleanif set to TRUE, will automatically rotate, that is, when a speed and direction have been applied.
pathObjecta Path object attached via setPath. See Classes > Path for available properties and methods.
timelineObjecta Timeline object attached via setTimeline. See Classes > Timeline for available properties and methods.
hasGravityBooleanif set to TRUE, will have gravity. Uses GAME.vars.GRAVITY. (default: FALSE)
hasFrictionBooleanif set to TRUE, will have friction. Uses GAME.vars.FRICTION. (default: FALSE)
canCreateBooleanif set to FALSE, create event will not execute. (default: TRUE)
canCollideStringused when determining collisions. Values: 'all', 'solid', 'nonsolid', 'none'. (default: 'all')
pauseObjectpauses a type of action, if applicable. Simply set any of the following properties to a value of TRUE/FALSE in order to pause/unpause the effect or motion:

  • fade
  • spin
  • rotate
  • wipe
  • scale
  • size
  • blink
  • pulse
  • tinter
  • move
  • follow
  • slide
  • wave
  • orbit
pauseEffectBooleanif set to TRUE, pauses all effect related actions; ie, the following:

  • fade
  • spin
  • rotate
  • wipe
  • scale
  • size
  • blink
  • pulse
  • tinter
pauseMotionBooleanif set to TRUE, pauses all motion related actions; ie, the following:

  • move
  • follow
  • slide
  • wave
  • orbit

Methods

Name Parameter Type Description
moveContactmoves entity to contact point of a target entity, relative to contact direction. Usually used in conjunction with placeMeeting method, since it returns a collision object; however, can be used in other contexts as long as target object is provided. NOTE: this method factors in entity scaling and bounding box.
* targetObjectthe target object to snap to.
* directionStringthe direction to move entity before contact with target. Values: 'up', 'down', 'left', 'right'
moveContactAlljust like moveContact, except no direction is required. It will automatically place entity at an approximated contact point. This works in most cases, but for more control, better use the moveContact method instead.
* targetObjectthe target object to snap to.
placeFreereturns TRUE if current entity placed at x/y does not collide with a SOLID object; otherwise, returns FALSE.
* xNumberthe x coordinate to check against.
* yNumberthe y coordinate to check against.
placeMeetingchecks if current entity collides with an instance of the target at position x/y. If so, will return the instance of that target; if not, will return FALSE. The target can be an entity object OR a global find object. This method's return value can be used with moveContact to snap entity into place. For example:

	if (other = obj.placeMeeting(obj.x - 1, obj.y, {class:'block'})){
		obj.moveContact(other, 'left');
		obj.hspeed = 0;
	}

* xNumberthe x coordinate of the potential target.
* yNumberthe y coordinate of the potential target.
* targetObjectthe target object to check for.
setTextmodifies the content and style of an existing text entity.
* contentStringtext to set.
styleObjectnew text style. (see Classes > Text : Style Properties)
setPathattaches a predefined Path object to this entity, assigning it to the path property. Once attached, you can invoke the Path's methods such as: pause, resume, and reverse. To detach the path, do this: obj.setPath(false)
* nameStringexisting path name.
options.???Mixedsee Classes > Path create options (except for name and points).
setTimelineattaches a predefined Timeline object to this entity, assigning it to the timeline property. Once attached, you can invoke the Timeline's methods such as: pause, resume, restart, goto, destroy. To detach the timeline, do this: obj.setTimeline(false)
* nameStringexisting timeline name.
options.???Mixedsee Classes > Timeline create options (except for name and points).
setAlarmsets a local Alarm, specific to this entity. The name parameter is optional, as a name is auto-generated if none provided; however if a name IS provided, you can easily destroy the named alarm at any time.
options.nameStringthe name of the alarm; used with destroyAlarm method.
* options.timethe length of time, in milliseconds, for alarm to run. (default: 1000)
options.???Mixedsee Classes > Alarm for create options.
callbackFunctionfunction to execute when alarm is done.
destroyAlarmnameStringname of local alarm to destroy.
callbackFunctionfunction to execute when alarm is destroyed.
hasClassnameStringreturns TRUE, if class name exists.
removeClassclassesStringa comma-separated string of classes to remove.
addClassclassesStringa comma-separated string of classes to add.
nearesttargetObjecta global find object to search for nearest entity instance. If no target provided, will search ALL active entities.
farthesttargetObjecta global find object to search for farthest entity instance. If no target provided, will search ALL active entities.
distancetargetObjecta global find object to check the distance to. (also accepts an actual entity object)
midpointtargetObjecta global find object to check the midpoint to. (also accepts an actual entity object)

Methods (effects)

Name Parameter Type Description
flipX[B][P][S][T] flips the entity on its X axis.
flipY[B][P][S][T] flips the entity on its Y axis.
blinkmakes the entity blink its alpha transparency value, forever. To cancel this effect, do this: obj.blink(false)
options.alphaNumberthe alpha transparency to blink to, with 0 being completely transparent, and 1 being completely opaque. (default: 1)
options.timeNumberthe duration of the effect, in milliseconds. (default: 10)
fadefades the alpha transparency completely in or out. If an alpha value is provided, then that will be the target alpha to fade to.
options.typeStringthe type of fade. Values: 'in', 'out'. (default: 'out')
options.alphaNumberthe alpha value to fade to. (default: 0)
options.timeNumberthe duration of the effect, in milliseconds. (default: 1000)
options.easingBooleanif set to TRUE, an easing effect is applied. (default: FALSE)
callbackFunctionfunction to execute once effect is complete.
fadeOutoptionsObjectfades completely out. Options are same as fade.
callbackFunctionfunction to execute once effect is complete.
fadeInoptionsObjectfades completely in. Options are same as fade.
callbackFunctionfunction to execute once effect is complete.
pulse[B][P][S][T] pulses the entity by scaling up and scaling down, forever. To cancel this effect, do this: obj.pulse(false)
* scaleXNumberthe x axis amount to scale.
* scaleYNumberthe y axis amount to scale.
timeNumberthe duration of the effect, in milliseconds. (default: 200)
rotate[B][P][S][T] rotates entity a certain amount of degrees over a period of time, that is, the higher the time, the longer it will take to rotate specified degrees.
directionStringthe direction of rotation. Values: 'cw', 'ccw'. (default: 'cw')
degreesNumberthe degrees of rotation. (default: 10)
timeNumberthe duration of the effect, in milliseconds. (default: 0)
callbackFunctionfunction to execute once effect is complete.
scale[B][P][S][T] scales entity on either x/y axis. The x and y scale values don't have to be the same, and can also be negative.
* xNumberthe amount to scale on x axis.
* yNumberthe amount to scale on y axis.
timeNumberthe duration of the effect, in milliseconds. (default: 200)
callbackFunctionfunction to execute once effect is complete.
spin[B][P][S][T] spins the entity clockwise/counterclockwise by a certain amount of degrees, forever. To cancel this effect, do this: obj.spin(false)
directionStringthe direction to spin in. Values: 'cw', 'ccw'. (default: 'cw'))
degreesNumberthe degree amount to spin; for example, a degree of 90 is a quarter turn. (default: 10)
tintertints the entity to a hex color over a period of time, optionally looping the effect forever. To cancel this effect, do this: obj.tinter(false).

NOTE: this is not a color transformation effect, therefore, depending on the entity's original color scheme, the tint may not always give the desired effect. For best results, use a Sprite animation instead.
* toStringa hex color to tint to; ie, #ff0000 = red.
timeNumberthe duration of the effect, in milliseconds. (default: 1000)
loopBooleanif set to TRUE, will loop the effect forever. (default: FALSE)
wipe[B][P][S][T] rotates entity with a wiping effect, that is, it rotates one direction, and then the other direction; kind of like windshield wipers. If the full option is set to TRUE, then the effect reverses to the fully opposite end; ie, if degrees is 90, will reverse all the way to 180, and back again.
options.directionStringthe direction of rotation. Values: 'cw', 'ccw'. (default: 'cw')
options.degreesNumberthe degree of rotation. (default: 45)
options.timeNumberthe duration of the effect, in milliseconds. (default: 1000)
options.fullBooleanif set to TRUE, will rotate fully to opposite angle. (default: FALSE)
callbackFunctionfunction to execute once effect is complete.

Methods (motion)

Name Parameter Type Description
bouncebounces the entity, after a collision has occurred. This is used in conjunction with the onCollision event, where you can pass the target object from the collision into the target property of this method. For example:

	ball.onCollision({class:'block'}, function(obj, target){
		obj.bounce(target);
	});	

targetObjecta target object obtained from a collision event.
followfollows an entity instance until followed instance is destroyed OR a new one appears. To cancel the motion, do this: obj.follow(false)
* options.targetObjectthe target object to follow. Can be an actual entity object or a global find object.
options.speedNumberthe speed, in pixels, to follow target at. (default: 1)
options.collideBooleanif set to TRUE, will not pass through solid objects. (default: FALSE)
movemoves the entity either toward another entity OR an x/y coordinate. If entity no longer exists or x/y coordinate is reached, this entity will stop moving. To cancel the motion, do this: obj.move(false)
* options.target.xNumberthe x coordinate to move to.
* options.target.yNumberthe y coordinate to move to.
options.speedNumberthe speed to move at. (default: 1)
options.collideBooleanif set to TRUE, will NOT pass through solid objects. (default: FALSE)
callbackFunctionfunction to execute once motion is complete.
orbitorbits either another existing entity object OR an x/y coordinate. If an orbitted entity instance no longer exists, will continue orbiting at last location. To cancel this motion, do this: obj.orbit(false)
* options.target.xNumberthe x coordinate to orbit.
* options.target.yNumberthe y coordinate to orbit.
directionStringthe direction of orbit; ie, clockwise or counter-clockwise. Values: 'cw', 'ccw'. (default: 'cw')
speedNumberthe speed of motion, in pixels. (default: 2)
radiusNumberthe distance from the center of orbited point, in pixels. (default: 64)
slideslides the entity a certain speed, in one of four directions ('up', 'down', 'left', 'right'), with an optional easing effect. If entity's hasFriction property is set to TRUE, it will affect this motion. To cancel the motion, do this: obj.slide(false)
* options.directionStringthe direction to slide in. Values: 'up', 'down', 'left', 'right'.
options.speedNumberthe speed, in amount of pixels, to slide. (default: 1)
options.easeOutBooleanif set to TRUE, will ease out of the slide. (default: FALSE)
options.moveContactBooleanif set to TRUE, will be placed at the point of contact with a solid object. (default: FALSE)
callbackFunctionfunction to execute once motion is complete.
slideUpoptionsObjectslides up. Options are same as slide.
callbackFunctionfunction to execute once motion is complete.
slideDownoptionsObjectslides down. Options are same as slide.
callbackFunctionfunction to execute once motion is complete.
slideLeftoptionsObjectslides left. Options are same as slide.
callbackFunctionfunction to execute once motion is complete.
slideRightoptionsObjectslides right. Options are same as slide.
callbackFunctionfunction to execute once motion is complete.
warpwarps entity to another x/y coordinate, after a certain time has elapsed. To cancel the motion, do this: obj.warp(false)
* xNumberthe x coordinate to warp to.
* yNumberthe y coordinate to warp to.
timeNumberthe time it takes, in milliseconds, BEFORE the warp actually occurs. (default: 500)
wavemakes the entity follow a mathematical sine wave, either horizontally, or vertically. To cancel the motion, do this: obj.wave(false)
amplitudeNumberthe height of the waves. (default: 32)
frequencyNumberthe compaction of waves. (default: 0.1)
speedNumberthe speed of entity movement, in pixels. (default: 1)
orientationStringthe orientation of movement. Values: 'horizontal', 'vertical'. (default: 'horizontal')

Events

All entity event callback functions have an implicit single parameter called obj, which essentially passes the entity reference into your callback. With this, you can continue to manipulate the original entity in any manner you wish.

Name Parameter Type Description
onCreatecallbackFunctionwhen the entity is created. Fires after ALL entities have been instantiated in the Room.
onUpdatecallbackFunctionwhen the entity is updated. Fires after ALL properties have been updated.
onDestroycallbackFunctionwhen the entity has been destroyed via a call of its destroy method.

NOTE: when going to the next room, an entity's destroy event is NOT called.
onCollisiontargetObjectthis can be one of two types: a) an actual entity object OR b) a global find object.
callbackFunctionfunction to execute when collision has occurred.

NOTE: this function has two parameters: obj and target, each passing the corresponding reference, respectively.
onMousePresscallbackFunctionthe function to execute when LEFT mouse button pressed OR screen is touched.

NOTE: for a "press" to occur, the mouse button has to be released.
onMouseDowncallbackFunctionthe function to execute while the LEFT mouse button is held down OR while finger is held down on screen.
onMouseUpcallbackFunctionthe function to execute when the LEFT mouse button is released OR when finger is released from screen.
onMouseOvercallbackFunctionthe function to execute when mouse moved over the entity.
onMouseAwaycallbackFunctionthe function to execute when mouse moved away from entity.
onKeyPresskeyStringthe key pressed. See Classes > Input for supported keycodes.
callbackFunctionthe function to execute when keycode is pressed. NOTE: for a "press" to occur, the key has to be released.
onKeyDownkeyStringthe key being held down. See Classes > Input for supported keycodes
callbackFunctionthe function to execute while key is held down.
onOutOfBoundscallbackFunctionthe function to execute when entity is no longer within game area.