manifest:
  id: free3d-plugin-api-manifest
  updated_at: 2026-03-13
  mode: strict
  owner: free3d.online
  purpose:
    - browser-approved plugin auth contract for external DCC tools
    - direct-file download contract for plugin routes backed by worker file inventory
    - source of truth for the 3ds Max plugin and future plugin families

sources_of_truth:
  api_docs_url: https://free3d.online/api-docs
  api_manifest_url: https://free3d.online/api/manifest.yaml
  plugin_manifest_url: https://free3d.online/assets/manifests/plugin-manifest.yaml
  plugin_guide_url: https://free3d.online/assets/manifests/plugin-guide.md
  worker_manifest_url: https://free3d.online/assets/manifests/worker-manifest.yaml

global_rules:
  https_only: true
  direct_pipeline_only: true
  fallbacks: forbidden
  prepare_stage: forbidden
  plugin_auth_separate_from_browser_session: true
  site_large_archive_caching: forbidden

auth:
  browser_approval_required: true
  plugin_token_headers:
    - Authorization: Bearer <plugin_token>
    - X-Plugin-Token: <plugin_token>
  default_scopes:
    - account:read
    - balance:read
    - entitlements:read
    - download:direct
    - scene:import

plugin_auth_flow:
  start:
    method: POST
    path: /api/apps/auth/start
    auth: public
  browser_authorize:
    method: GET
    path: /api/apps/auth/authorize/{session_id}
    auth: session_required
  confirm:
    method: POST
    path: /api/apps/auth/confirm
    auth: session_required
  poll:
    method: GET
    path: /api/apps/auth/poll/{session_id}
    auth: poll_token_required
  revoke:
    method: POST
    path: /api/apps/auth/revoke
    auth: plugin_token_required

plugin_account_routes:
  - path: /api/plugin/account
    method: GET
    auth: plugin_token_required
  - path: /api/plugin/account/balance
    method: GET
    auth: plugin_token_required
  - path: /api/plugin/account/entitlements
    method: GET
    auth: plugin_token_required

plugin_download_routes:
  discovery:
    path: /api/plugin/download/formats/{guid}
    method: GET
    auth: plugin_token_required
    selection_rules:
      - treat discovery payload as the only source of truth for downloadable scene files
      - when multiple topology folders exist, always pass the exact tuple returned by discovery: format + lod + relativePath
      - when variant is present, pass variant exactly as returned by discovery
    returns:
      - pricing
      - worker
      - previews
      - maxVariants
      - fbxVariants
      - import
  direct:
    path: /api/plugin/download/direct
    method: POST
    auth: plugin_token_required
    request:
      guid: string
      format: string
      lod: string
      variant: string|null
      relativePath: string|null
    request_rules:
      - guid and format are required
      - lod should match the selected discovery variant
      - relativePath should match the selected discovery variant
      - plugin must not guess topology folders or rebuild file paths heuristically
    response:
      downloadUrl: string
      fileName: string
      contentType: string
      relativePath: string
      chargedUsd: number
      balanceRemainingUsd: number
      supportFilesCount: number
      supportFiles:
        - relativePath: string
          url: string
          contentType: string
          kind: string
      import:
        dcc: 3dsmax
        mode: import | merge
        target: current_scene
        sceneFileUrl: string
        sceneRelativePath: string
        assetsRootUrl: string
        searchPaths: string[]
    response_rules:
      - downloadUrl is the final worker direct file URL
      - supportFiles must preserve product-relative paths
      - import.sceneRelativePath must equal the selected scene entry relativePath
      - import.assetsRootUrl should point at the selected topology folder root
      - import.searchPaths should include the selected topology root and texture subfolders when present

pricing_rules:
  first_unlock_per_model_usd: 1
  repeated_download_after_unlock_usd: 0
  unlimited_subscription_usd: 0

three_ds_max_plugin:
  public_assets:
    installer_script_url: https://free3d.online/assets/plugins/3dsmax/free3d_installer.ms
    rollout_script_url: https://free3d.online/assets/plugins/3dsmax/free3d_rollout.ms
    startup_script_url: https://free3d.online/assets/plugins/3dsmax/free3d_startup.ms
    update_feed_url: https://free3d.online/assets/plugins/3dsmax/update-feed.json
  import_rules:
    target_format: .fbx
    target_mode: additive_import
    direct_worker_files_required: true
    support_files_download_required: true
    textures_must_preserve_relative_paths: true
    topology_first_selection: true
    preferred_topology_order:
      - 100k
      - 10k
      - 1k
    preferred_format_order:
      - fbx
      - max
    animated_characters_should_prefer_variant: animated
    static_models_should_prefer_variant: static
    worker_prepare_fallback: forbidden

unity_plugin:
  public_assets:
    editor_script_url: https://free3d.online/assets/plugins/unity/free3d_online.cs
    update_feed_url: https://free3d.online/assets/plugins/unity/update-feed.json
  install_rules:
    mode: single_editor_script
    target_path: Assets/Editor/free3d_online.cs
    unity_versions:
      - "2021.3+"
      - "Unity 6"
  import_rules:
    target_format: .fbx
    target_mode: additive_import
    direct_worker_files_required: true
    support_files_download_required: true
    textures_must_preserve_relative_paths: true
    category_filters_supported: true
    pipeline_targets:
      - Built-in Standard
      - URP Lit
      - HDRP Lit
    preferred_topology_order:
      - 100k
      - 10k
      - 1k
