docs(plans): record research on open-source gacha animation projects

renderer/plans/reports/researcher-261001-1656-open-source-gacha-candidates.md

@@ -0,0 +1,76 @@
+---
+title: Open-source web gacha projects as a code source for /api/gachabeta
+date: 2026-10-01 16:56 (Asia/Saigon)
+---
+
+# Open-source web gacha projects as a code source for /api/gachabeta
+
+## Answer
+
+No candidate offers reusable code that would make the beta look more like the
+real game. The realistic simulators get their look by playing MP4/WebM clips
+recorded from the commercial games. Their code is often MIT-licensed, but the
+clips belong to the publisher (HoYoverse, Nexon, and others). Mantan21's README
+says so directly: "all assets used for this application belongs to Hoyoverse".
+The projects with their own art (original games) have simple pixel or HTML
+reveals that are weaker than the current beta. Copying either kind of code
+would give us one of two things: a `<video>` player that needs copyrighted
+footage, or an animation worse than what we already render.
+
+## Candidates
+
+Stars, licences, and dates come from the GitHub API on 2026-10-01.
+
+| # | Project | Stars | Stack | Code licence | How the pull animation is made | Reusable for us? |
+|---|---|---|---|---|---|---|
+| 1 | [Mantan21/Genshin-Impact-Wish-Simulator](https://github.com/Mantan21/Genshin-Impact-Wish-Simulator) ([live](https://wishsimulator.app)) | 293 | Svelte | MIT | Plays game-recorded clips (`3star-single.mp4` … `5star-multi.mp4`, `bg.webm`) through `_meteor.svelte` | Code yes, footage no |
+| 2 | [shadorki/genshin-impact-wish-simulator](https://github.com/shadorki/genshin-impact-wish-simulator) | 734 | JavaScript | None (all rights reserved) | Plays `dist/videos/5starwish.mp4` and similar game clips | No |
+| 3 | [Mantan21/HSR-Warp-Simulator](https://github.com/Mantan21/HSR-Warp-Simulator) ([live](https://hsr.wishsimulator.app)) | 40 | Svelte | MIT | Same author and approach, built on Star Rail game assets; the warp clip source was not checked | Code yes, assets no |
+| 4 | [jianzhishendi/Genshin-Impact-Wish-Simulator-1](https://github.com/jianzhishendi/Genshin-Impact-Wish-Simulator-1) | — | Svelte | Fork of #1 | Same as #1 | Same as #1 |
+| 5 | [U1805/ba-gacha](https://github.com/U1805/ba-gacha) | 18 | Vue | MIT | `VideoView.vue` plays Blue Archive clips per star tier | Code yes, footage no |
+| 6 | [dzmuh97/genshin-twitch-wish](https://github.com/dzmuh97/genshin-twitch-wish) | 2 | Python | None | Composites game `effect.mp4` backgrounds | No |
+| 7 | [Eling486/gacha-simulator](https://github.com/Eling486/gacha-simulator) | 23 | JavaScript | None | Arknights Spine skeletons (`.atlas`/`.skel`) extracted from the game | No |
+| 8 | [Spelljinxer/nikke-gacha-sim](https://github.com/Spelljinxer/nikke-gacha-sim) | 9 | HTML | None | Game images, no video | No |
+| 9 | [Catgenova/browsergacha](https://github.com/Catgenova/browsergacha) | 0 | Vanilla JS + canvas | None | Original pixel-art summon screen with free UI packs | No licence, and simpler than ours |
+| 10 | [HauntedBees/Public-Domains](https://github.com/HauntedBees/Public-Domains) | 1 | JavaScript | AGPL-3.0 | Public-domain art, static reveal; last push 2019 | AGPL would apply to our service; little animation to gain |
+| 11 | [DragonMarquise/GachaGameSimulator](https://github.com/DragonMarquise/GachaGameSimulator) | 7 | HTML/CSS/JS | AGPL-3.0 | Basic CSS reveal | AGPL, and simpler than ours |
+
+Tracker and analyser tools (for example `biuuu/genshin-wish-export`,
+`lgou2w/HoYo.Gacha`, `bhaoo/endfield-gacha`) came up in the searches but have
+no pull animation, so they are excluded.
+
+## What the code would actually give us
+
+- **Video player and skip handling (#1, #5).** We already render to MP4, so
+  there is nothing to gain.
+- **Pull rates and pity logic (#1).** MIT and realistic. It doesn't fit our
+  contract, though: the bot picks the winner uniformly and the caller sets
+  `rarity`. Adopting it would change bot behaviour, not visuals.
+- **Spine or Lottie playback (#7).** The technique could work through
+  `@remotion/lottie`, but only with original animation files, and none exist
+  in these repositories.
+
+## Honest options from here
+
+1. **Keep procedural rendering and add original painted textures**, as
+   recommended in the previous discussion: images generated once with an
+   image model or supplied by you, animated by the current code.
+2. **Commission or author a Lottie or Spine wish animation** and play it
+   through `@remotion/lottie`. This gives the highest fidelity without game
+   assets, but someone must make the animation file.
+3. **Use the game's recorded clips** as #1–#6 do. Not recommended: HoYoverse
+   owns the footage, the README promises no game assets, and the bot is public.
+
+## Method
+
+GitHub search (`gh search repos`, `--topic gacha`), repository trees and
+READMEs read through the GitHub API, plus two web searches. I checked
+animation sources by listing video and Spine files in each tree and reading
+Mantan21's `meteor-loader.js` and `_meteor.svelte`.
+
+## Unresolved questions
+
+- Is there a commercial or Creative Commons Lottie wish animation you would
+  accept, if we went with option 2?
+- How does the HSR simulator (#3) source its warp clip? I didn't check,
+  because it would not change the recommendation.

renderer/plans/reports/researcher-261001-1703-code-built-gacha-animation.md

@@ -0,0 +1,75 @@
+---
+title: Open-source gacha animations built in code (no video playback)
+date: 2026-10-01 17:03 (Asia/Saigon)
+---
+
+# Open-source gacha animations built in code (no video playback)
+
+## Answer
+
+No mature open-source web project renders a Genshin-quality gacha pull in
+code under a licence we can use. The web projects that draw effects in code
+are general effect or particle libraries, or card-pack reveals, not wish
+sequences. Non-web projects, such as a Unity Arknights roll recreation, are
+excluded. The most promising building block is **rollshade** (MIT): a three.js
+effect library with meteors, impacts, bloom, and camera shake. It is two days
+old, though, and its update loop is stateful, which conflicts with Remotion's
+frame-by-frame rendering.
+
+## Web candidates (code-built, no video)
+
+Data comes from the GitHub API and the repositories' READMEs on 2026-10-01.
+"Video files" counts `.mp4`/`.webm`/`.mov` files in each repository tree.
+
+| # | Project | Stars | Stack | Licence | Video files | What it is | Fit |
+|---|---|---|---|---|---|---|---|
+| 1 | [tsuyatt/rollshade](https://github.com/tsuyatt/rollshade) ([gallery](https://rollshade.tsuyatt.com/gallery/)) | 0 | three.js r186, WebGPU/TSL with WebGL2 fallback | MIT (npm `rollshade@0.1.0`) | 0 | 25 seeded spell effects (meteor, beam, impact, portal…) × 10 elements, with bloom and camera shake | Best effect source. Risks below. |
+| 3 | [briamkin/card-pack-animations](https://github.com/briamkin/card-pack-animations) | 0 | TypeScript, React wrappers | MIT | 0 | Card-pack tear and reveal | Different genre, small |
+| 4 | [paubineau/pack-cards](https://github.com/paubineau/pack-cards) | 0 | Vanilla JS and CSS | MIT | 1 (demo) | Pack wrapper, reveal animation, card materials | Different genre |
+| 5 | [Tmauc/prismo](https://github.com/Tmauc/prismo) | 0 | React, CSS-only | None | 0 | Holographic foil card effects for 10+ rarities | No licence |
+| 6 | [Takuro-U/gacha-animation](https://github.com/Takuro-U/gacha-animation) | 0 | React, Tailwind | None | 0 | Small gacha UI demo | No licence |
+| 7 | [drawcall/Proton](https://github.com/drawcall/Proton) | 2477 | JS particle engine (canvas, WebGL, pixi) | MIT | — | General particle library | Building block only |
+| 8 | [pixijs-userland/particle-emitter](https://github.com/pixijs-userland/particle-emitter) | 852 | PixiJS | MIT | — | Particle emitter with a visual editor | Building block only |
+
+## Using rollshade inside Remotion
+
+```js
+// rollshade's own loop: time is wall-clock deltas, state accumulates.
+fx.play(effect('meteor', 'fire', {seed: 7}), {from: start, to: target});
+fx.update(timer.getDelta());
+```
+
+The risks, roughly in order of severity:
+
+- **Determinism.** Remotion renders frames out of order across several
+  browser tabs, but `fx.update(dt)` accumulates state. Each frame would have
+  to replay from frame 0 with fixed steps (`1/fps`), so the cost grows with
+  clip length, or renders would have to run with concurrency 1.
+- **Rendering speed.** The server has no GPU. WebGPU will fall back to WebGL2
+  on SwiftShader, which is likely several times slower than our CSS frames.
+  The current beta already takes about 15s at 854px and 30fps against the
+  15s timeout.
+- **Maturity.** Version 0.1.0, first published this week, pinned to one three
+  release (r186), and the API can still change.
+- **New dependencies.** `three`, `rollshade`, and `@remotion/three` with
+  `@react-three/fiber`. That conflicts with our "CSS over custom rendering"
+  rule in AGENTS.md, so you'd need to approve it.
+
+## Options
+
+1. **Prototype one shot with rollshade.** Render the meteor and impact shot in
+   a separate composition, measure the render time on this server, and check
+   frame determinism before committing to a rewrite. About one session of
+   work, with no changes to `/api/gachabeta` until it proves out.
+2. **Keep our own code and borrow techniques.** Port ideas such as rollshade's
+   seeded variations, bloom-like layering, and impact timing into the existing
+   CSS and canvas renderer. No new dependencies, and no render-time risk.
+3. **Painted textures plus our current motion** (from the previous report).
+   Not code-only, but the biggest visual gain for the cost.
+
+## Unresolved questions
+
+- Would you accept adding three.js to the renderer if the prototype renders
+  inside the timeout?
+- I couldn't browse rollshade's live gallery here (no browser on this server),
+  so I haven't seen its meteor effect myself.