traviso.js - v0.1.4
Options
All
  • Public
  • Public/Protected
  • All
Menu

Traviso Isometric JS Engine Build Status npm

traviso.js logo

JavaScript Isometric World Engine

Traviso is an open source JS engine that makes it easy to build isometric applications that run in a web browser. It aims maximum flexibility in order you to implement your own logic on top of it. Along with a set of optimised algorithms, Traviso is built on top of the awesomely fast pixi.js rendering engine.

If you’re interested, you can follow me on twitter (@axaq) or visit the website for more info.

Tutorials

Docs

You can find the documentation here

What is Ahead
  • More tutorials
  • Built-in multi-controllable support
  • Priority levels for moving objects
  • Built-in support for block-like tiles
  • Ground/terrain height
  • Fog of war

Contribute

Do you want to contribute? That's awesome. You can either message me through Twitter (@axaq) or use the Traviso.js blog.

How to build

After cloning the repo, install the build dependencies using npm:

$> npm install

Then build:

$> npm run build

This will create browser, CommonJS, and ES module versions of the library under dist folder. A minified version for browsers can be found at the same place.

Usage

 
// Here, we initialize the pixi application
var pixiRoot = new PIXI.Application({
    width: 800,
    height: 600,
    backgroundColor: 0xffffff,
});

// add the renderer view element to the DOM
document.body.appendChild(pixiRoot.view);

// engine-instance configuration object
var instanceConfig = {
    mapDataPath: 'mapData.json', // the path to the json file that defines map data, required
    assetsToLoad: ['../assets/spritesheet.json', '../assets/house.png'], // array of paths to the assets that are desired to be loaded by traviso, no need to use if assets are already loaded to PIXI cache, default null
};

// initialize traviso instance and add it to the stage
var engine = TRAVISO.getEngineInstance(instanceConfig);
pixiRoot.stage.addChild(engine);

You can now also use traviso as a npm module:

$> npm install traviso.js

import * as TRAVISO from 'traviso.js';

var engine = TRAVISO.getEngineInstance(instanceConfig);

