Elpy NPM | npm.io

Elpy.js - 2D JavaScript game engine.

logo

Demo	Game examples

Docs

Install
Basic usage example
Engine
- create()
- add()
- key()
- keydown()
- keyup()
- mousemove()
- click()
- tick()
- nextTick()
- checkObjectInViewport()
- fixingCamera()
- unfixingCamera()
- destroy()
- on()
  - Event 'load'
  - Event 'animation'
- load()
Engine getters
Object
- run()
- move()
- fly()
- jump()
- fall()
- push()
- rotate()
- stop()
- destroy()
- collision()
- on()
  - Event 'collision'
  - Event 'move'
  - Event 'rotate'
  - Event 'destroy'
  - Event 'state'
  - Event 'jump'
  - Event 'fall'
  - Event 'fly'
  - Event object
- removeCollision()
Object getters
Object setters
Development
License

games

Install

Download

Latest builds are available in the project releases page.

CDN

https://unpkg.com/elpy/dist/elpy.min.js

NPM

npm install elpy

Basic usage example

<!DOCTYPE html>
<html>
<head>
  <title>Elpy.js</title>
</head>
<body>
  <canvas id="field"></canvas>
  <script src="elpy.min.js"></script>
  <script>
    const elpy = new Elpy('#field', 500, 500);
    const player = elpy.create('player', 50, 50, 20, 20);
    const wall = elpy.create('wall', 100, 50, 20, 20, { color: 'brown' });

    elpy.add(player);
    elpy.add(wall);
    player.collision(wall);

    elpy.key(key => {
      if (key === 'ArrowUp') {
        player.move(player.x, player.y - 1);
      }
      if (key === 'ArrowDown') {
        player.move(player.x, player.y + 1);
      }
      if (key === 'ArrowLeft') {
        player.move(player.x - 1, player.y);
      }
      if (key === 'ArrowRight') {
        player.move(player.x + 1, player.y);
      }
    });
  </script>
</body>
</html>

Engine

Create engine instance

const elpy = new Elpy(
  "#element", // id element canvas or HTML object element get by document.querySelector().
  500, // width.
  500, // height.
  // options.
  {
    preload, // default - true, enable / disable preloader.
    favicon // default - true, enable / disable favicon.
  }
)

create(name, x, y, width, height, options)

name	type	description
`name`	`<String>`	The object name must be unique.
`x`	`<Number>`	Position of the object along the x-axis.
`y`	`<Number>`	Position of the object along the y-axis.
`width`	`<Number>`	Object width in pixels.
`height`	`<Number>`	Object height in pixels.
`options`	`<Object>`	Additional object parameters.

Creates and returns an engine object.

min example

const player = elpy.create('player', 10, 10, 20, 20);

max example

const player = elpy.create('player', 10, 10, 20, 20, {
  obstacle: true, // default - true.
  pushing: false, // default - false.
  disabledEvents: false, // default - false.
  type: 'player object', // default - null.
  custom: {}, // default - null.
  color, // default - 'black'.
  // image: '' or image: { path: '', repeat: false }.
  image: { 
    path: '', // default - null.
    repeat: false // default - false.
  },
  // default - null.
  images: [
    {
      paths: ['images/player_left.png', 'images/player_right.png'], // path to image.
      state: 'move:left', // in what condition are the images available. player.state = 'move:left'.
      time: 100 // if player.animate = true - switching time between images.
    }
  ]
});

name	type	description
`obstacle`	`<Boolean>`	To determine if an object is an obstacle if there is a collision with the object. If the object was not added to the collision then the object will pass through another object. If an object has been added to a collision, then by default the object will stop on collision. If it is necessary that the collision event occur and the object passes through the object, then the obstacle property can be switched to false.
`pushing`	`<Boolean>`	Will the object move if it is pushed through the push method.
`disabledEvents`	`<Boolean>`	Disables all events for an object.
`type`	`<Null>`, `<String>`	A simple string that allows you to add your own data. It is convenient to use to set the type of an object in order to distinguish them from each other later.
`custom`	`<Null>`, `<Object>`	An object where you can add your fields and use them via `object.options.custorm`.
`color`	`<String>`	Set object color.
`image`	`<String>`, `<Object>`	Set image. Two data types can be used: String or Object. `image: 'path/to/image/'` or for repeat image `image: { path: 'path/to/image/', repeat: true }`.
`images`	`<Array>`	Can be used if the object has several images that can be changed through the state. For example, the image of the position when the player goes to the right or left. You can also make animation of switching frames through the animate property (Object getters). The switching `time` is set in the time property.

