massiveheights/black

World's fastest HTML5 2D game engine   🛸

BLACKSMITH 2D

Black is a highly optimized 2D framework for web, mobile games, and playable ads.

Most valuable when size matters
All engine code is written in ES6, fully GCC typed, allowing to eliminate all dead code from your app. For example the size of Donuts game is only 34KB gzipped for both engine and game code (GCC version).

Advanced scene graph and rendering pipeline
Dirty flag tracks scene changes and avoids unnecessary calculations and context calls. If no changes were made to the scene since last frame, no rendering will be done. Battery efficient.

Cache as bitmap
Automatically detects changes and updates bitmap cache. Allows to gain even more performance on heavy scenes and runs smoothly on old devices.

For more information about how to use Black Engine, please check the Blacksmith 2D website.

FEATURES

✔️ Extra lightweight
✔️ Display Resolution Awareness
✔️ Advanced Particle System
✔️ Vector Graphics
✔️ Vector Graphics Baking
✔️ Smart Cache As Bitmap
✔️ Tweens
✔️ Message Dispatcher
✔️ Sprite Animations
✔️ Asset Manager
✔️ Advanced Font Rendering and font metrics
✔️ Texture Atlas
✔️ Input
✔️ Clipping Rectangle
✔️ Component System
✔️ Audio Support
✔️ Audio Atlases
✔️ Bitmap Fonts
✔️ Graphics
✔️ Battery Efficient
✔️ Render Texture
✔️ Arcade Physics
✔️ Texture Wrap and Repeat
✔️ Nine slice grid
✔️ GCC Ready

GETTING STARTED

The easiest way to start using Black Engine is by downloading ready-up game template:

git clone https://github.com/MassiveHeights/Black-Template
cd Black-Template
npm install
npm start

Then open http://127.0.0.1:3000 in browser!

SUPPORT

Feel free to chat with developers directly on Facebook, Discord or Telegram. Have other questions? Feel free to contact support by email. Remember to check Documentation before asking questions.

CONTRIBUTING TO BLACK ENGINE

Written something cool using Black Engine? Please tell us about it via email.
Found a bug or issue — post them on Issues page.

QUICK LINKS

Getting Started — Examples — Game Template — EULA

black's Issues

`FontFaceAssetLoader` doesn't work with spaces in Google webfont name

Describe the bug
AssetManager never emits the complete event if a queued Google webfont asset has spaces in its font name. This happens because the assignment of the fontFamily with the queued font name in FontFaceAssetLoader has no effect:
https://github.com/MassiveHeights/Black/blob/master/src/assets/loaders/FontFaceAssetLoader.js#L75

this.mTestingElement.style.fontFamily = name + ',' + this.mTestingFontName;

If name is e.g. Press Start 2P the fontFamily for the testing element remains Courier New as configured earlier, because in a list of comma-separated families, names with spaces should be quoted. Thus the width of the testing element never changes and a successful load of the font is not triggered.
The problem can be fixed by adding quotes around the generated fontFamily name:

this.mTestingElement.style.fontFamily = '"' + name + '",' + this.mTestingFontName;

Note that quotes need to be used for TextField fonts in that case, too:

let textField = new TextField('Test 123', '"Press Start 2P"', 0xffffff, 64, FontStyle.NORMAL, FontWeight.BOLD, 8, 0);

FontFaceAssetLoader should probably not loop indefinitely if the testing element width won't change. I suggest to include a failure counter, too, and emit an error after X attempts.

To Reproduce
Steps to reproduce the behavior:

1. Include "black-engine": "0.5.12", as a dependency
2. Instantiate a default AssetManager: var assets = new AssetManager();
3. Queue loading of Google Webfont with spaces: assets.enqueueGoogleFont('Press Start 2P');
4. Bind complete handler to a method onAssetsLoaded and start loading:

assets.on('complete', this.onAssetsLoaded, this);
assets.loadQueue();

5. Observe that onAssetsLoaded is never called.

Expected behavior
onAssetsLoaded should be called.

Desktop (please complete the following information):

• OS: macOS Mojave 10.14.6
• Browser: Chrome
• Version: Version 85.0.4183.38 (Official Build) beta (64-bit)

Restriction of trigger playing HTML5 video

Describe the bug

For now, as all we know, mobile browsers can not autoplay a video without user interactions.

As a workaround, we guide users to emit valid user interactions, such as touchend. (Full list of valid events can be found here)

I implemented similiar function with PIXI before. But, when working with Black, I used the same method to implement this function, it doesn't work.

