@dcl/builder-client
v6.0.1
Published
Builder server client
Downloads
394
Readme
Builder client
Using the Builder client
Using the builder client requires an AuthIdentity
to be created.
An AuthIdentity
is an object containing:
- An ephemeral identity, that is, an address and a private and public key generated randomly.
- An expiration date, used to expire any signed messages.
- An AuthChain, which is a list of authorization objects used to validate the signed messages.
The library provides a function createIdentity
that uses a Signer
from ethers
, but any other implementation can be created to craft such identity.
Creating the identity using the createIdentity
can be easily done in NodeJS by instantiating an ethers wallet using a private key:
const wallet = new ethers.Wallet('aPrivateKey')
const identity = await createIdentity(wallet, 1000)
or by using a JsonRpcProvider:
const provider = new ethers.providers.JsonRpcProvider()
To use the BuilderClient
, just instantiate the class with the builder-server url, the identity and the signer's address:
const client = new BuilderClient('https://httpdump.io', identity, address)
Using the Item Factory
Building items is done by using the ItemFactory
. The ItemFactory
is a class that can be instantiated with an older item or in blank.
Initializing a new item
If the factory was instantiated without an item, a new item can be created by using the newItem
method that creates a basic item to later work on it.
// Initializes the factory
const itemFactory = new ItemFactory()
// Creates a new item
itemFactory.newItem({
id: 'anId'
name: 'aName',
rarity: Rarity.COMMON,
category: WearableCategory.EYEBROWS,
collection_id: 'aCollectionId',
description: 'aDescription'
})
Editing an item
An ItemFactory
instantiated with an older item or with a new item can modify every aspect of the item. This is done by using the factory methods:
const itemFactory = new ItemFactory(oldItem)
itemFactory
.withId('anId')
.withName('aName')
.withRarity(Rarity.COMMON)
.withCategory(WearableCategory.EYEBROWS)
.withCollectionId('aCollectionId')
.withDescription('aDescription')
Adding or removing representations to an item
Representations can be added using the withRepresentation
: or withoutRepresentation
methods.
const itemFactory = new ItemFactory(oldItem)
itemFactory.withRepresentation(
WearableBodyShape.MALE,
'a_model.glb',
{ 'a_model.glb': modelContent, [THUMBNAIL_PATH]: thumbnailContent },
{
triangles: 106,
materials: 107,
meshes: 108,
bodies: 109,
entities: 110,
textures: 111
}
)
or deleted from the item using the withoutRepresentation
method:
const itemFactory = new ItemFactory(oldItem)
itemFactory.withoutRepresentation(BodyShapeType.FEMALE)
When defining the representation's content, the contents
field must contain the model and the thumbnail.
The library's user is responsible for providing a thumbnail. The thumbnail can be also be changed / set using the withThumbnail
method.
Loading items from files
This library provides a function loadItem
that can be used to load an item from a file. The function accepts four types of files:
- A zip file that contains only the item's contents.
- A model file, that contains only the item's model.
- A zip file that contains the item's contents and the wearable config file
wearable.json
describing the item's information. - A zip file that contains the item's contents, the builder config file
builder.json
describing information required for the builder platform and optionally the wearable config filewearable.json
describing the item's information.
For the 1st and 2nd cases, the function will create a LoadedItem
object that will contain the item's contents as RawContent
,
that is content ready to be used with the ItemFactory, and the property mainModel
that defines the main model file of the contents.
After loading the file, the LoadedItem
object can be used to create an item using the ItemFactory
:
// Loads a ZIP file without the wearable config file or a model file
const loadedItem = await loadItem('model-without-wearable-config.zip')
const itemFactory = new ItemFactory()
itemFactory.newItem({
id: 'anId'
name: 'aName',
rarity: Rarity.COMMON,
category: WearableCategory.EYEBROWS,
collection_id: 'aCollectionId',
description: 'aDescription'
}).withRepresentation(
WearableBodyShape.MALE,
// Uses the main model from the loadedItem variable
loadedItem.mainModel,
// Uses the content from the loadedItem variable
loadedItem.content,
{
triangles: 106,
materials: 107,
meshes: 108,
bodies: 109,
entities: 110,
textures: 111
}
)
For the 3rd case, the function will create a LoadedItem
object that will contain the item's contents as RawContent
, and it will also contain the wearable property
that contains the information of the wearable config file.
A wearable config file is a JSON file that contains the item's information and it has the following shape:
{
// The item's URN (optional)
"id": "urn:decentraland:matic:collections-thirdparty:third-party-id:collection-id:item-id",
// The item's name
"name": "test",
// The item's Rarity (optional for third party items)
"rarity": "common",
// The item's description (optional)
"description": "a description",
"data": {
// The item's WearableCategory
"category": "eyebrows",
// The HideableWearableCategories that the item hides (optional)
"hides": [],
// The HideableWearableCategories that the item replaces (optional)
"replaces": [],
// The item's tags (optional)
"tags": ["special", "new", "eyebrows"],
// The item's representations (the item must have more than one representation)
"representations": [
{
// The body shapes that the representation will be used for (urn:decentraland:off-chain:base-avatars:BaseMale/urn:decentraland:off-chain:base-avatars:BaseFemale)
// If multiple body shapes are provided, a representation will be generated with both of them
"bodyShapes": ["urn:decentraland:off-chain:base-avatars:BaseMale"],
// The file path (path inside of the zipped file) to the main model of the representation
"mainFile": "aModelFile.glb",
// An array of file paths (paths inside the zipped file) to the files that the representation contains
"contents": ["aModelFile.glb", "aTextureFile.png", "thumbnail.png"],
// The representation's WearableCategories hides overrides
"overrideHides": [],
// The representation's WearableCategories replaces overrides
"overrideReplaces": []
}
],
// When true, the vrm export feature will be blocked if this wearable is equipped
"blockVrmExport": false
}
}
After loading the file zip file that contains a wearable.json
file, the LoadedItem
object can be used to create an item using the ItemFactory
:
const loadedItem = await loadItem('model-with-wearable-config.zip')
const itemFactory = new ItemFactory()
itemFactory.fromConfig(loadedItem.wearable, loadedItem.content)
For the 4th case, providing a builder.json
file we can extract information related to the Builder platform. This file can be accompanied optionally with a wearable.json
file,
resulting in a zipped wearable that describes a wearable and its place in the Builder platform.
{
// The item's ID in the builder platform (optional)
"id": "f12313b4-a76b-4c9e-a2a3-ab460f59bd67",
// The collection ID that the item belongs to or should belong to (optional)
"collectionId": "34262929-3ba9-4a9e-8769-d1a92623d6d1"
}
After loading the file zip file that contains a builder.json
and wearable.json
files, the LoadedItem
object can be used to create an item using the ItemFactory
:
const loadedItem = await loadItem('model-with-wearable-and-builder-config.zip')
const itemFactory = new ItemFactory()
itemFactory.fromConfig(
loadedItem.wearable,
loadedItem.content,
loadedItem.builder
)
To consider
The item's thumbnail and the wearable image must be set either manually, by using the factory's withThumbnail
method or by including the file thumbnail.png
in the item's contents.
Building an item
Building an item is the last step of the item's creation. The build
method returns a Promise
that resolves to an object containing the
item and the item's new contents, that is the variables values that are needed to do an item insert or update using the client.
const itemFactory = new ItemFactory(oldItem)
const builtItem = await itemFactory
.withId('anId')
.withName('aName')
.withRarity(Rarity.COMMON)
.withCategory(WearableCategory.EYEBROWS)
.withCollectionId('aCollectionId')
.withDescription('aDescription')
.withRepresentation(
WearableBodyShape.MALE,
'a_model.glb',
{ 'a_model.glb': modelContent, [THUMBNAIL_PATH]: thumbnailContent },
{
triangles: 106,
materials: 107,
meshes: 108,
bodies: 109,
entities: 110,
textures: 111
}
)
.build()
await client.upsertItem(builtItem.item, builtItem.newContent)