Data API – Creating Custom Runtime


Overview

There are many reasons why you might be interested in creating a custom runtime for overlap2d exported data. It does not matter what engine it will be based on, what programming or scripting language will it use. As long as we all agree on the API for the data.

We are going to take a look at the example scene that o2d renders, and take a look in detail on the data structures.

Current Version

This version of API is for files saved in data format 0.0.9 (this has nothing to do with editor or runtime versions, this is just a data format version, for future compatibility issues) you can ignore this information for now.

Benchmark Render

Here is an example of how the data structure we are going to use as “benchmark” should properly render (ignoring rulers, guides and gray-background, actual background should be black)

On the scene you can see many images, some of them grouped together in case of windmill, many have transformations applied and color tint. You can find the entire exported project data that your runtime should work with – here. All assets are included. Take a look at the ambient light, the point light element, particle effects, label, z-indexes and render ordering. If your runtime is implemented correctly images should match.

benchmark2

 

Data Structures

Format

Data format for Overlap2D exported files as JSON. Overlap2D Data fiels end with “dt” extension and are two types. First type is project overall file called project.dt in that file we keep general data about project name, list of resolutions, and things like that. Other file types are scene files, which are located in scenes directory and can have any name, ending with “.dt”. This files contains scene data.

Project Data

Project Data contains some general data about your entire project and overlap2d configuration, such as:

  • pixelToWorld – coordinates in o2d are set in world units, this value specifies how many render-able pixels are in one world unit.
  • originalResolution – is a resolution entry to specify for what screen size the original textures were provided for.
    • name – name of resolution
    • width – width in pixels
    • height – height in pixels
    • base – integer, if 0 base side is width, if 1, base side is height. because aspect ration might be different, base side is the one that textures resizing was based on.
  • resolutions – array of supported resolutions for which overlap2d generated re-sized textures
  • scenes – array of scenes for this project (Data Structure containing only one element sceneName).
  • libraryItems – list of Composite Item type elements each of them describes a grouped item , that is not on the scene, but has a name and can be accessed via code to be placed on the scene dynamically

Scene

Scene is a part of project that contains a lot of elements. One project can have many Scenes, and it’s usually used as one Level of your game, or one area, or a ui page like menu. Here is the list of elements scene consists of.

  • sceneName – name of the scene
  • composite – this is the root element from which the rest of items will be described. It is described by Composite data structure.
  • lightSystemEnabled – tells runtime that this scene will have lights
  • ambient color – this is a float array with 4 elements to describe the color of ambient light in R G B A format. (0f – 1f, for each float)
  • physicsPropertiesVO – contains data about world physics of that scene. Uses Scene Physics data structure.
  • verticalGuides – array of float X coordinates for vertical guides (this are not render-able and are just for developer to use as they want)
  • horizontalGuides – array of float Y coordinates for horizontal guides (this are not render-able and are just for developer to use as they want)

That’s it. The rest of the scene is mainly described by the composite data structure and scene physics data structure.

The hierarchical data of scene in general goes as follows:

  • scene
    • some scene related general data
    • composite
      • layers
      • arrays of different item types, like images, animations and composite items
        • composite item
          • composite
            • …. goes back to composite recursively, as items can be nested

Scene Physics

Scene Physics contains very few data, mainly if a physics engine should be used or not and with what configuration.

  • enabled – Tells runtime if it should prepare a physics engine
  • gravityX – x component of gravity vector if any
  • gravityY – y component of gravity vector if any

 

Composite

Composite structure describes a list of elements that were grouped together, as well as knows a lot about item types.Besides that this data structure has layers list that it consist of. But doesnot know which element is located on which level.

Here is the detailed data:

Main Item Structure

All Item types used here, have a main item structure in common, and additionallt some other custom elements of their own.

Here is the main elements that ALL item types have in their data:

  • uniqueId – a unique number identifier given by editor this item
  • itemIdentifier – unique string identifier given by user to this item
  • tags – array of strings to represent tags that this item has – user generated data
  • customVars – contains Custom Variables data structure
    • this is a String which contains another JSON in it, with key values for custom variables
  • float x, float y – coordinates of the item
  • scaleX, scaleY – this is the scale values for transformation of this item
  • originX, originY – local coordinates of origin point for this item
  • rotation – degrees in 360 system, for the item rotation.
  • zIndex – the numberical representation of ordering in render pipeline
  • layerName – String name of layer this item is located on. It is corresponding to the layer name from the list specified in Composite data structure for which this item is a child
  • tint – RGBA float array of 4, to represent Color of this item, Color is used to be multiplied in shader with the texture colors, to tint it.
  • shaderName – String name of a shader that is used to render this item, this is usually null, but in some custom cases users provide their custom shaders.
  • shape – this is a Shape data structure which can be attached to any item, and is usually a polygon, circle or rectangle
    • polygons – this is an array of arrays, containing vector2 data in form of array of convex polygons each containing array of points in clockwise order.
  • physics – some items can have physics data structure on them to tell about their mass and other physics body configuration ( a self explanatory data you can see in example JSON)

