- TypeScript 84.2%
- JavaScript 12.8%
- CSS 2.9%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
All checks were successful
Loopbound PR verification / Core / static and content (push) Successful in 15s
Loopbound PR verification / Core / tests (push) Successful in 11s
Loopbound PR verification / Browser / Playwright smoke (push) Successful in 1m2s
Loopbound PR verification / Security / production npm audit (push) Successful in 7s
Reviewed-on: #15 |
||
| .claude/agents | ||
| .forgejo/workflows | ||
| .github | ||
| content-schema | ||
| docs | ||
| scripts | ||
| slice planning/slice 3 | ||
| sprint-planning | ||
| src | ||
| src-tauri | ||
| test-results | ||
| tests | ||
| .gitignore | ||
| AGENTS.md | ||
| capacitor.config.ts | ||
| CI_CHECKS.md | ||
| CONTENT_AUTHORING.md | ||
| eslint.config.mjs | ||
| index.html | ||
| package-lock.json | ||
| package.json | ||
| plan-game-mechanics-addendum.md | ||
| plan.md | ||
| playwright.config.mjs | ||
| README.md | ||
| tsconfig.json | ||
| vite.config.ts | ||
LOOPBOUND
A time-loop incremental/idle game (Terraformental / Increlution lineage) wrapped in a medieval-fantasy narrative: your best friend is kidnapped, you find an amulet in the woods, the bandits kill you — and you wake at the exact moment you first put it on. Every death is data.
One TypeScript/React codebase, three platforms:
| Platform | Shell | Command |
|---|---|---|
| Browser | static web build | npm run build → deploy dist/ anywhere |
Desktop (Windows .exe, macOS, Linux) |
Tauri 2 | npm run desktop:build |
| Mobile (Android / iOS) | Capacitor | npm run mobile:add:android && npm run mobile:sync |
Quick start (all platforms start here)
Prerequisite for everything: Node.js ≥ 20 and npm.
git clone <this repo> && cd Loopbound
npm install
npm run dev # play at http://localhost:5173 (hot reload)
npm test # engine + story + content-integrity tests (vitest)
npm run validate:content # structural lint of the JSON content packs
Every platform below wraps the same web build — build once, ship everywhere:
npm run build # typecheck + production build -> dist/
Platform setup & build
1. Desktop — web (browser)
No extra tooling. npm run build produces a fully static dist/ folder.
- Local preview:
npm run preview→ http://localhost:4173 - Deploy: upload
dist/to any static host (GitHub Pages, Netlify, Cloudflare Pages, itch.io, an nginx folder — anything). No server code, no environment variables. The build uses relative asset paths (base: "./"), so it works from a subdirectory too. - Saves live in the browser's IndexedDB (per-origin). Players can move between machines with Settings → Export/Import save.
2. Desktop — native .exe / .app / .deb (Tauri 2)
One-time setup, per the Tauri prerequisites:
- Install Rust (stable) via rustup.
- Platform toolchain:
- Windows: Microsoft Visual Studio C++ Build Tools ("Desktop development with C++") and the WebView2 runtime (preinstalled on Windows 10/11).
- macOS:
xcode-select --install. - Linux:
webkit2gtk+ build essentials, e.g. on Debian/Ubuntu:sudo apt install libwebkit2gtk-4.1-dev build-essential libssl-dev libayatana-appindicator3-dev librsvg2-dev.
Then:
npm run desktop:dev # development window with hot reload
npm run desktop:build # release build + installers
Output lands in src-tauri/target/release/bundle/:
| Built on | You get |
|---|---|
| Windows | .exe NSIS installer + .msi, plus the bare loopbound.exe in src-tauri/target/release/ |
| macOS | .app bundle + .dmg |
| Linux | .deb, .rpm, .AppImage |
Tauri builds for the OS you run it on (cross-compiling is not supported out of the box) — build
the .exe on a Windows machine or a Windows CI runner.
App icons are already committed (src-tauri/icons/, including icon.ico). To regenerate from the
pixel-art source: npm run icon:gen && npm run desktop:icons.
3. Mobile — Android (Capacitor)
One-time setup:
- Install Android Studio (includes the Android SDK; install an SDK Platform ≥ 33 and command-line tools via its SDK Manager).
- Create the native project (once, generates
android/):
npm run mobile:add:android
Build & run:
npm run mobile:sync # npm run build + copy dist/ + sync plugins into android/
npm run mobile:open:android # opens the project in Android Studio
In Android Studio: pick an emulator or a USB-debugging device and press Run for a debug build,
or Build → Generate Signed App Bundle/APK for a release APK/AAB (create a signing keystore the
first time; Play Store uploads want the .aab).
CLI alternative without opening the IDE: npx cap run android.
Re-run npm run mobile:sync after every web-code change — the native project embeds a copy of dist/.
4. Mobile — iOS (Capacitor)
Requires a Mac with:
- Xcode (App Store) +
xcode-select --install. - CocoaPods:
sudo gem install cocoapods(orbrew install cocoapods). - Create the native project (once, generates
ios/):
npm run mobile:add:ios
Build & run:
npm run mobile:sync # npm run build + copy dist/ + pod install
npm run mobile:open:ios # opens ios/App/App.xcworkspace in Xcode
In Xcode: select the App target → Signing & Capabilities → pick your Apple developer team
(a free account works for running on your own device), choose a simulator or plugged-in iPhone,
press Run. For TestFlight/App Store: Product → Archive and distribute from the Organizer.
CLI alternative: npx cap run ios.
On both mobile platforms, saves use the Capacitor Preferences native store (survives webview
data clears; see src/platform/saveAdapter.ts), and the game autosaves on backgrounding because
mobile OSes may kill the app at any time.
Architecture
src/
engine/ GameClock+orchestrator (Game.ts), LoopManager (reset/carryover),
EventEngine (generic trigger/condition/effect evaluator),
modifiers (Mastery, timing, yield and progression), serialize (saves+migrations)
model/ GameState types (PersistentProgress vs LoopState) + content-pack schema
content/ JSON content packs: balance.json, core.json, prologue-expansion.json,
framework.json, manifest.json, plus story/*.json area/story packs
ui/ React views (World, Routes, Schools, Memory, Journal, Settings),
dialogue + loop-summary overlays, canvas pixel-sprite
platform/ SaveAdapter interface: IndexedDB (web+Tauri webview),
Capacitor Preferences (mobile native), localStorage fallback
content-schema/ standalone CLI validator for content packs
src-tauri/ desktop shell (Tauri 2)
capacitor.config.ts mobile shell
tests/ vitest: loop/reset model, Act 1 story flow, content integrity
The two rules that hold everything together
LoopStateis wiped and rebuilt fromPersistentProgresson every reset —LoopManager.createLoopState()is the only place a loop is constructed. Persistent Mastery ledgers, Aptitude, Journal, lore, unlocked regions and persistent flags survive; everything else dies with you.- Content is data. Regions, actions (with multi-method resolution +
sourceTypeXP rates + once-solved puzzle flags), generators, schools/tiers, Mastery configuration, NPCs, story events, dialogue (with loop-count variants) and journal topics are data-driven and evaluated by the shared content/event machinery. Story packs are composed undersrc/content/story/; new engine primitives belong in the existing registries rather than one-off story code.
Core systems
- Fixed loop budget: every loop has the same underlying catastrophe deadline. Ordinary world time remains visible, but the catastrophe countdown is not exposed before the protagonist has learned it. Progression makes solved work faster rather than arbitrarily extending the loop.
- Mastery: repeated execution builds persistent familiarity. Exact task and local-route familiarity have a finite endpoint; broad Mastery groups continue under their own diminishing- return curves. Full exact familiarity never makes the physical action unavailable.
- Aptitude (slow axis): 7 schools, persistent XP/tiers; XP source matters (instruction 2.5× > dedicated study 1.5× > applied use 1× > exposure 0.25×).
- Route graph (§6.6): regions with travel-time edges drawn from the doom-clock budget; different loops take different routes; the Journal keeps whatever any route taught, forever.
- Search before gather: a region only yields what you have found in it. Searching is slow and
raises how much that ground will give up this loop; gathering is fast and draws that down.
Each further search in the same loop costs more than the last, so "one more sweep?" is a real
question against the doom clock. Discovery is permanent — later loops follow the clue straight
to the patch, and only search when they want more than the base yield. Authored as
depositsin a content pack, plus asearch/gatheraction pair per deposit. - Offline progress (§7.6): analytic fast-forward for generators/study, capped at 12h.
- Saves (§12): versioned JSON with Decimal-safe serialization, migration registry, autosave (30s + backgrounding + loop end), manual export/import in Settings.
Content authoring
The shipped story is split across src/content/story/*.json, with shared world/system content in
core.json, prologue-expansion.json, balance.json and framework.json. Run
npm run validate:content after editing — it checks structure and resolves cross-pack
references (travel edges, dialogue and journal targets, deposit/action pairings, tier unlocks);
further engine-level checks run in npm test.
Two region flags decide where a loop starts: startingRegion is where every loop after the first
resets to, and prologueStartingRegion is where loop 1 opens, before the amulet is ever worn.
Deliberately post-MVP
Audio playback (the musicCue/stinger plumbing is wired end-to-end; it needs rendered loops),
cloud sync, per-school study minigames beyond the action layer, additional Act 2+ packs.