add(object)

name	type
`object`	`<String>`

Add an object to the engine.

elpy.add(player);

key(callback)

name	type
`callback`	`<Function>`

Listen for keydown and keyup events. Сallback is always called when a key is pressed.

elpy.key(key => {
  if (key === 'ArrowUp') {
    // ...
  }
});

keydown(callback)

name	type
`callback`	`<Function>`

Сallback fires once on click.

elpy.keydown(key => {
  if (key === 'ArrowUp') {
    // ...
  }
});

keyup(callback)

name	type
`callback`	`<Function>`

Сallback fires once on click.

elpy.keyup(key => {
  if (key === 'ArrowUp') {
    // ...
  }
});

mousemove(callback)

name	type
`callback`	`<Function>`

Handles mouse movement on the canvas.

elpy.mousemove((x, y) => {
  // x, y - coordinates inside the canvas.
});

click(callback)

name	type
`callback`	`<Function>`

Handles mouse click on the canvas.

elpy.click((x, y) => {
  // x, y - coordinates inside the canvas.
});

tick(callback)

name	type
`callback`	`<Function>`

Called recursively. The next call is queued after the scene is updated (render). To cancel the call inside the callback, return false.

let delta = 0;
// tick will be called 100 times.
elpy.tick(() => {
  if (delta === 100) {
    return false; // stop tick.
  }

  delta++;
  
  player.move(player.x + delta, player.y + delta);
});

nextTick(callback)

name	type
`callback`	`<Function>`

Adds a callback to the queue after the scene is updated (rendered) and calls callback once.

elpy.nextTick(() => {
  // ...
});

checkObjectInViewport(object)

name	type
`object`	`<Object>`

Checking if the object is in the visible area.

elpy.checkObjectInViewport(player); // returns true or false.

fixingCamera(object, fixedCamera)

name	type
`object`	`<Object>`
`fixedCamera`	`<Object>`

Fix the camera behind the object. You can fix both in one coordinate and in two.

min example

elpy.fixingCamera(player, {
  x: true
});

max example

elpy.fixingCamera(player, {
  x: true,
  y: true
});

unfixingCamera()

Unfix the camera from the one previously fixed behind the object.

elpy.unfixingCamera();

destroy()

Destroying all objects and stopping rendering.

elpy.destroy();

on(event, callback)

name	type
`event`	`<String>`
`callback`	`<Function>`

Listen to the engine event.

elpy.on('eventName', () => {
  // event handling.
});

Event: `'load'`

Called when the application has loaded all resources and is ready.

elpy.on('load', () => {
  // event handling.
});

Event: `'animation'`

name	type
object	`<Object>`
image	`<String>`
images	`<Array>`

Called when an object images are switched.

elpy.on('animation', (object, image, images) => {
  // object - object to be animated.
  // image - current image. Examlpe: 'images/player_left.png'.
  // images - a list of all images that were passed to paths when the object was created. Example: ['images/player_left.png', 'images/player_right.png'].
});

load()

The method is called automatically when document.readyState === 'complete'. If the engine has not loaded and is in a black window state, you can call load manually after all operations with the engine (creating objects, adding objects, etc.).

elpy.load();

Engine getters

name	type	description
width	`<Number>`	Returns the width of the canvas.
height	`<Number>`	Returns the height of the canvas.
offset	`<Object>`	Returns information on object and field offset.
objects	`<Object>`	Returns all added objects.

elpy.width;

Object

run(step)

name	type	default
`step`	`<Number>`	`1`

Vector movement. Moves in different directions depending on positive or negative values.

min example

player.run();

max example

player.run(-1);

move(x, y)

name	type
`x`	`<Number>`
`y`	`<Number>`

Move at coordinates.

player.move(10, 10);

fly(degrees, distance, step)

name	type	default
`degrees`	`<Number>`	`0`
`distance`	`<Number>`	`0`
`step`	`<Number>`	`1`

Vector flight.

min example

player.fly(0);

max example

player.fly(0, 100, 10);

jump(height, multiplier, forced)

name	type	default
`height`	`<Number>`	`0`
`multiplier`	`<Number>`	`0.1`
`forced`	`<Boolean>`	`false`

