Skip to content

space2pacman/elpy

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

269 Commits
dist
dist
 
 
docs
docs
 
 
src
src
 
 
.gitignore
.gitignore
 
 
LICENSE.md
LICENSE.md
 
 
README.md
README.md
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
webpack.config.js
webpack.config.js
 
 

Repository files navigation

Elpy.js - 2D JavaScript game engine.

logo

License: MIT JavaScript Size Downloads npm

Demo Game examples

Docs

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
name <String>
x <Number>
y <Number>
width <Number>
height <Number>
options <Object>

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: { src: '', repeat: false }
  image: { 
    src: '', // 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 description
obstacle 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 Will the object move if it is pushed through the push method.
disabledEvents Disables all events for an object.
type 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 An object where you can add your fields and use them via object.options.custorm.
color Set object color.
image Set image. Two data types can be used: String or Object.
image: 'path/to/image/'
or for repeat image
image: { src: 'path/to/image/', repeat: true }
images 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'

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

Event: 'animation'

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

min example

elpy.width;
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.

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>
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>
multiplier <Number> 0.1
forced <Boolean> false

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>
x <Number> 0
y <Number> 0

Object rotation.

min example

player.rotate(90);

max example

player.rotote(90, 10, 20);

stop()

Stop: 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>

Add an event listener.

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

Event: 'collision'

Callback arguments.

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

Event: 'move'

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

Event: 'rotate'

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

Event: 'destroy'

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

Event: 'state'

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

Event: 'jump'

Callback arguments.

name type description
event <Object> link 
player.on('jump', event => {
  // event - event object.
});

Event: 'fall'

Callback arguments.

name type description
event <Object> link 
player.on('fall', event => {
  // event - event object.
});

Event: 'fly'

Callback arguments.

name type description
event <Object> link 
player.on('fly', event => {
  // event - event object.
});

Event object

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

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() Stop object. If he was in a state: jump, fall, fly.
pause() Pause object. If he was in a state: jump, fall, fly.
resume() Resume object. If it was paused. 
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

min example

player.name;
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>
y <Number>
width <Number>
height <Number>
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>
added <Boolean> Is the object added.

Object setters

min example

player.width = 10;
name type description
x <Number>
y <Number>
width <Number>
height <Number>
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.

Development

npm run serve

License

MIT

About

2D JavaScript game engine.

space2pacman.github.io/elpy/docs/

Topics

javascript game gamedev games html5 canvas game-engine game-development game-2d html5-game-development 2d-game 2d 2d-game-engine game-engine-2d

Resources

Readme

License

MIT license
Activity

Stars

86 stars

Watchers

2 watching

Forks

0 forks
Report repository

Releases 15

1.1.13 Latest
Mar 28, 2023
+ 14 releases

Packages

No packages published

Languages