Skip to content

Commit 28c3395

Browse files
cyaioxcyaiox
authored
docs: Standarize readme and agent context (#151)
1 parent 11dbc84 commit 28c3395

2 files changed

Lines changed: 236 additions & 72 deletions

File tree

‎README.md‎

Lines changed: 155 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,150 @@
11
# Wearable Preview
22

3-
This webapp renders an interactive 3D preview of a wearable or an avatar. It can be configured via query params or via `postMessage`:
4-
5-
- `contract`: The contract address of the wearable collection.
6-
- `item`: The id of the item in the collection.
7-
- `token`: The id of the token (to preview a specific NFT).
8-
- `profile`: an ethereum address of a profile to load as the base avatar. It can be set to `default` or a numbered default profile like `default15` to use a default profile.
9-
- `urn`: a URN of a wearable or an emote to load. If it is a wearable, it will override anything loaded from a profile. It can be used many times.
10-
- `url`: a URL of a wearable or an emote to load. If it is a wearable, it will override anything loaded from a profile. It can be used many times. The url will be fetched and must return a valid definition following the [`WearableDefinition`](https://github.com/decentraland/common-schemas/blob/main/src/dapps/preview/wearable-definition.ts) or [`EmoteDefinition`](https://github.com/decentraland/common-schemas/blob/main/src/dapps/preview/emote-definition.ts) types.
11-
- `base64`: a wearable or an emote to load, encoded in base64. If it is a wearable, it will override anything loaded from a profile. It can be used many times. Once parsed it should be a valid definition following the [`WearableDefinition`](https://github.com/decentraland/common-schemas/blob/main/src/dapps/preview/wearable-definition.ts) or [`EmoteDefinition`](https://github.com/decentraland/common-schemas/blob/main/src/dapps/preview/emote-definition.ts) types.
12-
- `skin`: a color to be used by the skin material, it must be in hex.
13-
- `hair`: a color to be used by the hair material, it must be in hex.
14-
- `eyes`: a color to be used by the eyes tint, it must be in hex.
15-
- `bodyShape`: which body shape to use, possible values are `urn:decentraland:off-chain:base-avatars:BaseMale` or `urn:decentraland:off-chain:base-avatars:BaseFemale`.
16-
- `emote`: the emote that the avatar will play. Default value is `idle`, other possible values are: `clap`, `dab`, `dance`, `fashion`, `fashion-2`, `fashion-3`,`fashion-4`, `love`, `money`, `fist-pump` and `head-explode`.
17-
- `socialEmote`: when specified, duplicates the avatar and plays different animations on each avatar to create a social interaction scenario. The structure should be a JSON object with the following properties:
18-
- `title` (required): a string describing the social emote (e.g., `"High Five"`)
19-
- `loop` (required): a boolean indicating if the animation should loop (e.g., `true`)
20-
- `audio` (optional): a string URL for audio to play with the animation
21-
- `Armature` (optional): animation for the main avatar (e.g., `{"animation": "HighFive_Start"}`)
22-
- `Armature_Prop` (optional): animation for props/objects (e.g., `{"animation": "HighFive_Prop_Start"}`)
23-
- `Armature_Other` (optional): animation for the duplicated avatar using AvatarOther\_ nodes (e.g., `{"animation": "HighFive_Other_Start"}`)
24-
- Example: `{"title": "High Five", "loop": true, "Armature": {"animation": "HighFive_Start"}, "Armature_Other": {"animation": "HighFive_Other_Start"}}`
25-
- `zoom`: the level of zoom, it must be a number between 1 and 100.
26-
- `zoomScale`: a multiplier for the zoom level. By default is `1` but it can be increased to get extra zoom.
27-
- `camera`: which camera type to use, either `interactive` or `static`. By default it uses the `interactive` one.
28-
- `projection`: which projection type to use, either `orthographic` or `perspective`. By default it uses the `perspective` one.
29-
- `offsetX`: apply an offset in the X position of the scene. By default is `0`.
30-
- `offsetY`: apply an offset in the Y position of the scene. By default is `0`.
31-
- `offsetZ`: apply an offset in the Z position of the scene. By default is `0`.
32-
- `cameraX`: set the X position of the camera.
33-
- `cameraY`: set the Y position of the camera.
34-
- `cameraZ`: set the Z position of the camera.
35-
- `wheelZoom`: a multiplier of how much the user can zoom with the mouse wheel. By default is `1`, which means the wheel doesn't do any zoom. If the value were `2` the user would be able to zoom up to 2x.
36-
- `wheelPrecision`: the higher the value, the slower the wheel zooms when scrolled. By default is `100`.
37-
- `wheelStart`: a value between 0 and 100 which determines how zoomed in or out the wheel starts. By default is `50`, so the user can zoom in or out. If the value were `0` the zoom would start at minimum and the user would be able to zoom in. If the value were `100` the zoom would start at max and the user would be able to zoom out.
38-
- `background`: the color of the background in hex, ie: `ff0000`.
39-
- `peerUrl`: set a custom url for a Catalyst peer.
40-
- `marketplaceServerUrl`: set a custom url for the Marketplace API
41-
- `nftServerUrl`: set a custom url for the Marketplace API (legacy, marketplaceServerUrl takes priority)
42-
- `type`: set a custom PreviewType to render standalone items passed as urn, url or base64. currently only supports `wearable`.
43-
- `disableBackground`: if `true` it will make the background transparent.
44-
- `disableAutoRotate`: if `true` it will disable the auto-rotate behaviour of the camera.
45-
- `disableAutoCenter`: if `true` it will disable the auto-center around the bounding box.
46-
- `disableFace`: if `true` it will disable the facial features.
47-
- `disableDefaultWearables`: if `true` it will not load the default wearables (it will only load the base body shape).
48-
- `disableFadeEffect`: if `true` it will disable css transitions (the fade in / fade out effect). This is useful for automation tests.
49-
- `disableDefaultEmotes`: if `true` and `emote` is not passed, it will not load the default IDLE emote.
50-
- `showSceneBoundaries`: if `true` it will show a cylinder representing the recommended scene boundaries.
51-
- `showThumbnailBoundaries`: if `true` it will show a square representing the thumbnail boundaries.
52-
- `panning`: If `true`, enables the panning capability. By default it's `true`.
53-
- `lockAlpha`: If `true`, locks the alpha rotation, preventing the users from rotating the camera around alpha (in simpler terms, "horizontally").
54-
- `lockBeta`: If `true`, locks the beta rotation, preventing the users from rotating the camera around beta (in simpler terms, "vertically").
55-
- `lockRadius`: If `true`, locks the radius rotation, preventing the users from rotating the camera around radius (in simpler terms, "how far or close it is").
56-
- `env`: The environment to use, it can be `prod` (uses mainnet wearables and catalysts) or `dev` (uses testnet wearables and catalysts).
57-
58-
Example: https://wearable-preview.decentraland.org?contract=0xee8ae4c668edd43b34b98934d6d2ff82e41e6488&item=5
59-
60-
### `iframe` API:
3+
A webapp that renders interactive 3D previews of Decentraland wearables, emotes, and avatars. It can be embedded as an iframe and controlled via query parameters or `postMessage` API.
4+
5+
## Table of Contents
6+
7+
- [Features](#features)
8+
- [Dependencies & Related Services](#dependencies--related-services)
9+
- [Getting Started](#getting-started)
10+
- [Prerequisites](#prerequisites)
11+
- [Installation](#installation)
12+
- [Development](#development)
13+
- [Build](#build)
14+
- [Usage](#usage)
15+
- [Query Parameters](#query-parameters)
16+
- [iframe API](#iframe-api)
17+
- [iframe Events](#iframe-events)
18+
- [Controller RPC](#controller-rpc)
19+
- [Testing](#testing)
20+
21+
## Features
22+
23+
- **3D Avatar Preview**: Render full avatars with equipped wearables
24+
- **Wearable Preview**: Preview individual wearables on an avatar
25+
- **Emote Preview**: Play and control emote animations
26+
- **Social Emotes**: Preview two-person social interaction emotes
27+
- **Interactive Camera**: Pan, zoom, and rotate around the preview
28+
- **Screenshot Capture**: Programmatically capture screenshots via RPC
29+
- **iframe Embeddable**: Easy integration via iframe with postMessage API
30+
- **Multiple Input Sources**: Load items via URN, URL, base64, or contract/item IDs
31+
32+
## Dependencies & Related Services
33+
34+
This webapp interacts with the following services:
35+
36+
- **[Peer/Catalyst Server](https://github.com/decentraland/catalyst)**: Fetches wearable/emote entities, profiles, and content
37+
- **[Marketplace API](https://github.com/decentraland/marketplace)**: Retrieves item and NFT data by contract address
38+
39+
## Getting Started
40+
41+
### Prerequisites
42+
43+
- **Node.js**: Version 22.x
44+
- **npm**: Latest version compatible with Node.js 22.x
45+
46+
### Installation
47+
48+
```bash
49+
npm ci
50+
```
51+
52+
### Development
53+
54+
Start the development server:
55+
56+
```bash
57+
npm run start
58+
```
59+
60+
### Build
61+
62+
Build for production:
63+
64+
```bash
65+
npm run build
66+
```
67+
68+
## Usage
69+
70+
### Query Parameters
71+
72+
Configure the preview via URL query parameters:
73+
74+
#### Item Loading
75+
76+
| Parameter | Description |
77+
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
78+
| `contract` | The contract address of the wearable collection |
79+
| `item` | The id of the item in the collection |
80+
| `token` | The id of the token (to preview a specific NFT) |
81+
| `profile` | An ethereum address of a profile to load as the base avatar. It can be set to `default` or a numbered default profile like `default15` |
82+
| `urn` | A URN of a wearable or emote to load. If it is a wearable, it will override anything loaded from a profile. Can be used multiple times |
83+
| `url` | A URL of a wearable or emote to load. Must return a valid [`WearableDefinition`](https://github.com/decentraland/common-schemas/blob/main/src/dapps/preview/wearable-definition.ts) or [`EmoteDefinition`](https://github.com/decentraland/common-schemas/blob/main/src/dapps/preview/emote-definition.ts). Can be used multiple times |
84+
| `base64` | A wearable or emote encoded in base64. Once parsed it should be a valid [`WearableDefinition`](https://github.com/decentraland/common-schemas/blob/main/src/dapps/preview/wearable-definition.ts) or [`EmoteDefinition`](https://github.com/decentraland/common-schemas/blob/main/src/dapps/preview/emote-definition.ts). Can be used multiple times |
85+
86+
#### Avatar Customization
87+
88+
| Parameter | Description |
89+
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
90+
| `skin` | A color to be used by the skin material, must be in hex |
91+
| `hair` | A color to be used by the hair material, must be in hex |
92+
| `eyes` | A color to be used by the eyes tint, must be in hex |
93+
| `bodyShape` | Which body shape to use: `urn:decentraland:off-chain:base-avatars:BaseMale` or `urn:decentraland:off-chain:base-avatars:BaseFemale` |
94+
95+
#### Emote & Animation
96+
97+
| Parameter | Description |
98+
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
99+
| `emote` | The emote that the avatar will play. Default: `idle`. Options: `clap`, `dab`, `dance`, `fashion`, `fashion-2`, `fashion-3`, `fashion-4`, `love`, `money`, `fist-pump`, `head-explode` |
100+
| `socialEmote` | When specified, duplicates the avatar and plays different animations on each to create a social interaction. JSON object with: `title` (required), `loop` (required), `audio` (optional), `Armature`, `Armature_Prop`, `Armature_Other` (optional animation configs) |
101+
102+
#### Camera & View
103+
104+
| Parameter | Description |
105+
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
106+
| `zoom` | The level of zoom, must be a number between 1 and 100 |
107+
| `zoomScale` | A multiplier for the zoom level. Default: `1`, can be increased for extra zoom |
108+
| `camera` | Which camera type to use: `interactive` or `static`. Default: `interactive` |
109+
| `projection` | Which projection type to use: `orthographic` or `perspective`. Default: `perspective` |
110+
| `offsetX/Y/Z` | Apply an offset in the X/Y/Z position of the scene. Default: `0` |
111+
| `cameraX/Y/Z` | Set the X/Y/Z position of the camera |
112+
| `wheelZoom` | A multiplier of how much the user can zoom with the mouse wheel. Default: `1` (no zoom). Value of `2` allows zoom up to 2x |
113+
| `wheelPrecision` | The higher the value, the slower the wheel zooms when scrolled. Default: `100` |
114+
| `wheelStart` | A value between 0 and 100 determining initial zoom. Default: `50`. Value of `0` starts at min zoom, `100` starts at max zoom |
115+
| `panning` | If `true`, enables panning capability. Default: `true` |
116+
| `lockAlpha` | If `true`, locks the alpha rotation (horizontal rotation) |
117+
| `lockBeta` | If `true`, locks the beta rotation (vertical rotation) |
118+
| `lockRadius` | If `true`, locks the radius (zoom distance) |
119+
120+
#### Display Options
121+
122+
| Parameter | Description |
123+
| ------------------------- | ------------------------------------------------------------------------------------- |
124+
| `background` | The color of the background in hex, e.g.: `ff0000` |
125+
| `disableBackground` | If `true`, makes the background transparent |
126+
| `disableAutoRotate` | If `true`, disables the auto-rotate behaviour of the camera |
127+
| `disableAutoCenter` | If `true`, disables the auto-center around the bounding box |
128+
| `disableFace` | If `true`, disables the facial features |
129+
| `disableDefaultWearables` | If `true`, will not load default wearables (only loads the base body shape) |
130+
| `disableFadeEffect` | If `true`, disables CSS transitions (fade in/out effect). Useful for automation tests |
131+
| `disableDefaultEmotes` | If `true` and `emote` is not passed, will not load the default IDLE emote |
132+
| `showSceneBoundaries` | If `true`, shows a cylinder representing the recommended scene boundaries |
133+
| `showThumbnailBoundaries` | If `true`, shows a square representing the thumbnail boundaries |
134+
135+
#### Configuration
136+
137+
| Parameter | Description |
138+
| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
139+
| `peerUrl` | Set a custom URL for a Catalyst peer |
140+
| `marketplaceServerUrl` | Set a custom URL for the Marketplace API |
141+
| `nftServerUrl` | Set a custom URL for the Marketplace API (legacy, `marketplaceServerUrl` takes priority) |
142+
| `type` | Set a custom PreviewType for standalone items passed as urn/url/base64. Currently only supports: `wearable` |
143+
| `env` | The environment to use: `prod` (mainnet wearables and catalysts) or `dev` (testnet) |
144+
145+
**Example:** https://wearable-preview.decentraland.org?contract=0xee8ae4c668edd43b34b98934d6d2ff82e41e6488&item=5
146+
147+
### iframe API
61148

62149
It's possible to load the `wearable-preview` in an iframe and communicate with it via `postMessage`:
63150

@@ -75,7 +162,7 @@ sendMessage(iframe.contentWindow, PreviewMessageType.UPDATE, {
75162
})
76163
```
77164

78-
### `iframe` events:
165+
### iframe Events
79166

80167
You can listen to events sent by the iframe via `postMessage`.
81168

@@ -121,7 +208,7 @@ function handleMessage(event) {
121208
window.addEventListener('message', handleMessage)
122209
```
123210

124-
### `controller` RPC
211+
### Controller RPC
125212

126213
The `controller` allows to take screenshots and get metrics from the scene, and also control the emote animations (play/pause/stop/goTo).
127214

@@ -196,20 +283,16 @@ Now you can use it like this:
196283
const screenshot = await sendRequest('scene', 'getScreenshot', [512, 512]) // "data:image/png;base64..."
197284
```
198285

199-
### Setup
286+
## Testing
200287

201-
```
202-
npm ci
203-
```
204-
205-
### Development
288+
Run tests:
206289

207-
```
208-
npm run start
290+
```bash
291+
npm run test
209292
```
210293

211-
### Build
294+
## AI Agent Context
212295

213-
```
214-
npm run build
215-
```
296+
For detailed AI Agent context, see [docs/ai-agent-context.md](docs/ai-agent-context.md).
297+
298+
---

0 commit comments

Comments
 (0)