I compared the PIXI's interactionManager and Black's Input, can not find useful information about this issue.

So I made 2 demos, one for Black, one for PIXI.

1. black-video-autoplay-issue - not work
2. pixi-video-autoplay - works

Hope that some guys can give me some tips.

To Reproduce
You can use following steps to run above 2 demos:

1. clone the repo
2. yarn install
3. yarn start to run the development server
4. Open an iPhone browser, visit http://<ip of your phone in LAN>:9000
5. Then you will see 2 Buttons:
   • BUTTON DOM - ordinary button implemented with tag <div> (not sementic enough, I know);
   • BUTTON CANVAS - text implemented with corresponding engine's Text Class;
6. The BUTTOM DOM works as expected, it trigger the playing of video
7. The BUTTON CANVAS:
   • one with Black: not work, it doesn't trigger the playing of video;
   • one with PIXI: works as expected, it trigger the playing of video;

Expected behavior
Make Black can be trigger the playing of video.

Screenshots
None.

Desktop

• Device: iPhone6 / iPhone5 SE
• OS: iOS 12.0
• Browser: Chrome 69 / Safari

Some Ideas
I guess this is the problem about event bubbling. I am confirming it, also.

Engine and demo file size

In the README.md of the Black engine it is stated that the Donuts demo game is only 33KB gzipped for both engine and game. When building the demo game (https://github.com/MassiveHeights/Black-Donuts) using the latest Black engine (0.5.10) and running the production build script (npm run build) and analyzing the produced code bundle the gzipped bundle size is 56.25KB

To Reproduce
Steps to reproduce the behavior:

1. clone repo: https://github.com/MassiveHeights/Black-Donuts

2. run: npm install

3. install webpack-bundle-analyzer as a dev dependency to be able to analyse the code bundle.
   npm install --save-dev webpack-bundle-analyzer

4. Add the bundle analyzer as a plugin:

in webpack.config.js:
const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;

add the analyser as a plugin:

module.exports = { plugins: [ new BundleAnalyzerPlugin() ] }

5. create a production build
   npm run build

The bundle analyzer will create an interactive treemap visualization of the contents of the bundle.
The Gzipped size of the bundle is 56.25KB.

Expected behavior
The Gzipped size of the bundle should be 33KB as described inthe engin's readme.

Screenshots

Bundle file size is very important for my project. I would like to achieve the smallest bundle size possible. The demo game bundle size is almost double the size claimed in the engine's readme file.
Im not sure if the bundle size is related to a problem with my process or is there other optimizations that has to be done to achieve a small bundle size.

Reversed tween skips first update

Steps to reproduce the behavior:

let tween = new Tween(
      {
        y: 1000
      },
      0.5,
      {
        playOnAdded: true,
        ease: Ease.backOut,
        reversed: true,
      });

this.addComponent(tween);

After code above execution, game object would appear on its current position (y = 0) on the first frame (should be y = 1000). After first update tween proceeds as expected.

DefinitelyTyped Typings

I appreciate the jsdoc comments throughout this project, however in order to co-exist alongside other TypeScript projects at our company, we needed Typings for this project. I just wanted to raise awareness that I've opened a Pull Request on DefinitelyTyped to add type definitions for black-engine.

The PR is located here: DefinitelyTyped/DefinitelyTyped#59390

If anyone wants to review this PR please feel free. Or even better, if you wish to become a co-author, just leave a comment here or on the PR.

Vue-cli webpack issues due to empty black-engine.min.js

Describe the bug
The file "dist/black-engine.min.js" is empty. As such when dependencies are gathered this empty file is found for the engine resulting in failures at runtime.

To Reproduce
Steps to reproduce the behavior:

1. Go to "dist" folder
2. Click on 'black-engine.min.js'
3. See that the only line in it is 'use strict';

Expected behavior
It should contain the minified source code for the engine

Polygon.contains has a flaw

Describe the bug
The contains function of the Polygon class looks like it uses some form of ray casting to test whether a given point lies within the polygon. However, it presents incorrect results for certain points outside the polygon. Please see this jsFiddle for a concise view of the problem.

https://jsfiddle.net/ce62j3qa/59/

I have created a polygon in this example and used the vertices to draw a graphic of it on the stage. I then create 5000 random points on the stage and run them through the contains function. I draw those points in red if they are reported to be outside the polygon and green if they are reported to be inside the polygon.

I believe that a simple check that the a point is outside the bounds of the polygon first before doing the ray casting would be both more efficient and would correct the bug.

If you modify the creation of the polygon in the jsFiddle to use the extended Polygon2 class with bounds checks you should see the intended results.

Expected behavior
I would expect that points within the polygon would return true and points outside of the polygon would return false.

Screenshots

Desktop (please complete the following information):

• OS: Windows 10
• Browser: Chrome
• Version: 85

Integrate Black with Webpack 4.

I create a demo at here to describe the problem.

Also, I create a ES5 demo at here, same error occurs again.

NONE Scaling Mode

Is your feature request related to a problem? Please describe.
Currently when handling canvas scaling myself, there is no clean way to disable automatic scaling by BlackEngine.

Describe the solution you'd like
Add a new ScaleMode called StageScaleMode.NONE. This would perform no action in the refresh function here:

Black/src/display/Stage.js

Line 133 in af2ae79

if (this.mScaleMode === StageScaleMode.FIXED) {

Describe alternatives you've considered
The only alternative atm is to set the scale mode to something not supported and live with the constant console error messages.

engine.stage.scaleMode = 'NONE';

Typescript and Electron support

I wanted to experiment with blacksmith using typescript inside electron and still have access to the source code so I can debug/learn it instead of treating it like a black box. Took me a few hours to get it full working, so I figured I'd post here as an FYI in case people care. I know it's sloppy to just copy the code into my own codebase, so if there are better ways i'm all ears :)

https://github.com/xstos/KatanaKinesis/tree/main/app

Here's the lazy port to typescript:
https://github.com/xstos/KatanaKinesis/tree/main/app/src/Black

I made a second project that supports hot reloading as well.
https://github.com/xstos/KatanaKinesis/tree/main/black

Texture tiling and wrapping

Add ability to tile texture multiple times within a given area.
Add ability to wrap texture on x or y-axis in pixels.
Add ability to scale texture tiled texture.

Bitmap fonts don't display in Firefox

Describe the bug
No bitmap text is displayed in Firefox.

To Reproduce
Steps to reproduce the behavior:

1. Go to Bitmap font sample
2. No text is displayed, console indicates error

Expected behavior
Same result as Chrome, with three lines of text.

Screenshots

Desktop (please complete the following information):

• OS: Windows 10
• Browser Firefox
• Version 65.0.2

Vector Textures

The idea is to be able to load SVG or other format and work with it just like with a regular sprite.

9 Grid Slice

Add support for 9 grid slice sprites.

Visible seams in 9 grid slice

Describe the bug
On at least one browser, the slice seams are visible.

To Reproduce
Steps to reproduce the behavior:

1. Go to Slice-9-Grid example
2. Observe seams as the scale changes

Expected behavior
They should not be visible, just like in Chrome

Screenshots

Desktop (please complete the following information):

• OS: Windows 10
• Browser: Firefox
• Version: 65.0.2

PointerEvent issue in FF and Safari

The latest changes done in v0.5.11 to fix the incorrect pointerUp message done in Input.js is causing TypeError issues in FireFox and Safari.

To replicate the issue run the Donuts-Black game (using black v0.5.11) in FireFox or Safari to see the below error message in the console.

It seems like the path property of Event objects is non-standard.

See this StackOverlow for more details:
https://stackoverflow.com/questions/39245488/event-path-undefined-with-firefox-and-vue-js

Game does not resume when switching back and forth between tabs

Describe the bug
Game stops running after changing tabs multiple times.

To Reproduce
Steps to reproduce the behavior:

1. Go to Draw Bounds Example
2. Change tabs twice
3. Come back to the Draw Bounds tab
4. Notice the game has stopped
5. Change to a different tab
6. Come back to the Draw Bounds tab
7. Change to a different tab
8. Come back to the Draw Bounds tab
9. Game will now have resumed

Expected behavior
Game is expected to always resume when its tab is selected.

Desktop (please complete the following information):

• OS: Windows 10
• Browser Firefox
• Version 65.0.2

Desktop (please complete the following information):

• OS: Windows 10
• Browser Chrome
• Version 72.0.3626.121

Black.stage.orientation

Black.stage.orientation = StageOrientation.LANDSCAPE

It's not working on ios running on safari and when running added to home screen. Keeping rotating and do not lock orientation.

From example page : Orientation example

AnimationController.remove doesn't remove animations

The remove function in the AnimationController class doesn't actually remove the animation from this.mAnimations unless it is currently playing.

Black/src/animation/AnimationController.js

Line 51 in 3b31e2a

remove(name) {

How to fix:

Swap line 59

Black/src/animation/AnimationController.js

Line 59 in 3b31e2a

delete this.mAnimations[name];

and line 62

Black/src/animation/AnimationController.js

Line 62 in 3b31e2a

this.mCurrentAnim = null;

Orientation Lock

Add ability to lock desired orientation no matter what device orientation is.

Add GameObject.relativeTo method

Expected result: should return a vector representing GameObject's position relative to another GameObject.

GameObject.relativeTo(gameObject, offsetX, offsetY);

Stage is null when gameObject constructor is called

Describe the bug
Whenever I try to access this.stage directly in the constructor it is null and I end up with errors like Cannot read property 'on' of null

To Reproduce
See https://codepen.io/dmail/pen/QWKRaVQ

Expected behavior
this.stage is accessible

Screenshots

Desktop (please complete the following information):

• OS: MacOS
• Browser: Chrome

Additional context
I figured this out because I do not need to load asset in my minimalist game. So my code is not waiting for anything before trying to read this.stage and I have to force the loading of a fake asset or use setTimeout to fix that.

Skew

Add ability to skew the GameObject via skewX and skewY properties.

Fix worldTransformation to support skew.

Setting width or height on GameObject has no effect

Describe the bug
Setting width or height on a GameObject has no effect. The code updates the scale but doesn't store the passed in values. Example:

  // GameObject.js
  set width(value) {
    Debug.assert(!isNaN(value), 'Value cannot be NaN');

    this.scaleX = 1;
    const currentWidth = this.width;

    if (currentWidth != 0.0)
      this.scaleX = value / currentWidth;
  }

For more context, here's my use case: I tried creating a UI widget which consists of a frame (using a 9-slice-sprite) and lines of text. When creating the widget, I tried to specify width/height from the outside:

const widget = new TextWindow(); // extends GameObject
widget.x = 10;
widget.y = 10;
widget.width = this.stage.bounds.width / 2;
widget.height = 200;
this.add(widget);

which should allow me to create the child objects accordingly:

// TextWindow.onAdded:
// frame should take the entire size of the parent:
const frame = new Sprite('ui-frame');
frame.slice9grid = new Rectangle(10, 10, 4, 4);
frame.x = 0;
frame.y = 0;
frame.width = this.width;
frame.height = this.height;
this.add(frame);

However, this.width and this.height remain 0 even though the values were provided after creation.
If this is not how it is supposed to be done, what's the correct approach then?

To Reproduce
With Black 0.5.12, create a new GameObject and set the width to something >0. Then query the width and observe that it's still returned as 0.

Expected behavior
Changing the width programmatically should be accepted.

Desktop (please complete the following information):

• OS: macOS Mojave 10.14.6
• Browser: Chrome
• Version: Version 85.0.4183.38 (Official Build) beta (64-bit)

ScaleMode issue with StageOrientation.PORTRAIT

Recently, I'm using black-engine on a portrait layout page, and I think I found a issue.

The example code is here.

example 1

Black.stage.scaleMode = StageScaleMode.LETTERBOX
Black.stage.setSize(750, 1500)
Black.stage.orientation = StageOrientation.PORTRAIT

When I am using setSize(750, 1500) and StageOrientation.PORTRAIT, black-engine returns following to me:

But, I should be:

What is the problem? 750x1500 is a size that should fit PORTRAIT layout obviously, but It didn't work as expected.

example 2

As I mentioned in example 1, black-engine seems doing something wrong. I have to use setSize(1500, 750) (swap width and height) in order to make it work.

Black.stage.scaleMode = StageScaleMode.LETTERBOX
Black.stage.setSize(1500, 750)
Black.stage.orientation = StageOrientation.PORTRAIT

It returns the right result:

But it shouldn't return the right result. Because 1500x750 is a size that fits LANDSCAPE layout. It didn't work as expected.

---

Is it an issue?

Allow adding additional assets to the queue after loadQueue is triggered

Is your feature request related to a problem? Please describe.
I was investigating how loading of a Tiled map (tmx) could work in Black. tmx files are XML which contains references to additional files, like tilesets (tsx) or images, and tilesets are also XML which lists images. This means that additional resources which need to be queued for loading are only known after the map file was loaded and parsed.

Describe the solution you'd like
Assets should be able to queue additional assets while loading, for example by having access to the AssetManager from which they're being loaded. Currently the AssetManager would have to be passed in manually, but queuing while loading is currently denied due to an invalid state of the AssetManager.

Additional context
Tiled is a popular 2D map editor and importing Tiled files should be supported. I'd love to hear alternative approaches to deal with nested loading of assets.