This library includes a number of helpful pre-built tools that help you deal with common requirements that involve and interacting with data on the second layer blockchain.
To use any of the helpers provided by the utils library
- Install it as an
npm
package. Run this command in your scene's project folder:
npm i @dcl/l2-scene-utils @dcl/ecs-scene-utils eth-connect -B
Note: This command also installs the latest version of the @dcl/ecs-scene-utils and eth-connect libraries, that are dependencies of the l2 utils library
-
Run
dcl start
ordcl build
so the dependencies are correctly installed. -
Import the library into the scene's script. Add this line at the start of your
game.ts
file, or any other TypeScript files that require it:
import * as layerTwo from '@dcl/l2-scene-utils'
If you'll only be using part of this library in your scene, we recommend instead only importing the specific relevant subfolder/s. For example:
import { matic } from '@dcl/l2-scene-utils'
- In your TypeScript file, write
layerTwo.
and let the suggestions of your IDE show the available helpers.
As MANA is Decentraland's main currency, this library provies tools to make it especially easy to use in a scene.
To make players in your scene send MANA to a specific address, use the sendMana()
function. This function requires the following arguments:
address
: What ethereum address to send the MANA to
matic.balance(`0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`)
For example, your scene can have a button that requests players to make a MANA payment to the scene cretor's personal wallet. The button opens a door, but only once a transaction is sent to pay the fee.
import { matic } from '@dcl/l2-scene-utils'
(...)
let myWallet = `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`
button.addComponent(new OnPointerDown(async e => {
const balance = await matic.balance(myWallet)
if(balance > 10) {
// open door
}
))
To make players in your scene send MANA to a specific address, use the sendMana()
function. This function requires the following arguments:
toAddress
: What ethereum address to send the MANA toamount
: How many MANA tokens to send
matic.sendMana(`0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`, 100)
For example, your scene can have a button that requests players to make a MANA payment to the scene cretor's personal wallet. The button opens a door, but only once a transaction is sent to pay the fee.
import { matic } from '@dcl/l2-scene-utils'
(...)
let myWallet = `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`
button.addComponent(new OnPointerDown(async e => {
await matic.sendMana(myWallet, 100).then(
// open door
)
}
))
In this scenario, when players click on the button, they are prompted by Metamask to accept the transaction. Once that transaction is confirmed on the Matic network, the door opens.
In order to test changes made to this repository in active scenes, do the following:
- Run
npm run link
on this repository - On the scene directory, after you installed the dependency, run
npm link @dcl/l2-scene-utils
This repository uses semantic-release
to atumatically release new versions of the package to NPM.
Use the following convention for commit names:
feat: something
: Minor release, every time you add a feature or enhancement that doesn’t break the api.
fix: something
: Bug fixing / patch
chore: something
: Anything that doesn't require a release to npm, like changing the readme. Updating a dependency is not a chore if it fixes a bug or a vulnerability, that's a fix
.
If you break the API of the library, you need to do a major release, and that's done a different way. You need to add a second comment that starts with BREAKING CHANGE
, like:
commit -m "feat: changed the signature of a method" -m "BREAKING CHANGE: this commit breaks the API, changing foo(arg1) to foo(arg1, arg2)"