Merge pull request #12 from flycran/docs/sync-3.0.0-params

docs: 补充 max-simulation-time / scale / speed 参数说明

Author: flycran

README.md

@@ -43,10 +43,13 @@ Inspired by [Orta Therox](https://github.com/Orta). Thanks Orta for your outstan
 | `font-size` | ❌ | `80` | 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-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 |
 | `shape` | ❌ | `circle` | Shape of contribution blocks: `circle` or `square` |
 | `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 |
 | `width` | ❌ | `300` | Width of the physics world. ⚠️ Affects layout and SVG size |
 | `height` | ❌ | `150` | Height of the physics world. ⚠️ Affects layout and SVG size |
 | `size` | ❌ | `4` | Side length of each contribution block. ⚠️ Affects physics |
@@ -85,7 +88,9 @@ In most cases, just keep the default.
 `width`, `height`, `size` and `interval` change the physics world itself, not just the output
 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.
+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.
 
 `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

README_zh.md

@@ -42,10 +42,13 @@
 | `font-size` | ❌ | `80` | 碰撞文字大小 |
 | `compression-tolerance` | ❌ | `0.5` | 轨迹压缩容差（SVG 像素）。播放时每个原始时刻的动画位置与真实位置的偏差不超过该值。默认值适合多数场景；`0` 为完全无损（位置与节奏都精确）（见下文） |
 | `compression-algorithm` | ❌ | `Greedy` | 轨迹压缩算法：`Greedy`（快）、`DP`（体积最小）、`RDP`（最快），差异见下文 |
+| `max-simulation-time` | ❌ | - | 最大模拟时间（秒），按播放时长计（模拟时间 = 该值 × `speed`）。到时即返回已模拟的轨迹，不再等待所有方块静止；留空则模拟至全部静止 |
 | `shape` | ❌ | `circle` | 贡献方块的形状（`circle` 或 `square`） |
 | `text-top` | ❌ | `50` | 文字距离世界顶部的距离，控制文字垂直位置 |
 | `background-color` | ❌ | `transparent` | SVG 背景颜色（CSS 颜色值） |
 | `text-color` | ❌ | `black` | 碰撞文字颜色（CSS 颜色值） |
+| `scale` | ❌ | `3` | 显示缩放：SVG 的 `width`/`height` 为物理尺寸 × 缩放值，viewBox 保持原始物理尺寸 |
+| `speed` | ❌ | `3` | 播放倍速：动画时长 = 模拟时间 ÷ 倍速 |
 | `width` | ❌ | `300` | 物理世界宽度。⚠️ 会影响布局与 SVG 尺寸 |
 | `height` | ❌ | `150` | 物理世界高度。⚠️ 会影响布局与 SVG 尺寸 |
 | `size` | ❌ | `4` | 贡献方块边长。⚠️ 会影响物理表现 |
@@ -78,7 +81,8 @@
 
 `width`、`height`、`size`、`interval` 改动的是物理世界本身，而不只是输出尺寸。贡献方块按
 `size` 和 `interval` 排布，文字以 `width` 居中，下落高度由 `height` 决定——请成套调整并核对
-效果，不要只改其中一个。
+效果，不要只改其中一个。若调整后模拟无法收敛（Action 直接报错），可设置 `max-simulation-time`
+限制模拟时长，仍能拿到该时刻为止的轨迹。
 
 `font-path` 用于替换碰撞字体，可以给本地 `.ttf`/`.otf` 路径，也可以直接给 `http(s)` 链接。
 默认使用内置的 Liberation Serif Bold，因为它轮廓规整、能稳定三角化。自定义字体有风险：

package.json

@@ -1,7 +1,7 @@
 {
   "name": "github-gravity",
   "description": "Generate an animated SVG of your GitHub contribution graph falling under gravity, with custom text as collision obstacles",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "author": "flycran",
   "type": "module",
   "private": true,