asciify-engine

Asciify Engine

使用已发布的 asciify-engine npm 包。已针对 4.30.0 进行测试。使用更新的选项前，请检查应用中安装的版本及其公开类型；本地检出版本可能包含尚未发布的更改。

• Agent 入口：https://asciify.org/skill（重定向到本文档）。
• 组件：https://asciify.org/components · 风格：https://asciify.org/looks · 背景：https://asciify.org/backgrounds
• 交互式演示：https://asciify.org/editor · API 文档：https://asciify.org/docs/api
• 仓库：https://github.com/ayangabryl/asciify-engine

npm install asciify-engine@latest

入口：/kit 用于界面组件和背景，每项各调用一次；asciify-engine 和 /core 用于媒体和文本转换；/hover 用于网站悬停效果和动态图片运动；/studio 用于艺术风格、视觉效果和导出；/field 用于原始 GPU 字符场。每个可选入口仅在导入时加载。调用 GIF API 时才会加载 GIF 解码库 gifuct-js。

从这里开始：先用 kit

大多数需求表达的是一种感觉（“让加载状态更鲜活”“为定价区域加上宁静的背景”“像 asciify.org 一样”），而不是 API。按以下顺序操作：

1. 这是 UI 组件还是背景？ 几乎总是如此。阅读 applying-asciify.md（项目的设计规范：字符何时值得出现、墨色、清晰区域与遮罩、密度、圆角、动效、性能、无障碍，以及不同背景适合搭配哪些表面），然后从 components.md 中选择调用方式，并从 kit.md 中选择选项。除非 kit 没有适合该效果的选项，否则到此为止。
2. 阅读需求。 主题（用户的媒体、一个词，或没有主题）、位置（主视觉、卡片、控件、文字背后的背景）、氛围词、交互方式，以及任何参考网站。
3. 阅读设计规范。 查看项目的设计令牌：基础色与表面色、文字颜色、唯一的强调色、等宽字体与展示字体、圆角、浅色和深色主题、动效时长与缓动方式、减少动态效果的处理方式。将 kit 的墨色令牌（--ascii-ink、--ascii-ink-strong、--ascii-success、--ascii-warning、--ascii-error）映射到这些设计令牌上；绝不要添加品牌色。
4. 决定使用动态效果还是静态效果。 遵循用户的用词；文字背后的艺术效果、网格和数据视图应保持静态；减少动态效果时始终使用静态效果。参见动态效果还是静态效果。
5. 用一句话说明你的选择，并提供一个替代方案。只有在缺少媒体素材，或要为一个原本没有动效的网站新增动效时，才提出问题。

design-matching.md 将氛围词映射到较低层 API 的设置和媒体效果。

用户想要	使用
字符构成的 UI 组件：按钮加载状态、状态提示、Toast、选项卡、胶囊标签、里程表、图表、AI 思考和流式输出、过渡效果、登录、定价、404；活动网站元素（扰动效果标题栏和主标题、形变的排线主视觉、抖动辉光、点阵地球、双色照片、逐步组合的文字标识、喷洒式光标）	asciify-engine/kit（applying-asciify.md、components.md、kit.md）
主视觉、定价、文档或区块后面的浅色或深色背景	Kit fieldBackground(el, { preset: 'hero', clear })（asciify.org 的主视觉效果），或 background(el, { preset, clear })，搭配下方 12 种精选预设之一
用字符呈现用户的文字或品牌	Kit wordmark，或使用 wordField 的 background()
在页面上用字符呈现用户的视频	Kit asciiVideo
转换用户的照片、视频或 GIF，并可选择响应光标	高级：asciify / asciifyVideo / asciifyGif，以及来自 /hover 的 mountHover
使用 kit 不支持的效果创建全幅背景	高级：来自 /field 的 mountGlyphField（glyph-field.md）
将用户的照片或视频制作为指定风格的完整艺术作品：壁纸、海报、封面、印刷品或主视觉艺术作品（“新闻纸”“孔版印刷”“荧光粉”“雕版”“乐高”）	使用 /studio 中的 mountStudio / exportStudio，并搭配 looks.md 中的一种风格
艺术风格、已保存的效果、蒙版、特效、PNG/MP4/GIF 导出	高级：来自 /studio 的 mountStudio（studio-workspace.md）
多个媒体层和文字层组成的单幅作品	高级：来自 /studio 的 mountStudioProject（layered-projects.md）
文字横幅或字样	高级：asciifyText / renderTextToCanvas
透过媒体艺术效果可见的标题文字	高级：分层 HTML（layered-hero.md）

用一段话介绍工具包

每个工具包函数都会在你的元素上方或内部挂载一个 aria-hidden 场域，跟随元素的尺寸和边框圆角，以浅色和深色主题色为其着色，在元素离开视口时暂停，尊重减少动态效果设置；如果没有 WebGL2，则回退为不执行操作的句柄，同时确保 HTML 正常工作，并在调用 destroy() 时清理。components.md 包含 37 个组件的简短代码片段，并列出使用者给出的提示词，分类包括 Components、AI、Text、Transitions、Media、Pages 和 Backgrounds。在 React 中，在 effect 里创建句柄，并返回其 destroy 方法。

import { beam } from 'asciify-engine/kit';
const b = beam(card, { palette: 'mono', mode: 'pulse' });
// On unmount: b.destroy();

background()、它的预设、lazy、poster、setFieldBudget 和 setGlobalLook 是 4.14.0 中新增的；halo、ripple、mesh、interference、constellation、cascade、GPU 版 caustics 和 contour，以及 mark 选项是 4.19.0 中新增的。请检查已安装的 asciify-engine/kit 是否导出了这些内容；如果没有，请升级（upgrading.md）。

背景

background(element, { preset }) 会将 asciify.org/backgrounds 上的每种背景绘制为 GPU 字形场景，采用网站的石墨色墨迹，并跟随全局外观。按名称导入预设；页面只需承担其导入的预设所需的开销。cursor: false 可关闭这些预设的指针响应。关于每种背景适合哪种界面，以及如何让效果保持平和，请参阅 applying-asciify.md。

import { background, swell } from 'asciify-engine/kit';
const bg = background(pricing, { preset: swell, clear: pricingCopy });

12 个精选预设，按导出名称 → id（名称）列出，全部使用 GPU 字形场（WebGL2，共享上下文预算）：swell（Swell，点或字符）、drift（Drift）、halo（Halo）、caustics（Caustics）、contour（Contour）、ripple（Ripple）、mesh（Mesh）、interference（Interference）、constellation（Constellation）、cascade（Cascade）、wordField → field（Field）、fluid（Fluid）。

已停用的预设（aurora、halftone、dna、circuit、fire、grid、morph、noise、pulse、rain、silk、stars、terrain、veil、voidWell、wave、weave、dune、etch、facet、moire）仍会导出，并标记为 @deprecated，以确保旧代码继续运行；新代码中请勿使用它们。kit.md 列出了每个预设的替代项。fieldBackground 是单独的：其 hero、brand 和 notFound 预设分别对应 asciify.org 的 hero 背景、同一背景的品牌色版本，以及 404 页面。

从 asciify.org/backgrounds 下载的模板（例如从本地 ./wave.js 导入的 asciiBackground）在包含这些模板的应用中仍可正常工作，但网站已不再提供这些模板；请将这类应用迁移到最接近的 background() 预设（kit.md 列出了每个预设的对应项）。

安装 Agent 技能

npx skills add ayangabryl/asciify-engine --skill asciify-engine

这会使用 Vercel Skills CLI 安装仓库技能及其链接资源。npm 依赖和已安装的 Agent 技能需要分别更新。如果有人要求更新 Asciify，或某项集成需要更新的选项，请遵循 references/upgrading.md：检查 npm 当前的 latest 版本，使用项目的包管理器更新，然后仅在已安装的作用域中刷新此技能。请勿将本文档中经过测试的版本视为始终最新，也不要升级无关的技能或依赖项。

交接前验证

对于工具包相关工作，请按照 applying-asciify.md 末尾的清单进行检查。对于任何集成，请检查实际页面：两种主题下主体和文本均清晰可读，没有拉伸或意外边距，指针和键盘控制正常，移动端裁切合理，减少动态效果设置有效，自动播放失败时行为正常，关闭 WebGL 后页面仍可用，并且导航后能正确清理。观察动态效果运行数秒，并检查循环边界。报告任何 FPS 数值时，请说明测量所用设备和设置；仅凭截图无法证明性能。关于引擎对宿主页面的保证以及默认预算，请参阅 performance.md。

请勿导入不存在的辅助函数，例如 createRecorder 或 recordAndDownload。

高级：底层 API

当需求涉及媒体转换、艺术风格或导出，或效果超出工具包所能提供的范围时，请使用这些 API。它们不会为你处理主题墨色、海报、上下文预算或回退方案；结果仍须遵循 applying-asciify.md 中的规则。

选择集成方式

对于实时项目组件，请从 project-integration.md 开始：它会将每种使用场景映射到一个渲染管线，说明实例所有权，并确保 PNG/视频导出与实时播放相互独立。新建包含艺术风格、蒙版、背景和已保存设置的构图时，请使用 /studio。它已负责悬停/动态效果；不要再叠加另一个 /hover 实例。

• 静态图像：asciify(source, canvas, config) 会返回 Promise<() => void>。卸载时调用清理函数，静态图像也不例外。
• 视频：asciifyVideo(source, canvas, config) 会返回 Promise<() => void>。卸载时调用该函数。全幅英雄区使用 fitTo 和 objectFit: 'cover'；展示完整主体的预览使用 contain。
• GIF：asciifyGif(source, canvas, config) 会异步返回清理函数。
• 密集型自定义渲染：使用 imageToAsciiTextFrame 和 renderTextFrameToCanvas；转换和渲染时使用相同的选项。需要逐单元格修改时，使用对象帧。

如需了解通过 ASCII 叠加 HTML 的英雄区，请阅读 references/layered-hero.md，并使用配套的 HTML、CSS 和 JavaScript。这些是普通的 Vite/打包器输入，不是额外的 npm 依赖。请提供自己的媒体素材。

有关裁剪、滚动、React 生命周期和底层 API 的详情，请阅读 references/media-api.md。

从清晰易读的源素材开始

使用普通图像或视频素材，再用 Asciify 转换。不要让图像/视频生成器预先渲染 ASCII。暗色主体搭配细窄高光通常会变成轮廓；切换为全彩也无法恢复缺失的中间调。优先选择易于辨认的主体、宽阔的受光表面、受控的高光和稳定的取景。

请有意选择颜色：

• fullcolor：保留源素材颜色；不要预先将源像素转换为灰度。
• grayscale：灰色字符。
• accent：通过 accentColor 使用单一品牌色。
• matrix：绿色效果。

从 fontSize: 7、fps: 24 或 30，以及 maxRenderDimension: 960 左右开始。这些只是初始预算，并不保证达到相应 FPS。检查实际视口和目标硬件后，再增加细节。对于色调平坦的源素材，必要时使用 normalize: true；对于已调色的视频，请与 false 对比，因为逐帧归一化可能会改变画面效果。

import { asciifyVideo } from 'asciify-engine';
const stop = await asciifyVideo('/hero.mp4', canvas, {
  fitTo: hero,
  objectFit: 'cover',
  objectPosition: 'center',
  fontSize: 7,
  fps: 24,
  maxRenderDimension: 960,
  options: {
    charset: ' .:-=+*#%@',
    colorMode: 'fullcolor',
    normalize: false,
    animationStyle: 'none',
    hoverStrength: 0,
  },
});
// On unmount: stop();

自定义字符

options.charset 是密度渐变字符集。customText 会重复一个字符串，是另一项功能。要在保留明暗符号的同时融入品牌字符，请构建如下渐变字符集：

const letters = [...new Set('ASCIIFY'.toUpperCase().replace(/[^A-Z]/g, ''))].join('');
const charset = ` .:-=+${letters}#%@`;

预览效果：不同字形的密度各异，因此任意词语不会自动成为排序均匀的渐变字符集。如果用户希望用自己的名字绘制作品，工具包的 wordmark 或 wordField 背景即可实现；在原始 /field 上，将词语放在较稀疏的渐变字符集之后（' .,:-+' + word），使用一种墨色并设置 shade: 1，让亮度呈现图像（参见 design-matching.md）。保留开头的空格以及表示明亮/浓密的符号。适用时，请使用 /core 中经过整理的 CHARACTER_SETS.standard.chars、detailed.chars、blocks.chars 或 braille.chars。

引擎效果与工作室效果

核心 HoverEffect ID 包括 spotlight、magnify、repel、glow、colorShift、attract、shatter、trail 和 glitchText。这些仍是有效 API，但与当前网站增强后的交互并不完全相同。

网站通过可选的工作室表面模块提供 Trail、Dissolve、Contour、Emboss、Ripple rings、Ink bleed、Water、Silk、Vortex、Magnetic Pull、Scatter、Elastic、Lens wake、Smudge、Loupe、Reveal、Repel、Tilt、Heat haze 和 Off，每种效果都支持 scope: 'all' | 'subject' | 'outside'，可将效果限制在抠出的主体上或主体周围（rake 已弃用，显示为 Silk）。其十种感知图像内容的静态图像动态效果——Relight、Specular sweep、Highlight bloom、Glints、Parallax、Slow push、Focus pull、Mist、Drift、Develop——会读取图像自身的光照和深度信息（已弃用的 ID（如 caustics）会加载最接近的替代效果），这些效果与精细抖动处理都包含在同一个 asciify-engine/hover 模块中。请使用其类型化选项，不要将显示名称转换为引擎的 hoverEffect 或 animationStyle 值。

如需复现这些交互，请阅读 references/studio-effects.md。从 asciify-engine/hover 导入 mountHover；无需单独下载。使用该模块时，请将引擎的 hoverStrength: 0 和 animationStyle: 'none' 保持不变，以免叠加两种效果。Trail 是网站的默认效果。用户希望产生尾迹但不发生空间位移时，优先选择 Trail 或 Dissolve 等网格位置固定的效果。

如果只使用内置悬停效果，请采用受支持的 options.hoverEffect 和适度的非零 hoverStrength；应验证其表现，不要承诺它与网站效果一致。

媒体艺术上的文本分层

对于界面底色，文本应置于清晰区域和磨砂遮罩上（applying-asciify.md）。对于需要让标题透过艺术图像清晰可读的媒体主视觉区，请使用真实的 HTML，并创建单一、独立的主视觉区层叠上下文：

1. 标题位于 z-index: 0。
2. 透明 ASCII 画布／舞台位于 z-index: 1。
3. 描述、CTA 和动态效果控件位于 z-index: 2 或更高。

将这些内容作为同级图层。经过变换或隔离的内容包装器可能会使其所有后代元素都被限制在画布下方。将装饰性图稿设为 pointer-events: none；如需启用悬停输入，请将其附加到定位后的主视觉区容器。确保控件可点击、可聚焦且不会被视觉遮挡。让画布背景保持透明；不透明的画布或舞台会遮住其下方的标题。若阅读效果更佳，也可以将图稿置于所有文本后方。

性能与生命周期

• 在降低源视频播放帧率之前，先缩小处理尺寸并减少单元格数量。不要默认将 24 fps 视频设为 60 fps。
• 视频从 24–30 fps 开始，处理尺寸上限设为 720–960px。增加处理像素并不会凭空产生源视频中没有的细节。
• 用户要求制作流畅的高帧率主视觉时，优先使用 kit 或 /field，而不是 canvas 管线，并将 canvas 管线保留为备用方案。
• 保持 canvas 尺寸稳定；仅在布局发生变化时调整大小，不要在每个动画帧都调整。
• 避免在指针移动或每次 React 渲染时重新挂载渲染器。
• 媒体移出视口或文档隐藏时暂停播放。对于减少动态效果的用户，应显示静态画面；不要只用 CSS 隐藏仍在播放的视频。
• 为异步初始化添加保护：如果组件在 API 返回前卸载，应立即调用 API 返回的清理函数。处理加载失败时，不要移除 HTML 内容或 CTA。
• 根据 ASCII 采样需求的合适分辨率压缩媒体，移除未使用的音频，使用 fast-start MP4，并提供小尺寸海报图。不可变缓存需要带内容哈希的 URL；此技能的 URL 应保持可重新验证。
• 精细抖动可以增加纹理，但在动态画面中可能产生闪烁。对比静态画面和循环动画，并提供无抖动渲染版本。
• YouTube 页面 URL 和 iframe 播放器不能直接作为 canvas 视频源。请使用符合许可要求且支持合适 CORS 的直接媒体文件；参见 https://asciify.org/docs/youtube。
• 如需确定性地导出构图，请使用 /studio。如需录制现有交互式 canvas，请使用浏览器的 MediaRecorder，并选择受支持的 canvas.captureStream() 格式，同时清理其轨道；如需截取快照，请检查已发布的 captureSnapshot / snapshotAndDownload 类型。

主视觉润饰

/hover 支持文字形状的木炭色镂空（textMask）、边缘扫描线／色边控制（edgeEffect）、固定强调色墨水、Prism 边缘柔化（edgeSoftness）以及固定网格流体 Trail。请参阅完整 API、图层示例、生命周期和回退方案限制。

Studio 构图与导出

如需制作具有现成风格的成品艺术作品（壁纸、海报、封面、印刷品），请从 references/looks.md 开始：其中包含 22 种风格，每种都提供提示词、精确设置，以及壁纸／海报／循环动画的导出尺寸。如需可选的壁纸／背景、备用渲染器、调色板、蒙版、已保存风格、文字字体或确定性 MP4/GIF 导出，请阅读 references/studio-workspace.md。/studio 与 /hover 和 AsciiOptions 相互独立；不要仅为添加背景而替换现有的主视觉管线。

GPU 字形场

kit 基于 asciify-engine/field 中的 mountGlyphField 构建。仅当 kit 没有提供所需风格选项时，才直接使用它；并请阅读 references/glyph-field.md 和 components.md 末尾的原始字段辅助函数。它会在 WebGL2 上从图像、视频或生成的动态效果中绘制字形渐变（包括单词和盲文），并带有流体尾迹。它不能取代 /studio，因为 /studio 支持 24 种渲染风格、抖动、印刷风格、特效和导出。请检查 isGlyphFieldSupported()，提供海报图和回退方案，遵循减少动态效果偏好，并在卸载时调用 destroy()。如需使用 kit 的底层机制构建自己的组件，请改用 mountSurface（kit.md）。

当前目录

如果要在单个实时组件中使用多个媒体／文本图层，请使用 4.8+ 的 mountStudioProject，并阅读 layered-projects.md。它会为最多八个可独立设置样式的图层共享一个播放循环和渲染预算。将源键与媒体分开保存，并使用 exportStudioProject 分别导出。不要为每个图层创建一个已挂载的 Studio 实例，也不要将可访问的界面文本栅格化。

旧版 CHARSETS、ART_STYLE_PRESETS、CHARSET_SEQUENCES、LIVING_STYLE_PRESETS 及其键类型已移除。不要导入它们，也不要生成 Katakana、Binary、Waves 或 Smoke 等旧名称。渲染样式选择器和 /studio 渲染请使用 24 个 STUDIO_STYLES。对于仅含 ASCII 字符的字符渐变，请使用 /core 中的 CHARACTER_SETS 或 /studio 中的 STUDIO_CHARACTER_SETS；仍支持自定义 Unicode 和用户提供的帧数组。Core 的 artStyle 仅接受 classic；请使用显式选项，而不要使用预设快捷方式。尽管请求的版本号是 4.1.0，迁移这些已移除的 API 属于破坏性变更。

版本说明

如果已安装的版本低于经过测试的版本，或者用户指定了某项功能，请阅读这些说明。

精细抖动与创意控制（4.2）

Studio 新增 hex、led 和 cmyk 渲染样式、方向性／径向抖动模式、其他调色板、亮度映射、RGB 分离、锐化，以及可调节的静态图像动态强度。有关确切选项、密度预算以及预览／导出一致性，请阅读 studio-workspace.md。这些是本地 Canvas/WebGL 效果，不是 AI 生成，也不意味着与所有竞品目录功能相同。

从 4.5 起，dither.algorithm: 'blue-noise' 使用预先计算的分散阈值平铺图，与白噪声 noise 分开。Studio 的 color 还接受 blackPoint、whitePoint、gamma、shadows 和 highlights，可在转换前调整细节。这些选项默认均为中性。添加这些控制项前，请阅读 tonal detail and blue noise；它们属于 /studio，不属于 core AsciiOptions。

从 4.6 起，Studio 新增 color.curves（RGB、red、green、blue）以及可选的保边 color.denoise。更新后，player.settings 会返回一个分离的快照，供保存或导出使用。有关点数限制、更新语义和处理预算，请阅读 channel curves and source noise。不要默认开启降噪，也不要对已渲染的字符再次应用降噪。

从 4.7 起，Studio 支持最多八个按顺序排列的源变形：Twirl、Pinch、Spherize、Ripple、Zigzag、Shear、Smudge、Polar 和 Fragment。请根据 STUDIO_WARPS 构建控制项，保留数组顺序，并阅读 source shaping 了解边界、Alpha／边缘策略及缓存映射性能。这些功能会调整源图像；要让静态图像动起来，请使用 motion.type，要实现指针交互，请使用 hover.effect。两者应保持独立，默认使用空的变形堆栈。

从 4.9 起，可选的 Studio 新增 Stipple、Engraving、Crosshatch、Woodblock、Risograph 和 Pointillism，并配有共享的 print 设置组。有关确切控制项、浅墨／深墨极性、静态动态集成和密集渲染限制，请阅读 print and illustration。这些是新增的实际渲染路径；不要用抖动预设替代它们的 ID。

生动图像与交互入门方案（4.10）

STUDIO_ANIMATION_PRESETS 通过 /studio 和 /hover 提供六组可编辑的动态／悬停配对。将 motion 和 hover 应用于现有 Studio 播放器，以保留源图像和艺术样式；不要将这些配对视为额外的艺术样式。有关新增 ID、循环限制和实时组件示例，请阅读 studio-effects.md。

GPU 字形场（4.11）和工具包（4.13）

asciify-engine/field 在 4.11 中新增了 mountGlyphField、isGlyphFieldSupported 和 glyphFieldTier；在 4.12 中新增了 mark、clear 和 pulse()。asciify-engine/kit 于 4.13 推出；随后加入 background() 及其预设、lazy、poster、上下文预算和全局外观。较旧的安装版本不包含这些条目；使用前请先升级。

场景提示词

使用 scenario-prompts.md 获取可直接复制的需求说明，涵盖图像、英雄区域、角色、所有样式、抖动、背景、视频/GIF、滚动、图层、文本、导出、框架、程序化轨迹、参考匹配、故障排除、升级、已保存外观和无障碍。根据用户意图调整提示词；不要添加无关功能。使用已发布渲染器原生的 Trail；不要添加单独的色调丝带叠加层。