Back to Details

asciify-engine

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Asciify Engine

Asciify 引擎

Use the published 
asciify-engine
npm package. Tested against 4.32.8. Check the application's installed version and its public types before using newer options; a local checkout can contain unpublished changes.
sh
npm install asciify-engine@latest
Entries: 
/kit
for interface components and backgrounds, one call each; 
asciify-engine
and 
/core
for media and text conversion; 
/hover
for the website hovers and living-image motion; 
/studio
for art styles, looks and export; 
/field
for raw GPU character fields. Each optional entry loads only when imported. GIF decoding loads 
gifuct-js
when a GIF API is called.
使用已发布的 
asciify-engine
npm 包。以 4.32.8 版本完成测试。在使用较新的选项前，请检查应用安装的版本及其公开类型；本地 checkout 可能包含尚未发布的更改。
sh
npm install asciify-engine@latest
入口：
/kit
用于界面组件和背景，每次只需调用一次；
asciify-engine
和 
/core
用于媒体及文本转换；
/hover
用于网站悬停效果和动态图像动效；
/studio
用于艺术风格、Looks 和导出；
/field
用于原始 GPU 字符场。每个可选入口仅在导入时加载。调用 GIF API 时，GIF 解码器会加载 
gifuct-js
。

Start here: kit first

从这里开始：先用 kit

Most requests are a feeling ("make the loading state feel alive", "a calm background behind pricing", "like asciify.org") rather than an API. Work in this order:
  1. Is it a UI component or a background? Almost always, yes. Read applying-asciify.md (the house design: when characters earn a place, ink, the clear zone and veil, density, radii, motion, performance, accessibility, which background suits which surface), then take the call from components.md and its options from kit.md. Stop there unless the kit has no option for the look.
  2. Read the request. Subject (their media, a word, or nothing), placement (hero, card, control, background behind text), mood words, interaction, any reference site.
  3. Read the design. Open the project's tokens: ground and surface colours, text colours, the one accent, mono and display fonts, radii, light and dark themes, motion durations and easing, reduced-motion handling. Map the kit's ink tokens (
    --ascii-ink
    , 
    --ascii-ink-strong
    , 
    --ascii-success
    , 
    --ascii-warning
    , 
    --ascii-error
    ) onto them; never add a brand colour.
  4. Decide living or still. Follow the user's words; keep art behind text, in grids and in data views still; reduced motion always gets a still. See living or still.
  5. Say what you chose in one line and offer one alternative. Ask only when the media is missing or motion would be new to a site that has none.
