rpgjs

RPGJS v5 项目

概述

使用此技能在 RPGJS v5 项目中工作，并以最新文档为准。开始时先确认当前代码库确实是 RPGJS 项目，然后在进行更改之前，使用 curl 或同等的命令行抓取工具加载相关的 RPGJS 和 CanvasEngine 文档。

从这里开始

在进行任何操作之前，先确认当前工作区确实是 RPGJS 项目。

检查一个或多个 package.json 文件，查找 @rpgjs 包。

可用命令：

rg -n '"@rpgjs|@rpgjs/' . --glob 'package.json'
rg --files . | rg 'package.json$'

如果项目本地没有任何 package.json 使用 @rpgjs/*，请勿凭记忆手动搭建项目结构。

先阅读 RPGJS v5 快速入门，然后按照文档所述流程安装项目。

在引导缺失的项目之前，必须先阅读快速入门。

全新安装已包含 Tiled 地图编辑器集成和示例地图，因此请以此脚手架为基础，而不是手动组装项目。

使用此 URL：

https://v5.rpgjs.dev/guide/quick-start.md

加载最新文档

请勿依赖记忆中的 RPGJS v5 用法详情。安装或更改代码之前，使用 curl 或类似的命令行工具抓取文档，并阅读相关页面。

抓取 RPGJS 文档索引：

curl -fsSL https://v5.rpgjs.dev/llms.txt

将 llms.txt 文件用作目录。从中提取相关的 Markdown 链接，然后抓取所需页面。

工作流示例：

curl -fsSL https://v5.rpgjs.dev/llms.txt -o /tmp/rpgjs-v5-llms.txt
rg -o 'https://[^ )]+\\.md' /tmp/rpgjs-v5-llms.txt
curl -fsSL https://v5.rpgjs.dev/guide/quick-start.md

如果 llms.txt 使用相对链接，请以 https://v5.rpgjs.dev/ 为基准解析。

优先只阅读任务所需的页面。将抓取的文档控制在精简且有针对性的范围内。

.ce 文件的 CanvasEngine 规则

将每个 .ce 文件都视为 CanvasEngine 代码。

编辑、创建或解释 .ce 文件之前，请先抓取 CanvasEngine 文档索引：

curl -fsSL https://canvasengine.net/llms.txt

然后抓取其中引用的相关 Markdown 页面。如果能直接查阅文档，请勿凭记忆编造 CanvasEngine 语法。

如果任务涉及菜单、HUD、叠加层、对话框、标题画面，或任何以 .ce 结尾的文件，请先加载 CanvasEngine 文档，然后检查项目中附近的组件，了解本地约定。

GUI CSS 规则

GUI 样式应采用 RPGJS UI CSS 库，而不是另行设计一套无关的 CSS 系统。

更改 GUI 样式、类或布局规则之前，请先抓取并阅读此文档：

curl -fsSL https://raw.githubusercontent.com/RSamaium/RPG-JS/refs/heads/v5/packages/ui-css/README.md

如果任务会影响 GUI 外观、菜单、HUD、对话框、通知、商店或标题画面：

• 检查项目中现有的 RPGJS UI CSS 用法
• 根据 UI CSS README 核实可用的类、结构和样式模式
• 优先沿用并扩展该库的约定，而不是编写一次性的自定义 CSS

物理规则

RPGJS 使用专用的 RPG 物理引擎来处理碰撞及相关行为。

更改碰撞、移动限制、碰撞箱、地图阻挡或其他与物理相关的游戏行为之前，请先抓取并阅读此文档：

curl -fsSL https://raw.githubusercontent.com/RSamaium/RPG-JS/refs/heads/v5/packages/physic/README.md

请勿根据通用游戏引擎的经验猜测碰撞行为。请先查阅物理库文档并核实。

同步规则

当数据表示状态时，客户端与服务器之间必须通过同步的玩家属性进行同步。

更改同步状态、复制的玩家数据、快照行为或跨地图持久化之前，请先抓取并阅读此指南：

curl -fsSL https://v5.rpgjs.dev/guide/synchronization.md

对于必须在同步、快照、服务器重启或地图转移后保留的持久状态，请使用玩家的 props。

当 props 是正确的模型时，请勿使用临时变通渠道来保存持久的游戏状态。

使用 map.broadcast(type, data) 在当前地图上广播不应成为已保存状态的临时消息。

仅当确实需要这种通信模式时，才使用 player.on(key, cb) 监听客户端发送的套接字数据。

工作顺序

按以下顺序操作：

1. 检查 package.json 中是否包含 @rpgjs/*，确认当前工作区是否为 RPGJS 项目。
2. 如果不是，请获取并阅读 https://v5.rpgjs.dev/guide/quick-start.md。
3. 按照文档中的快速入门流程安装项目。
4. 确认生成的脚手架中现在包含 @rpgjs/* 包。
5. 使用 curl 或同等工具获取 https://v5.rpgjs.dev/llms.txt。
6. 获取任务所需的特定 RPGJS Markdown 页面。
7. 如果涉及 .ce 文件，也请获取 https://canvasengine.net/llms.txt 和相关的 CanvasEngine Markdown 页面。
8. 如果涉及 GUI 样式，请获取 RPGJS UI CSS README，并将其用作 CSS 参考。
9. 如果涉及碰撞或物理，请获取 RPGJS physic README，并将其用作物理参考。
10. 如果涉及同步状态或联网玩家数据，请获取同步指南，并将 props 用作默认状态模型。
11. 编辑前，先检查本地代码库中的约定。
12. 实现更改，并使用项目的常规命令进行验证。

安装规则

如果尚不存在 RPGJS 项目：

1. 使用 curl 或同等工具阅读快速入门页面。
2. 按照文档中的安装步骤操作，不要猜测包名或文件夹布局。
3. 除非用户明确要求移除或替换，否则保留生成的 Tiled 集成和示例地图。
4. 只有在脚手架就绪且项目确认为 RPGJS 代码库后，才开始开发功能。

如果安装需要网络访问，或需要在沙盒外写入包管理器文件，请先请求批准，然后继续安装，不要只停留在提供建议。

项目线索

在 RPGJS v5 项目中，通常会有以下部分特征：

• package.json 中包含 @rpgjs/* 依赖
• client.ts、server.ts，有时还包含 standalone.ts 入口文件
• config.client.* 和 config.server.* 配置文件
• server/client/common 分层
• 与 Tiled 关联的地图或世界内容
• 游戏玩法类、事件定义和地图逻辑
• 使用 .ce 文件编写的 UI 组件

遵循文档后，应以现有项目结构作为首要约定来源。

编辑指南

创建新的游戏对象、地图逻辑或 UI 组件前，请先阅读最接近的现有文件。

处理游戏玩法或引擎集成时：

• 根据获取的 RPGJS 文档验证导入项和 API
• 优先遵循项目附近的模式，而非通用抽象
• 确保服务端和客户端的职责与当前代码库保持一致
• 检查地图是通过 provideTiledMap 还是自定义的 provideLoadMap 加载

处理 packages/studio 中的 RPGJS Studio 运行时：

• 同步更新相应的运行时区块架构、类型、执行器、注册表导出和 skills/rpgjs-studio 引用
• 如果区块在游戏引擎内执行，请在 packages/studio/tests 下添加或更新 Vitest 覆盖
• 对于可复用的 Studio 事件，请使用 commonEventId；call_common_event 会执行所选事件工作流，而 spawn_common_event 会将可见的运行时对象委托给 map.createDynamicEvent(...)
• 将公共事件数据保存在 RPGJS 地图运行时上下文中，以便区块执行器无需在游戏过程中额外调用 Studio API 即可解析这些数据

处理 .ce 组件时：

• 根据获取的文档验证 CanvasEngine 语法
• 检查同级 .ce 文件，了解已有模式
• 除非用户要求进行更广泛的重构，否则保留现有组件风格

处理 GUI 样式时：

• 默认使用 RPGJS UI CSS 库作为样式系统
• 根据 UI CSS README 验证类名和结构
• 除非用户明确要求，否则避免用临时 CSS 替代库的约定

处理碰撞或移动规则时：

• 根据 RPGJS physic README 验证相关假设
• 将专用物理引擎视为碰撞行为的权威依据
• 避免导入库不支持的通用物理模式

处理同步状态时：

• 对于需要跨地图、快照或重启持久保留的状态，使用玩家 props
• 根据文档选项，审慎配置同步和持久化
• 使用 map.broadcast(...) 发送临时、非持久化的全地图消息
• 仅在需要显式进行客户端到服务端的套接字通信时使用 player.on(...)
• 如果同步属性已能满足需求，避免通过自定义路径存储持久的游戏状态

参考资料

需要规范的文档 URL、最精简的获取流程以及缺少项目时的引导规则时，请阅读 source-map.md。 需要了解本仓库使用的 RPGJS v5 核心项目模型时，请阅读 architecture-notes.md。