Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

创建库

创建你自己的 Decentraland 库，与他人共享

库是共享常见问题解决方案的绝佳方式。复杂的挑战可以只处理一次，将解决方案封装到库中，每当再次遇到时，你只需要写一行代码。通过与社区共享库，我们可以让所有创作者的生产力呈指数级增长。

目前，这些库在 示例页面 可供所有人使用。我们也鼓励你创建并分享自己的库。

按照这里详细说明的步骤，你可以避开创建一个与 Decentraland 场景兼容且易于与他人共享的库时所带来的大部分复杂性。

创建一个库

📔 注意：在构建库之前，请确保你使用的是 Node 20 版或更高版本。

要创建你自己的库并通过 NPM 共享，请执行以下操作：

  1. 创建一个新的空文件夹，并在其中打开一个新的 VS Studio Code 窗口。

  2. 在 Visual Studio 左侧边栏中选择 Decentraland 选项卡

  3. 点击 创建项目，然后选择 库

    这将为 Decentraland 库创建所有默认文件和依赖项。

  4. 设置一个唯一的 名称 在 package.json。这是发布到 NPM 时使用的名称，请确保在 npm 上没有其他现有项目使用该名称。还要填写描述和任何标签，以帮助他人找到你的库。

  5. 创建一个新的 公开 GitHub 仓库，用于你的项目。

    该项目已配置为使用 GitHub Actions，在每次推送到 main.

    在 package.json 文件中，请确保在 仓库 你将 url 字段指向你的仓库 URL。这样用户在浏览 npmjs.com.

  6. 获取一个 NPM 令牌：

    1. 创建一个账户或登录 https://www.npmjs.com/。

    2. 前往 账户 > 访问令牌 > 生成新令牌 创建一个新令牌，并赋予它 发布 权限。

      成功消息中包含一个新生成令牌的字符串。复制这串字符串并将其存放在安全的地方。

  7. 在你的 GitHub 仓库中，前往 设置 > 机密 > Actions，然后点击 新建仓库机密.

    为你的机密命名 NPM_TOKEN，并将 NPM 令牌中的字符串粘贴为其值。

  8. 将一个更改（任意更改）推送到你的 GitHub 仓库的主分支，包就会被发布。

    就是这样，现在任何人都可以使用以下方式安装该包 npm i <package-name>！现在，如果你在……中按名称搜索，就可以找到你的库 npmjs.com.

  9. 充实你的 /src 项目文件夹，加入你想要公开的全部功能，并将更改推送到 GitHub。

开发

将你想要公开的任何函数、组件等添加到库的 index.ts 文件中，这样它们就很容易导入。

例如，如果你添加一个 RotatorComponent 组件的 index.ts，然后你可以通过编写以下内容将此组件导入到场景中：

import { RotatorComponent } from 'my-library'

在开发过程中，使用一个新的 Decentraland 场景来测试你的库。通过运行以下命令将你的 npm 包安装到场景中 npm i <package-name>。然后构建一个用于试用库功能的场景。尝试用你的场景覆盖不同的测试用例，以确保你的库在各种情况下都能按预期工作。

快速迭代

如果你需要不断对库做小调整并进行测试，那么每次都要提交更改、然后等待 npm 发布完成，之后才能在场景中试用新版本，这会很耗费精力。幸运的是，有一种更快得多的替代方案可以用来测试你的库。

在一个 测试场景项目:

  1. 将此脚本添加到 scripts 列表中，位于 package.json： "link-sdk": "cd node_modules/@dcl/sdk && npm link && cd ../js-runtime && npm link"

  2. 运行 npm install

  3. 运行 npm install YOUR_LIBRARY_PATH，例如， npm install /User/projects/dcl-sdk7-library-test

  4. 运行 npm run link-sdk

在 库项目:

  1. 运行 npm install

  2. 运行 npm run build

  3. 运行： npm link @dcl/sdk @dcl/js-runtime

❗警告：这些步骤的顺序很重要。换个顺序可能行不通。

这将使你的场景与本地磁盘上直接存在的库版本保持同步。对于你想测试的任何库更改，只需运行 npm run build 在库文件夹中执行即可，无需将更改发布到 GitHub 或 NPM。

