Merge pull request #26 from flycran/docs/trim-comments-and-descriptions

docs: 精简源码注释，修正参数描述与文档

Author: flycran

README.md

@@ -41,17 +41,17 @@ 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. The default fits most cases; `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; `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 simulation time in seconds, counted as playback duration (simulated time = this value × `speed`). When reached, the trajectory simulated so far is returned instead of waiting for every block to settle. Leave empty to simulate until all blocks rest |
+| `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` |
 | `friction` | ❌ | `0.3` | Friction coefficient of the contribution blocks |
-| `restitution` | ❌ | `0` | Restitution (bounciness) of the contribution blocks. Values far from 0 may fling blocks out of the visible area; blocks falling below the world bottom are removed |
+| `restitution` | ❌ | `0` | Restitution (bounciness) of the contribution blocks. Values far from 0 may fling blocks out of the visible area |
 | `text-top` | ❌ | `50` | Distance from the top of the world to the text |
 | `background-color` | ❌ | `transparent` | Background color of the SVG (CSS color value) |
 | `text-color` | ❌ | `black` | Color of the collision text (CSS color value) |
-| `scale` | ❌ | `3` | Display zoom factor: the SVG `width`/`height` are the physics dimensions × scale, while the viewBox keeps the raw physics size |
-| `speed` | ❌ | `3` | Playback speed multiplier: the animation duration is the simulated time ÷ speed |
+| `scale` | ❌ | `3` | Overall zoom applied to the final SVG; does not change the actual size of the physics world |
+| `speed` | ❌ | `3` | Playback speed multiplier: the higher the value, the faster the animation plays |
 | `css` | ❌ | `false` | Use the CSS animation engine instead of SMIL `animateTransform`. See below |
 | `animation` | ❌ | `var(--n) var(--dur) linear both` | Custom CSS `animation` value for the CSS engine. ⚠️ Modify with caution — a wrong value breaks the animation. Requires `css: true` |
 | `width` | ❌ | `300` | Width of the physics world. ⚠️ Affects layout and SVG size |
