> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/ku/create-libraries.md).

# 创建库

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

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

目前，以下库已在 [示例页面](https://studios.decentraland.org/resources?sdk_version=SDK7\&resource_type=Library) 上提供，任何人都可以使用。我们也鼓励你创建并分享自己的库。

按照这里详述的步骤操作，可以避免创建与 Decentraland 场景兼容且易于与他人分享的库时遇到的大部分复杂问题。

## 创建库

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

要创建自己的库并通过 NPM 分享，请按以下步骤操作：

1. 新建一个空文件夹，并在其中打开一个新的 Visual Studio Code 窗口。
2. 在 Visual Studio 左侧边栏中选择 Decentraland 选项卡
3. 点击 **创建项目**，然后选择 **库**

   这将创建 Decentraland 库所需的所有默认文件和依赖项。
4. 设置一个唯一的 `name` ，位于 `package.json`中。这是发布到 NPM 时使用的名称，请确保 npm 上没有其他现有项目使用该名称。还要填写描述并添加标签，以便其他人找到你的库。
5. 为你的项目创建一个新的 *公开* GitHub 仓库。

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

   分支时发布软件包的新版本。 `package.json` 文件中，请确保在 `repository` 中将 `url` 字段指向你的仓库 URL。这样，用户在 [npmjs.com](https://www.npmjs.com).
6. 浏览时就能轻松找到你的库。
   1. 获取 NPM 令牌：
   2. 创建账户或登录 <https://www.npmjs.com/。> **前往“账户 > 访问令牌 > 生成新令牌”** 创建新令牌，并为其授予 **发布** 权限。

      成功消息中会包含新生成的令牌字符串。复制该字符串并妥善保存。
7. 在你的 GitHub 仓库中，前往 **设置 > 密钥 > Actions**，然后点击 **新建仓库密钥**.

   将密钥命名为 **NPM\_TOKEN**，并将 NPM 令牌字符串粘贴为其值。
8. 向 GitHub 仓库的 main 分支推送一项更改（任何更改均可），软件包就会发布。

   就是这样，现在任何人都可以使用 `npm i <package-name>`安装此软件包！现在，你可以在 [npmjs.com](https://www.npmjs.com).
9. 完善项目的 `/src` 文件夹，添加你想公开的所有功能，然后将更改推送到 GitHub。

## 开发

将你想公开的函数、组件等添加到库的 `index.ts` 文件中，这样就可以轻松导入它们。

例如，如果你将一个 `RotatorComponent` 组件添加到 `index.ts`中，就可以在场景中通过以下语句导入该组件：

`import { RotatorComponent } from 'my-library'`

开发库时，可以在一个新的 Decentraland 场景中使用它来进行测试。运行以下命令，将 npm 软件包安装到场景中： `npm i <package-name>`。然后构建一个用于试用库功能的场景。尽量在场景中覆盖不同的测试用例，确保库在各种情况下都能按预期运行。

### 快速迭代

如果你需要不断对库进行小幅调整并测试，那么每次都要提交更改，然后等待 npm 发布完成，才能在场景中试用新版本，会让人疲惫不堪。幸运的是，有一种更快的方法可以使用你的库进行测试。

在 **测试场景项目**:

1. 中，将此脚本添加到 package.json 的 `scripts` 列表中： `"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. 在 scene 文件夹中运行 `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` 库中的这个函数：

  ```ts
  /**
   * 限制一个值，使其不低于最小值，也不高于最大值。
   *
   * @param value - 输入数值
   * @param min - 最小输出值。
   * @param max - 最大输出值。
   * @returns 最小值与最大值之间映射后的结果
   * @public
   */
  export function clamp(value: number, min: number, max: number) {
  	let result = value

  	if (value > max) {
  		result = max
  	} else if (value < min) {
  		result = min
  	}
  	return result
  }
  ```

  使用此库的用户在输入 `clamp()` 函数时，会看到这些提示：
* 始终声明类型。不要让使用者猜测他们需要处理的对象结构。
* 让你的库保持轻量，并专注于一项功能。编译 Decentraland 场景时，其中所有库的全部代码都会被打包，即使场景从未调用过这些代码。因此，最好避免创建庞大臃肿的库。精简的库更好，能让创作者只使用真正需要的部分。
* 留意你的库的代码仓库，其他人可能会提交拉取请求或报告问题。
* 在代码仓库中注明许可信息，让其他人知道是否可以自由使用你的库。默认库采用开放的 Apache 2 许可证；如有需要，你可以更改它。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/ku/create-libraries.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
