Class: Sprite

MC.Sprite(typeopt) → {MC.Sprite}

new Sprite(typeopt) → {MC.Sprite}

Creates a Sprite Object.
MC considers all drawn assets to be Sprites
Constructor can be passed an Object of key: value pairs at configuration (see example below), or subsequently with the setValues(parameters) method
Sprites use the MC.Sprite.update methos to automatically change position, rotation, scale, animation etc etc.
Developers should augment the MC.Sprite.dev Object to further customise the Sprite's behaviour. CAUTION: Developers are recommended to ONLY modify this namespace, otherwise further MC Engine updates may break your code.
To assist, the method is automatically called after MC.Sprite.update()
This:
Parameters:
Name Type Attributes Default Description
type Object <optional>
 "circ" MUST be in format of {type:"circ"} or other type i.e. "poly", "star", "rect", "anim", "pict" or "free"
Properties:
Name Type Default Description
type string "circ" Must be either "circ", "poly", "star", "rect", "anim", "pict" or "free"
size1 Number 0 For "circ" = radius, "poly" & "star" = outer radius, all other types = width
size2 Number 0 For "star" = inner radius, "rect", "anim" & "pict" = height
sides Number 0 Number of sides for a "poly" or points for a "star"
scale Number 1 Scale modifier applied to the base size1 & size2 properties
dev Object A Place holder Object for Developer customisation.
Initialised with placeholder functions for
(1) dev.update() (automatically called at the end of any MC.Sprite.update() call) and
(2) dev.onKill() (automatically called at the end of the MC.Sprite.kill() call)
CAUTION: It is highly recommended that any Developer ONLY use this namespace to customise Sprites (and their behaviour).
pointsArray Array.<MC.Point> Used internally by the MC Engine
boundingBox Object Used internally by the MC Engine
innerRadius Number Radius of the largest circle which can be contained within the Sprite (centred on it's position)
hitBox Object Used internally by the MC Engine
fillColor MC.Color | string Will also accept a HTML5 colour name string, e.g. "Black" or "Salmon"
edgeColor MC.Color | string As above
edgeWidth Number 0 N.B. greater than 1 adds to the render size of the object, but not for purposes of hit calculations
pos MC.Point Mid-Screen In-game canvas position of the CENTRE of the Sprite
vel MC.Point 0 In-game velocity of the Sprite (in pixels per second)
acc MC.Point 0 In-game Acceleration of the Sprite (in pixels per second per second)
frontAngle Number 0 Rotational offset to indicate the "forward" direction of the Sprite (particulary useful with Sprite Sheets)
angle Number 0 Current rotational angle of the sprite
angleVel Number 0 Angular Velocity of the Sprite (in degrees per second, +ve = clockwise)
gravity Boolean False if True, Sprite will be accelerated by the value set in MC.game.gravity
followNose Boolean False if True, Sprite will automatically rotate to match it's velocity vector
edgeBounce Boolean False if True, Sprite will bounce off the edges of the game bounds (as defined MC.game.setBounds())
N.B. Sprites edgeBouncing have their position retarded by any edge interpeneration
edgeKill Boolean False if true, Sprites that leave the Canvas Bounds will call the kill() method.
N.B. the kill () method only clears references to Sprites held in a MC.SpriteBin.
wrapAround Boolean False if True, Sprite will leave the game bounds and return from the other side
mobile Boolean True if False, Sprite will not move (or rotate) during update() - useful as a pause since other movement properties are maintained
collider Boolean True if false, Sprite Bounding Box is not maintained and all hitTest()'s will be ignored. Useful for background objects
Set this to false when not required, as it also saves some computing overhead.
WARNING: must be True for wrapAround and edgeBounce to work.
lastNormal MC.Point During bounce() lastNormal is updated with the normal of the last collision surface
lastIP MC.Point As above; this vector reports the Interpenetration of a sprite after a Hit Detection. In the direction of the lastNormal.
lastHit false | Object_reference A reference to the last Sprite hit by this one. Reset to false after a "failed" Hit() test
restitution Number 1 Value applied by default in any reflect() calls. 1 = perfectly elastic, 0 = all velocity killed on impact
dead Boolean False "dead" sprites are flagged for destuction (and will not update(), or render())
CAUTION Sprites in SpriteBin's are set to null if they have been detected during an update() call.
If manaually handling Sprites, Developer's need to find other ways to kill references to dead Sprites
killAge Number null Age at which the Sprite will die, i.e. toggle dead to true
Age is incremented during update(), and not when MC.game.paused == true
age Number 0 In-game age of the Sprite (in Seconds) updated in update()
Source:
Returns:
a new Object
Type
MC.Sprite
Example
new MC.Sprite({
	type :"circ",
	size1 : 20,
	edgeColor : MC.utils.randomColor(),
	edgeWidth : 2,
	wrapAround : true,
	pos : new MC.Point(MC.maths.randBetween(0,MC.canvas.right),MC.maths.randBetween(0,MC.canvas.bottom)),
	fillColor : MC.utils.randomColor(),
	vel : new MC.Point(MC.maths.randBetween(-100,100),MC.maths.randBetween(-100,100))
	});

Methods

bounce(target) → {this}

detects whether a Sprite has hit another and, if so, reflects off it
N.B. This is an approximation using the velocity of the calling Sprite.
The Sprite's lastIP, lastNormal and lastHit properties are reset at the beginning of this call.
So Developers can use if (mySprite.lastHit) { // do something} to detect a bounce during the update cycle
Rotating targets may lead to irregular results.
Velocity will be reduced based upon the calling sprite's Restitution value. Otherwise speed is maintained.
For simplicity Sprite.type "star" and "poly" are treated as circles, and there is no transfer of momentum/speed between objects.
The following collision types are supported
... Circle on Circle
... Circle on rotated Rectangle (and vice versa)
... Axis Aligned Rectangles
Non-axis aligned rectangles will "bounce" but use their (and/or target's) outer bounding boxes
Parameters:
Name Type Description
target MC.Sprite | MC.SpriteBin The Sprite to be tested against, if a SpriteBin is specified, then the bounce() method is called against all the contents
Source:
Throws:
Console warning if target is undefined or otherwise not valid
.
Returns:
Enables Method Chaining
Type
this

clone() → {MC.Sprite}

Clones the Sprite and returns a new copy. N.B. the MC.Sprite.dev object may or may not be deep-copied, depending upon how it has been Developer customised
Source:
Returns:
a new Sprite with the same propeties (EXCEPTION: age is set to 0)
Type
MC.Sprite

drawBB(coloropt) → {this}

Draws a 1x pixel outline showing the sprite's Bounding Box
Useful for debugging purposes
1 - either an MC.Color object or an HTML5 color name can be used as a Color (White is default)
Parameters:
Name Type Attributes Default Description
color Color | string <optional>
 "White" Desired outline color (1)
Source:
Returns:
Enabled method chaining
Type
this

drawIC(coloropt) → {this}

Draws a 1x pixel circle representing the Sprite's inner Circle.
Useful for debugging purposes
1 - either an MC.Color object or an HTML5 color name can be used as a Color (White is default)
Parameters:
Name Type Attributes Default Description
color Color | string <optional>
 "White" Desired outline color (1)
Source:
Returns:
Enabled method chaining
Type
this

getInnerRadius() → {Number}

Returns the inner Radius of the Sprite. Anything inside this radius is 100% certain to be be inside the Sprite
CAUTION: "free" type sprites can have interesting results.
Used internally by the MC engine to populate the sprite's innerRadius property
Source:
Returns:
The Sprite's inner radius
Type
Number

getPointsArray() → {Array.<MC.Point>}

Returns an array of the screen coordinates of the vertices of a non-circular sprite
Source:
Returns:
Screen coordinates of the Sprite's vertices
Type
Array.<MC.Point>

hit(target) → {Boolean}

Checks if a Sprite has "hit" (i.e. intersects with) something
Parameters:
Name Type Description
target MC.Point | MC.Sprite | MC.SpriteBin The something to check intersection with
N.B. it is very common for the "Point" option to be the Mouse Coordinates, e.g. MySprite.hit(MC.game.mouse)
N.B. Sprites with collider property set to false will always retuns a false>
Source:
Returns:
true if the point or any sprite (singular or in the SpriteBin) intersects the calling Sprite, else false
Type
Boolean

kill(delayopt)

Kills the Sprite by setting it's dead property to true
Additionally, calls the dev.onKill() method which can be customised by the Developer
CAUTION: MC.SpriteBin's handle setting of their contents to null if a dead Sprite is detected. Destruction of manually managed Sprites is the responsibility of the Developer.
Parameters:
Name Type Attributes Default Description
delay Number <optional>
 0 In seconds, if provided, sets the Sprite killAge, and once reached will recall this method (and therefore fire the dev.onKill() method)
Source:

moveBy(Vector) → {this}

Moves the Sprite's position by the desired amount
This is the prefered method to translate a Sprite, as it's bounding box is automatically updated.
Parameters:
Name Type Description
Vector MC.Point Translation required
Source:
Returns:
Enables Method Chaining
Type
this

moveTo(Position) → {this}

Moves the Sprite's position to the desired place
This is the prefered method to move a Sprite, as it's bounding box is automatically updated.
Parameters:
Name Type Description
Position MC.Point where the new Sprite centre will be
Source:
Returns:
Enables Method Chaining
Type
this

reflect(normal, restitutionopt) → {this}

Reflects the sprite from a surface normal, resulting in a new direction of motion (and possible reduction of speed)
N.B currently the MC Engine does not support transfer of momentum (rotational or otherwise) between objects, so speed and rotation angle are preserved Used during the Sprite bounce() method calls
Parameters:
Name Type Attributes Default Description
normal MC.Point Normal of the surface impacted.
restitution Number <optional>
 this.restitution Used if the collision requires a restitution other than the Sprite's own.
Source:
Returns:
Enables method chaining
Type
this

render() → {this}

Renders the Sprite to the canvas (as defined by MC.game.canvas)
Usually called at the end of the game loop (after update())
Source:
Returns:
Enables method chaining
Type
this

resetHit() → {this}

Resets the Sprite's lastNormal and lastIP properties
Called automatically after a failed hitTest()
Source:
Returns:
Enables method chaining
Type
this

retard() → {this}

Retards the Sprite's position by the last recorded lastIP value.
The lastIP is then reset to zero.
Source:
Returns:
Enables method chaining
Type
this

rotateBy(Angle) → {this}

Rotates the Sprite by the desired amount
This is the prefered method to rotate a Sprite, as it's bounding box is automatically updated.
Parameters:
Name Type Description
Angle angle Rotation required (in degrees, +ve = clockwise)
Source:
Returns:
Enables Method Chaining
Type
this

setAnimation(GridX, GridY, StartX, StartY, FinishX, FinishY, SecPerFrame, BaseRotationopt) → {this}

Enables Sprite Sheet animation for a type:"anim" Sprite
Parameters:
Name Type Attributes Default Description
GridX Number The number of horizontal frames in the Sprite Sheet
GridY Number The number of vertical frames in the Sprite Sheet
StartX Number The X frame section for the first of the animation frames (first = 0, last = GridX -1)
StartY Number The Y frame section for the first of the animation frames (first = 0, last = GridY -1)
FinishX Number The X frame section for the last of the animation frames (first = 0, last = GridX -1)
FinishY Number The Y frame section for the last of the animation frames (first = 0, last = GridY -1)
SecPerFrame Number Time between frame transitions
BaseRotation Number <optional>
 0 Base Rotation to be applied to the Sprite sheet (to counter any art issues)
Source:
Returns:
Enables method chaining
Type
this

setValues(values)

Configures a Sprite by passing an object made of key:value pairs e.g. {size1 = 34, size2 = 10,fillColor = new MC.Color(125,230,10,1)}
N.B. called automatically by the Constructor with any such dictionary used as a parameter
Parameters:
Name Type Description
values Object {Object of key:value pairs}
Source:
Throws:
Console warning if key is not present in the Sprite

towards(target) → {Boolean}

Checks is a Sprite is moving towards a particular postion
Parameters:
Name Type Description
target MC.Point | MC.Sprite Screen location or Sprite sought
Source:
Returns:
True is the Sprite's velocity will take it closer to the target Location
Type
Boolean

update(DeltaTimeopt)

Automatically updates the Sprite's position due to velocity, acceleration etc. This method should be called within any game requestAnimationFrame() game loop, and within any required loop Once complete, this method calls the Developer customisable MC.Sprite.dev.update() method
Parameters:
Name Type Attributes Default Description
DeltaTime Number <optional>
 MC.game.deltaTime The Time increment (in Seconds) to be applied to the Sprite
N.B. usually MC.game.deltaTime and applied within the GameLoop
Source:

updateBounds()

Refreshes the internally held bounding box coordinates
This is called automatically upon update() and Developers should not need to call it
However: Sprites that are manually moved (by direct manipulation of the pos or angle properties), or flagged as NOT mobile may need it
Source: