# @edv4h/usketch-plugin-character 中文文档

规范地址：https://npmcn.com/package/%40edv4h/usketch-plugin-character/

版本：0\.10\.1
npm 元数据更新时间：2026-11-10T02:57:43.218Z
中文译文更新时间：2026-11-13T07:41:22.778Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40edv4h/usketch-plugin-character
原文对照：https://npmcn.com/package/%40edv4h/usketch-plugin-character/?lang=original
项目主页：https://github.com/EdV4H/usketch#readme
源码仓库：https://github.com/EdV4H/usketch

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：287 kB，63 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=19
- 首次发布：2026-09-26T07:55:11.482Z
- 最新版本发布：2026-11-10T02:57:42.855Z
- 近 30 天下载量：3312（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @edv4h/usketch-plugin-character
```

也可以使用：`pnpm add @edv4h/usketch-plugin-character`、`yarn add @edv4h/usketch-plugin-character`、`bun add @edv4h/usketch-plugin-character`

## README

# @ edv4h/ usketch- plugin- 字符集

USketch 的可控字符: 在屏幕上选择位置放置, 驱动 使用自定义的密钥(默认情况下为WASD),跟踪其面朝哪个方向,并有 摄影机跟着它 要么让世界保持正轨 要么让世界走向正轨 字符标题(通过 Core 视图端口进行搜索视图) `rotation`) (中文(简体) ). 其它 用户的字符通过 Yjs 意识与您同时出现 .

**插件没有绘图 .** 它计算位置和标题 并把它们交给  `renderCharacter`,所以外观(文稿、汽车、相机、标签、动画)是 完全属于宿主.

```ts
import { createCharacterPlugin } from "@edv4h/usketch-plugin-character";