This content is released under the (http://opensource.org/licenses/MIT) MIT License.

Index

Classes

Type aliases

Variables

Functions

Type aliases

TColumnRowPair

TColumnRowPair: { c: number; r: number }

Type declaration for column-row pair objects

Type declaration

  • c: number

    column index of the column-row pair

  • r: number

    row index of the column-row pair

TDirection

TDirection: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8

TDirections

TDirections: { E: 7; N: 5; NE: 6; NW: 4; O: 0; S: 1; SE: 8; SW: 2; W: 3 }

Type declaration for reserved direction IDs

Type declaration

  • Readonly E: 7

    east

  • Readonly N: 5

    north

  • Readonly NE: 6

    north-east

  • Readonly NW: 4

    north-west

  • Readonly O: 0

    idle, no direction

  • Readonly S: 1

    south

  • Readonly SE: 8

    south-east

  • Readonly SW: 2

    south-west

  • Readonly W: 3

    west

TEngineConfiguration

TEngineConfiguration: { assetsToLoad?: string[]; backgroundColor?: number; changeTransparencies?: boolean; checkPathOnEachTile?: boolean; dontAutoMoveToTile?: boolean; engineInstanceReadyCallback?: (engineInstance: EngineView) => unknown; followCharacter?: boolean; highlightPath?: boolean; highlightTargetTile?: boolean; initialPositionFrame?: TPositionFrame; initialZoomLevel?: number; instantCameraRelocation?: boolean; instantCameraZoom?: boolean; instantObjectRelocation?: boolean; isoAngle?: number; mapDataPath: string; mapDraggable?: boolean; maxScale?: number; maxZoom?: number; minScale?: number; minZoom?: number; numberOfZoomLevels?: number; objectReachedDestinationCallback?: (objectView: ObjectView) => unknown; objectSelectCallback?: (objectView: ObjectView) => unknown; objectUpdateCallback?: (objectView: ObjectView) => unknown; otherObjectsOnTheNextTileCallback?: (objectView: ObjectView, otherObjectViews: ObjectView[]) => unknown; pathFindingClosest?: boolean; pathFindingType?: number; tileHeight?: number; tileHighlightAnimated?: boolean; tileHighlightFillAlpha?: number; tileHighlightFillColor?: number; tileHighlightStrokeAlpha?: number; tileHighlightStrokeColor?: number; tileSelectCallback?: (r: number, c: number) => unknown; useMask?: boolean; zoomIncrement?: number }

Type declaration for engine-specific configuration.

Type declaration

  • Optional assetsToLoad?: string[]

    Array of paths to the assets that are desired to be loaded by traviso, no need to use if assets are already loaded to PIXI cache, default null

    default

    null

  • Optional backgroundColor?: number

    Background color, if defined the engine will create a solid colored background for the map, default null

    default

    null

  • Optional changeTransparencies?: boolean

    Make objects transparent when the controllable is behind them, default true

    default

    true

  • Optional checkPathOnEachTile?: boolean

    Looks for a path every time an object moves to a new tile (set to false if you don't have other moving objects on your map), default true

    default

    true

  • Optional dontAutoMoveToTile?: boolean

    When a tile selected don't move the controllable immediately but still call 'tileSelectCallback', default false

    default

    false

  • Optional engineInstanceReadyCallback?: (engineInstance: EngineView) => unknown

    Callback function that will be called once everything is loaded and engine instance is ready, default null

    default

    null

  • Optional followCharacter?: boolean

    defines if the camera will follow the current controllable or not, default true

    default

    true

  • Optional highlightPath?: boolean

    Highlight the path when the current controllable moves on the map, default true

    default

    true

  • Optional highlightTargetTile?: boolean

    Highlight the target tile when the current controllable moves on the map, default true

    default

    true

  • Optional initialPositionFrame?: TPositionFrame

    frame to position the engine, default { x : 0, y : 0, w : 800, h : 600 }

    default

    { x : 0, y : 0, w : 800, h : 600 }

  • Optional initialZoomLevel?: number

    initial zoom level of the map, default 0

    default

    0

  • Optional instantCameraRelocation?: boolean

    specifies whether the camera moves instantly or with a tween animation to the target location, default false

    default

    false

  • Optional instantCameraZoom?: boolean

    specifies whether to zoom instantly or with a tween animation, default false

    default

    false

  • Optional instantObjectRelocation?: boolean

    specifies whether the map-objects will be moved to target location instantly or with an animation, default false

    default

    false

  • Optional isoAngle?: number

    the angle between the top-left edge and the horizontal diagonal of a isometric quad, default 30

    default

    30

  • mapDataPath: string

    The path to the json file that defines map data, required

  • Optional mapDraggable?: boolean

    Enable dragging the map with touch-and-touchmove or mousedown-and-mousemove on the map, default true

    default

    true

  • Optional maxScale?: number

    maximum scale that the PIXI.Container for the map can get, default 1.5

    default

    1.5

  • Optional maxZoom?: number

    maximum zoom level, engine defined

  • Optional minScale?: number

    minimum scale that the PIXI.Container for the map can get, default 0.5

    default

    0.5

  • Optional minZoom?: number

    minimum zoom level, engine defined

  • Optional numberOfZoomLevels?: number

    used to calculate zoom increment, defined by user, default 5

    default

    5

  • Optional objectReachedDestinationCallback?: (objectView: ObjectView) => unknown

    Callback function that will be called when any moving object reaches its destination (call param will be the moving object itself), default null

    default

    null

  • Optional objectSelectCallback?: (objectView: ObjectView) => unknown

    Callback function that will be called when a tile with an interactive map-object on it is selected (call param will be the object selected), default null

    default

    null

  • Optional objectUpdateCallback?: (objectView: ObjectView) => unknown

    Callback function that will be called every time an objects direction or position changed, default null

    default

    null

  • Optional otherObjectsOnTheNextTileCallback?: (objectView: ObjectView, otherObjectViews: ObjectView[]) => unknown

    Callback function that will be called when any moving object is in move and there are other objects on the next tile, default null

    default

    null

  • Optional pathFindingClosest?: boolean

    whether to return the path to the closest node if the target is unreachable, default false

    default

    false

  • Optional pathFindingType?: number

    the type of path finding algorithm two use, default TRAVISO.PF_ALGORITHMS.ASTAR_ORTHOGONAL

    default

    TRAVISO.PF_ALGORITHMS.ASTAR_ORTHOGONAL

  • Optional tileHeight?: number

    height of a single isometric tile, default 74

    default

    74

  • Optional tileHighlightAnimated?: boolean

    Animate the tile highlights, default true

    default

    true

  • Optional tileHighlightFillAlpha?: number

    Alpha value for the tile highlight fill (this will be overridden if a highlight-image is defined), default 0.5

    default

    0.5

  • Optional tileHighlightFillColor?: number

    Color code for the tile highlight fill (this will be overridden if a highlight-image is defined), default 0x80d7ff

    default

    0x80d7ff

  • Optional tileHighlightStrokeAlpha?: number

    Alpha value for the tile highlight stroke (this will be overridden if a highlight-image is defined), default 1.0

    default

    1.0

  • Optional tileHighlightStrokeColor?: number

    Color code for the tile highlight stroke (this will be overridden if a highlight-image is defined), default 0xFFFFFF

    default

    0xFFFFFF

  • Optional tileSelectCallback?: (r: number, c: number) => unknown

    Callback function that will be called when a tile is selected (call params will be the row and column indexes of the tile selected), default null

    default

    null

      • (r: number, c: number): unknown

      • Parameters

        • r: number
        • c: number

        Returns unknown

  • Optional useMask?: boolean

    Creates a mask using the position frame defined by 'initialPositionFrame' property or the 'posFrame' parameter that is passed to 'repositionContent' method, default false

    default

    false

  • Optional zoomIncrement?: number

    zoom increment amount calculated by the engine according to user settings, default 0.5

    default

    0.5

TPathFindingAlgorithmID

TPathFindingAlgorithmID: 0 | 1

Type declaration for the IDs of available path finding algorithms

TPathFindingAlgorithms

TPathFindingAlgorithms: { ASTAR_DIAGONAL: TPathFindingAlgorithmID; ASTAR_ORTHOGONAL: TPathFindingAlgorithmID }

Type declaration for available path finding algorithms

Type declaration

TPositionFrame

TPositionFrame: { h: number; w: number; x: number; y: number }

Type declaration for position frame setting.

Type declaration

  • h: number

    height of the frame

  • w: number

    width of the frame

  • x: number

    x position of the frame

  • y: number

    y position of the frame

TPositionPair

TPositionPair: { x: number; y: number }

Type declaration for x-y position pair objects

Type declaration

  • x: number

    x position of the pair

  • y: number

    y position of the pair

TTravisoConfiguration

TTravisoConfiguration: { logEnabled: boolean }

Type declaration for global traviso configuration.

Type declaration

  • logEnabled: boolean

    Determines if TRAVISO can log helper text.

    default

    false

Variables

Const DIRECTIONS

DIRECTIONS: Readonly<TDirections> = ...

The direction IDs to be used in the engine

memberof

TRAVISO

for

TRAVISO

property
static
constant

Const PF_ALGORITHMS

PF_ALGORITHMS: Readonly<TPathFindingAlgorithms> = ...

The types of available path finding algorithms

memberof

TRAVISO

for

TRAVISO

property
static
constant

Const VERSION

VERSION: Readonly<string> = '$_VERSION'

String of the current TRAVISO version.

memberof

TRAVISO

for

TRAVISO

property
static
constant

Functions

Const dotProduct

enableDisableLogging

  • enableDisableLogging(enabled?: boolean): boolean

  • Determines if TRAVISO can log helper text.

    memberof

    TRAVISO

    for

    TRAVISO

    method
    function
    static

    Parameters

    • enabled: boolean = true

      enable logging or not, default true

    Returns boolean

    logging enabled or not

Const existy

  • existy(value: unknown): boolean

  • Checks if the value existy.

    memberof

    TRAVISO

    for

    TRAVISO

    method
    function
    static

    Parameters

    • value: unknown

      value to check

    Returns boolean

    if the value existy or not

Const getDist

Const getEngineInstance

  • Creates and returns an isometric engine instance with the provided configuration. Also initializes traviso global settings if it hasn't been already.

    memberof

    TRAVISO

    for

    TRAVISO

    method
    function
    static

    Parameters

    Returns EngineView

    A new instance of the isometric engine

Const getUnit

Const isInPolygon

  • Checks if the given point is the polygon defined by the vertices.

    memberof

    TRAVISO

    for

    TRAVISO

    method
    function
    static

    Parameters

    • gp: TPositionPair

      point to check

    • vertices: number[][]

      array containing the vertices of the polygon

    Returns boolean

    if the point is inside the polygon

Const mathMap

  • mathMap(v: number, min1: number, max1: number, min2: number, max2: number, noOutliers?: boolean): number

  • Linear maps a given number in a source range to a target range

    memberof

    TRAVISO

    for

    TRAVISO

    method
    function
    static

    Parameters

    • v: number

      value to map

    • min1: number

      minimum value of the source range

    • max1: number

      maximum value of the source range

    • min2: number

      minimum value of the target range

    • max2: number

      maximum value of the target range

    • noOutliers: boolean = false

      If the outlier values won't be processed, default false

    Returns number

    mapped value according to target range

skipHello

  • skipHello(): void

  • Skips the hello message of renderers that are created after this is run.

    memberof

    TRAVISO

    for

    TRAVISO

    function
    method
    static

    Returns void

trace

  • trace(s: string): void

  • Writes logs to the browser console

    memberof

    TRAVISO

    for

    TRAVISO

    method
    function
    static

    Parameters

    • s: string

      text to log

    Returns void