design-matching.md maps mood words to settings for the lower-level APIs and media looks.
The user wantsUse
A UI component in characters: button loading, status, toasts, tabs, pills, odometer, chart, AI thinking and streaming, transitions, sign-in, pricing, 404; event-site pieces (scrambling headers and headlines, morphing hatched heroes, dithered glows, a dotted globe, two-tone photos, assembling wordmarks, a spray cursor); an ASCII ocean of swimming creatures; interactive backgrounds visitors stir, grow and ripple
asciify-engine/kit
(applying-asciify.md, components.md, kit.md)
A background behind a hero, pricing, docs or a section, light or darkKit 
fieldBackground(el, { preset: 'hero', clear })
(asciify.org's hero) or 
background(el, { preset, clear })
with one of the 12 curated presets below
Their word or brand in charactersKit 
wordmark
, or 
background()
with 
wordField
Their video in characters on the pageKit 
asciiVideo
Their photo, video or GIF converted, optionally answering the cursorAdvanced: 
asciify
/ 
asciifyVideo
/ 
asciifyGif
, plus 
mountHover
from 
/hover
A full-bleed field with a look the kit has no option forAdvanced: 
mountGlyphField
from 
/field
(glyph-field.md)
Their photo or video as finished artwork in a named look: a wallpaper, poster, cover, print or hero artwork ("newsprint", "riso", "phosphor", "engraving", "Lego")
mountStudio
/ 
exportStudio
from 
/studio
with a look from looks.md
Art styles, saved looks, masks, effects, PNG/MP4/GIF exportAdvanced: 
mountStudio
from 
/studio
(studio-workspace.md)
Several media and text layers in one artworkAdvanced: 
mountStudioProject
from 
/studio
(layered-projects.md)
A text banner or letteringAdvanced: 
asciifyText
/ 
renderTextToCanvas
Headline text visible through media artAdvanced: layered HTML (layered-hero.md)
大多数需求表达的是一种感觉（“让加载状态仿佛活起来”“在定价页背后营造平静背景”“像 asciify.org 那样”），而不是指定某个 API。按以下顺序处理：
  1. 它是 UI 组件还是背景？ 几乎总是两者之一。阅读 applying-asciify.md（这套官方设计规范涵盖何时适合使用字符、墨色、清晰区域与遮罩、密度、圆角、动效、性能、无障碍，以及哪种背景适合哪种界面），然后根据 components.md 选择调用方式，并从 kit.md 查看选项。除非 kit 没有相应的 Look 选项，否则无需继续深入。
  2. 阅读请求。 了解主体（对方的媒体、一个词，或没有主体）、放置位置（hero、卡片、控件、文字背后的背景）、情绪词、交互方式，以及任何参考网站。
  3. 阅读设计。 打开项目的设计 token：基础色和表面色、文字颜色、唯一的强调色、等宽字体和展示字体、圆角、明暗主题、动效时长与缓动，以及 reduced motion 处理方式。将 kit 的墨色 token（
    --ascii-ink
    、
    --ascii-ink-strong
    、
    --ascii-success
    、
    --ascii-warning
    、
    --ascii-error
    ）映射到这些 token；绝不添加品牌色。
  4. 决定使用动态还是静态效果。 根据用户的措辞决定；位于文字后方的艺术元素、网格中的艺术元素以及数据视图中的艺术元素应保持静态；对于 reduced motion 用户始终提供静态版本。参见 living or still。
  5. 用一行说明你的选择，并提供一个替代方案。 仅在媒体缺失，或某站点此前没有动效而此次需要加入动效时提问。
design-matching.md 将情绪词映射到底层 API 和媒体 Look 的设置。
用户想要使用
字符形式的 UI 组件：按钮加载、状态、Toast、标签页、药丸、里程表、图表、AI 思考与流式输出、转场、登录、定价、404；活动站点元素（扰乱式标题和主标题、变形剖面线 hero、抖动光晕、点阵地球、双色照片、组装式字标、喷溅光标）；由游动生物组成的 ASCII 海洋；访客可搅动、生长并激起涟漪的交互背景
asciify-engine/kit
（applying-asciify.md、components.md、kit.md）
hero、定价、文档或某个区块背后的明色或暗色背景Kit 
fieldBackground(el, { preset: 'hero', clear })
（asciify.org 的 hero），或使用下方 12 个精选 preset 之一的 
background(el, { preset, clear })
用字符呈现对方的文字或品牌Kit 
wordmark
，或搭配 
wordField
的 
background()
在页面上用字符呈现对方的视频Kit 
asciiVideo
将对方的照片、视频或 GIF 转换为字符，并可选地响应光标高级用法：
asciify
/ 
asciifyVideo
/ 
asciifyGif
，以及来自 
/hover
的 
mountHover
使用 kit 没有提供相应选项的 Look 的全屏字形场高级用法：来自 
/field
的 
mountGlyphField
（glyph-field.md）
将对方的照片或视频制作成采用指定 Look 的完整作品，如壁纸、海报、封面、印刷品或 hero 作品（“newsprint”“riso”“phosphor”“engraving”“Lego”）来自 
/studio
的 
mountStudio
/ 
exportStudio
，并采用 looks.md 中的 Look
艺术风格、保存的 Look、遮罩、特效以及 PNG/MP4/GIF 导出高级用法：来自 
/studio
的 
mountStudio
（studio-workspace.md）
在一件作品中组合多个媒体和文字图层高级用法：来自 
/studio
的 
mountStudioProject
（layered-projects.md）
文本横幅或艺术字高级用法：
asciifyText
/ 
renderTextToCanvas
可透过媒体艺术看到的主标题文字高级用法：分层 HTML（layered-hero.md）

The kit in one paragraph

用一段话概括 kit

Each kit function mounts an 
aria-hidden
field over or inside your element, follows its size and border radius, inks it from your theme in light and dark, pauses off screen, honours reduced motion, falls back without WebGL2 to an inert handle that leaves your HTML working, and cleans up on 
destroy()
. components.md has 37 components as short snippets with the prompt a person gives, in categories Components, AI, Text, Transitions, Media, Pages and Backgrounds. In React, create the handle in an effect and return its 
destroy
.
ts
import { beam } from 'asciify-engine/kit';
const b = beam(card, { palette: 'mono', mode: 'pulse' });
// On unmount: b.destroy();
background()
, its presets, 
lazy
, 
poster
, 
setFieldBudget
and 
setGlobalLook
are new in 4.14.0; 
halo
, 
ripple
, 
mesh
, 
interference
, 
constellation
, 
cascade
, the GPU 
caustics
and 
contour
, and the 
mark
option are new in 4.19.0. Check that the installed 
asciify-engine/kit
exports them; if not, upgrade (upgrading.md).
每个 kit 函数都会在目标元素上方或内部挂载一个 
aria-hidden
字段，跟随元素的尺寸和圆角，依据应用的明暗主题着色，在元素离开屏幕时暂停，遵循 reduced motion，在没有 WebGL2 时回退到不执行渲染的句柄并保持 HTML 可用，并在调用 
destroy()
时清理资源。components.md 以简短代码片段提供了 37 个组件及用户可直接使用的提示词，分类包括 Components、AI、Text、Transitions、Media、Pages 和 Backgrounds。在 React 中，应在 effect 中创建句柄并返回其 
destroy
。
ts
import { beam } from 'asciify-engine/kit';
const b = beam(card, { palette: 'mono', mode: 'pulse' });
// On unmount: b.destroy();
background()
、它的 presets、
lazy
、
poster
、
setFieldBudget
和 
setGlobalLook
是 4.14.0 新增的；
halo
、
ripple
、
mesh
、
interference
、
constellation
、
cascade
、GPU 
caustics
和 
contour
，以及 
mark
选项是 4.19.0 新增的。请检查已安装的 
asciify-engine/kit
是否导出了这些 API；如果没有，请升级（upgrading.md）。

Backgrounds

背景

background(element, { preset })
draws every background on asciify.org/backgrounds as a scene of the GPU glyph field, in the site's graphite inks and following the global look. Import presets by name; a page pays only for those it imports. 
cursor: false
turns the pointer response off for any of them. Which one suits which surface, and how to keep it calm, is in applying-asciify.md.
ts
import { background, swell } from 'asciify-engine/kit';
const bg = background(pricing, { preset: swell, clear: pricingCopy });
The 12 curated presets, as export → 
id
(name), all on the GPU glyph field (WebGL2, sharing the context budget): 
swell
(Swell, dots or characters), 
drift
(Drift), 
halo
(Halo), 
caustics
(Caustics), 
contour
(Contour), 
ripple
(Ripple), 
mesh
(Mesh), 
interference
(Interference), 
constellation
(Constellation), 
cascade
(Cascade), 
wordField
→ 
field
(Field), 
fluid
(Fluid).
The retired presets (
aurora
, 
halftone
, 
dna
, 
circuit
, 
fire
, 
grid
, 
morph
, 
noise
, 
pulse
, 
rain
, 
silk
, 
stars
, 
terrain
, 
veil
, 
voidWell
, 
wave
, 
weave
, 
dune
, 
etch
, 
facet
, 
moire
) are still exported and marked 
@deprecated
so old code runs; do not reach for them in new work. kit.md maps each to its replacement. 
fieldBackground
is separate: its 
hero
, 
brand
and 
notFound
presets are the asciify.org hero ground, the same ground in the brand colour, and the 404.
Templates already downloaded from asciify.org/backgrounds (
asciiBackground
from a local 
./wave.js
) keep working in apps that ship them, but the site no longer offers them; move those apps to 
background()
with the closest preset (kit.md maps each).
background(element, { preset })
会将 asciify.org/backgrounds 上的每一种背景绘制为 GPU 字形场中的一个场景，采用站点的石墨色墨迹，并遵循全局 Look。按名称导入 presets；页面只会承担实际导入项的开销。对任何 preset 设置 
cursor: false
即可关闭指针响应。哪种背景适合哪种界面，以及如何让背景保持平静，请参阅 applying-asciify.md。
ts
import { background, swell } from 'asciify-engine/kit';
const bg = background(pricing, { preset: swell, clear: pricingCopy });
这 12 个精选 preset 的导出名 → 
id
（名称）如下，全部基于 GPU 字形场（WebGL2，共享 context budget）：
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）。
已停用的 presets（
aurora
、
halftone
、
dna
、
circuit
、
fire
、
grid
、
morph
、
noise
、
pulse
、
rain
、
silk
、
stars
、
terrain
、
veil
、
voidWell
、
wave
、
weave
、
dune
、
etch
、
facet
、
moire
）仍会导出并标记为 
@deprecated
，因此旧代码仍可运行；新工作不要使用它们。kit.md 提供了每个 preset 的替代项。
fieldBackground
是独立入口：它的 
hero
、
brand
和 
notFound
presets 分别对应 asciify.org 的 hero 背景、采用品牌色的相同背景，以及 404 背景。
从 asciify.org/backgrounds 下载的旧模板（来自本地 
./wave.js
的 
asciiBackground
）在随应用发布的代码中仍可使用，但网站已不再提供这些模板；应将相关应用迁移到 
background()
，并选择最接近的 preset（kit.md 提供了对应关系）。

Install the agent skill

安装 Agent skill

sh
npx skills add ayangabryl/asciify-engine --skill asciify-engine
This uses the Vercel Skills CLI to install the repository skill and its linked resources. The npm dependency and an installed agent skill update separately. When asked to update Asciify or when an integration needs newer options, follow references/upgrading.md: check npm's current 
latest
, update with the project's package manager, then refresh only this skill in its installed scope. Do not treat this document's tested version as permanently latest, or upgrade unrelated skills/dependencies.
sh
npx skills add ayangabryl/asciify-engine --skill asciify-engine
这会使用 Vercel Skills CLI 安装仓库中的 skill 及其链接资源。npm 依赖和已安装的 agent skill 分别更新。当用户要求更新 Asciify，或集成需要较新的选项时，请遵循 references/upgrading.md：检查 npm 当前的 
latest
，使用项目的包管理器进行更新，然后只在已安装范围内刷新此 skill。不要将本文档中经过测试的版本视为永久最新版，也不要升级无关的 skill 或依赖项。

Verify before handing off

交付前验证

Run the checklist at the end of applying-asciify.md for kit work. For any integration, check the real page: readable subject and text in both themes, no stretching or unintended margins, working pointer and keyboard controls, mobile crop, reduced motion, autoplay failure, WebGL off, and cleanup after navigation. Observe several seconds of motion and a loop boundary. State the measured device and settings with any FPS figure; screenshots alone do not establish performance. What the engine guarantees a host page, and its default budgets, are in performance.md.
Do not import nonexistent helpers such as 
createRecorder
or 
recordAndDownload
.
对于 kit 工作，请执行 applying-asciify.md 末尾的检查清单。对于任何集成，都应在真实页面上检查：明暗主题下的主体和文字均可读、没有拉伸或意外边距、指针和键盘控件正常工作、移动端裁剪正确、reduced motion 表现正确、自动播放失败时仍可使用、关闭 WebGL 时能够回退，并且导航后资源得到清理。观察数秒的动效以及一个循环边界。如提供任何 FPS 数据，应同时说明测试设备和设置；仅凭截图无法证明性能。引擎对宿主页面的保证及其默认预算请参阅 performance.md。
不要导入 
createRecorder
或 
recordAndDownload
等不存在的辅助函数。

Advanced: the lower-level APIs

高级：底层 API

Use these when the request is media conversion, art styles or export, or a field look the kit cannot give. They do not handle theme ink, posters, the context budget or fallbacks for you; the rules in applying-asciify.md still apply to the result.
当请求涉及媒体转换、艺术风格或导出，或者需要 kit 无法提供的字段 Look 时，使用这些 API。它们不会替你处理主题墨色、poster、context budget 或 fallback；但 applying-asciify.md 中的规则仍适用于最终结果。

Choose the integration

选择集成方式

For a live project component, start with project-integration.md: it maps each use case to one rendering pipeline, covers instance ownership, and keeps PNG/video export independent of live playback. Use 
/studio
for a new composition with art styles, masks, backdrops and saved settings. It already owns hover/motion; do not add another 
/hover
instance on top.
  • Static image: 
    asciify(source, canvas, config)
    returns 
    Promise<() => void>
    . Call the cleanup on unmount, including for a still image.
  • Video: 
    asciifyVideo(source, canvas, config)
    returns 
    Promise<() => void>
    . Call that function on unmount. Use 
    fitTo
    and 
    objectFit: 'cover'
    for full-bleed heroes; 
    contain
    for a whole-subject preview.
  • GIF: 
    asciifyGif(source, canvas, config)
    returns a cleanup function asynchronously.
  • Dense custom rendering: use 
    imageToAsciiTextFrame
    and 
    renderTextFrameToCanvas
    ; keep the same options when converting and rendering. Use object frames when per-cell mutation is required.
For a hero with HTML layered through the ASCII, read references/layered-hero.md and use the accompanying HTML, CSS, and JavaScript. These are ordinary Vite/bundler inputs, not another npm dependency. Supply your own media.
For crop, scroll, React lifecycle, and low-level API details, read references/media-api.md.
对于实时项目组件，请先阅读 project-integration.md：它会将每种用例映射到一条渲染管线，涵盖实例所有权，并确保 PNG 或视频导出独立于实时播放。使用 
/studio
创建带有艺术风格、遮罩、背景和保存设置的新构图。它已经负责 hover 和 motion；不要在其上再添加另一个 
/hover
实例。
  • 静态图片：
    asciify(source, canvas, config)
    返回 
    Promise<() => void>
    。组件卸载时应调用返回的清理函数，即使是静态图片也一样。
  • 视频：
    asciifyVideo(source, canvas, config)
    返回 
    Promise<() => void>
    。组件卸载时应调用该函数。对于全屏 hero，使用 
    fitTo
    和 
    objectFit: 'cover'
    ；若需要完整预览主体，则使用 
    contain
    。
  • GIF：
    asciifyGif(source, canvas, config)
    异步返回清理函数。
  • 密集自定义渲染：使用 
    imageToAsciiTextFrame
    和 
    renderTextFrameToCanvas
    ；转换和渲染时保持选项一致。需要逐单元格变更时，使用对象帧。
对于让 HTML 穿透 ASCII 显示的 hero，请阅读 references/layered-hero.md，并使用配套的 HTML、CSS 和 JavaScript。这些只是普通的 Vite 或 bundler 输入文件，并非另一个 npm 依赖。请自行提供媒体。
有关裁剪、滚动、React 生命周期和底层 API 的详细信息，请阅读 references/media-api.md。

Start with a readable source

从清晰可辨的源素材开始

Use ordinary images or footage, then convert them with Asciify. Do not ask an image/video generator to pre-render ASCII. A dark subject with thin highlights tends to become an outline; changing to full color cannot recover missing midtones. Prefer recognizable subjects, broad illuminated surfaces, controlled highlights, and stable framing.
Choose color intentionally:
  • fullcolor
    : preserve source colors; do not grayscale source pixels first.
  • grayscale
    : gray characters.
  • accent
    : a single brand color via 
    accentColor
    .
  • matrix
    : green treatment.
Start around 
fontSize: 7
, 
fps: 24
or 
30
, and 
maxRenderDimension: 960
. These are a starting budget, not an FPS guarantee. Increase detail only after checking the actual viewport and target hardware. Use 
normalize: true
for flat sources when helpful; compare it against 
false
on already graded video because frame-by-frame normalization may change the look.
js
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();
先使用普通图片或视频素材，再通过 Asciify 进行转换。不要让图片或视频生成器预先渲染 ASCII。主体较暗且只有细窄高光时，转换结果往往只剩轮廓；改为全彩也无法恢复缺失的中间调。优先选择容易辨认的主体、宽广且受光的表面、受控的高光和稳定的构图。
有意识地选择颜色：
  • fullcolor
    ：保留源颜色；不要先将源像素转换为灰度。
  • grayscale
    ：使用灰色字符。
  • accent
    ：通过 
    accentColor
    使用单一品牌色。
  • matrix
    ：使用绿色处理效果。
初始设置可从 
fontSize: 7
、
fps: 24
或 
30
以及 
maxRenderDimension: 960
入手。这些只是起始预算，并不保证 FPS。只有在检查实际视口和目标硬件后，才能提高细节量。对于平面素材，可在有帮助时使用 
normalize: true
；对于已经调色的视频，应将其与 
false
进行比较，因为逐帧归一化可能改变视觉效果。
js
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();

Custom letters

自定义字母

options.charset
is the density ramp. 
customText
repeats a string and is a different feature. To incorporate a brand's letters while retaining shading symbols, build a ramp such as:
js
const letters = [...new Set('ASCIIFY'.toUpperCase().replace(/[^A-Z]/g, ''))].join('');
const charset = ` .:-=+${letters}#%@`;
Preview it: letter glyph densities differ, so arbitrary words are not automatically an evenly ordered ramp. When the user wants the artwork drawn in their name, the kit's 
wordmark
or 
wordField
background does it; on raw 
/field
, put the word after a quiet ramp (
' .,:-+' + word
), use one ink with 
shade: 1
, and let brightness carry the image (see design-matching.md). Keep the leading space and the light/dense symbols. Use the curated 
CHARACTER_SETS.standard.chars
, 
detailed.chars
, 
blocks.chars
, or 
braille.chars
from 
/core
when appropriate.
options.charset
是密度 ramp。
customText
会重复一个字符串，属于另一项功能。若要在保留明暗符号的同时融入品牌字母，可以构建如下字符集：
js
const letters = [...new Set('ASCIIFY'.toUpperCase().replace(/[^A-Z]/g, ''))].join('');
const charset = ` .:-=+${letters}#%@`;
请先预览：不同字形的密度不同，因此任意单词不会自动形成按密度均匀排序的 ramp。当用户希望作品用其名字绘制时，使用 kit 的 
wordmark
或 
wordField
背景；在原始 
/field
中，将单词放在低密度 ramp（
' .,:-+' + word
）之后，使用一种墨色并设置 
shade: 1
，让亮度承载图像效果（参见 design-matching.md）。务必保留开头的空格以及由浅到密的符号。适合时，使用 
/core
提供的精选 
CHARACTER_SETS.standard.chars
、
detailed.chars
、
blocks.chars
或 
braille.chars
。

Engine effects versus studio effects

引擎特效与 Studio 特效

The core 
HoverEffect
IDs are 
spotlight
, 
magnify
, 
repel
, 
glow
, 
colorShift
, 
attract
, 
shatter
, 
trail
, and 
glitchText
. Those remain valid APIs, but they are not identical to the current website's enhanced interactions.
The website offers Trail, Dissolve, Contour, Emboss, Ripple rings, Ink bleed, Water, Silk, Vortex, Magnetic Pull, Scatter, Elastic, Lens wake, Smudge, Loupe, Reveal, Repel, Tilt, Heat haze, and Off through an optional studio surface module, each with 
scope: 'all' | 'subject' | 'outside'
to keep it on a cut-out subject or around it (
rake
is retired and plays Silk). Its ten photo-aware still-image motions—Relight, Specular sweep, Highlight bloom, Glints, Parallax, Slow push, Focus pull, Mist, Drift, Develop—read the image's own light and depth (retired IDs such as 
caustics
load as their closest replacement), and they and the fine-dither treatments ship in the same 
asciify-engine/hover
module. Use its typed options rather than converting display names into engine 
hoverEffect
or 
animationStyle
values.
To reproduce those interactions, read references/studio-effects.md. Import 
mountHover
from 
asciify-engine/hover
; no separate download is needed. Keep engine 
hoverStrength: 0
and 
animationStyle: 'none'
when using it, to avoid applying two effects. Trail is the site's default. Prefer a stationary-grid effect such as Trail or Dissolve when the user wants a wake without spatial displacement.
For built-in hover alone, use a supported 
options.hoverEffect
and a restrained nonzero 
hoverStrength
; validate its behavior instead of promising that it matches the website.
核心 
HoverEffect
ID 包括 
spotlight
、
magnify
、
repel
、
glow
、
colorShift
、
attract
、
shatter
、
trail
和 
glitchText
。这些仍是有效 API，但与当前网站增强后的交互并不完全相同。
网站通过可选的 studio surface 模块提供 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 这类固定网格效果。
如果只需要内置 hover，请使用受支持的 
options.hoverEffect
和克制的非零 
hoverStrength
；应验证其实际行为，而不能承诺它与网站效果完全一致。