createCharacterPlugin({
  renderCharacter: ({ screenHeading, appearance, name }) => (
    <div style={{ transform: `rotate(${screenHeading}deg)`, color: String(appearance.color) }}>▲</div>
  ),
  appearance: { color: "#e44" },   // broadcast, so others draw you the same way
  wsProvider,                      // optional: omit for single-player
  userName: "Alice",
  keys: { up: ["KeyW", "ArrowUp"] }, // KeyboardEvent.code values
  cameraMode: "rotate",            // "fixed" | "rotate" | "free"
  controlScheme: "vehicle",        // "directional" | "vehicle"
  drift: true,                     // vehicle: Shift + steer drifts (or tuning overrides)
  jump: true,                      // Space jumps (or tuning overrides)
  renderShadow: ({ altitude }) => <div className="shadow" style={{ scale: 1 / (1 + altitude / 60) }} />,
  screenAnchor: { x: 0.5, y: 0.75 },
});
```

## 概念

-   **标题**: 学位, `0` =上升(世界-y),顺时针阳性——同一公约 作为CSS `rotate()` 和视图端口 `rotation`。 。 。 .
    
-   **渲染道具**数字 : `heading` (这个世界), `screenHeading` (= (单位:千美元) `heading + viewport.rotation`, (中文(简体) ), 由什么旋转自上而下图案, `moving`, (中文(简体) ), `speed`, (中文(简体) ), `steering`, (中文(简体) ), `slip`, (中文(简体) ), `drifting`, (中文(简体) ), `zoom`, (中文(简体) ), `size`, (中文(简体) ), `appearance`, (中文(简体) ), `name`, (中文(简体) ), `isSelf`, (中文(简体) ), `id`, (中文(简体) ), `elevation`, (中文(简体) ), `z`, (中文(简体) ), `altitude`, (中文(简体) ), `airborne`, (中文(简体) ), `verticalSpeed`, (中文(简体) ), `hovering`, (中文(简体) ), `hoverGauge` (0. 1, (中文(简体) ), `null` 与徘徊 关了). 每个字符都放在屏幕位置上 在一个屏幕- 空格层中, 因此在缩放下, 自我和远程字符看起来是一样的 相机旋转.
    
-   **大小** (单位:千美元)`size` 选项/ `setSize`,只有外观: `size` 介质道具中 屏幕 px 绘制身体 . `{ scale: "screen", value: 36 }` 以物配主 屏幕上每个缩放都一样 就像一个地图针. `{ scale: "world", value: 24 }` 使它成为24个世界单位,因此它随地而缩放 地形) `minPx` (默认 12) `maxPx` (默认 480) 在屏幕上。 这个 物理学仍将一个字符当作点: `motion.maxStep` 财务报告和审定财务报表 `jump.height` 决定 它攀爬的,不是它的大小.
    
-   **控制计划**
    
    -   `directional` ——按屏幕方向移动键(相机相对);标题 转向移动在 `turnRate`与 `rotate` 相机,左/右 故作圆相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.
    -   `vehicle` 上下节流阀和倒向,左/右方向舵。 指导比额表 以速度(被停车不能转弯)和倒转为倒转. 执掌方向 (-1. 1) 处于姿势并制出道具,例如使前轮转向.
-   **漂流** (单位:千美元)`vehicle`,通过 `drift`: 握住漂移键(Shift)并方向 开始向方向移动的速度 变紧了 引导和滑动身体通过 `slip` 度(在 `heading + slip`· ; 它一直走着 `heading`) (中文(简体) ). 向上走会拉紧它, 反导打开它(从不旋转). 打开密钥, 减速到下面 `stopSpeed` 或倒行逆施,而后退。 调教( T)`DriftParams`: `startSpeed` 编号 : `stopSpeed` (违反 `moveSpeed`, (中文(简体) ), `turnRate` 编号 : `steerRate` (单位:百万 `turnRate`, (中文(简体) ), `slipAngle` 编号 : `steerSlipAngle` (分数), `recoveryRate` (单位:1/s). 与 `hop: true`在地面上按下漂移键 `hopHeight` (默认 10 ) 首先,如果键仍然被握住, 漂移开始于起落 转向架(一辆车不能在空中行驶). 漂移键只在漂移时被捕获 开始.
    
-   **跳下来** (选择通过 `jump`: 按跳键( Space)来跳. 弧由 其顶端 `height` (世界单位)和 `timeToApex`坠落 `fallGravity` ×快于 它会升起,释放出钥匙,而升起则会缩短它的时间`releaseCut`内部的媒体 `bufferTime` 在着陆前跳下触地得分 跳入内地 `coyoteTime` 联 合 国 离开一扇窗台还是算数的 姿势抬起脚来 `z` (绝对,像 地面高度, `vz` 财务报告和审定财务报表 `airborne`。如果跳动键也是活动漂移 键(两者都可以反弹) 漂移取胜. `api.jump()` (和HUD) 动作)从代码跳出,作为全跳.
    
-   **多弹跳** (单位:千美元)`jump.airJumps`,默认 0 : 空气中的新鲜相机使用其中之一 `airJumps` 任何剩余时的额外跳跃(1=双跳);每个都达到 `airJumpRatio` (违约0.8)× `height` (起飞速度××RATIO). 他们回来了 着陆.
    
-   **缓冲** (单位:千美元)`jump.hover`,默认关闭; `true` 或部分 `HoverParams`: 一旦空气 跳跃被用掉( 或没有), 跳动键在起火时被握住 推倒并排出一个持续测量仪 `duration` (1.5 s); 平时空出计. `thrust` 是重力的倍数( 默认 0 = 一滑翔): 1以下字符汇, 在1时,它保持了垂直速度,在1以上,它爬升,只要按住键. 隐蔽被封住 `fallSpeed` (默认15个世界单位 / s, 0 = 永不下沉),攀登 时间 `riseSpeed` (60个). 测量器重新填充 在地面上结束 `rechargeTime` 0.8 s),起降时不同时起降. 摆姿势 `hovering` 财务报告和审定财务报表 `hoverGauge` (第1站并停放);两者均播出.
    
-   **密钥**:跳跃(Space)和漂移(Shift)有自己的键. 高级UD提议 每个键的几个键(`KEY_CHOICES`:空间、移动、Z、X、C、J、K、L); `setKeys` 带 任意 `KeyboardEvent.code`s 和 `getKeys` 返回绑定符.
    
-   **立于三维**:每个位置(和制造器内容周围的包装)保持 3D 语境`transform-style: preserve-3d`),因此在三维视图(模式7)下a 制造器可以站在平地上 而不是躺在地上 上面:读取从 `view3dService` (单位:千美元)`@edv4h/usketch-shared`)并转 图标由 `rotateX(-pitch)` 环绕其下边缘( e)`transform-origin: bottom`) (中文(简体) ). 在平板上 `pitch` 是0,所以同样的渲染器从上面向下画出.
    
-   **阴影**: 通过 `renderShadow` 以画出一副阴影;它放在地上 身体处于高地时的每个角色 `z`,因此在三维视图下 (模式7)一跃将身体从它的阴影中抬出. `altitude` (单位:千美元)`z - elevation`让它 随着角色的上升而收缩.
    
-   **键盘焦点**: 移动键在 `window` 当字符是 上,但页面需要时除外:当文本字段有焦点时,什么都不用取 或焦点位于对话框/菜单内( q)`dialog`, (中文(简体) ), `role="dialog"`, (中文(简体) ), `alertdialog`, (中文(简体) ), `menu`· ; 包含棋盘本身不计数的对话框,箭头键留给 使用它们的部件(范围/无线电输入, `role="slider"`, (中文(简体) ), `radio`, (中文(简体) ), `tab`, (中文(简体) ), `option`, (中文(简体) ), `combobox`, (中文(简体) ), `menubar` 物项, `grid`, (中文(简体) ), `treeitem` ...) WASD则保持 驱动,空间则留给它激活的按钮、链接和其他控制器。 焦点 读取 `composedPath()`,所以网络组件对话框也算数。 移动焦点 向这种目标释放它使用的被扣钥匙.
    
-   **触摸/ 游戏板( 虚拟输入)**: 主机控制输入模拟输入 `api.setVirtualInput({ throttle, steer, drift })` (单位:千美元)`throttle` 编号 : `steer` 在-1. 1中; 以-1. 1为单位; `directional` 把它们读作屏幕上/右). 发送当前状态 变动和 `null` 释放时。 它添加了被扣键( 封口为± 1) , 所以键盘 并可以一起驱动 `throttle` 目标为顶部的这个部分 速度和一个部分 `steer` 由分数转出 触摸它会恢复停顿 跟着相机像移动键。 它被忽略了 当角色关闭,和 关闭字符发布它. `jump: true` 是跳动按钮: 像 跳键(在起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起 在两个框之间仍然数。 A 类 `drift` 按下, 当 `drift.hop` 开始.
    
-   **相机模式**
    
    -   `fixed` - 跟着,世界保持正向.
    -   `rotate` ——跟随并扭转世界 `-heading` (特征总是面对).
    -   `free` 别动相机.
    
    手接相继; 按动作键恢复 。 缩放保持 随后. 把角色关了 把相机反向直上.
    
    在3D视图(模式7)下,以下还会以字符来提升视图相机 (租赁; `view3dService.setCameraHeight`所以爬山不会走 屏幕上方的字符。 在地上它跟随脚;在空中 它能保持起飞高度,所以普通的跳跃仍然会升起在屏幕上并跑出 在坑上放起的窗帘不会沾上风景 盘旋或高多跳 爬得更多 比起来 `cameraHeightMargin` 在起飞高度( 默认 = 跳跃高度) 上方拖动 相机的上方 起飞高度以下的下方 将它倒下. `0` 如下 身体的高度是准确的(`setCameraHeightMargin` 在运行时间.
    
-   **多人游戏**: 通过 `wsProvider` (任何带有y-protocols的东西) `awareness`) (中文(简体) ).  字符在 `character` 认识领域(~20赫兹,只有当它 变动,包括 `steering`, (中文(简体) ), `slip` 财务报告和审定财务报表 `drifting`其他的则在 更新。 它的发光: 一个人物 当它的主人断开或关机时消失 无所存为相.
    
-   **地面高度**: 当插件提供时 `groundHeightService` (从) `@edv4h/usketch-shared`,例如地图插件升起的地形),移动到 地面超过 `motion.maxStep` (默认24个世界单位,HUD"Q")更高 而不是角色所在的位置被屏蔽;而是沿着悬崖滑行. 台阶是用脚来测量的,所以跳跃中更高的悬崖是能够伸到的;一扇起落架 在脚上方的台阶上 踩下脚步夹 倒下;倒下较大(即使跳下也适用重力). 渲染道具 携带 `elevation` (地上)和 `z` 在三维视图(模式7)下 字符被提升到脚高.
    
-   **固体**: 当插件提供时 `solidHeightService` (例如,形状-3d的形状与 (单位:千美元) `collision`),其答案与地面结合:一堵墙 (`Infinity`块 每进一出,每入一出,每入一出,每入一出,每入一出 被踩住或被跳上并站住`blockingHeight` 编号 : `standingHeight`) (中文(简体) ). 一个动作 最多可检查长度 `SWEEP_STEP` (4) 世界单位(`sweepToGround`),这样 快速字符或车辆不能跳过一框内薄壁.
    
-   **斜坡**:在平滑地上(如高地插件的山地),单靠台阶永远不会 绑住,所以 `motion.maxSlope` (度,默认为0=无限制,HUD"Q") 限制斜坡向上行走;更陡峭地块,如悬崖起立 向下滑动( e)`slideOnSteep`移动速度的一半。 坡度是用 超过 ±8 世界单位(`groundSlope`),所以一步——地图平地 水平,一个盒子的边缘——读作平地并停留 `maxStep`业务。 在空气中 限制不适用(跳出它).
    
-   **跳出斜坡时** 直上和地平线之间的叶子: `jump.slopeRatio` (0=上行,1=正行,默认为0.5,HUD"坂でのジャンプの向き". 侧道部分( A)`pose.vx` 编号 : `vy`由空气中携带(`pushInAir`并且现在 着陆时降落 空气跳出,漂浮跳出直上.
    
-   **倾斜**: 在 三维视图( 第 7 模式) 下, 层会铺设每个字符( 及其阴影) 沿着地底下,通过 `motion.slopeTilt` (0... 1,默认 1,HUD) "QQ") × 三维过渡(`slopeTiltTransform`) (中文(简体) ). 在空气中 身体的精度在第一时间消退 `AIR_LEAN_FADE` 地面上的世界单位 (单位:千美元)`bodyLeanFactor`),所以从一跃下行或一徘徊的地势不会倾斜 阴影仍然存在于地上 平板不变.
    
-   **投入**: 从窗口跟踪持有的密钥 `keydown`编号 :`keyup` (抓捕阶段, `event.code`),在字符如此单字母工具上被吞入 捷径不会开火。 文本字段中的打字,以及带有 Ctrl/Cmd/Alt 的密钥和弦, 被忽略.
    

## 人权联盟

“ QQ” 设置组( 启动/ 关闭、 相机、 计划、 漂移、 漂移键、 跳跃、 跳跃键、 跳跃高度、 空气) 跳跃,跳跃方向在坡地上,徘徊,徘徊时间,徘徊推力,速度,转速,可攀爬的台阶,可攀爬的坡地上,靠坡地上,大小及其尺度,屏幕位置,相机后差等)外加动作来切换 字符,放在屏幕位置,然后跳出.

## 服务

```ts
import { getCharacterApi } from "@edv4h/usketch-plugin-character";

