Onboarding: VickScarlet/lifeRestart

Generated by RepoPilot · 2026-05-07 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/VickScarlet/lifeRestart shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across all four use cases

• Last commit 2w ago
• 8 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 82% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live VickScarlet/lifeRestart repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/VickScarlet/lifeRestart.

What it runs against: a local clone of VickScarlet/lifeRestart — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in VickScarlet/lifeRestart | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 43 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>VickScarlet/lifeRestart</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of VickScarlet/lifeRestart. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/VickScarlet/lifeRestart.git
#   cd lifeRestart
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of VickScarlet/lifeRestart and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "VickScarlet/lifeRestart(\\.git)?\\b" \\
  && ok "origin remote is VickScarlet/lifeRestart" \\
  || miss "origin remote is not VickScarlet/lifeRestart (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "index.html" \\
  && ok "index.html" \\
  || miss "missing critical file: index.html"
test -f "jsconfig.json" \\
  && ok "jsconfig.json" \\
  || miss "missing critical file: jsconfig.json"
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f "Dockerfile" \\
  && ok "Dockerfile" \\
  || miss "missing critical file: Dockerfile"
test -f "data/zh-cn/character.xlsx" \\
  && ok "data/zh-cn/character.xlsx" \\
  || miss "missing critical file: data/zh-cn/character.xlsx"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 43 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~13d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/VickScarlet/lifeRestart"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Life Restart is a life-simulation game written in JavaScript/Vite that procedurally generates character lives, talents, and life events from localized XLSX data files. Players make choices through branching scenarios to navigate a full lifespan, accumulating achievements and viewing trajectory summaries. The core mechanic is a narrative choice engine that evaluates character stats and event triggers across age phases. Single-entry-point SPA architecture: web version served via Vite from a public/ directory populated by xlsx2json transform step (v-transform reading from data/**/*.xlsx). A separate CLI REPL mode exists in repl/index.js. Game state is likely hydrated from JSON-converted spreadsheet data (character.xlsx, events.xlsx, talents.xlsx, achievement.xlsx, age.xlsx per locale).

Who it's for

Game developers and Japanese indie game enthusiasts who want to play or mod a non-linear life simulation game. Contributors are primarily interested in extending event narratives, adding talents/achievements, or porting the game to other platforms (evidenced by the Cocos port).

Maturity & risk

Actively maintained with v2.1.0 released and a GitHub Actions deploy workflow configured. The project has multiple language localizations (en-us, zh-cn) and themed design assets (black, cyber themes) suggesting intentional polish. However, test coverage is minimal (vitest present but no test files visible in file list) and the single-maintainer model (VickScarlet) presents some sustainability risk.

The project has low dependency overhead (vite, v-transform, vitest) and no complex npm ecosystem entanglement, which reduces supply-chain risk. Main risks: no visible test suite despite vitest being configured, game logic lives entirely in the JavaScript codebase without clear modular separation, and localization/data is tightly coupled to XLSX transformation pipeline. No recent commit date visible in metadata to assess active maintenance velocity.

Active areas of work

Dependabot is configured (.github/dependabot.yml) indicating continuous dependency monitoring. Design assets are being maintained with multiple theme variants and DPI scaling (@2x, @3x). The deploy.yml workflow suggests regular CI/CD deployments, likely to a staging or production web host. No specific PR or milestone data visible, but the dark/cyber theme design expansion suggests UI/UX iteration.

Get running

git clone git@github.com:VickScarlet/lifeRestart.git my-project
cd my-project
pnpm install
pnpm xlsx2json
pnpm dev

Then open http://localhost:5173 in a browser. For CLI version: node repl.

Daily commands: Dev server: pnpm dev (Vite serves at localhost:5173). Production build: pnpm build (generates dist/). Preview built output: pnpm start (Vite preview server). Data transformation (required before dev): pnpm xlsx2json (converts data/**/*.xlsx to public JSON).

