Declick Engine

Declick Engine is a javascript interpreter and runtime environment that can be used with graphical and non-graphical objects. Object names and methods are fully internationalized, as well as runtime environemnt itself. Graphical objects are rendered using Phaser library. Declick Engine has been built primarily as an educational tool to teach children how to code and allow them to easily create small graphical games.

Demonstration

A demonstration page is available here: https://colombbus.gitlab.io/declick-engine/

How to build

install dependencies

npm install

build library

npm run build

Generated library is located in dist directory. Currently two versions are generated:

• declick-engine.js, CommonJS library
• declick-engine-esm.js ES module (no size optimization)

demo

When library is built, a demo web page is generated at demo/dist/index.html

Documentation

Objects (Work in progress)

Documentation in English

• Web version
• Markdown version

Documentation en français

• Version web
• Vesion markdown

Sprites and maps

• How to build and use sprites and maps

How to add objects

Internationalization

Classes names and exposed methods are internationalized, using two tools:

• i18n Tagged Template Literals
• Metadata proposal through decorators

These tools make it really easy to define a translated name for a class or a method:

import 'reflect-metadata'

@Reflect.metadata('translated', 'MyClass')
class MyClass {
  @Reflect.metadata('translated', 'exposedMethod')
  @Reflect.metadata('help', 'exposedMethod_help')
  exposedMethod(value) {
    this._value = value
  }
}

For internationalization of exposedMethod, two parameters are defined:

• i18`exposedMethod is the translated name
• i18n`exposedMethod_help is the help text that will be used for this method

Following i18n Tagged Template Literals scheme, translation texts are stored within directory translations.

Note: in Visual Studio Code, the use of i18n Tagged Template Literals extension makes it really easy to manage translation texts.

Adding a basic class

Classes are stored in directory src/objects/classes. A basic class should derive from BaseClass:

import 'reflect-metadata'

class MyClass extends BaseClass {
    ...
}

export default MyClass

Adding a graphical class

Graphical classes are stored in directory src/objects/classes. They derive from GraphicClass:

import GraphicClass from '../graphic-class'

class MyGraphicClass extends GraphicClass {

  constructor() {
    super()
    this._object = // _object holds reference to the actual graphics object, handled by Phaser
  }

  static setup() {
    // this static method is called once at setup: it can be used e.g. to load some assets used by every instance
  }

  tick(delta) {
    // called by graphics framework, may be used to animate the instance
  }

  getX() {
    // should be implemented to give the X coordinate of the instance
  }

  getY() {
    // should be implemented to give the Y coordinate of the instance
  }

  setLocation(x, y) {
    // should be implemented to position the object
  }

}

Adding an instance

Instances are stored in directory src/objects/instances. An instance should derive from BaseInstance:

import BaseInstance from '../base-instance'

class MyInstance extends BaseInstance {}

export default MyInstance

Checking arguments of exposed methods

Since exposed metohds will be used from outside of Declick, there is a strong need for checking the type of provided arguments.To do so, Declick object may use @checkArguments as a decorator for the exposed method:

import { checkArguments } from '../utils/checks'

  @checkArguments(['integer'])
  myExposedMethod(value) {
    // value should be an integer, otherwise an error is thrown
    ...
  }

  @checkArguments(['integer', 'string'])
  myExposedMethod2(value1, value2) {
    // value1 should be an integer, value2 should by a string
    ...
  }

  @checkArguments(['integer', 'string', 'array'], 2)
  myExposedMethod3(value1, value2, value3) {
    // value1 should be an integer, value2 should by a string, value3 should by an array
    // the two last parameters are optional
    ...
  }

  @checkArguments(['integer', 'integer|string|boolean'])
  myExposedMethod4(value1, value2) {
    // value1 should be a en integer
    // value2 should be an integer OR a string OR a boolean
    ...
  }

Available types are: integer, string, array, number, boolean, object, function, canvas, any

Handling events

Classes and instances may manage events using the following methods:

• this.addListener('eventName', function) adds a listener for event eventName
• this.dispatch('eventName') dispatches event eventName

Dependencies

Declick Engine uses the following libs:

• acorn javascript parser
• JS-Interpreter
• Phaser for graphical objects rendering