DSP: 0020 Title: Parcel Manifest Format Author: Esteban Ordano <esteban@decentraland.org> Status: Draft Type: Process Created: 2017-10-16
A manifest file contains the description of the contents of a land parcel. This description contains whatever models, scripts, or resources are required to provide the in-world experience that the parcel's owner intended to give.
This document describes the format of documents that are linked to from the LAND contract. This manifest file serves as the main source of truth for what should be displayed in a land parcel. In alternative implementations of the Decentrland client or in a compatible application, some aspects of this manifest might be ignored.
The design of this manifest file is heavily inspired by the `manifest.json` standard for HTML5. It contains concepts like pre-fetching, notes about security and consistency of the experience, and considerations about allowing access and soft constraints imposed over the contents.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 8174 when, and only when, they appear in all capitals, as shown here.
The manifest file format is JSON, following a particular [json-schema.org] containing the resources needed to display the scene. The goals of this file are to:
- Describe the scene: From this file, the Decentraland client (and alternative clients) must be able to give some basic information about the parcels. This information may include the name that the owner wants to give to the parcel, the coordinates and the Ethereum address that owns the parcel. As Decentraland is a social experience, it's good to have some means to contact the owner of the parcel.
- List and download assets: Allow the client to fetch all assets that are needed to render the scene. This includes 3d models, textures, sounds, and scripts.
- Support scenes comprising multiple parcels: Define a simple way to allow multiple parcels to show the same scene. This allows for better performance. The usability of editors also improves if they don't have to chunk scenes.
- Enable P2P Communications: Describe how to communicate with other users that are in the same location.
- Signal about the contents of the parcel: Allow land owners to specify to Decentraland clients the suitable audiences for this parcel. For example, to prevent mature content from being displayed to a younger audience. This is not going to be the only effort that Decentraland carries out to police content.
- Signal restrictions to client resources: allow a land owner to prevent users from using voice chat, flying, or restrict other features from being enabled in the parcel. Even if clients can be modified to not follow these policies, it might be desirable to provide control over the users' experience to the land owner.
{
"id": "https://github.com/decentraland/proposals/",
"$schema": "http://json-schema.org/draft-06/schema#",
"description": "Schema for a land parcel description",
"type": "object",
"required": [ "assets", "owner", "main", "display" ],
"properties": {
"assets": {
"type": "object",
"description": "Mapping a unique name to the assets that the scene needs. The values of this object can be prefetched by the Decentraland client before the user actually enters the parcel. Referencing one of these assets is needed for the \"main\" root property."
},
"owner": {
"type": "string",
"description": "Ethereum address of the owner of the parcel",
"pattern": "0x[0-9a-fA-F]{40}"
},
"contact": {
"type": "object",
"description": "Describe different ways of contacting the land owner",
"additionalProperties": true,
"properties": {
"name": {
"type": "string",
"description": "Given name for the parcel owner"
},
"email": "string",
"im": "string",
"url": "string"
}
},
"main" {
"type": "string",
"description": "Key in the `assets` root property that contains the a-frame/a-minus content of the main scene"
},
"scene": {
"type": "object",
"description": "Describes a scene, a set of parcels whose content is treated as the same entity. A list of parcels is listed, for which one of them is considered the \"base\" for positioning purposes.",
"properties": {
"base": { "$ref": "#coordinates" },
"parcels": {
"type": "array",
"items": { "$ref": "#coordinates" }
}
}
},
"communications": {
"type": "object",
"description": "Describes the protocol and URL to use to connect to other users in the same land",
"properties": {
"protocol": {
"type": "string",
"description": "A unique identifier of the protocol used to establish communications with other users"
},
"location": {
"type": "string",
"description": "URL or another means to find other peers"
}
}
},
"policy": {
"type": "object",
"description": "Allow the land owner to set up different hints on what the experience in his land should be"
},
"display": {
"type": "object",
"description": "Information related to how should this land be displayed apart from the normal rendering of the scene",
"properties": {
"title": {
"type": "string",
"description": "A name so other users can identify what the contents of this land should be"
},
"description": {
"type": "string",
"optional": true,
"description": "A description that will be shown on client's nav map when the scene is selected"
},
"favicon": {
"type": "string",
"optional": true,
"description": "Allow the land owner to set up a favicon to this land"
},
"navmapThumbnail": {
"type": "string",
"optional": true,
"description": "Thumbnail that will appear in navmap's toast window"
}
},
"additionalProperties": true
}
},
"definitions": {
"coordinates": {
"$id": "#coordinates",
"type": "string",
"description": "A (x, y) coordinate",
"pattern": "^-?[0-9]+,-?[0-9]+$"
}
}
}
Example of a land parcel description:
{
"assets": {
"scene": "/ipfs/QmZ1d5v83XSM7xbKDVAdFgS1PZmCzxuF5UtYrjMtFt6d6b",
"material_wood": "/ipfs/QmZ1d5v83XSM7xbKDVAdFgS1PZmCzxuF5UtYrjMtFt6d6b",
"material_iron": "/ipfs/QmZ1d5v83XSM7xbKDVAdFgS1PZmCzxuF5UtYrjMtFt6d6b",
"door_model": "/ipfs/QmZ1d5v83XSM7xbKDVAdFgS1PZmCzxuF5UtYrjMtFt6d6b",
"favicon_asset": "/ipfs/QmZ1d5v83XSM7xbKDVAdFgS1PZmCzxuF5UtYrjMtFt6d6b",
"background_music": "/ipfs/QmZ1d5v83XSM7xbKDVAdFgS1PZmCzxuF5UtYrjMtFt6d6b"
},
"owner": "0x0f5d2fb29fb7d3cfee444a200298f468908cc942",
"contact": {
"name": "John Doe",
"email": "john@doe.com",
"im": "https://chat.decentraland.org/direct/jdoe",
"url": "https://forum.decentraland.org/topic/2/hello-decentraland"
},
"main": "scene",
"scene": {
"base": "2,2",
"parcels": [
"1,2", "1,3", "1,4",
"2,2", "2,3", "2,4",
"3,2", "3,3", "3,4"
]
},
"communications": {
"type": "webrtc",
"signalling": "https://signalling-01.decentraland.org"
},
"policy": {
"contentRating": "E",
"fly": "yes",
"voiceEnabled": "yes",
"blacklist": ["0,0", "1,0", "1,1", "1,1"],
"teleportPosition": "0.5,1.4,23.12"
},
"tags": ["land", "decentraland", "parcel"],
"display": {
"title": "My Land",
"favicon": "favicon_asset",
"preview": {
"loading": "<a-scene><a-entity position='5 0 0' rotation='0 90 0'><a-box color='#ff00aa' position='-2 0 0' /><a-box color='#00aaff' position='2 0 0' /></a-entity></a-scene>"
"50m": "<a-scene><a-entity position='5 0 0' rotation='0 90 0'><a-box color='#ff00aa' position='-2 0 0' /><a-box color='#00aaff' position='2 0 0' /></a-entity></a-scene>"
}
}
}
This document is under the public domain.