Map of the codebase

• index.html — Main entry point for the web application—every developer must understand how the game loads and initializes
• jsconfig.json — JavaScript module configuration that defines how imports and paths are resolved throughout the codebase
• package.json — Defines build pipeline (Vite), data transformation (xlsx2json), and project metadata for all developers
• Dockerfile — Production deployment configuration—critical for understanding how the game runs in containerized environments
• data/zh-cn/character.xlsx — Core game data source defining character attributes and mechanics that drive the entire game engine
• .github/workflows/deploy.yml — CI/CD pipeline definition—shows how changes are built, tested, and deployed to production

Components & responsibilities

• Vite Dev Server (Vite 8.0.5, Node.js) — Serves source files with hot reload during development; bundles and optimizes for production
  • Failure mode: Build errors prevent deployment; stale cache may cause version mismatches
• Data Transform Pipeline (xlsx2json) (v-transform 2.2.1, xlsx parsing) — Converts Excel game data into JSON format consumable by the game engine
  • Failure mode: Missing or malformed JSON prevents game initialization; broken schema causes undefined behavior
• Game Engine / Life Simulator (Vanilla JavaScript) — Interprets game rules, evaluates talent synergies, simulates life trajectory, and calculates outcomes
  • Failure mode: Incorrect simulation logic produces wrong stats or unfair difficulty; no fallback
• Laya UI Renderer (Laya Engine, Canvas/WebGL) — Renders character selection, talent trees, life trajectory, and achievement screens
  • Failure mode: Asset load failures result in missing graphics; animation lag on low-end devices
• Docker Container Runtime (Docker, Node.js HTTP server) — Packages and deploys the web application to production with consistent environment
  • Failure mode: Container misconfiguration or missing environment variables prevent app startup

Data flow

