3dstreet.app

{
  "type": "object",
  "properties": {
    "entityId": {
      "type": "string",
      "description": "The ID of the managed street entity to update"
    },
    "operation": {
      "type": "string",
      "description": "Operation to perform (\"add-segment\", \"update-segment\", \"remove-segment\")"
    },
    "segmentIndex": {
      "type": "number",
      "description": "Index of the segment to update or remove (for update-segment and remove-segment operations)"
    },
    "segment": {
      "type": "object",
      "description": "Segment definition. For add-segment, \"type\" is required; other fields fall back to defaults if omitted. For update-segment, supply only the fields you want to change — omitted fields are left untouched.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Display name of the segment"
        },
        "type": {
          "type": "string",
          "description": "Type of segment. Valid values: \"drive-lane\", \"bike-lane\", \"sidewalk\", \"parking-lane\", \"divider\", \"grass\", \"rail\", \"bus-lane\", \"boundary\". \"boundary\" is SYNTHETIC flanking land use (buildings, waterfront, fences) for scenes without geographic context — it renders outside the travelled way at the street edge and auto-tiles models edge-to-edge (`variant` + `side`, no `generated` needed). Do not add boundaries when the scene has a location: the Google 3D Tiles already show the real surroundings and synthetic buildings would overlap them."
        },
        "surface": {
          "type": "string",
          "description": "Surface material (e.g., \"asphalt\", \"concrete\", \"grass\", \"sidewalk\", \"gravel\", \"sand\", \"planting-strip\", \"none\", \"solid\"). Optional for building segments — the variant supplies a sensible default. For hatched dividers use `generated.striping` with `striping: \"hatched\"` instead of a surface."
        },
        "color": {
          "type": "string",
          "description": "Hex color code (e.g., \"#ffffff\")"
        },
        "elevation": {
          "type": "number",
          "description": "Vertical offset in meters (0 = road level, 0.15 = curb/sidewalk height). Negative values are not supported."
        },
        "width": {
          "type": "number",
          "description": "Width in meters"
        },
        "direction": {
          "type": "string",
          "description": "Traffic direction (\"none\", \"inbound\", \"outbound\")"
        },
        "variant": {
          "type": "string",
          "description": "Variant preset for `type: \"boundary\"` segments. Valid values: \"brownstone\" (urban mixed-use SM3D blocks), \"suburban\" (detached single-family houses), \"arcade\" (arched street-front buildings), \"water\" (seawall), \"grass\" (fenced grass strip), \"parking\" (fenced parking lot), \"sp-mixeduse\" (StreetPlan mixed-use), \"sp-residential\" (StreetPlan single-family/townhouse), \"sp-big-box\" (StreetPlan big-box stores), \"custom\" (preserve existing settings). Setting variant on a boundary segment auto-fits the model array; do NOT pass `generated.clones` for boundaries unless you want full control. Only meaningful when `type: \"boundary\"`, and only for scenes without geographic context (see `type`)."
        },
        "side": {
          "type": "string",
          "description": "Side of the street the segment sits on. Required for `type: \"boundary\"` (controls placement outside the travelled way edge and which direction the models face). Valid values: \"left\", \"right\". Frame of reference is the street's own cross-section, not the camera: \"left\" is the inbound side and \"right\" the outbound side (right-hand-drive convention; swap for left-hand-drive countries). segments[0] sits at the first edge; getGeoContext reports the compass bearing of each edge.",
          "enum": [
            "left",
            "right"
          ]
        },
        "generated": {
          "type": "object",
          "description": "Optional generated content — omit to receive the type preset. Two different systems: `clones` places 3D models (vehicles, cyclists, trees, lamps, furniture — any listMixins id with generator \"clones\"); `stencil` paints flat road markings (arrows, sharrows, words like BUS ONLY — only ids with generator \"stencil\"). Never put a vehicle in `stencil` or a marking in `clones`.",
          "properties": {
            "clones": {
              "type": "array",
              "description": "Clones configuration for repeated 3D models",
              "items": {
                "type": "object",
                "properties": {
                  "mode": {
                    "type": "string",
                    "description": "Clone mode (\"random\", \"fixed\", \"single\")"
                  },
                  "modelsArray": {
                    "type": "string",
                    "description": "Comma-separated 3D model ids from listMixins (generator \"clones\"), e.g. \"sedan-rig, box-truck-rig\" or \"bus\". Unknown ids are rejected."
                  },
                  "spacing": {
                    "type": "number",
                    "description": "Distance between models in meters"
                  },
                  "count": {
                    "type": "number",
                    "description": "Number of models (for random mode)"
                  },
                  "facing": {
                    "type": "number",
                    "description": "Rotation in degrees"
                  },
                  "randomFacing": {
                    "type": "boolean",
                    "description": "Random rotation"
                  },
                  "cycleOffset": {
                    "type": "number",
                    "description": "Offset in the repeating pattern (0-1)"
                  }
                },
                "required": [
                  "mode",
                  "modelsArray",
                  "spacing"
                ]
              }
            },
            "stencil": {
              "type": "array",
              "description": "Stencil configuration for road markings",
              "items": {
                "type": "object",
                "properties": {
                  "modelsArray": {
                    "type": "string",
                    "description": "Comma-separated painted-marking ids (generator \"stencil\"), e.g. \"bike-arrow\", \"sharrow\", \"word-bus, word-only\". Unknown ids are rejected — use listMixins."
                  },
                  "spacing": {
                    "type": "number",
                    "description": "Distance between stencils"
                  },
                  "padding": {
                    "type": "number",
                    "description": "Edge padding"
                  },
                  "cycleOffset": {
                    "type": "number",
                    "description": "Pattern offset (0-1)"
                  },
                  "direction": {
                    "type": "string",
                    "description": "Stencil orientation"
                  },
                  "stencilHeight": {
                    "type": "number",
                    "description": "Height of stencil"
                  }
                },
                "required": [
                  "modelsArray",
                  "spacing"
                ]
              }
            },
            "pedestrians": {
              "type": "array",
              "description": "Pedestrian configuration",
              "items": {
                "type": "object",
                "properties": {
                  "density": {
                    "type": "string",
                    "description": "Pedestrian density (\"normal\", \"dense\")"
                  }
                },
                "required": [
                  "density"
                ]
              }
            },
            "striping": {
              "type": "array",
              "description": "Striping configuration for lane markings",
              "items": {
                "type": "object",
                "properties": {
                  "striping": {
                    "type": "string",
                    "description": "Stripe pattern type"
                  },
                  "side": {
                    "type": "string",
                    "description": "Side of segment (\"left\", \"right\")"
                  }
                },
                "required": [
                  "striping"
                ]
              }
            }
          }
        }
      },
      "required": []
    }
  },
  "required": [
    "entityId",
    "operation"
  ]
}