@@ -62,7 +62,7 @@ Inspired by [Orta Therox](https://github.com/Orta). Thanks Orta for your outstan
 
 ### Reducing file size
 
-The trajectory is compressed by default: `compression-tolerance` (default `0.5`) merges
+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.
@@ -92,16 +92,15 @@ Two output engines are available; both produce a single static SVG file and play
 same trajectory at the same pace:
 
 - **SMIL** (default) drives every block with `<animateTransform>` elements.
-- **CSS** (`css: true`) drops those elements and declares all animations in one
-  self-contained `<style>` block: each block's trajectory becomes a `@keyframes` rule.
+- **CSS** (`css: true`) drives every block with a CSS `animation` declaration.
 
 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.
 
 With `css: true`, the `animation` input replaces the animation declaration applied to
-every block (default `var(--n) var(--dur) linear both`). Available variables:
+every block. Available variables:
 
 - `--n` — each block's keyframes name, required
 - `--dur` — the playback duration
@@ -116,8 +115,7 @@ Must not contain braces, semicolons or `]]>`.
 size. The contribution blocks are laid out from `size` and `interval`, the text is centered
 with `width`, and the drop height follows `height` — change them together and re-check the
 result rather than tweaking one in isolation. If the simulation fails to settle after your
-changes, set `max-simulation-time` to cap the simulation and still get the trajectory up to
-that point.
+changes, set `max-simulation-time` to cap the animation duration and still get the SVG.
 
 `font-path` swaps the collision font. It accepts a local `.ttf`/`.otf` path or an `http(s)` URL.
 The bundled Liberation Serif Bold is used by default because its contours are clean and
@@ -127,7 +125,6 @@ decompose stably. Custom fonts are not guaranteed to work:
   collision shapes.
 - Some fonts cannot be parsed by opentype.js at all (common ones such as DejaVu fail on their
   GSUB tables).
-- Different font metrics usually require re-tuning `font-size` and `text-top`.
 
 ### Outputs
 

README_zh.md

@@ -40,17 +40,17 @@
 | `text` | ❌ | `username` 的值 | 作为碰撞障碍物的文字 |
 | `output-path` | ❌ | `gravity.svg` | SVG 输出路径 |
 | `font-size` | ❌ | `48` | 碰撞文字大小 |
-| `compression-tolerance` | ❌ | `0.5` | 轨迹压缩容差（SVG 像素）。播放时每个原始时刻的动画位置与真实位置的偏差不超过该值。默认值适合多数场景；`0` 为完全无损（位置与节奏都精确）（见下文） |
+| `compression-tolerance` | ❌ | `0.5` | 轨迹压缩容差（SVG 像素）。播放时每个原始时刻的动画位置与真实位置的偏差不超过该值；`0` 为完全无损（位置与节奏都精确）（见下文） |
 | `compression-algorithm` | ❌ | `Greedy` | 轨迹压缩算法：`Greedy`（快）、`DP`（体积最小）、`RDP`（最快），差异见下文 |
-| `max-simulation-time` | ❌ | - | 最大模拟时间（秒），按播放时长计（模拟时间 = 该值 × `speed`）。到时即返回已模拟的轨迹，不再等待所有方块静止；留空则模拟至全部静止 |
+| `max-simulation-time` | ❌ | - | 动画最长播放时长（秒）。到时动画即止，方块停在当前位置，不再等待全部落定；留空则播放至全部静止 |
 | `shape` | ❌ | `circle` | 贡献方块的形状（`circle` 或 `square`） |
 | `friction` | ❌ | `0.3` | 贡献方块的摩擦系数 |
-| `restitution` | ❌ | `0` | 贡献方块的弹性（碰撞恢复系数），远离 0 的值可能把方块弹出画面，掉出画面底部的方块会被移除 |
+| `restitution` | ❌ | `0` | 贡献方块的弹性（碰撞恢复系数），远离 0 的值可能把方块弹出画面 |
 | `text-top` | ❌ | `50` | 文字距离世界顶部的距离，控制文字垂直位置 |
 | `background-color` | ❌ | `transparent` | SVG 背景颜色（CSS 颜色值） |
 | `text-color` | ❌ | `black` | 碰撞文字颜色（CSS 颜色值） |
-| `scale` | ❌ | `3` | 显示缩放：SVG 的 `width`/`height` 为物理尺寸 × 缩放值，viewBox 保持原始物理尺寸 |
-| `speed` | ❌ | `3` | 播放倍速：动画时长 = 模拟时间 ÷ 倍速 |
+| `scale` | ❌ | `3` | 最终 SVG 的整体缩放，不影响物理世界的实际大小 |
+| `speed` | ❌ | `3` | 动画播放倍速，数值越大播放越快 |
 | `css` | ❌ | `false` | 启用 CSS 动画引擎替代 SMIL `animateTransform`，见下文 |
 | `animation` | ❌ | `var(--n) var(--dur) linear both` | 自定义 CSS `animation` 值（仅 `css: true` 时有效）。⚠️ 谨慎修改，可能破坏动画效果 |
 | `width` | ❌ | `300` | 物理世界宽度。⚠️ 会影响布局与 SVG 尺寸 |
@@ -61,7 +61,7 @@
 
 ### 减小文件体积
 
-轨迹默认开启压缩：`compression-tolerance`（默认 `0.5`）会把轨迹点合并为关键帧，保证播放时
+轨迹默认开启压缩：`compression-tolerance` 会把轨迹点合并为关键帧，保证播放时
 每个原始时刻的插值位置与真实位置的偏差（SVG 像素）不超过阈值——碰撞、落地、停顿等速度
 变化按真实节奏保留。
 
@@ -86,15 +86,13 @@
 提供两种输出引擎；两者都输出单个静态 SVG 文件，播放轨迹与节奏完全一致：
 
 - **SMIL**（默认）：每个方块由 `<animateTransform>` 元素驱动。
-- **CSS**（`css: true`）：不再输出 animate 元素，所有动画声明收敛进单个自包含的
-  `<style>` 块，每个方块的轨迹生成一条 `@keyframes` 规则。
+- **CSS**（`css: true`）：每个方块由一条 CSS `animation` 声明驱动。
 
 渲染出的动画完全一致。当目标环境对 SMIL 支持不佳时选 CSS——部分 sanitizer 会剥除
 SMIL 动画元素，而 SVG 内的 CSS 动画支持面更广（GitHub README 以 `<img>` 加载 SVG，
 两种引擎都能正常播放）。文件体积略大于 SMIL。
 
-`css: true` 时，`animation` 输入可替换作用在每个方块上的 animation 声明，默认
-`var(--n) var(--dur) linear both`。可用变量：
+`css: true` 时，`animation` 输入可替换作用在每个方块上的 animation 声明。可用变量：
 
 - `--n`：方块绑定的关键帧名，必须包含
 - `--dur`：播放时长
@@ -107,14 +105,13 @@ web preview 里验证。值中不能包含花括号、分号或 `]]>`。
 `width`、`height`、`size`、`interval` 改动的是物理世界本身，而不只是输出尺寸。贡献方块按
 `size` 和 `interval` 排布，文字以 `width` 居中，下落高度由 `height` 决定——请成套调整并核对
 效果，不要只改其中一个。若调整后模拟无法收敛（Action 直接报错），可设置 `max-simulation-time`
-限制模拟时长，仍能拿到该时刻为止的轨迹。
+限制动画播放时长，仍能正常生成 SVG。
 
 `font-path` 用于替换碰撞字体，可以给本地 `.ttf`/`.otf` 路径，也可以直接给 `http(s)` 链接。
 默认使用内置的 Liberation Serif Bold，因为它轮廓规整、分解结果稳定。自定义字体不保证可用：
 
 - 轮廓不规整（未闭合、自相交等）的字体，碰撞体的分解结果可能不可靠、形状异常。
 - 部分字体根本无法被 opentype.js 解析（例如很常见的 DejaVu 系列，会因 GSUB 表解析失败）。
-- 字体度量不同，通常需要重新调整 `font-size` 和 `text-top`。
 
 ### 输出
 

action.yml

@@ -27,26 +27,25 @@ inputs:
       animation, the interpolated position stays within this distance of the real one,
       which shrinks the SVG at the cost of a small visual approximation. 0 keeps the
       trajectory lossless in both position and timing (only uniform straight segments
-      and pauses are compressed); the default fits most cases.
+      and pauses are compressed).
     required: false
     default: '0.5'
   compression-algorithm:
     description: >-
