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 color red, green, and blue values between 0 and 1 inclusive.
  "ambient_color": [1, 1, 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 red, green, and blue values between 0 and 1 inclusive.
  "clear_color": [0, 0, 0],

  // Optional. Directional light color red, green, and blue values between 0 and 1 inclusive.
  "directional_color": [1, 1, 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. Distance at which entites start getting obscurbed by the "clear_color"
  //   until the end up being completely obscured. If "fog_end" is 0, no fog is computed.
  "fog_end": 100,
  "fog_start": 0,

  // 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 position other than 10.
    "position_y": 10
  },

  // Optional. Particle types to be created when the level is loaded.
  "particles": {
    "example_particle": {
      // Optional. False if the vertex position should just wrap upon reaching max/min,
      //   or true if the vertex position wrap should be randomized instead.
      "randomize": true,

      // Optional. Vertex movement speed upon each axis.
      "speed_x": 0,
      "speed_y": 0,
      "speed_z": 0,

      // Optional. Maximum and minimum vertex position values before the vertex is wrapped.
      "x_max": 100,
      "x_min": -100,
      "y_max": 100,
      "y_min": -100,
      "z_max": 100,
      "z_min": -100
    }
  },

  // Optional. Paths that characters can move along.
  "paths": {
    "example_path": {
      // Optional. If those that use this path should still collide with things.
      "collision": true,

      // 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 points in order.
      "points": [
        {
          // Optional. The distance from this point at which the
          //   character is considered to be at the point.
          "distance": 0,

          // Optional. Event handling when this point is reached.
          // More event info can be found in the example entity below.
          "event_limit": false,
          "event_todo": [],

          // Optional. Point position relative to "0, 0, 0".
          // Leave absent to use current position of that axis.
          "position_x": 0,
          "position_y": 0,
          "position_z": 0,

          // Optional. Forced rotation that is applied to all characters that reach this point.
          // Leave absent to maintain current rotation.
          "rotate_x": 0,
          "rotate_y": 90,
          "rotate_z": 0,

          // Optional. Speed multiplier when characters are approaching this point.
          "speed": 2
        },
        {
          // Optional. Paths can have unlimited points.
          "position_x": -10,
          "position_z": -10
        }
      ],

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

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

  // Optional. What amount of picking this level allows.
  // 0 = picking disabled, 1 = picking allowed when repo uses it, 2 = picking allowed and occurs every logic frame
  "picking": 2,

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

  // Optional. If this level should display the reticle in the center of the screen.
  // Very useful for aiding players with first person picking.
  "reticle": true,

  // Optional. Properties that are applied to all non-static characters when they spawn.
  "spawn": {
    "position_y": 5,
    "position_z": 5
  },

  // Optional. Custom texture URIs.
  "textures": {
    "gear.png": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAAyAQMAAAAk8RryAAAABlBMVEVCQkLb29sGyE
RuAAAAgklEQVQY04XQsQ2AQAgFUIyJlNfa3SImbqZ2rnUbuIIjWFJc/ILJb4xGmtcQ4CP/pfZqr9aFg1oKJ7W8uFAbi0iD1eY93CpcgVd
xZzf6RteRDJxhAmqoZ7Zb09t0tDXA3qCGtMi3z37O4Vzu4V7ewbt4J+9mDuZiTubmH/iXj7/91wWexXU3xpBXrwAAAABJRU5ErkJggg=="
  },

  // Optional. Minimum character Y position before forced death and respawn.
  "y_min": -200,

  // Optional. Array of groups to create, excluding automatically created groups such as "skybox".
  "groups": [
    "example_group_0",
    "example_group_1"
  ],

  // Optional. Array of character objects to use to create 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 position.
      "camera_lock": true,

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

      // Optional. The maximum distance that collision can occur.
      // Bottom is y-, top is y+, and xz is horizontal.
      "collide_bottom": 3,
      "collide_top": 3,
      "collide_xz": 2,

      // 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. "change_position_y" set when the character jumps.
      "jump_height": 1,

      // Optional. Optional object with values that NPC characters can use to control themselves.
      // Object property labels match core.js keybinds stored in localStorage.
      "keys": false,

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

      // Optional. Current character xp.
      "level_xp": 0,

      // Optional. Current and maximum life.
      "life": 1,
      "life_max": 1,

      // Optional. Remaining character lives, or -1 for 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 position to 10.
        "position_y": 5
      },

      // Optional. Either boolean false when no model is created,
      //   or an object of properties that are passed to the character model creator.
      //
      "model": {},

      // Optional. Optional object with values that NPC characters can use to control themselves.
      // Object property labels match core.js pointer properties stored in "globalThis.core_pointer".
      "pointer": false,

      // 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 current scale multiplier of this character that scales all attached entities.
      "scale_x": 1,
      "scale_y": 1,
      "scale_z": 1,

      // Optional. Properties that are applied to this character when it spawns.
      "spawn": {
        "camera_rotate_x": 45
      },

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

      // 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 backward and forward, or when slowly down.
        "speed_backward": -0.1,
        "speed_forward": 0.1,

        // The maximum speed that the vehicle can move backwards and forwards.
        "speed_max_backward": -0.5,
        "speed_max_forward": 1
      },

      // Optional. Array of entities that should be loaded and attached to the camera position (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. Position offset relative to position 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. 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 "webgl_properties.draw_range".
          "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.
          // If range is a number > 0, only within a certain radius.
          // If range is an array of 3 numbers, only within a cuboid of that size.
          "event_range": false,

          // Optional. Array of things todo when this event occurs.
          // If a property === "_self" then the event parent ID is used.
          // If a property === "_target" then the event target ID is used.
          "event_todo": [
            {
              // Optional. The number of times this todo should occur.
              // Exclude this property for no limit.
              "limit": 1,

              // Optional. How much to randomly add to "value".
              "random_max": 0,
              "random_min": 0,

              // 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 "light_range" is greater than 0, emit a light of a certain color within that range.
          "light_color": [1, 1, 1],
          "light_range": 0,

          // 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. Maximum range between the entity and character within which picking can occur.
          // If 0, picking range is unlimited.
          "picking_range": 0,

          // Optional. If the xyz position on the picked entity should also be calculated and returned.
          "picking_xyz": false,

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

          // Optional. Rotation of entity in degrees between 0 inclusive and 360 exclusive.
          "rotate_x": 0,
          "rotate_y": 0,
          "rotate_z": 0,

          // Optional. Scale of this entity, with 1 being default.
          "scale_x": 1,
          "scale_y": 1,
          "scale_z": 1,

          // Optional. ID of texture within core_images.
          // If the texture is not animated, only include the image name.
          // If the texture is animated, include movement in the texture ID separated by commas,
          //   such as "gear.png,0.1,0.2", with the 1st number being X movement and the 2nd being Y movement.
          "texture": "gear.png",

          // Optional. Texture alignment string.
          "texture_align": "11010010",

          // 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 position of each vertex,
          //   relative to the entity position.
          // 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. Position of the center of the cuboid relative to the parent character position.
        "position_x": 0,
        "position_y": 0,
        "position_z": 0,

        // 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. Array of objects indicating which character or entity properties should be randomized.
  "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": "position_z"
    }
  ]
}