💡 提示：要验证链接是否成功，请运行 npm ls --link。你应该会看到库名称指向你本地文件中的文件夹。

如果你对库做了更改，你必须运行 npm run build 来更新它们。为了避免每次都这样做：

  1. 将脚本 "start": "tsc -p tsconfig.json --watch" 添加到库的

  2. 运行 npm start 在库中

完成测试后，记得取消链接该库。

  1. 在场景文件夹中运行 npm install <library name>

  2. 然后在库中运行 rm -rf node_modules && npm install

版本控制

你的库版本会自动发布到 npm 并配合一个 @latest 和一个 @next 标记。

该 @next 标记始终指向……上的最后一次提交 main 分支。由于最后的更改可能尚未经过测试，这个版本可能不稳定。你的库用户可以通过执行以下操作安装它（风险自负）： npm i <library name>@next.

该 @latest 标记指向该库的最后一个稳定版本。你的库用户通常应安装这个版本。npm 在他们执行以下操作时获取的就是这个版本 npm i <library name>.

要使 @latest 标记指向你最新的提交，你需要创建一个 发布版本 ，在 GitHub 上发布你的库。

  1. 打开你项目的 GitHub 页面。打开 发布版本 链接，位于页面右侧边栏。

  2. 点击 起草新版本.

  3. 开启 选择标签 为你的新版本写一个名称，例如“1.1.0”。同时在 发布标题上填写一个名称。通常这与版本号相同，例如“1.1.0”。

    重要：标签必须是数字，不能包含其他字母或符号。该数字必须高于之前已发布版本的数字。

  4. 描述你的发布内容，让用户知道有哪些新内容。

    提示：点击按钮 自动生成发布说明 即可列出自上次发布以来的所有提交。

  5. 点击 发布版本。此操作会触发一次新的自动发布到 npm，并带有 @latest 标记。你的库用户现在将下载这个版本。

可用性说明

尽你所能让你的库易于其他创作者使用。我们的假设总是会帮助塑造我们所制作的工具。很多时候，这些假设在我们看来显而易见，但处于其他语境中的人可能会有完全不同的假设。

  • 为库中的一切仔细选择名称，包括函数、组件和参数。一个能够自解释的长名称，胜过一个令人完全摸不着头脑的短名称。

  • 广泛思考你的库可能的不同使用场景。也许有人会在智能可穿戴设备中使用你的库，也许有人需要在某些时候开启或关闭你的系统，也许有人需要在同一个场景中添加你系统的多个实例。并不是每个人都会面临与你相同的挑战。

  • 话虽如此，你不需要支持所有可能的使用场景。事实上，在灵活性与易用性之间总是需要权衡，打造好工具的关键就在于找到合适的平衡。要有策略地决定你不支持哪些内容，以及界限画在哪里。不过，清晰地记录你决定采用的限制条件也很重要。

  • 这就引出了文档。请清晰地为你的库编写文档，包含示例、每个参数的作用说明、哪些场景不适用的说明，以及你对其使用环境所做的假设。库的 README.md 通常是展示这些内容的最佳位置。

  • 另一个很棒的方法是直接在代码中添加元数据注释。当你的库用户输入时，IDE（如 VS Studio Code）会显示这些注释。你可以描述每个函数/组件的用途，描述每个参数期望接收什么，以及函数返回什么。得益于此，你的库用户无需在代码和文档之间切换，一切都集中在一个地方！例如，看看来自以下库的这个函数： @dcl/ecs-scene-utils 库：

    该库的用户在输入时会看到这些提示显示为 clamp() 函数：

  • 始终声明类型。不要让人去猜测他们将要使用的对象结构。

  • 让你的库保持轻量，并专注于单一功能。当一个 Decentraland 场景被编译时，它所使用的所有库中的所有代码都会被打包进去，甚至包括场景从未调用过的代码。因此，最好避免创建庞大臃肿的库。更好的做法是使用精简的库，让创作者只使用他们真正需要的部分。

  • 留意你的库仓库，别人可能会提交拉取请求或报告问题。

  • 在你的仓库中包含许可证信息，这样别人就知道他们是否可以自由使用你的库。默认库包含一个开放的 Apache 2 许可证，如果你愿意，随时可以更改它。

上一页库目录
下一页编程模式

最后更新于