Object jumps with further fall.

min example

player.jump(10);

max example

player.jump(10, 0.5, true);

fall(multiplier)

name	type	default
`multiplier`	`<Number>`	`0.1`

Free fall.

min example

player.fall();

max example

player.fall(0.5);

push(object)

name	type
`object`	`<Object>`

Pushing an object. The one who pushes must have a collision with what he pushes.

player.push(object);

rotate(degrees, x, y)

name	type	default
`degrees`	`<Number>`	`0`
`x`	`<Number>`	`0`
`y`	`<Number>`	`0`

Object rotation.

min example

player.rotate(90);

max example

player.rotote(90, 10, 20);

stop()

Stop actions: jump, fall, fly.

player.stop();

destroy()

Destroy object.

player.destroy();

collision(object)

name	type
`object`	`<Object>`, `<Array>`

Add collision object.

player.collision(object);

on(event, callback)

name	type
`event`	`<String>`
`callback`	`<Function>`

Listen to the object event.

player.on('eventName', () => {
  // event handling.
});

Event: `'collision'`

name	type
`object`	`<Object>`
`side`	`<String>`

Called in the collision of the object.

player.on('collision', (object, side) => {
  // object - collision object.
  // side - side of the object that was collided.
});

Event: `'move'`

Called when moving the object.

player.on('move', () => {
  // event handling.
});

Event: `'rotate'`

Called when rotating the object.

player.on('rotate', () => {
  // event handling.
});

Event: `'destroy'`

Called when the object is destroyed.

player.on('destroy', () => {
  // event handling.
});

Event: `'state'`

Called when changing the condition of the object.

player.on('state', () => {
  // event handling.
});

Event: `'jump'`

name	type	description
`event`	`<Object>`	link

Called when jumping an object.

player.on('jump', event => {
  // event - event object.
});

Event: `'fall'`

name	type	description
`event`	`<Object>`	link

Called when the object falls.

player.on('fall', event => {
  // event - event object.
});

Event: `'fly'`

name	type	description
`event`	`<Object>`	link

Called when the object flies.

player.on('fly', event => {
  // event - event object.
});

Event object

name	type	description
`stopped`	`<Boolean>`	The property will be `true` if the object has been stopped.
`paused`	`<Boolean>`	The property will be `true` if the object has been paused.
`stop()`	`<Function>`	Stop object. If he was in a state: `jump`, `fall`, `fly`.
`pause()`	`<Function>`	Pause object. If he was in a state: `jump`, `fall`, `fly`.
`resume()`	`<Function>`	Resume object. If it was paused.

The object that is returned in the event callback: jump, fall, fly.

player.on('jump', event => {
  event.stopped; // returns true or false.
  event.paused; // returns true or false.
  event.stop();
  event.pause();
  event.resume();
});

removeCollision(object)

name	type
`object`	`<Object>`

Remove collision object from collision list.

player.removeCollision(object);

Object getters

name	type	description
name	`<String>`	Returns the name of the object.
options	`<Object>`	Returns object options.
track	`<Object>`	Returns the object's previous moves.
dest	`<Object>`	Returns the coordinates where the object is moving.
offset	`<Object>`	Returns the offset coordinates of an object.
isPushing	`<Boolean>`	Is it possible to push an object.
isJumping	`<Boolean>`	Is the object in a jump.
isFlying	`<Boolean>`	Is the object in fly.
isExist	`<Boolean>`	Does the object exist.
x	`<Number>`	Position of the object along the x-axis.
y	`<Number>`	Position of the object along the y-axis.
width	`<Number>`	Object width in pixels.
height	`<Number>`	Object height in pixels.
state	`<String>`	Returns the current state of the object.
animate	`<Boolean>`	Is the object animated.
ghost	`<Boolean>`	Whether collision is canceled with other objects that go to it.
degrees	`<Number>`	The degrees the object is rotated.
added	`<Boolean>`	Is the object added.

player.name;

Object setters

name	type	description
x	`<Number>`	Position of the object along the x-axis.
y	`<Number>`	Position of the object along the y-axis.
width	`<Number>`	Object width in pixels.
height	`<Number>`	Object height in pixels.
state	`<String>`	Used to switch textures.
animate	`<Boolean>`	Whether to animate the object.
ghost	`<Boolean>`	Cancels collision with other objects that go to it.
added	`<Boolean>`	Is the object added.