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 camera zoom.
  // When 0, characters are forced into 1st person mode.
  "camera-zoom-max": 50,

  // 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. Fog density and if fog is enabled.
  "fog-density": 0.0001,
  "fog-state": false,

  // Optional. Gravity acceleration and maxiumum downward terminal velocity.
  "gravity-acceleration": -0.05,
  "gravity-max": -2,

  // 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.
      //   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. 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. 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 experience.
      "experience": 0,

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

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

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

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

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

      // 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.
      //   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.
      "vehicle-stats": false,

      // 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 number of times this event should occur, or false for unlimited.
          "event-limit": false,

          // Optional. Array of stats to modify when this event occurs.
          "event-modify": [
            {
              // Optional. If this event should set the stat to a specific number value,
              //   or add the value to the stat. Non-number values are always set.
              "set": false,

              // REQUIRED. ID of the stat that will be modified.
              "stat": "health",

              // Optional. ID of the character or entity that will be affected.
              "target": "example-entity-1",

              // Optional. Which variable is used during modification, such as
              //   "entity_entities" (default), "webgl_characters", or "webgl_properties".
              "type": "entity_entities",

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

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

          // Optional. ID required for event to occur, or false to allow all.
          "event-target-id": "_me",

          // Optional. Type required for this event to occur, either "character" or "entity".
          "event-target-type": "character",

          // Optional. String name of a function to run with "event-todo-args" passed,
          //   or string name of a variable that has its value changed to "event-todo-args",
          //   or false for no action.
          "event-todo": false,

          // Optional. Color used for picking identification during event handling
          //   or false for no picking.
          "pick-color": false,

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

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

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

          // Optional. How many times the texture will repeat.
          "texture-repeat-x": 1,
          "texture-repeat-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"
    }
  ]
}