-      Trajectory compression algorithm: Greedy (default) is fast with near-optimal
+      Trajectory compression algorithm: Greedy is fast with near-optimal
       results; DP finds the globally fewest keyframes (smallest SVG) but can take
       seconds on long trajectories; RDP is the fastest with somewhat more keyframes.
       All algorithms preserve speed and timing — bounces and stops stay keyframes.
     required: false
     default: Greedy
   max-simulation-time:
     description: >-
-      Maximum simulation time in seconds, counted as animation playback duration:
-      the simulated time is this value multiplied by the playback speed. When reached,
-      the simulation stops and the trajectory simulated so far is returned instead of
-      waiting for every block to settle. Leave empty to simulate until all blocks rest.
+      Maximum animation playback duration in seconds. Once the animation reaches
+      it, blocks freeze where they are instead of waiting for every block to
+      settle. Leave empty to play until all blocks rest.
     required: false
   shape:
-    description: Shape of the contribution blocks (circle or square). Circle has smoother physics and less likely to clip through obstacles.
+    description: Shape of the contribution blocks (circle or square).
     required: false
     default: circle
   text-top:
@@ -63,22 +62,22 @@ inputs:
     default: black
   scale:
     description: >-
-      Display zoom factor: the SVG width and height attributes are the physics
-      dimensions multiplied by it, while the viewBox keeps the raw physics size.
+      Overall zoom applied to the final SVG. It does not change the actual
+      size of the physics world.
     required: false
     default: '3'
   speed:
     description: >-
-      Playback speed multiplier: the animation duration is the simulated time
-      divided by it.
+      Playback speed multiplier: the higher the value, the faster the
+      animation plays.
     required: false
     default: '3'
   css:
     description: >-
-      Use the CSS animation engine (a self-contained style block with @keyframes,
-      animations bound via data-date selectors) instead of SMIL animateTransform.
+      Render the animation with CSS animation (the only engine the animation
+      input works with) instead of SMIL animateTransform.
       Both stay a single static SVG file; CSS plays more reliably in environments
-      with poor SMIL support, and stays visually identical. Default: false.
+      with poor SMIL support, and stays visually identical.
     required: false
     default: 'false'
   animation:
@@ -103,14 +102,14 @@ inputs:
     default: '150'
   size:
     description: >-
-      Side length of each contribution block. Change with caution: larger blocks are more
-      likely to squeeze against each other or clip through the text.
+      Side length of each contribution block. Change with caution: too large
+      pushes the block matrix out of the world bounds.
     required: false
     default: '4'
   interval:
     description: >-
-      Spacing between contribution blocks. Change with caution: too small makes blocks overlap,
-      too large pushes them out of the world bounds.
+      Spacing between contribution blocks. Change with caution: too large
+      pushes the block matrix out of the world bounds.
     required: false
     default: '1.5'
   friction:
@@ -120,18 +119,16 @@ inputs:
     default: '0.3'
   restitution:
     description: >-
-      Restitution (bounciness) of the contribution blocks. Values far from 0 may fling
-      blocks out of the visible area; such blocks are removed once they fall below the
-      world bottom.
+      Restitution (bounciness) of the contribution blocks. Values far from 0
+      may fling blocks out of the visible area.
     required: false
     default: '0'
   font-path:
     description: >-
       Path to a custom font (.ttf/.otf), relative to the repository root, or an http(s) URL.
       Defaults to the bundled Liberation Serif Bold. Use with caution: some fonts contain open
       or self-intersecting contours that the triangulation algorithm rejects, and some cannot
-      be parsed by opentype.js at all; different font metrics may also require re-tuning
-      font-size and text-top.
+      be parsed by opentype.js at all.
     required: false
 
 outputs: