JSON Level Format

iterami/Docs.htm/common JSON Level Format
example.json is an example valid level file with every property.
Optional properties can be removed and order does not currently matter.
Must be valid JSON. This commented example below is not valid. iterami style formatting is optional.
{
  // Optional. Title to use when loaded.
  "title": "Example Level",

  // Optional. Ambient light values, between 0 and 1 inclusive.
  "ambient-blue": 1,
  "ambient-green": 1,
  "ambient-red": 1,

  // Optional. Maximum and minimum camera zoom.
  // When max is 0 then characters are forced into 1st person mode.
  "camera-zoom-max": 50,
  "camera-zoom-min": 0,

  // Optional. Clear color values, between 0 and 1 inclusive.
  "clearcolor-blue": 0,
  "clearcolor-green": 0,
  "clearcolor-red": 0,

  // Optional. Mouse cursor to display.
  "cursor": "pointer",

  // Optional. Directional light values, between 0 and 1 inclusive.
  "directional-blue": 1,
  "directional-green": 1,
  "directional-red": 1,

  // Optional. If directional lighting is enabled and its vector.
  "directional-state": true,
  "directional-vector": [0, 1, 0],

  // Optional. The maximum distance at which entities are drawn, or false for unlimited.
  "draw-range": 1000,

  // Optional. Fog density and if fog is enabled.
  "fog-density": 0.0001,
  "fog-state": false,

  // Optional. Gravity acceleration, maxiumum downward terminal velocity, and if fall damage occurs.
  "gravity-acceleration": -0.05,
  "gravity-damage": false,
  "gravity-max": -2,

  // Optional. Locked properties that are applied to all characters before collision detection.
  "lock": {
    // This example prevents any characters from having any y translation other than 10.
    "translate-y": 10
  },

  // Optional. Paths that characters can move along.
  "paths": {
    "example-path": {
      // Optional. What occurs when the end of the path is reached:
      //   exit = stop and exit path. Default.
      //   loop = loop from the beginning by moving towards 1st point.
      //   reverse = return back along path.
      //   warp = teleport back to 1st point.
      "end": "loop",

      // REQUIRED. Path waypoints in order.
      "points": [
        {
          // Optional. Speed multiplier when characters are approaching this point.
          "speed": 2,

          // Optional. Waypoint translation relative to "0, 0, 0".
          // Leave absent to use current translation of that axis.
          "translate-x": 0,
          "translate-y": 0,
          "translate-z": 0
        },
        {
          "translate-x": -10,
          "translate-z": -10
        },
        {
          "translate-x": 0,
          "translate-y": 0
        }
      ],

      // Optional. Speed multiplier applied to every character on this path.
      "speed": 2
    }
  },

  // Optional. If the level starts paused or not.
  "paused": false,

  // Optional. If this level will request the pointer remain locked to the canvas.
  "pointerlock": false,

  // Optional. Rotation of newly spawned character in degrees between 0 inclusive and 360 exclusive.
  "spawn-rotate-x": 45,
  "spawn-rotate-y": 0,
  "spawn-rotate-z": 0,

  // Optional. Translation of newly spawned character relative to "0, 0, 0".
  "spawn-translate-x": 0,
  "spawn-translate-y": 5,
  "spawn-translate-z": 5,

  // Optional. Minimum character Y translation before forced death and respawn.
  "y-min": -200,

  // Optional. Array of groups to create.
  // Do not include automatically created groups, such as "skybox".
  "groups": [
    "example-group-0",
    "example-group-1"
  ],

  // Optional. "characters" that is array of objects.
  // Set to false to create no new characters.
  "characters": [
    {
      // Optional. ID of character.
      "id": "_me",

      // Optional. If this character is moving forward regardless of key states.
      "automove": false,

      // Optional. If the camera is locked to the character's translation.
      "camera-lock": true,

      // Optional. Camera rotation. Can be overwritten by spawn rotation.
      "camera-rotate-x": 0,
      "camera-rotate-y": 0,
      "camera-rotate-z": 0,

      // Optional. Current camera zoom value.
      // When 0, camera is in 1st person mode.
      "camera-zoom": 20,

      // Optional. Amount that character rotation/translation should change by when the character is updated.
      // Player rotation changes affect the camera rotation as well.
      // Player translations are reset after each movement to allow stopping.
      "change-rotate-x": 0,
      "change-rotate-y": 0,
      "change-rotate-z": 0,
      "change-translate-x": 0,
      "change-translate-y": 0,
      "change-translate-z": 0,

      // Optional. The maximum distance that collision can occur.
      "collide-range-xz": 2,
      "collide-range-y": 3,

      // Optional. If the character collides into entities that have collision.
      "collides": true,

      // Optional. Which controls this character will use.
      "controls": "rpg",

      // Optional. Current character gravity multiplier.
      "gravity": 1,

      // Optional. "dy" set when the character jumps.
      "jump-height": 1,

      // Optional. Current character level.
      // -1 means character is just a camera and cannot gain xp.
      "level": 0,

      // Optional. Current character xp.
      "level-xp": 0,

      // Optional. Current and maximum life.
      "life": 1,
      "life-max": 1,

      // Optional. Remaining character lives.
      // -1 means character has unlimited lives.
      "lives": -1,

      // Optional. Locked properties that are applied this character before collision detection.
      "lock": {
        // This example does nothing because this example level locks character y translation to 10.
        "translate-y": 5
      },

      // Optional. Current assigned path or false, current path point target, and movement direction.
      // What occurs when the end of the path is reached:
      //   "" = use default end set by path.
      //   exit = stop and exit path. Default.
      //   loop = loop from the beginning by moving towards 1st point.
      //   reverse = return back along path.
      //   warp = teleport back to 1st point.
      "path-direction": 1,
      "path-end": "",
      "path-id": "",
      "path-point": 0,

      // Optional. The color of the character's reticle, or false is none should be visible.
      "reticle": "#fff",

      // Optional. Rotation of character in degrees between 0 inclusive and 360 exclusive.
      "rotate-x": 0,
      "rotate-y": 0,
      "rotate-z": 0,

      // Optional. Character movement speed.
      "speed": 1,

      // Optional. Translation of the character relative to "0, 0, 0".
      "translate-x": 0,
      "translate-y": 0,
      "translate-z": 0,

      // Optional. How many degrees this character turns at once.
      "turn-speed": 5,

      // Optional. Which vehicle this character is controlling, or false if not.
      "vehicle": false,

      // Optional. The stats of this character when used as a vehicle, or false if not possible.
      // If not false, then all properties within this object are required.
      "vehicle-stats": {
        // The ID of the character that is controlling this vehicle, or false if none.
        "character": false,

        // Current vehicle lock state:
        //   0: unlocked. Characters may freely enter and exit this vehicle.
        //   1: cannot enter. Characters may exit this vehicle but not enter it.
        //   2: cannot exit. Characters may enter this vehicle but not exit it.
        //   3: locked. Characters cannot enter or exit the vechile.
        "lock": 0,

        // Current vehicle movement speed.
        "speed": 0,

        // How quickly the vehicle accelerates when moving forward.
        "speed-acceleration": 0.1,

        // How quickly the vehicle decelerates when not moving forward.
        "speed-deceleration": -0.1,

        // The maximum speed that the vehicle can move.
        "speed-max": 1
      },

      // Optional. Array of entities that should be loaded and attached to the camera translation (without zoom).
      // Uses same format as level entities.
      "entities": []
    },

    // Example of character with entities.
    {
      "id": "world-static",
      "entities": [
        {
          // Optional. Entity ID.
          "id": "example-entity-0",

          // Optional. Alpha value for the vertices of this entity, between 0 and 1 inclusive.
          "alpha": 1,

          // Optional. ID of character or entity that this entity is attached to, or false if not attached.
          "attach-to": false,

          // Optional. Variable that contains what this entity is attached to.
          "attach-type": "entity_entities",

          // Optional. Translation offset relative to translation of the entity/character attached to.
          "attach-x": 0,
          "attach-y": -2,
          "attach-z": 0,

          // Optional. If the entity will rotate based on the location of the camera.
          "billboard": false,

          // Optional. Amount that entity rotation should change by when the entity is updated.
          "change-rotate-x": 0,
          "change-rotate-y": 0,
          "change-rotate-z": 0,

          // Optional. The maximum distance that collision can occur.
          "collide-range-xz": 2,
          "collide-range-y": 3,

          // Optional. If characters can collide with this entity.
          "collision": true,

          // Optional. If the entity should be drawn or not.
          "draw": true,

          // Optional. How the vertices should be drawn.
          "draw-mode": "TRIANGLE_FAN",

          // Optional. The maximum distance at which this specific entity is drawn,
          //   or false to use "draw-range" from "webgl_properties".
          "draw-range": 500,

          // Optional. The number of times this event should occur, or false for unlimited.
          "event-limit": false,

          // Optional. The range at which this event occurs, or false to disable.
          // If range is 0, only during collisions.
          "event-range": false,

          // Optional. Array of things todo when this event occurs.
          "event-todo": [
            {
              // Optional. The number of times this todo should occur.
              // Exclude this property for no limit.
              "limit": 1,

              // Optional. If this todo should add the value or overwrite the existing value.
              "set": false,

              // Optional. ID of the stat that will be modified if a character or entity is modified.
              "stat": "life",

              // Optional. ID of the character/entity or the name of the function/variable that will be affected.
              "todo": "example-entity-1",

              // Optional. What is being done during this todo, which includes:
              //   "entity" (default), "character", "function", and "variable".
              "type": "entity",

              // Optional. Value of change that occurs when this event occurs.
              "value": -100
            }
          ],

          // Optional. If this entity should have its vertices modified based upon particle properties.
          "particle": false,

          // Optional. If this entity can be selected via picking.
          // If true, an RGB array will be generated based upon the current entity_id_count and replace this property.
          "picking": false,

          // Optional. The size of each point when this entity uses the "POINTS" draw mode.
          "point-size": 500,

          // Optional. Rotation of entity in degrees between 0 inclusive and 360 exclusive.
          "rotate-x": 0,
          "rotate-y": 0,
          "rotate-z": 0,

          // Optional. ID of texture within core_images.
          "texture": "default.png",

          // Optional. Texture alignment.
          "texture-align": [
            1, 1,
            1, 0,
            0, 0,
            0, 1
          ],

          // Optional. Enable animated texture handling for this entity.
          "texture-animated": false,

          // Optional. How many times the texture will repeat.
          "texture-x": 1,
          "texture-y": 1,

          // Optional. Array of numbers between 0 and 1 inclusive, indicating the color of each vertex.
          // Each row is: red, green, blue, alpha
          // If only 4 numbers are included, then that color will be used for all vertices.
          // If not included then a random color will be selected.
          "vertex-colors": [
            1, 1, 1, 1,
            1, 0, 0, 1,
            0, 1, 0, 1,
            0, 0, 1, 1
          ],

          // REQUIRED. Array of numbers indicating the translation of each vertex,
          //   relative to the entity translation.
          // Each row is: x, y, z
          "vertices": [
            10, 0, 10,
            10, 0, -10,
            -10, 0, -10,
            -10, 0, 10
          ],

          // Optional. Array of groups this entity will be added to. Groups must exist.
          // This is where entities are added to the "skybox".
          "groups": [
            "example-group-0",
            "example-group-1"
          ]
        }
      ]
    }
  ],

  // Optional. Array of prefabs to create via various specific functions.
  "prefabs": [
    {
      // REQUIRED. Prefab type.
      "type": "webgl_primitive_cuboid",

      // REQUIRED. Properties of this prefab. Passed as args.
      "properties": {
        // Optional. Prefix added to each created entity ID.
        "prefix": "example-cuboid",

        // Optional. Properties applied to every face of this cuboid.
        "all": {},

        // Optional. Properties applied to the -z face.
        // Set "exclude" to true to prevent this face from being created.
        "back": {},

        // Optional. Properties applied to the -y face.
        // Set "exclude" to true to prevent this face from being created.
        "bottom": {},

        // Optional. Which character this cuboid should be attached to.
        "character": "world-static",

        // Optional. Properties applied to the +z face.
        // Set "exclude" to true to prevent this face from being created.
        "front": {},

        // Optional. Properties applied to the -x face.
        // Set "exclude" to true to prevent this face from being created.
        "left": {},

        // Optional. Properties applied to the +x face.
        // Set "exclude" to true to prevent this face from being created.
        "right": {},

        // Optional. Size of the cuboid.
        "size-x": 1,
        "size-y": 1,
        "size-z": 1,

        // Optional. Properties applied to the +y face.
        // Set "exclude" to true to prevent this face from being created.
        "top": {},

        // Optional. Translation of the center of the cuboid relative to the parent character translation.
        "translate-x": 0,
        "translate-y": 0,
        "translate-z": 0
      }
    }
  ],

  // Optional. Array of objects indicating which character or entity properties should be randomized.
  // Leave as [] to not randomize any properties.
  "randomized": [
    {
      // Optional. True if this affects character property, or false if this affects entity property.
      "character": false,

      // REQUIRED. Array of character or entity IDs, depending on the character property.
      "ids": [
        "example-entity-0"
      ],

      // REQUIRED. The range in which to choose a number, which is then added to the property.
      "max": 100,
      "min": -100,

      // REQUIRED. The property that will be modified.
      "property": "translate-z"
    }
  ]
}