tiennm99
7ca1468a43
/api/gacha now renders the 6-second portrait pack-cards opening that was served on /api/gachabeta. The Remotion meteor wish, its timeline, and the beta route are removed, and the pack-cards renderer and page take the plain gacha names. BREAKING CHANGE: /api/gachabeta is gone, and /api/gacha returns a 6-second portrait video (360x640 for width 640, 480x854 for width 854) instead of the 7-second landscape one.
wheelofnames
Self-hosted API that renders wheel-of-names GIF animations with Remotion and gacha wish MP4 animations with pack-cards.
API
POST /api/gif
Content-Type: application/json
Accept: image/gif
Authorization: Bearer change-me
{
"options": ["alice", "bob", "carol"],
"winnerIndex": 1,
"durationMs": 6500,
"holdMs": 1200,
"fps": 15,
"size": 512,
"theme": "classic"
}
Response is image/gif with winner metadata headers:
X-Wheel-Winner-IndexX-Wheel-WinnerX-Render-Duration-Ms
X-Wheel-Winner is URL-encoded so non-ASCII labels are safe in HTTP headers.
Gacha wish
POST /api/gacha
Content-Type: application/json
Accept: video/mp4
Authorization: Bearer change-me
{
"label": "Bún bò",
"rarity": 5,
"fps": 24,
"width": 640
}
Renders a 6-second portrait wish: a collectible card pack from
pack-cards is torn open, its card
spins out with a burst of sparkles, and lands showing the request's label,
its rank, and its stars under a polychrome rainbow foil. rarity (required)
picks the rank (B for 3★, A for 4★, S for 5★), the star count, the
card's material (rare, epic, legendary), and the colour (blue, purple, gold).
fps is 24 or 30. width is the long edge of the portrait frame:
640 renders 360×640 and 854 renders 480×854. Optional seed (integer,
0 to 2147483647) seeds the page's randomness; when omitted the service
picks a random one, so every roll looks different. The caller chooses the
result and its rarity — the service only draws it.
Response is a silent H.264 video/mp4 (Telegram plays it as an animation)
with X-Gacha-Rarity and X-Render-Duration-Ms headers. Both routes share the
MAX_CONCURRENT_RENDERS slots. No game assets are used.
pack-cards animates on the browser clock, so the wish does not use Remotion
compositions. src/render/render-gacha.js keeps one headless Chrome per
server process in --deterministic-mode, steps virtual time one frame at a
time, tears the pack with a scripted drag, captures each frame, and encodes
them with Remotion's bundled ffmpeg. The page (src/gacha/page/) and the
package are served from disk; the page has no network access. The first render
compiles the pack's WebGL shaders in software, which takes several seconds, so
server start-up runs one throwaway wish first.
pack-cards has no npm release, so it is installed from a GitHub tarball pinned
to a commit. A moving branch URL would change the tarball's checksum and break
npm ci against the lockfile, and the Docker image has no git for a git
dependency.
Local
Install dependencies and Chromium once:
npm install
npm run browser:ensure
Start the local API:
npm run dev
Generate GIF files locally
Generate the quick smoke fixtures at the git-ignored paths
fixtures/smoke.gif and fixtures/gacha-5-star.mp4:
npm run render:smoke
Generate the complete fixture set at fixtures/smoke.gif,
fixtures/vietnamese.gif, fixtures/sixteen-options.gif, and
fixtures/gacha-{3,4,5}-star.mp4:
npm run render:fixtures
Render a custom GIF directly without starting the API server:
npm run render:local -- `
--output wheel.gif `
--option "Chiều nay uống CraneTea" `
--option "Chiều nay uống CraneTea" `
--option "Cà phê" `
--winner 1
macOS, Linux, or Git Bash:
npm run render:local -- \
--output wheel.gif \
--option "Chiều nay uống CraneTea" \
--option "Chiều nay uống CraneTea" \
--option "Cà phê" \
--winner 1
--winner is a zero-based index and is random when omitted. Run
npm run render:local -- --help for duration, hold, FPS, size, theme, and timeout
options. The documented root wheel.gif and fixtures/*.gif/*.mp4 outputs are
git-ignored and safe to delete; custom output paths may need their own ignore
rule.
Verify
Run the API smoke test and quality gates:
npm run api:smoke
npm run lint
npm run typecheck
npm test
Deploy
Use a container runtime first. Static-only platforms cannot satisfy
POST /api/gif because Remotion server rendering needs Node, Chromium/runtime
dependencies, and FFmpeg/compositor support.
docker build -t wheelofnames .
docker run --rm -p 3000:3000 -e API_TOKEN=change-me wheelofnames
Recommended starting resources: 1-2 vCPU and 1-2 GB RAM, with
MAX_CONCURRENT_RENDERS=1. RENDER_TIMEOUT_MS defaults to 15000 and is
raised to Remotion's 7000ms browser timeout floor when configured lower.
API_TOKEN is required when NODE_ENV=production.