Layer Structure

Layer Structure is a simple structure to describe one layer. One layer contains only 3 fields.

  • layerName – String name of layer
  • isLocked – this is boolean, if false – means all items on the layer do not listen to input events – clicks
  • isVisible – this is boolean, id false – means all items on the layer are not visible and not going to be rendered

Composite Item

Composite item is a Group of items placed on the screen at a specific coordinate with provided transformation and tint data.

Composite Item contains all the fields described in Main Item structure, but also has additional fields:

  • composite – Composite data structure to contain another set of item types and layers.
  • scissorX, scissorY, scissorWidth, scissorHeight – contains rectangular masking information on which part of this composite should be rendered – in local coordinates. this is usually not used.
  • width, height – composite item size.

Image Item

Image item is a simple image, sprite or a polygon sprite placed on the scene

Image Item contains all the fields described in Main Item structure, but also has additional fields:

  • imageName – string name of texture region to render this image
  • isRepeat – should this image be repeated if it’s size is bigger then region size or of it is rendered as polygon (if false, it should be stretched instead)
  • isPolygon – is this image rendered in a custom polygon shape rather then in a normal rectangular shape

Nine Patch Item

Nine Patch Image Item is a 9patch structure, meaning it knows which part of it should be stretched and which parts left as is, given width and height.

Nine Patch Image Item contains all the fields described in Main Item structure, but also has additional fields:

  • imageName – string name of texture region to render this image
  • width, height – this is size of the item

Label Item

Label Item is a simple text label, it has position, font, and text

Label Item contains all the fields described in Main Item structure, but also has additional fields:

  • text – String text of label
  • style – this is FONT NAME of the label (font is a TTF bundled with the exported assets) (you can also use bitmap fonts)
  • size – size of font in pixels.
  • align – integer describing align login in bit flags described here
  • width, height – size of the bounding box
  • multiline – boolean to allow or not for label to be multiline

Particle Effect Item

Particle effect is usually rendered based on the name it has that is attached to particle configuration file provided in exported assets. It knows things about it’s emmiters and textures. But in terms of data structure it’s very simple.

Particle Effect Item contains all the fields described in Main Item structure, but also has additional fields:

  • particleName – name of configuration file, that is in libGDX particle effect format.

Light Item

Lights can be either point lights or cone lights, and are only in effect if ambient light is darkened and light system is ON.

Light Item contains all the fields described in Main Item structure, but also has additional fields:

  • type  – POINT or CONE (enum repersented as String in JSON)
  • rays – number showing how detailed the light is – more rays – better
  • distance – the distance of light in world units (radius of influence)
  • directionDegree – this is basically the rotation of light or it’s direction, this only makes sense if it’s cone light
  • coneDegree – the inner angle of cone light
  • softnessLength – the value of “soft outer area of light
  • isStatic – light is not planned to be dynamically moved, so lights engine will optimize on that (if your engine has this type of option)
  • isXRay – if set to false, this light will not pass through other physics bodies on the scene.

Spine Animations

Spine Animations are animations created using http://esotericsoftware.com/  It contains all the fields described in Main Item structure, but also has additional fields:

  • animationName – name of entire animation, where it’s settings are found
  • currentAnimationName – each spine animation contains several sub animations, like run, jump e.g. this is the current playing animation name.

Sprite Animations

Sprite Animations are simple frame by frame animations, that are contained in a single texture atlas file.Sprite Animation region-frame names are usually numbered in frame order.

It contains all the fields described in Main Item structure, but also has additional fields:

  • animationName – texture atlas name of this animation
  • fps – frames per second value
  • frameRangeMap is an array of frame ranges that describe sub animations in a big animation frame list. For example 0 to 6 run, 7-10 jump
    • name – name of sub animation
    • startFrame – index of starting frame
    • endFrame – index of end frame
  • currentAnimation – name of current sub animation from frameRangeMap (i nothing then we animate all frames on sequental order)
  • playMode – integer (0 – NORMAL, REVERSED – 1, LOOP – 2, LOOP_REVERSED – 3, LOOP_PINGPONG – 4, LOOP_RANDOM – 5)

Spriter Animations

Spriter Animations are animations created using http://www.brashmonkey.com/  It contains all the fields described in Main Item structure, but also has additional fields:

  • animationName – name of the animation to be found in exported assets
  • entity – integer of entity as described in Spriter docs
  • animation  – integer of current sub animation as described inSpriter docs.

Example JSON

This section contains example JSON files, pretty printed and commented for readability, that were used to render the benchmark scene.

Project JSON

 

Scene JSON