\n\n\n \n\nAdshares plugin for **Decentraland** SDK. You can use it in your scenes for addition hassle-free earnings.\n\nEasy configuration. Just fill out your payout address (Adshares blockchain or as BEP20 token) and get paid in $ADS for every visitor on your scene. See [DCL Example Scene](https://github.com/adshares/dcl-scene).\n\n## Install\n\n```bash\nnpm install @adshares/decentraland -B\n```\n\n### Update\n\n```bash\nnpm update @adshares/decentraland\n```\n\n## Usage\n\n### 1. Import dependencies\n\n```js\nimport * as Ads from '@adshares/decentraland'\n```\n\n### 2. Create supply agent\n\n```js\nconst agent = new Ads.SupplyAgent(adserver: string, publisherId: string)\n```\n\nor\n\n```js\nconst agent = Ads.SupplyAgent.fromWallet(adserver: string, chain: string, wallet: string)\n```\n\nIn function **fromWallet()** first argument is adserver network, second argument is payout network (ads, bsc), and third argument is wallet address in this payout network.\n\n### 3. Create Placement or Stand\n\n#### Placements\n\nPlacements are the basic objects for displaying creatives.\nEvery placement implements IEntity and has access to IEntity methods.\n\nUsage:\n\n```js\nconst placement = new Ads.PlainPlacement(name: string, options?: {})\n```\n\nAvailable options:\n\n```js\n{\n position?: Vector3, // @decentraland-ecs\n rotation?: Quaternion, // @decentraland-ecs\n width?: number,\n ratio?: '9:16' | '3:4' | '1:1' | '4:3' | '16:9',\n no?: number | null,\n types?: string[] | null,\n mimes?: string[] | null,\n}\n```\n\n#### UI placements\n\nUI placements are elements of interface for displaying creatives, when player is on scene.\nKeep in might that UI placement doesn't need to be added to Decentraland engine. UI placement can be closed after 5 seconds from displaying.\n\nUsage:\n\n```js\nconst placement = new Ads.UIPlacement(name: string, position: 'top' | 'bottom' | 'left' | 'right' | 'center')\n```\n\n#### Stands\n\nStands combine several placements into one object.\nEvery stand implements IEntity and has access to IEntity methods.\n\nThe simplest stand is the PlainStand, which repeats the PlainPlacement and adds a frame and a background that covers the gaps between the layers. You can define own Material for frame.\n\n```js\nconst plain = new Ads.PlainStand(name: string, options?: {})\n```\nAvailable options:\n\n```js\n{\n position?: Vector3, // @decentraland-ecs\n rotation?: Quaternion, // @decentraland-ecs\n width?: number,\n ratio?: '9:16' | '3:4' | '1:1' | '4:3' | '16:9',\n no?: number | null,\n types?: string[] | null,\n mimes?: string[] | null,\n frameMaterial?: Material,\n}\n```\n\nAvailable stands:\n\n| Class | Description | Ratios | Models |\n|-----------|------------------------------------------------------------------|-------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|\n| Totem | A simple advertising totem | 9:16 | ads_totem_9_16.glb |\n| Citylight | Rectangular 4-sided advertising totem with the ability to rotate | 9:16 | ads_citylight_9_16.glb |\n| Billboard | Advertising billboard with multiple ratios | 9:16 16:9 3:4 4:3 1:1 | ads_billboard_9_16.glb ads_billboard_16_9.glb ads_billboard_3_4.glb ads_billboard_4_3.glb ads_billboard_1_1.glb | \n\n\nYou must copy the models to the root scene folder before using the stands. It's a good practice to copy only the models you use.\n\n```bash\nmkdir -p models/@adshares && cp -r node_modules/@adshares/decentraland/models/ads_totem_9_16.glb models/@adshares\n```\n\nUsage Totem:\n\n```js\nconst totem = new Ads.Totem(name: string, options?: {})\n```\n\nAvailable options:\n\n```js\n{\n types?: string[] | null,\n mimes?: string[] | null,\n}\n```\n\nUsage Citylight:\n\n```js\nconst citylight = new Ads.Citylight(name: string, options?: {})\n```\n\nAvailable options:\n\n```js\n{\n types?: string[] | null,\n mimes?: string[] | null,\n rotation?: boolean, // default true\n}\n```\n\nUsage Billboard:\n\n```js\nconst billboard = new Ads.Billboard(name: string, options?: {})\n```\n\nAvailable options:\n\n```js\n{\n types?: string[] | null,\n mimes?: string[] | null,\n ratio?: '9:16' | '3:4' | '1:1' | '4:3' | '16:9', // default 1:1\n}\n```\n\n\n### 4. Add placements into Decentraland engine\n\n```js\nengine.addEntity(placement)\n// or\nengine.addEntity(totem)\n```\nor \n\n```js\nplacement.setParent(myEntity)\n// or\ntotem.setParent(myEntity)\n```\n\n### 5. Add placement into agent and spawn banner\n\n```js\nagent.addPlacement(placement: IPlacement | IStand).spawn()\n```\n\n### Example to add placements\n\n```js\nimport * as Ads from '@adshares/decentraland'\n\nconst agent = Ads.SupplyAgent.fromWallet('https://app.web3ads.net', 'ads', '0001-00000000-9B6F')\n\nconst placement1 = new Ads.PlainPlacement('unit1', {\n position: new Vector3(8, 2, 8),\n rotation: new Quaternion(0, 0, 0, 1),\n width: 5,\n ratio: '16:9',\n})\nengine.addEntity(placement1)\n\nconst placement2 = new Ads.PlainPlacement('unit2', {\n position: new Vector3(11, 2, 6),\n rotation: new Quaternion(0, 1, 0, 1),\n width: 3,\n ratio: '3:4',\n})\nengine.addEntity(placement2)\n\nagent.addPlacement(placement1, placement2, totem).spawn()\n```\n\n![Placement example](/assets/placement_example.png \"Decentraland scene\")\n\n\n### Example to add advertising stands\n\n```js\nimport * as Ads from '@adshares/decentraland'\n\nconst agent = Ads.SupplyAgent.fromWallet('https://app.web3ads.net', 'ads', '0001-00000000-9B6F')\n\nconst totem = new Ads.Totem('totem')\ntotem.addComponent(new Transform({\n position: new Vector3(3,0,8),\n}))\nengine.addEntity(totem)\n\nconst billboard = new Ads.Billboard('billboard_16_9', { ratio: '16:9' })\nbillboard.addComponent(new Transform({\n position: new Vector3(11,0,8),\n}))\nengine.addEntity(billboard)\nagent.addPlacement(totem, billboard).spawn()\n```\n\n![Stand example](/assets/stands_example.png \"Decentraland scene\") \n\n### Example to add UI placement\n\n```js\nimport * as Ads from '@adshares/decentraland'\n\nconst agent = Ads.SupplyAgent.fromWallet('https://app.web3ads.net', 'ads', '0001-00000000-9B6F')\n\nconst uiPlacementRight = new UIPlacement('UI-right', 'right')\nconst uiPlacementLeft = new UIPlacement('UI-left', 'left')\nconst uiPlacementCenter = new UIPlacement('UI-center', 'center')\n\nagent.addPlacement(uiPlacementRight, uiPlacementLeft, uiPlacementCenter).spawn()\n```\n\n![UI placement example](/assets/ui_placement_example.png \"Decentraland scene\")\n\n### Contributing\n\nPlease follow our [Contributing Guidelines](docs/CONTRIBUTING.md)\n\n### Versioning\n\nWe use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/adshares/decentraland/tags).\n\n## Authors\n\n- **[Mykola Zhura](https://github.com/Niko-Yea)** - _programmer_\n- **[Maciej Pilarczyk](https://github.com/m-pilarczyk)** - _programmer_\n- **[Contributor](https://github.com/smartsir796)** - _programmer_\n\nSee also the list of [contributors](https://github.com/adshares/decentraland/contributors) who participated in this project.\n\n### License\n\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.\n\n## More info\n\n- [DCL Example Scene](https://github.com/adshares/dcl-scene)\n- [DCL Smart Banner](https://github.com/adshares/dcl-smart-banner)\n- [Adshares](https://adshares.net)\n- [Adshares Docs](https://docs.adshares.net)\n","readmeFilename":"README.md"}
![\"Adshares\"](\"https://adshares.net/logos/ads.svg\")
\n \n