const api = getCharacterApi(app.services);
api?.enable();
api?.setCameraMode("rotate");
api?.setRenderer(myRenderer);
api?.setDrift({ slipAngle: 35, hop: true }); // true / false / tuning overrides
api?.setJump({ height: 60 });     // true / false / tuning overrides
api?.setJump({ airJumps: 1, hover: { duration: 2 } }); // double jump + hover (hover: true / false / partial)
api?.jump();
api?.setKeys({ ...api.getKeys(), drift: ["KeyX"] }); // KeyboardEvent.code values
api?.setShadowRenderer(myShadow);
api?.setSize({ scale: "world", value: 24, minPx: 20 }); // scale with the ground (render props `size`)
api?.getPose(); // { x, y, heading, speed, moving, steering, slip, drift, z, vz, airborne, hovering, hoverGauge }
api?.setVirtualInput({ throttle: 0.8, steer: -0.3 }); // touch stick; null on release
api?.setVirtualInput({ throttle: 0.8, steer: 0, jump: true }); // + jump button held
```

## 限制

在相机旋转时, 覆盖可以计算屏幕位置 (snap向导,调整手柄大小,连接器,评论徽章,背景网格) 尚未意识到旋转。 穿过核心的工具 `screenToWorld` 起来 正确的坐标.

## 常见问题

### 如何安装 @edv4h/usketch-plugin-character？

在项目目录运行 npm install @edv4h/usketch-plugin-character，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @edv4h/usketch-plugin-character 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @edv4h/usketch-plugin-character 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @edv4h/usketch-plugin-character 可以商用吗？

@edv4h/usketch-plugin-character 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @edv4h/usketch-plugin-character 的下载量有多少？

根据 npm 官方下载统计，@edv4h/usketch-plugin-character 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,312 次，日均约 110 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @edv4h/usketch-plugin-character 还在维护吗？

最新版本 0\.10\.1 发布于 2026/11/10（3 天前）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2026/09/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。