Text layering over media art

在媒体艺术上叠加文字

For interface grounds, text sits on a clear zone and a frosted veil (applying-asciify.md). For a media hero where the headline should read through the artwork, use real HTML and a single isolated hero stacking context:
  1. Headline at 
    z-index: 0
    .
  2. Transparent ASCII canvas/stage at 
    z-index: 1
    .
  3. Description, CTA, and motion controls at 
    z-index: 2
    or above.
Keep these as sibling layers. A transformed or isolated content wrapper can trap all its descendants below the canvas. Set decorative artwork to 
pointer-events: none
; attach optional hover input to the positioned hero host. Keep controls clickable, focusable, and visually unobscured. Leave canvas background transparent; an opaque canvas or stage hides the headline beneath it. Choose artwork behind all text when it reads better.
对于界面底图，文字应位于清晰区域和磨砂遮罩之上（applying-asciify.md）。对于需要让主标题透过艺术作品清晰可见的媒体 hero，请使用真实 HTML，并建立单一、独立的 hero 堆叠上下文：
  1. 主标题使用 
    z-index: 0
    。
  2. 透明的 ASCII canvas 或 stage 使用 
    z-index: 1
    。
  3. 描述、CTA 和动效控件使用 
    z-index: 2
    或更高层级。
这些元素应保持为同级图层。经过 transform 或包含独立堆叠上下文的内容容器，可能会将所有后代元素限制在 canvas 下方。将装饰性艺术设置为 
pointer-events: none
；可选的悬停输入应绑定到定位后的 hero 宿主元素。确保控件可点击、可聚焦，并且不会被视觉遮挡。canvas 或 stage 的背景应保持透明；不透明的 canvas 或 stage 会遮住下方的标题。如果将艺术作品放在所有文字后方更利于阅读，应优先采用这种方式。

