hachitus / flatworld

2D strategy game engine for browsers

Development halted

Unfortunately for several (personal) reasons, I've decided to cancel the development of the engine. There was a game in an ok status being developed with it, so with small performance and bug tweaks then engine was in quite a good shape already. But there is a time for everything.

ALPHA!

The development is still in alpha stage. Basic features are mostly done for the engine, but the API and structure can still go under changes, please take that into account! Also please contact me if you plan to use the engine or have questions! Gitter is an easy option too.

Introduction

2D turn-based strategy game engine for browsers. The engine originally got into development to get an engine for more hard-core turn-based games and not casual games. I was frustrated at waiting for those games and decided to start making it on my own. Browser environment is a perfect match for turn-based multiplayer. You can continue your turn easily anywhere, any time!

If you are interested contact me (http://hyytia.level7.fi/). I am eager and grateful to get any feedback or help with the project.

Table of contents

• Hot links
• Developing
  • Installation
  • Examples
  • Setup a simple map
  • Factories
  • Extensions
  • Templates
  • Events
• Requirements and restrictions
  • Supported environments
  • Aimed mapsize and efficiency
• Sponsors
• Credits

Hot links

• API documentation
• Contribution guidelines
• Chat in Gitter
• Base plunkr
• Changelog

Developing

Installation

npm i flatworld

Examples

Best example is found in plunkr. This is the base map created with the engine. The latest example will be found from the engines manual tests (in src/tests/-folder). A working example should also be found in: http://flatworld.level7.fi/manualStressTest.html, but not quaranteed that it is always on (as server can be down or dns changed).

Setup a simple map

The main module for the whole map is core.Flatworld, so you should always primarily look through it's API and then dig deeper. The best examples for setting up a map at the moment is still going through the code. Check the test-files: tests/manualTest.html and tests/manualStressTest.html (which are more comprehensive). They use horizontalHexaFactory to go through the map data and setup objects based on that data. You can use horizontalHexaFactory if you want or setup your own factory and own data structure. Factories always have to follow a certain data structure so they might not be something everyone wants or can cope with.

Simple example:

import Loader from 'resource-loader';
import { ObjectTerrain, ObjectUnit } from "/components/map/extensions/hexagons/Objects";

const baseUrl = '';
preload = new Loader( baseUrl, { crossOrigin: false } );
preload.add( "terrainBase.json" );

preload.load(() => {
	var map, thisLayer, newObject;
	var layerOptions = {
    	name: "terrainLayer",
      	drawOutsideViewport: {
        	x: 100,
        	y: 100
      	},
      	selectable: layerData.name === "unitLayer" ? true : false
    };
    var objData = {
      typeData: "typeData,
      activeData: "someData"
    };
    var currentFrame = 1;
    var hexagonRadius = 50;
    var objectOptions = {
        currentFrame,
    	radius: hexagonRadius
    };

	map = new Map(canvasElement, mapOptions );
	dialog_selection = document.getElementById("selectionDialog");
    defaultUI = new UI_default(dialog_selection, map);

    /* Initialize UI as singleton */
    UI(defaultUI, map);

	map.init( pluginsToActivate, startPoint );

	thisLayer = map.addLayer('terrain', layerOptions);
	newObject = new ObjectTerrain({ x: 1, y: 1 }, objData, objectOptions);
	thisLayer.addChild(newObject);
})

Factories

Factories are the ones that get the server-side data, iterate through it and create the necessary objects to the FlaTWorld map.

You most likely need to implement your own factory function for your game, if the game is not very close to the factory that the engine provides. At the moment I suggest you read through the code in hexaFactory.js and create your own based on that.

Extensions

The map supports adding extensions and even some of the core libraries parts have been implemented as extensions. You must comply to few rules:

• Be careful when constructing an extension. They have a lot of freedom to mess around with the map data (which might change in the future).
• When extension is initialized, it will create this.mapInstance and this.protectedProperties. First has the current instantiated map and second the private methods and properties for plugins to use
• Extensions init-method must return promise, to verify, when the plugin is ready
• All parameters extensions can receive are functions, that are bound in plugin context
• Must return an object containing:
  • init-method
  • 'PluginName' variable, which has same value as the exported library name

You can see the required format from e.g. hexagon extension.

The format for these rules as an example:

	export const sameNameThatIsExported = setupModuleFunction();

	function setupModuleFunction() {
    return {
  	  pluginName: "sameNameThatIsExported",
  	  init: function(map) {}
    }
	}

Templates

All UIThemes should extend the UIParent module and they have to implement methods listed in UIs private function validateUITheme.

You have to initialize the UI by calling UIInit method in flatworld.

Events

For events involved with the FlaTWorld map, you should check the current list from the mapEvents.js file. We try to keep it as up-to-date as possible.

Requirements and efficiency goals

Supported environments

• Desktop: Edge, Chrome, Firefox, Safari
• Mobile: Devices not listed, but basically anything that has browser, with these restrictions:
  • WebGL support: supported devices, webgl on your browser
  • Must support ES6 or if you use the transpiled version, then babel restrictions apply for ES6.

Aimed mapsize and efficiency

These are still subject to change (both raised and lowered). The map is planned to be big! In the way that I checked pretty much the biggest civilization community made maps and got over it. Since those maps do not seem to be sufficient for the plans I have for the engine! But these are still very realistic goals with the present setup.

• Maximum map size: 225 000 000 pixels (15k * 15k)
• Total object count on map: ~50k
• FPS in mobile min. 30. No FPS goal set for desktop as mobile defines the limits.

Credits

Testing:

• Thank you to browserstack for providing magnificient testing tools

Graphics:

• Realistic units from freecivs amplio set (http://download.gna.org/freeciv/contrib/tilesets/amplio/Readme).

Sounds:

• http://www.freesound.org/people/_hash_Hazard/sounds/127601/
• http://www.freesound.org/people/Artmasterrich/sounds/345458/

Contributors:

• https://github.com/dmitrysteblyuk (Pathfinding module)

flatworld's Issues

Fixed framerate

We might want to set possibility for a fixed framerate for the engine. So something in flatworld.js, where you could define fixed framerate for the whole map.

Ui module redesign

Review the UI module system (ui.js, default.js) and redesign as needed. The system is supposed to have the possibility to offer flexible way of making themes for the ui.

Setup example game

Creating a separate repository for the example game.

Reduce garbage collection

Especially in map movement and fog of war extensions, since those are the 2 most resource heavy parts. But elsewhere too.

The memory is not the issue in the game, but rather CPU and GPU efficiency. Doing garbage collection too often will slow down the javascript. There should be optimal efficiency for tasks. Remember to prioritize efficiency over memory-usage.

You can use stunts like object pooling (e.g. https://github.com/Nazariglez/obj-pool/blob/master/README.md), memoization etc. as you see most efficient.

Before you start optimizing, you should already take up performance results and compare them when doing the task and when the task is done. So we have better idea how much the efficiency has improved.

Fix memory leak

There is a small memory leak, that should be fixed. Just move and zoom the map around and you should see it

Finish minimap module

The engine has a minimap extension, but it is not working as nicely as it should. Refactor, polish and finish the module.

Smoother map scrolling

The map should be movable with smoother animation and something where we can be sure the white hidden areas outside viewport won't be shown and there is time to populate them. Now it is just simply moves the same way as the player drags the map.

I think we should implement the smoother mobile way of dragging, so a bit of acceleration and deceleration in the dragging and possibly in mobiles use velocity parameter too.

Optimize fog of war extension

It is still too slow and we need to make it faster.

Offline functionality

We should implement a possibility to play the game even when there is no internet connection. How we do this and what is part of the engine and what is handled outside of it, has to be thought.

We can use straight up service worker in this, as it should have enough support for us. We can basically store the data locally, e.g. to localstorage or somewhere else, if the http request to server does not succeed.

Remove UIs from core

UIs like default UI, shouldn't be in the core. These are very game-centric stuff and can't really be put to the core. It will only be really few games that could use them.

Fine tune map controls for dragging and pressing

There are couple of improvement to touch / mouse controls:

• After you have selected a unit and press / hold the mouse / finger down the unit is issue a move order. The order should get issued only after the pointer has been raised up. Now it happens immediately after certain timeout (so on mouseDown 1 secs after that, the order is executed).
  When a player holds mouse down (pointer / finger) over a unit, nothing should happen, but if the user moves the pointer, there will be map move event and if the user does not move pointer, but releases it (mouse up), then the order should be executed.
• Also we should make another test change and test this thoroughly. Maybe the map movement doesn't need to have a minimum movement set. So now map movement happens only, when the pointer has been moved X pixels. But we could let the player move the map even in 1 pixel movement, but also enable the clicking and pressing options, IF the map hasn't been moved more than Y pixels. This might provide a little bit better user experience as you could move the map as little as you wanted.

We should still playtest this, when the change is being done, to make sure it is change for the better.

Optimize mapmovement extension

Mapmovement is the most demanding part of the map currently, so we need to optimize it most.

Factories refactor

I think the hexa factory (and factories in general) should not be in the library (flatworld.factories.hexaFactory), but rather just separate part. The games can hold any kind of data structure and we can not use this specific factory, but only in few handful of cases.

Factories also create the render-tree and basically they do that mostly apart from flatworld engine. So we could have some more general factory that can handle the iteration and would get some basic configurations, but many of the functionalities would be outside of this basic factory.

mapMoved event reports wrong coordinates

In some cases the mapMoved event reports wrong coordinates, specifically, when the map is zoomed. It does not take all the calculations (toGlobal etc.) into account properly.

Endless map scroller

A feature that makes it possible to move the map like it was a planet. So you can scroll the map from one edge smoothly to the other edge. So that you can scroll the map indefinetly and also issue commands to it. Making the map seem like a round globe rather than restricted area of land.

The changes necesary to make this are not clear yet. If extension is enough or if we need other changes and if we can use the map movement plugin as it is, or not.

Pinch zooming moves the map

Zooming with touch controls (pinching) shouldn't move the map. But now when you pinch the screen and zoom in and out continuously, it moves the map also.

Zoom out zooms incorrectly with touch! It moves the map in arc to the right.

Resizing canvas / map not working

There is a bug with resizing the canvas, it simply doesn't resize. Something has obviously broke down or up.

Polish touch controls

We use hammer for touch controls currently, but it doesn't seem to work as well as it should currently. I do not know if the issue is some native timeout in mobiles or if the hammer library has some issue or possibly some configurations we use setting up hammer is wrong.

Now when you test it, when you select units by pressing them on mobile, it doesn't always succeed. When the touch is not totally accurate or too soft, it might fail. Or if you move your finger while pressing it might cause issues too.

I tested this with my 3 year old daughter, who got the issue quite fast :D.

Keyboard shortcut extension

We should make an extension, that handles pushing keyboard keys and doing certain action, like arrow keys moving the map. The keys should be changeable, so any key can be bound to any action.

Here is a PIXI plugin that might be usable out-of-the-box: https://github.com/Nazariglez/pixi-keyboard

Animations

You need to check and plan using animations in the engine. So involves at least:

• Animations when units are moved.
• Animations for more static content, like water, fog of war etc.

This issue can involve just testing and planning the usage of animations, We can make separate issues for the actual implementation, when we know where we need to make changes.

Refactor flatworld.js

We should expose less of the internals, like: GetMovableLayer and getZoomableLayer. Those really just let you use the actual PIXI containers that we use, but we could instead of them provide more specific methods to the users, like addLayer(type = 'movable' / 'zoomable') OR attachLayer (special version of addLayer, that attaches to existing layers, but doesn't create new one at the same time).
So we should force the user to use more specific functionalities, instead of exposing our internals.

Other controllers

Check can you use different controllers in the game, like gamepad, remote controllers, steam controller etc. Etc.

Loading bar

Setup loading bar for the engine

Issues when dragging after unit was selected

At least in samsung tablet, there is a noticable, but not fully repeatable bug. This bug happens, when you are choosing a unit and for some reason it fails the first time. You can click the unit again and then it chooses the unit. But after this, when you start to drag the map, the map jumps suddenly to incorrect coordinates and starts the drag there. So somehow the fail selection of unit, changes the starting coordinates for the map drag.

Practically when the map is moved in these error cases, it is centered to the selected unit and not the current coordinates

Engine should throw error when webgl not available

We should have a check for webgl support and throw error if it's not available

Use coordinate objects

Use PIXI.Point or rather some own object extended from PIXI.Point.

This is supposed to be used in all the places, so it is more standard, reliable and we can add information there that will help in debugging + possibly optimize.

Reviewing the code and updating the documentation

Basically just go through the code and review the API on bigger level. At the same time update documentation and pick up things that could be changed in the upcoming milestones, so the API is will be more consistent, usable and makes sense. Currently the documentation at least, is a bit out-of-date. The biggest benefit is So we can see that the game engine is heading to correct path and that the documentation can be used.

Some suggestions regarding documentation:
Adding #crossLink, @required, @default, @event and @optional to documentation, where needed

Changing volume

There should a possibility to change master volume for the game / engine.

Pathfinding plugin for hexagons

We need a pathfinding plugin for the hexagon example game. This plugin will determine if a unit can reach point B from point A.

The pathfinding needs to take obstacles into account. So as an example a car can not drive over a mountain, but drives 2 times faster on road, than compared to a human. The FlaTWorld works with coordinates, not hexagon indexes, so you have to take that into account. We most likely have to create some utility functions, e.g. a function that calculates nearby hexagon coordinates.

Also using this pathfinding function we can create a unit movement, attack etc. highlighter. So something that shows the player where the selected unit can move to. This might be something that needs to be considered while making the plugin. The actual highlighter will have it's own issue and either this plugin will be extended to hold that functionality or it goes somewhere else.

An extra tip / note regarding this is that, as I understand Scirras engine: Contruct 2 uses webworkers for managing the pathfinding. I think that should be investigated and learned upon.

How about using:
https://github.com/qiao/PathFinding.js/
http://gamedev.stackexchange.com/questions/44812/finding-shortest-path-on-a-hexagonal-grid

Rename staticlayer as zoomlayer

Staticlayer is not as descriptive and zoomlayer, since the layer only handles zooming really.

Moving everything under module system

We should bundle and transpile everything using some module bundler (like webpack). It would provide much better base for building different bundles, keeping everything orderly, using sourcemaps and transpiling. E.g. now sourcemaps do not work correctly for some reason and using a module bundler should give advantage using sourcemaps pretty naturally.

ES6 modules should be preferred as the module format as the project is ES6 based.

ES6 modules were the original format of the project actually, but for some reason the module formats just didn't work with the whole project. There was extensive amount of time used to it and eventually reverted to using global modules.

We would need a way to make different bundles, one with transpiling and another with native ES6. Also possibly different bundles with the core flatworld and another with all the extensions.

An example of the style I used at the beginning of the project (in early commits): https://github.com/Hachitus/warmapengine/blob/bd41edfd242d7aab8c1063103b24de43cfcd6447/public/components/map/core/Map.js

Fog of war moves in different frames than map

We need to make the fog of war move synchronized with the actual map movement. Now when map is moved you can see that fog of war moves separately from the underlaying map.

Area highlighting

E.g. When unit is selected it could show all the possible areas you can move / attack to