No description
  • TypeScript 84.2%
  • JavaScript 12.8%
  • CSS 2.9%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
alexander cab69c4ed5
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
Merge pull request 'Implement Slice 11 rescue failed-salvation reveal and Act 1 acceptance' (#15) from mcp/slice-11-implementation into main
Reviewed-on: #15
2026-10-05 17:35:21 +02:00
.claude/agents docs: sync specialist role summaries with settled PR 33 contract 2026-09-15 07:25:56 +02:00
.forgejo/workflows ci: resolve Playwright amd64 manifest on runner 2026-09-20 12:07:51 +02:00
.github fix(slice-5): close final acceptance blockers 2026-09-20 13:08:00 +02:00
content-schema Lock canonical terminal coupling wiring statically 2026-10-02 12:47:38 +02:00
docs Synchronize development status for Slice 11 repair 2026-10-01 12:41:01 +02:00
scripts Loopbound: time-loop incremental game — engine, Act 1 content, web/desktop/mobile 2026-07-02 22:28:02 +00:00
slice planning/slice 3 Mark Slice 3 planning repairs re-review ready 2026-09-15 12:31:30 +02:00
sprint-planning Tighten Slice 11 causal event ordering and lore condition 2026-09-25 13:57:23 +02:00
src Scope catastrophe evaluation through observation-only context 2026-10-02 14:43:39 +02:00
src-tauri Loopbound: time-loop incremental game — engine, Act 1 content, web/desktop/mobile 2026-07-02 22:28:02 +00:00
test-results Give the planner the git access its own first step needs 2026-09-12 16:33:15 +00:00
tests Prove aptitude cascades preserve observation policy 2026-10-02 14:44:15 +02:00
.gitignore Ignore Playwright run artifacts 2026-09-12 16:34:48 +00:00
AGENTS.md docs: clarify causal deadline exception 2026-09-14 23:23:45 +02:00
capacitor.config.ts Loopbound: time-loop incremental game — engine, Act 1 content, web/desktop/mobile 2026-07-02 22:28:02 +00:00
CI_CHECKS.md docs: reconcile final Forgejo CI contract 2026-09-20 11:41:40 +02:00
CONTENT_AUTHORING.md Document policy propagation through engine cascades 2026-10-02 14:44:34 +02:00
eslint.config.mjs Allow separate TypeScript type imports in lint 2026-08-31 15:34:14 +02:00
index.html Loopbound: time-loop incremental game — engine, Act 1 content, web/desktop/mobile 2026-07-02 22:28:02 +00:00
package-lock.json Merge branch 'main' into dependabot/npm_and_yarn/react-c3539c2691 2026-09-14 12:26:26 +02:00
package.json ci: format Forgejo workflow definitions 2026-09-20 10:57:34 +02:00
plan-game-mechanics-addendum.md docs: repair PR 33 final acceptance findings 2026-09-15 05:02:53 +00:00
plan.md Synchronize roadmap delivery status 2026-09-25 11:33:03 +02:00
playwright.config.mjs Add Playwright browser smoke configuration 2026-08-31 15:26:15 +02:00
README.md Synchronize current architecture and progression docs 2026-09-15 14:04:18 +02:00
tsconfig.json Loopbound: time-loop incremental game — engine, Act 1 content, web/desktop/mobile 2026-07-02 22:28:02 +00:00
vite.config.ts Loopbound: time-loop incremental game — engine, Act 1 content, web/desktop/mobile 2026-07-02 22:28:02 +00:00

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:

  1. Install Rust (stable) via rustup.
  2. 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:

  1. Install Android Studio (includes the Android SDK; install an SDK Platform ≥ 33 and command-line tools via its SDK Manager).
  2. 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:

  1. Xcode (App Store) + xcode-select --install.
  2. CocoaPods: sudo gem install cocoapods (or brew install cocoapods).
  3. 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

  1. LoopState is wiped and rebuilt from PersistentProgress on 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.
  2. Content is data. Regions, actions (with multi-method resolution + sourceType XP 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 under src/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 deposits in a content pack, plus a search/gather action 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.