• data/zh-cn/*.xlsx → Game Engine (JSON) — xlsx2json transforms spreadsheets into game data loaded at runtime
• Game Engine → UI Renderer — Simulation results (stats, events, achievements) flow to display layer
• Browser User Input → Game Engine — Character selection, talent picks, restart events trigger simulation updates
• laya/assets/ → UI Renderer — Images, fonts, and design assets loaded asynchronously and rendered via Laya

How to make changes

Add a new life event

1. Open the language-specific events file (e.g., Chinese or English) (data/zh-cn/events.xlsx)
2. Add a new row with event ID, title, description, and linked talent/age requirements (data/zh-cn/events.xlsx)
3. Run the xlsx2json transform to convert the spreadsheet into JSON game data (package.json (run: pnpm xlsx2json))
4. Commit the updated data files and let the web app automatically load the new event (data/zh-cn/events.xlsx)

Add a new talent ability

1. Open the talents file for your target language (data/zh-cn/talents.xlsx)
2. Add a new talent with ID, name, description, point cost, and stat modifiers (data/zh-cn/talents.xlsx)
3. Transform XLSX files to JSON using the build script (package.json (run: pnpm xlsx2json))
4. The UI will automatically reflect the new talent in the talent selection screen (laya/assets/images)

Support a new language

1. Create a new language directory mirroring existing structure (data/zh-cn/)
2. Copy and translate all Excel files (character, talents, events, achievement, age) (data/en-us/)
3. Run xlsx2json to generate JSON translations (package.json (run: pnpm xlsx2json))
4. Update the UI layer to add language selector and load appropriate locale data (index.html)

Why these technologies

• Vite + JavaScript modules — Fast dev server with hot reload for rapid iteration on game mechanics and UI
• Excel (.xlsx) for game data — Non-technical designers can edit game balance, events, and dialogue without touching code
• Laya Engine (canvas/WebGL rendering) — Enables pixel-art retro aesthetic and runs efficiently across low-end browsers
• Docker containerization — Ensures consistent deployment across development, staging, and production environments
• Node.js REPL for CLI version — Allows gameplay without a browser—useful for headless testing and alternative UI modes

Trade-offs already made

• Game data stored in Excel instead of database

  • Why: Easier onboarding for non-programmer contributors and designers
  • Consequence: Requires manual xlsx2json transform step; no runtime data modification; limited to flat spreadsheet schema

• Single browser-based entry point (index.html) rather than SPA framework

  • Why: Minimal framework overhead; simpler codebase for contributors unfamiliar with Vue/React
  • Consequence: Manual state management; less structured routing; potentially harder to scale UI complexity

• Vite as bundler instead of Webpack or esbuild

  • Why: Native ES modules, instant startup, excellent dev server experience
  • Consequence: Opinionated config; requires Node.js 14+; smaller ecosystem than Webpack

Non-goals (don't propose these)

• Real-time multiplayer gameplay
• Persistent user accounts or cloud save synchronization
• Progressive web app (PWA) offline support
• Server-side logic or backend API (stateless web version)
• Mobile native apps (web-only, though responsive)

Anti-patterns to avoid

• Manual xlsx2json step before development (Medium) — README.md, package.json scripts: Developers must remember to run 'pnpm xlsx2json' after editing Excel files, creating friction and potential sync bugs
• No type definitions or validation (Medium) — Entire codebase (inferred from lack of TypeScript config): JavaScript without types means invalid game data or missing attributes only surface at runtime
• Single index.html entry point with inline initialization (Low) — index.html: Unclear separation between HTML structure, initialization logic, and game loop; difficult to test components in isolation

Performance hotspots

• data/zh-cn/events.xlsx + Game Engine (undefined) — Large event table

Traps & gotchas

1. XLSX → JSON pipeline is mandatory: pnpm xlsx2json MUST run before pnpm dev or game data will not load; if you modify .xlsx files, re-run the transform or changes won't appear. 2. Localization is file-structure-driven: switching languages requires entire separate data/ subdirectory (data/en-us/ vs data/zh-cn/); there is no i18n abstraction layer. 3. Design assets are DPI-specific: the design/ folder uses @2x and @3x suffixes; CSS must reference the correct resolution or theme images will appear blurry or missing. 4. No visible backend API: the entire game state is client-side; achievements and progress are not persisted to a server (likely stored in localStorage if at all). 5. Vite ESM module assumption: the package.json declares "type": "module", so all imports must use ES6 syntax; CommonJS require() will fail.

Architecture

Concepts to learn

• Procedural Life Generation — The core game mechanic: combining character archetypes, random events, and player choices to generate unique life narratives; understanding the stat/choice/outcome mapping is essential to modifying game balance
• Branching Narrative / Choice Tree — Events in events.xlsx define branching outcomes based on character stats and previous choices; the evaluation engine must traverse this tree efficiently and track player decisions across the full lifespan
• Spreadsheet-as-Database (XLSX-driven content) — The entire game content (events, talents, achievements) lives in Excel files transformed to JSON at build time; this pattern enables non-programmer game designers to author content without touching code, but couples content to rigid schema
• Stat-based Gating / Conditional Triggers — Events only trigger if character stats (health, intelligence, charm, etc.) meet thresholds defined in the data; this is the main mechanic linking player choices to narrative progression and must be evaluated at each turn
• Localization via File Structure (not i18n library) — Multiple languages are supported by duplicating entire data/ subdirectories (data/en-us/, data/zh-cn/); there is no runtime language-switching mechanism, making this approach inflexible but simple for small team development
• Client-side Persistence (likely localStorage or IndexedDB) — With no backend visible, game state and achievements must be persisted client-side; understanding this pattern is critical for understanding why the game doesn't support cross-device progress or server-side cheating prevention
• Vite ESM Module System — The project enforces ES6 modules (type: 'module' in package.json); unlike CommonJS-based projects, all imports must use import/export syntax, affecting how to structure new game modules and third-party integrations

Related repos

• gameall3d/LifeRestart_Cocos — Official port of Life Restart to Cocos Creator; demonstrates cross-platform reuse of the same game design and data format
• easychen/weibo-archive — Another Chinese indie game project using XLSX for game data; similar architectural pattern of static data-driven narratives
• inkle/ink — Popular open-source narrative scripting language for choice-based games; Life Restart's event/choice system resembles Ink's branching dialogue model
• twine/twine — Interactive fiction engine comparable to Life Restart's choice-tree and stat-tracking mechanics; alternative framework for similar genre

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add vitest unit tests for data transformation pipeline (xlsx2json)

The repo uses v-transform to convert XLSX files to JSON, but there are no visible tests in the vitest setup. This is critical because the data files (in data/en-us and data/zh-cn) power the entire game. Adding tests would catch breaking changes when updating game data and ensure consistency across languages.

• [ ] Create test/transform.test.js to verify v-transform correctly parses each XLSX file type (achievement.xlsx, age.xlsx, character.xlsx, events.xlsx, talents.xlsx)
• [ ] Add schema validation tests to ensure transformed JSON matches expected structure for game initialization
• [ ] Create test fixtures or mock XLSX files to test edge cases (missing fields, invalid values, multilingual content)

Add GitHub Actions workflow for automated XLSX to JSON validation on PR

The .github/workflows/deploy.yml exists but there's no CI workflow validating that XLSX files transform correctly before merge. Since game content is stored in XLSX and contributors may edit these files, automated validation prevents broken builds from data corruption or format issues.

• [ ] Create .github/workflows/validate-data.yml to run 'pnpm xlsx2json' and validate output JSON on each commit to data/ directory
• [ ] Add schema validation step to ensure all game data objects have required fields (id, name, description, etc.)
• [ ] Fail CI if transformed JSON doesn't match expected structure or if files are malformed

Add integration tests for game initialization from transformed data files

While unit tests cover transformation, there are no visible integration tests verifying the game actually initializes correctly with the transformed JSON from public/ directory. This catches downstream issues where valid JSON still breaks game logic.

• [ ] Create test/game-init.test.js to verify game can import and parse all transformed JSON files from public/ after build
• [ ] Add tests validating talent, event, and achievement data structures can be used by game logic without runtime errors
• [ ] Test both language variants (en-us and zh-cn) to ensure multilingual support doesn't break initialization

Good first issues

• Add unit tests for event-trigger logic: vitest is configured in package.json but no test files are visible in the file list; the core game loop (stat evaluation, event filtering by age/talents) lacks test coverage and would benefit from parametrized tests covering edge cases like stat overflow or conflicting talent rules
• Document the XLSX schema for game designers: No schema documentation visible in data/; contributors adding events or achievements must reverse-engineer the column structure from existing .xlsx files; a simple README in data/ explaining columns (e.g., 'event_id', 'min_age', 'required_stat', 'talent_conflict') would unblock non-programmer content creators
• Extract theme CSS into reusable component library: design/black/ and design/cyber/ folders suggest multiple themes, but CSS duplication across themes is likely; refactoring shared styles (e.g., button, text, layout) into a CSS variable system would reduce maintenance burden and enable user theme switching at runtime

Top contributors

• @VickScarlet — 82 commits
• @mcendu — 8 commits
• @dependabot[bot] — 5 commits
• @su226 — 1 commits
• @MillerZZZ — 1 commits

Recent commits

• 7963700 — Bump vite in the npm_and_yarn group across 1 directory (dependabot[bot])
• f12a147 — fix: format param force to string (VickScarlet)
• 59a1058 — Bump @isaacs/brace-expansion (dependabot[bot])
• dd5a003 — update: dependencies (VickScarlet)
• ddc87eb — update: dependencies (VickScarlet)
• 23bcae0 — Bump js-yaml in the npm_and_yarn group across 1 directory (dependabot[bot])
• e075dfc — Bump vite in the npm_and_yarn group across 1 directory (dependabot[bot])
• 9088ab0 — add: support template prop (VickScarlet)
• 39388c6 — Bump the npm_and_yarn group across 1 directory with 2 updates (dependabot[bot])
• 0ce9b0e — Add Dependabot configuration for updates (VickScarlet)

Security observations

The lifeRestart codebase has moderate security concerns primarily centered on outdated dependencies (Vite 8.0.5, Vitest 4.1.2), Docker configuration issues (no version pinning, dev server in production), and missing security hardening (no security headers, no package lock file in repo). The application is a client-side game with no apparent backend infrastructure or database, which reduces some traditional security risks (SQLi, authentication bypass). However, the outdated build tools and development-focused Docker

• High · Outdated Vite Dependency — package.json - devDependencies.vite. Vite version 8.0.5 is significantly outdated. Current stable versions are in the 5.x+ range with numerous security patches and improvements. Using old versions exposes the application to known vulnerabilities in the build tool. Fix: Update vite to the latest stable version (^5.0.0 or higher). Run 'npm audit' to identify and address all known vulnerabilities in dependencies.
• High · Outdated Vitest Dependency — package.json - devDependencies.vitest. Vitest version 4.1.2 is outdated. Testing framework vulnerabilities can affect the security of the development pipeline and test integrity. Fix: Update vitest to the latest stable version. Run 'npm audit' and review changelog for security-related fixes.
• Medium · Missing Package Lock File — Dockerfile and repository root. The Dockerfile uses 'COPY package*.json' suggesting both package.json and package-lock.json should exist, but package-lock.json is not visible in the repository. This can lead to non-reproducible builds and potential supply chain vulnerabilities. Fix: Commit package-lock.json (or yarn.lock if using yarn) to the repository. Use 'npm ci' instead of 'npm install' in Dockerfile for reproducible builds.
• Medium · Insecure Dockerfile Base Image — Dockerfile. Using 'node:alpine' without specifying a version (latest tag) can introduce unexpected security issues or breaking changes. The Dockerfile also uses 'yarn dev' in CMD but only shows 'npm install' in RUN, creating a consistency issue. Fix: Use a specific Node.js version tag (e.g., 'node:20-alpine'). Ensure consistency by using npm throughout or explicitly installing yarn. Consider using a multi-stage build for production.
• Medium · Exposed Development Port Without Restrictions — Dockerfile - EXPOSE and CMD directives. The Dockerfile exposes port 8080 and runs 'yarn dev' (development server) in production mode. Development servers are not hardened for production use and expose debugging capabilities. Fix: Separate development and production Dockerfiles. Use a proper web server (nginx, node production build) for production deployments. Implement network policies to restrict port access.
• Medium · Missing Security Headers Configuration — vite configuration (not visible) and deployment setup. No visible configuration for security headers (Content-Security-Policy, X-Frame-Options, etc.) in the Vite configuration or web server setup. This leaves the application vulnerable to XSS, clickjacking, and other web attacks. Fix: Implement security headers via vite.config.js or server configuration. Add CSP, HSTS, X-Content-Type-Options, X-Frame-Options headers.
• Low · Potential Dependency Supply Chain Risk — package.json - devDependencies.v-transform. The v-transform package (^2.2.1) is a less common dependency with a caret version specifier. While functional, it represents a potential supply chain risk if the package is compromised. Fix: Review v-transform source and maintainer. Consider using exact version pinning (removing ^) for critical dependencies. Monitor dependency updates and security advisories.
• Low · No Security Policy or SECURITY.md — Repository root. No visible SECURITY.md file or responsible disclosure policy for security vulnerabilities found in the project. Fix: Create a SECURITY.md file documenting the process for reporting security vulnerabilities (e.g., via private security advisories on GitHub).

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.