Skip to content
Merged
24 changes: 16 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ Inspired by [Orta Therox](https://github.com/Orta). Thanks Orta for your outstan
| `text` | ❌ | `username` value | Text to display as collision obstacles |
| `output-path` | ❌ | `gravity.svg` | Path to write the generated SVG file |
| `font-size` | ❌ | `48` | Font size of the collision text |
| `compression-tolerance` | ❌ | `0.5` | Trajectory compression tolerance in SVG pixels. At every original moment, the animated position stays within this distance of the real one; `0` is lossless in both position and timing (see below) |
| `compression-tolerance` | ❌ | `0.5` | Trajectory compression tolerance in SVG pixels. At every original moment the animated position stays within this distance of the real one (per axis with CSS, combined offset with SMIL); `0` is lossless in both position and timing (see below) |
| `compression-algorithm` | ❌ | `Greedy` | Trajectory compression algorithm: `Greedy` (fast), `DP` (smallest SVG), `RDP` (fastest). See below for the trade-offs |
| `max-simulation-time` | ❌ | - | Maximum animation playback duration in seconds. Once reached, blocks freeze where they are instead of waiting for every block to settle. Leave empty to play until all blocks rest |
| `shape` | ❌ | `circle` | Shape of contribution blocks: `circle` or `square` |
Expand All @@ -62,10 +62,16 @@ Inspired by [Orta Therox](https://github.com/Orta). Thanks Orta for your outstan

### Reducing file size

The trajectory is compressed by default: `compression-tolerance` merges
trajectory points into keyframes so that, at every original moment, the interpolated
position stays within the given distance (in SVG pixels) of the real one — speed changes
such as bounces, landings and stops keep their real pace.
The trajectory is compressed by default: `compression-tolerance` merges trajectory
points into keyframes so that, at every original moment, the interpolated position
stays within the given distance (in SVG pixels) of the real one — speed changes such
as bounces, landings and stops keep their real pace.

With the CSS engine each axis is compressed independently: the bound applies to each
axis, constant axes (a block falling straight down barely moves horizontally) collapse
into static values, and a fast-spinning block no longer densifies the position
animation. SMIL keeps a shared position timeline, which uses slightly more keyframes
but produces a byte-identical output to earlier versions.

The default is invisible to the eye and already shrinks the output by orders of magnitude,
so most setups can keep it. Set `0` for a lossless trajectory — only uniform straight
Expand Down Expand Up @@ -97,12 +103,14 @@ same trajectory at the same pace:
The rendered animation is identical. Choose CSS when the target environment handles
SMIL poorly — some sanitizers strip SMIL animation elements, while CSS animation in
SVG is more widely supported (GitHub READMEs load SVGs via `<img>`, where both work).
The CSS output is slightly larger than SMIL.
The CSS output is usually smaller, since it compresses each axis (and the rotation)
independently and drops animations for axes that never move.

With `css: true`, the `animation` input replaces the animation declaration applied to
every block. Available variables:
every block. Each axis (x, y and rotation) gets its own copy of this declaration, with
`var(--n)` replaced by that axis' animation name. Available variables:

- `--n` — each block's keyframes name, required
- `--n` — placeholder for each axis' keyframes name, required
- `--dur` — the playback duration

⚠️ This value is spliced into the generated style block as-is — modify with caution,
Expand Down
16 changes: 10 additions & 6 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@
| `text` | ❌ | `username` 的值 | 作为碰撞障碍物的文字 |
| `output-path` | ❌ | `gravity.svg` | SVG 输出路径 |
| `font-size` | ❌ | `48` | 碰撞文字大小 |
| `compression-tolerance` | ❌ | `0.5` | 轨迹压缩容差(SVG 像素)。播放时每个原始时刻的动画位置与真实位置的偏差不超过该值;`0` 为完全无损(位置与节奏都精确)(见下文) |
| `compression-tolerance` | ❌ | `0.5` | 轨迹压缩容差(SVG 像素)。播放时每个原始时刻的动画位置与真实位置的偏差不超过该值(CSS 引擎按轴向各自保证,SMIL 按合成位移保证);`0` 为完全无损(位置与节奏都精确)(见下文) |
| `compression-algorithm` | ❌ | `Greedy` | 轨迹压缩算法:`Greedy`(快)、`DP`(体积最小)、`RDP`(最快),差异见下文 |
| `max-simulation-time` | ❌ | - | 动画最长播放时长(秒)。到时动画即止,方块停在当前位置,不再等待全部落定;留空则播放至全部静止 |
| `shape` | ❌ | `circle` | 贡献方块的形状(`circle` 或 `square`) |
Expand All @@ -62,8 +62,10 @@
### 减小文件体积

轨迹默认开启压缩:`compression-tolerance` 会把轨迹点合并为关键帧,保证播放时
每个原始时刻的插值位置与真实位置的偏差(SVG 像素)不超过阈值——碰撞、落地、停顿等速度
变化按真实节奏保留。
每个原始时刻的插值位置与真实位置的偏差(SVG 像素)不超过阈值——碰撞、落地、停顿等
速度变化按真实节奏保留。CSS 引擎按轴独立压缩:阈值按轴向各自生效,几乎不变的轴
(垂直下落的方块横向基本不动)会收缩为静态值,快速自转也不再让位置动画变密;
SMIL 保持共享的位置时间轴,关键帧略多,产物与旧版本逐字节一致。

默认值肉眼不可见,体积已经能小几个数量级,多数场景保留默认即可。设为 `0` 得到无损轨迹——
只有匀速直线段和静止段会被压缩;调大(如 `1.5`)压缩更狠,但轨迹会明显走样。
Expand All @@ -90,11 +92,13 @@

渲染出的动画完全一致。当目标环境对 SMIL 支持不佳时选 CSS——部分 sanitizer 会剥除
SMIL 动画元素,而 SVG 内的 CSS 动画支持面更广(GitHub README 以 `<img>` 加载 SVG,
两种引擎都能正常播放)。文件体积略大于 SMIL。
两种引擎都能正常播放)。CSS 产物体积通常更小:它按轴(以及自转)独立压缩,并省掉
从不移动的轴对应的动画。

`css: true` 时,`animation` 输入可替换作用在每个方块上的 animation 声明。可用变量:
`css: true` 时,`animation` 输入可替换作用在每个方块上的 animation 声明:每个轴
(x、y 与自转)各复制一份该声明,其中 `var(--n)` 替换为该轴的动画名。可用变量:

- `--n`:方块绑定的关键帧名,必须包含
- `--n`:各轴关键帧名的占位符,必须包含
- `--dur`:播放时长

⚠️ 该值会原样拼进生成的 style 块,谨慎修改,可能破坏动画效果,修改前先在
Expand Down
25 changes: 24 additions & 1 deletion __tests__/integration.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -336,7 +336,11 @@ describe('css animation engine', () => {
expect(circleSvg).not.toContain('fill="#')
expect(circleSvg).not.toContain('data-g')
expect(circleSvg).toContain('#b>circle{r:2px}')
expect(circleSvg).toContain('.g0{--n:g0}')
// 圆形只有 x/y 两个通道;单列数据下 x 全程恒定,折叠为静态值并关闭该动画
expect(circleSvg).toContain('.g0{--nx:none;--x:')
expect(circleSvg).toContain(';--ny:g0y}')
expect(circleSvg).not.toContain('--nr')
expect(circleSvg).not.toContain('@keyframes g0x')
// 每种颜色一条规则:规则数与唯一 class 数一致
const fillClasses = [
...new Set(
Expand All @@ -360,6 +364,25 @@ describe('css animation engine', () => {

expect(rectSvg).toContain('<rect class="f0 g0"/>')
expect(rectSvg).toContain('#b>rect{x:-2px;y:-2px;width:4px;height:4px}')
// 方形额外挂自转通道,走独立 keyframes 与独立时间轴
expect(rectSvg).toContain('--nr:g0r')
expect(rectSvg).toContain('@keyframes g0r{')
})

it('switches custom animation per channel', async () => {
const svg = await gensvg({
username: 'testuser',
text: 'Hi',
fontSize: 40,
css: true,
animation: 'var(--n) 1s linear both',
calendarList: makeCalendarList()
})

// var(--n) 按通道替换,圆形两段(x、y)
expect(svg).toContain(
'animation:var(--nx) 1s linear both,var(--ny) 1s linear both}'
)
})

it('applies a custom animation value', async () => {
Expand Down
Loading
Loading