Performance and lifecycle

性能与生命周期

  • Reduce processing dimensions and cell count before dropping source playback FPS. Do not default to 60 fps on a 24 fps video.
  • Start video at 24–30 fps with a 720–960px processing cap. More processing pixels do not create detail absent from the source.
  • When the user asks for a smooth, high-frame-rate hero, prefer the kit or 
    /field
    over a canvas pipeline, and keep the canvas pipeline as its fallback.
  • Keep stable canvas dimensions; resize on layout changes, not on every animation frame.
  • Avoid remounting the renderer on pointer movement or each React render.
  • Pause media offscreen and when the document is hidden. Reduced-motion users should get a still; do not merely hide a playing video with CSS.
  • Guard asynchronous setup: if a component unmounts before an API resolves, immediately call its returned cleanup. Handle loading failures without removing the HTML content or CTA.
  • Compress media at a resolution appropriate to ASCII sampling, remove unused audio, use fast-start MP4, and provide a small poster. Immutable caching requires a content-hashed URL; keep this skill's URL revalidatable.
  • Fine dithering can add texture but can shimmer on moving footage. Compare a still and a loop, and offer a non-dithered rendering.
  • YouTube page URLs and iframe players are not direct canvas video sources. Use permitted direct media files with suitable CORS; see https://asciify.org/docs/youtube.
  • For deterministic composition export, use 
    /studio
    . To record an existing interactive canvas, use a browser 
    MediaRecorder
    with a supported 
    canvas.captureStream()
    format and clean up its tracks; for snapshots, inspect the published 
    captureSnapshot
    / 
    snapshotAndDownload
    types.
  • 应先降低处理尺寸和单元格数量，再降低源视频的播放 FPS。不要在 24 fps 视频上默认使用 60 fps。
  • 视频应从 24–30 fps 启动，并将处理尺寸限制在 720–960px。增加处理像素并不会创造源素材中不存在的细节。
  • 当用户需要流畅的高帧率 hero 时，优先使用 kit 或 
    /field
    ，并将 canvas 管线作为回退方案。
  • 保持 canvas 尺寸稳定；仅在布局变化时调整尺寸，不要在每个动画帧都调整。
  • 避免在指针移动或每次 React 渲染时重新挂载渲染器。
  • 媒体离开屏幕或文档隐藏时应暂停。对于 reduced motion 用户，应提供静态效果；不要仅通过 CSS 隐藏正在播放的视频。
  • 防范异步初始化问题：如果组件在 API resolve 之前卸载，应立即调用其返回的清理函数。处理加载失败时，不要移除 HTML 内容或 CTA。
  • 将媒体压缩到适合 ASCII 采样的分辨率，移除未使用的音频，使用支持 fast-start 的 MP4，并提供较小的 poster。不可变缓存需要使用内容哈希 URL；应确保此 skill 的 URL 可重新验证。
  • 精细抖动可以增加纹理，但可能在动态素材上产生闪烁。请比较静态效果和循环效果，并提供不抖动的渲染方案。
  • YouTube 页面 URL 和 iframe 播放器不是可直接用于 canvas 的视频源。应使用允许访问且具备适当 CORS 配置的直接媒体文件；参见 https://asciify.org/docs/youtube。
  • 如需确定性的构图导出，请使用 
    /studio
    。如需录制现有的交互式 canvas，请使用浏览器 
    MediaRecorder
    以及受支持的 
    canvas.captureStream()
    格式，并清理其轨道；如需获取快照，请检查已发布的 
    captureSnapshot
    / 
    snapshotAndDownload
    类型。

