improve outputs format

[blake-mealey]

The current format of the outputs command is not well thought-out. I would like to do some proper thinking & user research to see what a more optimal format is, and also to see if there are some more useful options we could add to the command (e.g. filtering the included resource types). We can also look into what a simple Roblox Lua SDK might look like to wrap around the outputs file.

[blake-mealey]

Adding to milestone v1.0.0 because the format should be stable before v1.0.0

[blake-mealey]

Current output format: a dictionary of resource IDs (in the format <type>_<id>) to outputs. The outputs are an odd format though because if they have no values they will just be the resource type as a string, or an object with the resource type as a key to the actual outputs.

Example:

{
  "experienceActivation_singleton": "experienceActivation",
  "experienceConfiguration_singleton": "experienceConfiguration",
  "experience_singleton": {
    "experience": {
      "assetId": 3296599132,
      "startPlaceId": 8667346609
    }
  },
  "placeConfiguration_start": "placeConfiguration",
  "placeFile_start": {
    "placeFile": {
      "version": 2
    }
  },
  "place_start": {
    "place": {
      "assetId": 8667346609
    }
  }
}

A better format might be to have a dictionary of resource type to a dictionary of ID to metadata objects. Each metadata object would optionally include an outputs dictionary if the resource had outputs. Example:

{
  "experienceActivation": {
    "singleton": {
      "outputs": null
    }
  },
  "experienceConfiguration": {
    "singleton": {
      "outputs": null
    }
  },
  "experience": {
    "singleton": {
      "outputs": {
        "assetId": 3296599132,
        "startPlaceId": 8667346609
      }
    }
  },
  "placeConfiguration": {
    "start": {
      "outputs": null
    }
  },
  "placeFile": {
    "start": {
      "outputs": {
        "version": 2
      }
    }
  },
  "place": {
    "start": {
      "outputs": {
        "assetId": 8667346609
      }
    }
  }
}

This would be a more expandable format since the metadata object could be added to later. For example, we could include a list of dependencies in the metadata object if it was useful.

[blake-mealey]

We should also consider this to be a public API of Mantle and it should be documented appropriately (new Outputs page in the docs)

[blake-mealey]

I also want to publish a Wally package that consumes the outputs to make it super easy to consume

[nomer888]

What would dev products look like in the new format? It's been a while since, but when I tried to consume Mantle outputs for the purposes of grabbing game pass/dev product IDs and relevant data, I experienced some friction in determining what was a game pass/dev product in a succinct way. I also remember wanting some data passthrough such as price instead of it just containing generated data.

My desired use case was to refer to products only by an internal string id and use Mantle outputs to get price, name, image, etc.

[blake-mealey]

Interesting. I was assuming that you would use the roblox APIs to get the product details given the ID, but since Mantle has all of that data available it would make sense to offer that to you as well.

The format would look something like this:

{
  "product": {
    "myProductLabel": {
      "outputs": {
        "assetId": 1221336160,
        "productId": "10502302"
      },
      "inputs": {
        "name": "My first product",
        "description": "With an amazing description",
        "price": 50
      }
    }
  },
  "productIcon": {
    "myProductLabel": {
      "outputs": {
        "assetId": 7989677340
      },
      "inputs": {
        "filePath": "developer-product-1.png"
        "fileHash": "2fe64fc151209486cc7afd0d28d7a4b44ef139d36f8e67190a4276bb0cfacc7e"
      }
    }
  }
}

[blake-mealey]

Something worth noting is that if you rely on that data instead of the data from Roblox's APIs, old servers will still show the old data. It might be best to lazy-load the data from Roblox's APIs and update this data when available.

[blake-mealey]

Given the recent request to include the environment in the outputs (see #182), I think the format should be updated to something like:

{
  "environment": {
    "label": "dev"
  },
  "resources": {
    // same as above
  }
}

Interestingly, this is starting to look a lot like the state file format...