Torena Sim

Torena Sim is a race and skill simulation toolkit for Uma Musume: Pretty Derby Global server. It helps players, theorycrafters, and tool builders test race behavior with repeatable simulations instead of relying only on in-game trial runs.

Project Context

This repository combines:

• A web app for configuring race scenarios and visualizing outputs.
• A simulation engine for speed, acceleration, stamina, and skill activation behavior.
• Data tooling and scripts for extracting, syncing, and validating skill and course data.

The goal is to provide a practical environment for understanding how different builds and race conditions affect performance.

What It Is Used For

Use this project when you want to:

• Compare skill loadouts under the same race setup.
• Evaluate skill activation consistency and expected value.
• Inspect velocity and distance trends across many simulation runs.
• Iterate on runner stats, strategy, and conditions before testing in-game.
• Debug or experiment with simulation logic through local scripts.

Quick Start

Install and Run

bun install
bun run dev

Open the local URL printed by Vite to use the simulator UI.

Sync Game Data

bun run db:fetch        # 1. Download latest master.mdb to ./db
bun run extract:all     # 2. Extract course geometry from master.mdb
bun run sync:data       # 3. Sync entity catalog (skills, umas, cards) from GameTora

Start with master.mdb to establish what's live on Global, then sync GameTora to overlay the full catalog (including upcoming content). sync:data only re-fetches data that changed since the last sync.

See docs/data-extraction/data-pipeline.md for details.

Deployment

Production deploys run automatically on every push to main (rolling releases). GitHub Releases from semantic-release are for changelog/tags only and do not trigger deploys.

The canonical app is hosted on Cloudflare Pages.

Target	Role	Workflow	URL
Cloudflare Pages	Canonical	.github/workflows/deploy-cloudflare.yml	https://torena-sim.pages.dev

Cloudflare Pages runs the full build (incl. the Rust/wasm engine) and can also be triggered manually via workflow_dispatch.

Legacy jalbarrang.github.io/umalator-global (GitHub Pages) and sundays-shadow.netlify.app (Netlify) still serve a static 301 redirect to the canonical domain from their last deployment, so old inbound links keep working. Their deploy workflows have been retired — the redirects are static and need no further builds.

Versioning

Releases are driven by Conventional Commits on main (enforced locally via commitlint). semantic-release tags the deployed commit and opens a GitHub Release — there is no chore(release) commit on main.

• __APP__VERSION__: latest v* tag semver + current short commit hash (e.g. 0.13.0+6f1340a)
• In-app changelog: CHANGELOG.md is regenerated during deploy builds (bun run changelog:generate); locally run that after git fetch --tags to refresh the modal in dev
• GitHub Releases: release notes for Discord / announcements

# Preview the next version and release notes
GITHUB_TOKEN=<pat> bun run release:dry-run

# Tag current commit and create GitHub Release
GITHUB_TOKEN=<pat> bun run release

Use DATA_UPDATE_PAT as GITHUB_TOKEN for local releases.

Required Secrets & Variables

Name	Type	Used by
DATA_UPDATE_PAT	Secret	versioning.yml — PAT for semantic-release (push tags, releases)
CLOUDFLARE_API_TOKEN	Secret	Cloudflare Pages deploy (scope: Cloudflare Pages → Edit)
CLOUDFLARE_ACCOUNT_ID	Secret	Cloudflare Pages deploy (also used by the suggestion-bot Worker)
VITE_PUBLIC_POSTHOG_KEY	Secret	Build-time analytics key
VITE_PUBLIC_POSTHOG_HOST	Variable	Build-time analytics host
VITE_BASE_PATH	Variable	GitHub Pages base path

Useful Commands

• bun run dev: start local development server
• bun run build: build production assets
• bun run preview: preview built app
• bun run typecheck: run TypeScript checks
• bun run lint: run ESLint
• bun run test: run test suite
• bun run sync:data: sync entity catalog from GameTora
• bun run db:fetch: download latest master.mdb to ./db
• bun run extract:all: extract course geometry from master.mdb

Acknowledgements

This project is inspired by and built on the work of the Uma simulation community. Special thanks to:

• alpha123 for the original simulator and UI foundations.
• Transparent Dino, jechtoff2dudes and Kachi for extensive fixes, systems rework, and simulator enhancements made in VFalator.
• GameTora for game data, including the entity catalog (skills, umas, support cards), event rewards, and skill hint mappings that power this tool.

Copyright and Fair Use Notice

Uma Musume: Pretty Derby, its characters, names, artwork, game assets, and related trademarks are the property of Cygames, Inc. and their respective rights holders.

This project is an independent, fan-made simulation and analysis tool. It is not affiliated with, endorsed by, or sponsored by Cygames, Inc.

Any referenced game data, terminology, or limited derivative material is used for commentary, research, education, and interoperability purposes. This repository is intended to fall under applicable fair use / fair dealing principles and equivalent exceptions under relevant copyright laws.