Hero finish

Hero 收尾

/hover
supports text-shaped charcoal cutouts (
textMask
), peripheral scanline/fringe control (
edgeEffect
), fixed accent ink, Prism edge softness (
edgeSoftness
), and fixed-grid fluid Trail. See the complete API, layering example, lifecycle, and fallback limits.
/hover
支持文字形状的炭黑色镂空（
textMask
）、外围扫描线或色散控制（
edgeEffect
）、固定强调墨色、Prism 边缘柔化（
edgeSoftness
），以及固定网格流体 Trail。请参阅完整 API、分层示例、生命周期和回退限制。

Studio composition and export

Studio 构图与导出

For a finished artwork in a ready look (wallpaper, poster, cover, print), start from references/looks.md: 22 looks, each with the prompt, exact settings, and wallpaper/poster/loop export sizes. For optional wallpaper/backdrops, alternate renderers, palettes, masks, saved looks, text fonts, or deterministic MP4/GIF export, read references/studio-workspace.md. 
/studio
is separate from 
/hover
and 
AsciiOptions
; do not replace an existing hero pipeline just to add a backdrop.
对于要制作成壁纸、海报、封面或印刷品等完整作品的成品 Look，请从 references/looks.md 开始：其中包含 22 种 Look，每种都有提示词、精确设置以及壁纸、海报和循环导出尺寸。如需可选的壁纸或背景板、备用渲染器、调色板、遮罩、保存的 Look、文本字体或确定性的 MP4/GIF 导出，请阅读 references/studio-workspace.md。
/studio
独立于 
/hover
和 
AsciiOptions
；不要仅仅为了添加背景板就替换现有的 hero 管线。

GPU glyph fields

GPU 字形场

The kit is built on 
mountGlyphField
from 
asciify-engine/field
. Use it directly only for a look the kit has no option for, and read references/glyph-field.md and the raw-field helper at the end of components.md. It draws glyph ramps (including words and braille) from images, video or generated motion on WebGL2 with a fluid wake. It does not replace 
/studio
for the 24 render styles, dither, print styles, effects or export. Check 
isGlyphFieldSupported()
, provide a poster and a fallback, honour reduced motion, and call 
destroy()
on unmount. To build your own component with the kit's plumbing instead, use 
mountSurface
(kit.md).
kit 建立在 
asciify-engine/field
的 
mountGlyphField
之上。仅当需要 kit 没有提供相应选项的 Look 时，才应直接使用它；请阅读 references/glyph-field.md 以及 components.md 末尾的原始字段辅助函数。它会在 WebGL2 上根据图片、视频或生成的动效绘制字形 ramp，包括单词和盲文，并带有流体尾迹。它不能替代 
/studio
的 24 种渲染风格、抖动、打印风格、特效或导出功能。请检查 
isGlyphFieldSupported()
，提供 poster 和 fallback，遵循 reduced motion，并在卸载时调用 
destroy()
。如果希望使用 kit 的基础设施构建自己的组件，请使用 
mountSurface
（kit.md）。

Current catalogs

当前 API 目录

For multiple media/text layers in one live component, use 4.8+ 
mountStudioProject
and read layered-projects.md. It shares one playback loop and rendering budgets across up to eight independently styled layers. Persist source keys separately from media, and use 
exportStudioProject
for independent exports. Do not create one mounted Studio instance per layer or rasterize accessible interface text.
Legacy 
CHARSETS
, 
ART_STYLE_PRESETS
, 
CHARSET_SEQUENCES
, 
LIVING_STYLE_PRESETS
and their key types are removed. Do not import them or generate old names such as Katakana, Binary, Waves or Smoke. Use the 24 
STUDIO_STYLES
for render-style selectors and 
/studio
rendering. For ASCII-only character ramps use 
CHARACTER_SETS
from 
/core
or 
STUDIO_CHARACTER_SETS
from 
/studio
; custom Unicode and user-provided frame arrays remain supported. Core 
artStyle
only accepts 
classic
; use explicit options instead of preset shortcuts. Despite the requested 4.1.0 version number, migrating these removed APIs is a breaking change.
如需在一个实时组件中组合多个媒体和文字图层，请使用 4.8+ 的 
mountStudioProject
，并阅读 layered-projects.md。它最多可在八个独立样式的图层之间共享一个播放循环和渲染预算。应单独持久化 source key，使其与媒体分离，并使用 
exportStudioProject
进行独立导出。不要为每个图层创建一个已挂载的 Studio 实例，也不要将可访问的界面文字栅格化。
旧版 
CHARSETS
、
ART_STYLE_PRESETS
、
CHARSET_SEQUENCES
、
LIVING_STYLE_PRESETS
及其 key 类型均已移除。不要导入它们，也不要生成 Katakana、Binary、Waves 或 Smoke 等旧名称。使用 24 个 
STUDIO_STYLES
作为渲染风格选择器，并通过 
/studio
进行渲染。对于仅使用 ASCII 的字符 ramp，请使用 
/core
中的 
CHARACTER_SETS
或 
/studio
中的 
STUDIO_CHARACTER_SETS
；自定义 Unicode 和用户提供的帧数组仍然受支持。核心 
artStyle
仅接受 
classic
；请使用明确的选项，而不是 preset 快捷方式。尽管请求中指定的是 4.1.0 版本号，迁移这些已移除 API 仍属于破坏性变更。

Version notes

版本说明

Read these when the installed version is older than the tested one, or when a user names a specific feature.
当已安装版本低于经过测试的版本，或用户点名某项特定功能时，请阅读以下说明。

Fine dither and creative controls (4.2)

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

Studio adds 
hex
, 
led
, and 
cmyk
render styles, directional/radial dither patterns, additional palettes, luminance mapping, RGB split, sharpening, and adjustable still-image motion strength. Read studio-workspace.md for exact options, density budgets and preview/export consistency. These are local Canvas/WebGL effects, not AI generation or a claim of parity with every competing catalog.
From 4.5, 
dither.algorithm: 'blue-noise'
uses a precomputed dispersed threshold tile, separate from white 
noise
. Studio 
color
also accepts 
blackPoint
, 
whitePoint
, 
gamma
, 
shadows
and 
highlights
to shape detail before conversion. All are neutral by default. Read tonal detail and blue noise before adding these controls; they belong to 
/studio
, not core 
AsciiOptions
.
From 4.6, Studio adds 
color.curves
(RGB, red, green, blue) and optional edge-preserving 
color.denoise
. 
player.settings
returns a detached snapshot for saving or exporting after updates. Read channel curves and source noise for point limits, update semantics and the processing budget. Do not turn noise reduction on by default or apply it again to the already-rendered characters.
From 4.7, Studio supports up to eight ordered source warps: Twirl, Pinch, Spherize, Ripple, Zigzag, Shear, Smudge, Polar and Fragment. Build controls from 
STUDIO_WARPS
, retain array order, and read source shaping for bounds, alpha/edge policy and cached-map performance. These shape the source; use 
motion.type
to bring a still image to life and 
hover.effect
for pointer interaction. Keep them independent, with an empty warp stack by default.
From 4.9, optional Studio adds Stipple, Engraving, Crosshatch, Woodblock, Risograph and Pointillism with a shared 
print
settings group. Read print and illustration for exact controls, light-ink versus dark-ink polarity, still-motion integration and dense-render limits. These are genuine additional render paths; do not substitute dither presets for their IDs.
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
，而不是核心 
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，了解精确控件、浅色墨与深色墨的极性、静态动效集成方式和密集渲染限制。这些是真正新增的渲染路径；不要用抖动 preset 替代它们的 ID。

Lively images and interaction starting points (4.10)

动态图像与交互起点（4.10）

STUDIO_ANIMATION_PRESETS
provides six editable motion/hover pairings through 
/studio
and 
/hover
. Apply 
motion
and 
hover
to an existing Studio player to keep the source and art style; do not treat the pairings as additional art styles. Read studio-effects.md for exact new IDs, loop limits and the live component example.
STUDIO_ANIMATION_PRESETS
通过 
/studio
和 
/hover
提供六组可编辑的 motion/hover 配对。将 
motion
和 
hover
应用到现有的 Studio player，可保留源素材和艺术风格；不要把这些配对视为额外的艺术风格。请阅读 studio-effects.md，了解准确的新 ID、循环限制和实时组件示例。

GPU glyph fields (4.11) and the kit (4.13)

GPU 字形场（4.11）与 kit（4.13）

asciify-engine/field
adds 
mountGlyphField
, 
isGlyphFieldSupported
and 
glyphFieldTier
in 4.11; 
mark
, 
clear
and 
pulse()
in 4.12. 
asciify-engine/kit
arrives in 4.13; 
background()
and its presets, 
lazy
, 
poster
, the context budget and the global look follow it. Older installs do not have these entries; upgrade before using them.
4.11 为 
asciify-engine/field
新增 
mountGlyphField
、
isGlyphFieldSupported
和 
glyphFieldTier
；4.12 新增 
mark
、
clear
和 
pulse()
。
asciify-engine/kit
在 4.13 中推出；随后又加入 
background()
及其 presets、
lazy
、
poster
、context budget 和全局 Look。较旧的安装版本不包含这些入口；使用前请先升级。

Scenario prompts

场景提示词

Use scenario-prompts.md for copyable briefs covering images, heroes, characters, all styles, dither, backgrounds, video/GIF, scroll, layers, text, export, frameworks, procedural trails, reference matching, troubleshooting, upgrades, saved looks and accessibility. Adapt the prompt to the user's intent; do not add unrelated features. Use the published renderer's native Trail; do not add a separate tonal ribbon overlay.
请使用 scenario-prompts.md 获取可复制的任务简报，涵盖图片、hero、字符、所有风格、抖动、背景、视频/GIF、滚动、图层、文字、导出、框架、程序化尾迹、参考匹配、故障排查、升级、保存的 Look 和无障碍。根据用户意图调整提示词，不要添加无关功能。使用已发布渲染器原生的 Trail；不要额外叠加独立的色调 ribbon overlay。