flatworld.Flatworld Class
Main class for the engine
Initializes the whole structure and plugins and is used as primary API for all operations. This class is e.g. passed to every plugin that get initialized with their init-method.
You use the class by instantiating it (new) and then finishing initialization with init-method. Please see examples below.
The biggest part of creating the map, is the data structure. There is a clear data structure that you can see from the tests/data-folder, but the factory is responsible for creating the objects, so you can use your own factory implementation. So to understand more, please see e.g. flatworld.factories.hexaFactory.
The map consists of layer on top of each other. The example is best understood when thinking typical war strategy game. The structure is this:
- StaticLayer: Handles things like scaling / zooming the map
- MovableLayer: Obviously handles movement of the map. Also is a good place to get map coordinates. Since getting global coordinates won't help you much, half of the time.
- Different layers: like units, terrain, fog of war, UIs etc. Can also contains special layers like dynamically changed UIlayers.
- possible subcontainers (used for optimized object selection and map movement). Can also contains special layers like dynamically changed UIlayers.
- Individual objects, like units, terrains, cities etc...
Plugins can be added with activatePlugins-method by sending them to the class. Plugins must always implement init-method, which receives Map instance. Plugins are not yet restricted what they can do and can add functionality without touching map or can modify objects or their prototypes through access to Map instance.
Constructor
flatworld.Flatworld
-
mapCanvas -
[props] -
[trackFPSCB]
Parameters:
-
mapCanvasHTMLElementHTML element which will be container for the created canvas element.
-
[props]Object optionalExtra properties
-
boundsObjectBounds of the viewport
-
widthIntegerBound width -
heightIntegerBound height
-
-
[mapSize]Object optionalThe total mapSize
-
xIntegerx-axis -
yIntegery-axis
-
-
rendererOptionsObjectRenderer options passed to PIXI.autoDetectRenderer
-
subcontainersObjectSubcontainers size in pixels. If given, will activate subcontainers. If not given or false, subcontainers are not used.
-
widthIntegerSubcontainer width -
heightIntegerSubcontainer height
-
-
-
[trackFPSCB]FPSCallback optionalCallback function for tracking FPS in renderer. So this is used for debugging and optimizing.
Returns:
New Map instance
Example:
var map = new Map(divContainer, mapOptions );
promises = map.init( gameData.pluginsToActivate, mapData.startPoint );
A note on the UI part of the map. The UI is not the primary UI interface for the map, but instead it is the UI that is used when interacting with the map and objects in it. So e.g. when user selects a unit on the map. How that unit is highlighted as selected and what kind of possible info-box we show to the user regarding that object, movement of units etc.
Item Index
Methods
- _defaultTick
- _getLayersWithAttributes
- _getSubcontainersUnderPoint
- _retrieveObjects
- activateFogOfWar
- activatePlugin
- addLayer
- addUIObject
- createSpecialLayer
- drawOnNextTick
- drawOnNextTick
- getAllObjects
- getMinimapLayer
- getMovableLayer
- getObjectsUnderArea
- getPrimaryLayers
- getRenderer
- getStaticLayer
- getSubcontainerConfigs
- getViewportArea
- getZoom
- getZoomLayer
- init
- initMinimap
- moveMap
- pluginsArray
- removeLayer
- removeUIObject
- setPrototype
- setZoom
- toggleFullScreen
- toggleFullsize
- usesSubcontainers
- whenReady
- zoomIn
- zoomOut
Methods
_defaultTick
()
private
This handles the default drawing of the map, so that map always updates when drawOnNextTick === true. This tick callback is always set and should not be removed or overruled
_getLayersWithAttributes
-
attribute -
value
This returns layers by filtering them based on certain attribute. Can be used with more higher order filtering
Parameters:
-
attributeString -
value
Returns:
the current map instance
_getSubcontainersUnderPoint
-
globalCoords -
options
Get subcontainers under certain point or rectangle
Parameters:
-
globalCoordstype -
optionsObjectOptional options.
Returns:
All subcontainers that matched the critea
_retrieveObjects
-
allCoords -
[{}.type] -
[{}.subcontainers]
Retrieves the objects from ObjectManager, with the given parameters. Mostly helper functionality for getObjectsUnderArea
Parameters:
Returns:
Found objects
activateFogOfWar
()
Plugin will overwrite create this method. Method for actually activating fog of war.
activatePlugin
-
plugin
Activate plugin for the map. Plugins need .pluginName property and .init-method. Plugins init-method activates the plugins and we call them in Map. Plugins init-metho receivse this (Map instance) as their only parameter.
Parameters:
-
pluginObjectPlugin module
Throws:
Throws a general error if there is an issue activating the plugin
addLayer
()
MapLayer
All parameters are passed to ParentLayerConstructor (normally constructor of MapLayer).
Returns:
created MapLayer instance
addUIObject
-
layer -
object
Add an UI object to the wanted layer.
Parameters:
-
layerIntegerType of the layer. this.layerTypes.STATIC.id or layerTypes.MOVABLE.id.
-
objectObject | ArrayThe object to be attached as UI object.
createSpecialLayer
-
name -
options
Create a special layer, that can holds e.g. UI effects in it.
Parameters:
Returns:
The created UI layer
drawOnNextTick
()
The correct way to update / redraw the map. Check happens at every tick and thus in every frame.
drawOnNextTick
()
The correct way to update / redraw the map. Check happens at every tick and thus in every frame.
getAllObjects
-
[{}.filters]
Get all objects on the map, from layers and subcontainers.
Parameters:
-
[{}.filters]MapDataManipulator optionalThe mapDataManipulator instance, that you use for filtering.
Returns:
Array of found objects
getMinimapLayer
()
Return minimap layer. Holds minimap, if used in the game.
getMovableLayer
()
MapLayer | PIXI.Container | PIXI.ParticleContainer
Returns movable layer. This layer is the one that moves when the player moves the map. So this is used for things that are relative to the current map position the player is seeing. This can be used e.g. when you want to display some objects on the map or UI elements, like effects that happen on certain point on the map.
Returns:
getObjectsUnderArea
-
globalCoords -
options
Gets object under specific map coordinates. Using subcontainers if they exist, other methods if not. If you provide type parameter, the method returns only object types that match it.
NOTE! At the moment filters only support layers! You can not give filters object: object and expect them to be filtered. It will filter only layers (object: layer)!
Parameters:
Returns:
Array of object found on the map.
getPrimaryLayers
-
[{}.filters]
This returns the normal parent layers that we mostly use for manipulation everything. MovableLayer and staticLayer are built-in layers designed to provide the basic functionalities like zooming and moving the map. These layers provide everything that extends the map more.
Parameters:
-
[{}.filters]MapDataManipulator optionalThe mapDataManipulator instance, that you use for filtering.
Returns:
Basically anything in the map that is used as a layer (not really counting subcontainers).
getRenderer
()
PIXI.Renderer
Returns the PIXI renderer. Don't use this unless you must. For more advanced or PIXI specific cases.
Returns:
getStaticLayer
()
Return static layer. The static layer is the topmost of all layers. It handles zooming and other non-movable operations.
getSubcontainerConfigs
()
Object
Returns current subcontainers configurations (like subcontainers size).
Returns:
getViewportArea
-
isLocal
Get the size of the area that is shown to the player. More or less the area of the browser window.
Parameters:
-
isLocalBooleanDo we want to use Map coordinates or global / canvas coordinates. Default = false
Returns:
} x- and y-coordinates and the width and height of the viewport
getZoom
()
MapLayer | PIXI.Container | PIXI.ParticleContainer
Get map zoom. 1 = no zoom. <1 zoom out, >1 zoom in.
Returns:
getZoomLayer
()
MapLayer | PIXI.Container | PIXI.ParticleContainer
This returns the layer that is responsible for map zoom
Returns:
init
-
plugins -
coord -
tickCB -
options
This initializes the map and makes everything appear on the map and actually work. Also initializes the given plugins since normally the plugins have to be activated before the map is shown.
Parameters:
-
pluginsString[] | Object[]Plugins to be activated for the map. Normally you should give the plugins here instead of separately passing them to activatePlugins method. You can provide the module strings or module objects.
-
coordObjectStarting coordinates for the map.
-
xIntegerX coordinate.
-
yIntegerY coordinate.
-
-
tickCBFunctioncallback function for tick. Tick callback is initiated in every frame. So map draws happen during ticks.
-
optionsObjectExtra options.
-
fullsizeBooleanDo we set fullsize canvas or not at the beginning. Default: true
-
Returns:
Returns an array of Promises. If this is empty / zero. Then there is nothing to wait for, if it contains promises, you have to wait for them to finish for the plugins to work and map be ready.
initMinimap
()
Plugin will overwrite create this method. Method for actually activating minimap.
moveMap
-
coord -
absolute
Moves the map the amount of given x and y pixels. Note that this is not the destination coordinate, but the amount of movement that the map should move. Internally it moves the movableLayer, taking into account necessary properties (like scale). Draws map after movement.
Parameters:
-
coordObjectThe amount of x and y coordinates we want the map to move. I.e. { x: 5, y: 0 }. With this we want the map to move horizontally 5 pixels and vertically stay at the same position.
-
xIntegerX coordinate
-
yIntegerY coordinate
-
-
absoluteIntegerIf the given coordinates are not relative, like move map 1 pixel, but instead absolute, like move map to coordinates { x: 1, y: 2 }. Defaults to false (relative).
pluginsArray
-
pluginsArray
Activate all plugins for the map. Iterates through the given plugins we wish to activate and does the actual work in activatePlugin- method.
Parameters:
-
pluginsArrayObject[]Array that consists the plugin modules to be activated
Returns:
Promise. If string are provided resolved those with System.import, otherwise resolves immediately.
removeLayer
-
layer
Remove a primary layer from the map
Parameters:
-
layerMapLayer | PIXI.Container | PIXI.ParticleContainerThe layer object to be removed
removeUIObject
-
layer -
objectName
Remove an UI object to the wanted layer.
Parameters:
-
layerIntegerType of the layer. layerTypes.STATIC of layerTypes.MOVABLE.
-
objectNameStringThe object to be attached as UI object.
setPrototype
-
property -
value
Setting new prototype methods for the Map instance
Parameters:
-
propertyStringThe property you want to set
-
valueValue for the property
setZoom
-
scale
Set map zoom. 1 = no zoom. <1 zoom out, >1 zoom in.
Parameters:
-
scaleNumberThe amount of zoom you want to set
Returns:
The amount of zoom applied
toggleFullScreen
()
Toggles fullscreen mode. Defined by the baseEventlisteners-module (core modules plugin)
toggleFullsize
()
Resize the canvas to fill the whole browser content area. Defined by the baseEventlisteners-module (core modules plugin)
usesSubcontainers
()
Boolean
Just a convenience function (for usability and readability), for checking if the map uses subcontainers.
Returns:
whenReady
()
Promise
Returns a promise that resolves after the map is fully initialized
Returns:
Promise that holds all the individual plugin loading promises
zoomIn
()
This is abstract method and needs to be implemented with a plugin. Core module has an implementation for this and if you don't implement your own, I suggest you use it.
zoomOut
()
This is abstract method and needs to be implemented with a plugin. Core module has an implementation for this and if you don't implement your own, I suggest you use it.
Attributes
canvas
HTMLElement
required
canvas element that was generated and is being used by this new generated Map instance.
Fires event canvasChange
Fires when the value for the configuration attribute canvas is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added:
canvas
HTMLElement
required
canvas element that was generated and is being used by this new generated Map instance.
Fires event canvasChange
Fires when the value for the configuration attribute canvas is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added:
currentlySelectedObjects
Array
The object or objects that are currently selected for details and actions / orders. This gets set by other modules, like plugins.
Fires event currentlySelectedObjectsChange
Fires when the value for the configuration attribute currentlySelectedObjects is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added:
isTouch
Boolean
Set variable showing if the device supports touch or not.
Fires event isTouchChange
Fires when the value for the configuration attribute isTouch is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added:
layerTypes
Object
Layer types. Can be extended, but the already defined types are supposed to be constants and not to be changed.
Fires event layerTypesChange
Fires when the value for the configuration attribute layerTypes is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added:
mapSize
X: Number, y: Number
optional
Fires event mapSizeChange
Fires when the value for the configuration attribute mapSize is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added:
objectManager
ObjectManager
ObjectManager instance. Responsible for retrieving the objects from the map, on desired occasions. Like when the player clicks the map to select some object. This uses subcontainers when present.
Fires event objectManagerChange
Fires when the value for the configuration attribute objectManager is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added:
plugins
Set
list of plugins that the map uses and are initialized
Fires event pluginsChange
Fires when the value for the configuration attribute plugins is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added:
subcontainersConfig
Width: Integer, height: Int, maxDetectionOffset: Int
Subcontainers size that we want to generate, when layers use subcontainers.
Fires event subcontainersConfigChange
Fires when the value for the configuration attribute subcontainersConfig is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added:
trackFPSCB
Function
Callback function that gets the current FPS on the map and shows it in DOM
Fires event trackFPSCBChange
Fires when the value for the configuration attribute trackFPSCB is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added:
VERSION
SEMVER http://semver.org/
Self explanatory
Fires event VERSIONChange
Fires when the value for the configuration attribute VERSION is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added: