"You didn't wake up to rule. You woke up to decide."

Village Economy is an interactive visual novel and economic simulation game built for Hackonomics. You play as a newly reincarnated village chief advised by a talking donkey named Li (Prophet), and face ten sequential economic crises — each built around a real concept from micro and macroeconomics. Every decision is permanent, morally ambiguous, and has cascading effects on your village's GDP, CPI, unemployment, happiness, and population.

The game ends by profiling your economic ideology: are you a Keynesian Architect, a Free Market Libertarian, an Iron-Fisted Statist, or a Pragmatic Centrist? Fully playable in Chinese (中文) and English.

Live demo: https://hackonomics.vercel.app/

• Features
• Gameplay
• The Ten Economic Events
• Endings
• Tech Stack
• Project Architecture
• Getting Started
• Game Systems
• Achievement System
• Language Support
• Design Philosophy

• Visual novel narrative — cinematic opening sequence, emoji-based character portraits, and a full RPG-style dialogue engine
• 10 economic events spanning opportunity cost, diminishing marginal utility, negative externalities, creative destruction, inflation, monopoly, the paradox of thrift, taxation, comparative advantage, and currency warfare
• Real macroeconomics engine — GDP (expenditure approach), CPI (money-supply/productivity ratio), unemployment (labor market model), and daily ticks with compound interactions
• Live villager swarm — 20 animated NPCs walk, starve, and die based on your stats in real time
• 34 achievements — 30 choice-based achievements each named after a real economic concept, plus 4 ending achievements
• 4 possible endings — a true good ending, two bad endings, and a secret philosophical ending
• Bilingual — full Chinese/English support with a single toggle button; all dialogue, UI, crisis alerts, and daily messages switch instantly
• Persistent save — auto-saves to localStorage after every action; resumes exactly where you left off

The game opens with a fully voiced-style cutscene. You wake up in a dark room, hear three aunties debating whether your brain is broken, and then a donkey fills the screen and tells you the village is about to collapse. You are its new chief.

Between story events the game enters idle mode — a dual-panel management screen:

Each day you start with 3 Action Points. Spend them, then click Next Day to run the daily economic tick. Building infrastructure also determines which crisis events fire.

Each day automatically:

1. Calculates food production (foraging + farms + pastures) and consumption
2. Starves the village if food goes negative (deaths = ⌈deficit / 1.5⌉)
3. Computes income modified by happiness, market level, mine level, and tech
4. Recalculates GDP, CPI, and unemployment from first principles
5. Checks for immigration, inflation crises, and riot conditions
6. Dispatches the next story event if its trigger condition is met

Events interrupt the idle loop with a full-screen crisis alert showing the shock effects, then drop you into a multi-character dialogue scene that ends with an A / B / C choice. Your choice permanently alters stats and unlocks an achievement.

Each event fires once, in order of infrastructure and day progression. No choice is "correct" — every option maps cleanly to a real economic school of thought.

The granary has 18 kg of wheat. There are 20 villagers. Everyone needs at least 1 kg to survive.

After every event, Li the donkey delivers a short economics lesson — naming the concept, explaining why every path had a cost.

Complete all ten events. The epilogue reflects on your accumulated decisions and profiles your economic ideology. Achievement: The Watcher of Era (时代的守望者).

Population reaches zero from starvation. The village falls silent. Achievement: A Ghost Town (死寂之村).

Happiness reaches zero. Villagers storm the office with torches and pitchforks. Achievement: The Fall of a Tyrant (独裁者的末日).

Click Clear Memory on the title screen instead of starting the game. A slow cinematic plays out as you relinquish understanding of the world, live a simple life, and grow old. Achievement: The Gift of Being Unremarkable (平庸之赐).

No external game engine, no Redux, no animation library — all systems built from scratch in ~4 000 lines of TypeScript.

Hackonomics/
└── village-economy/
    └── src/
        ├── app/
        │   ├── layout.tsx          # Root layout — wraps children in LanguageProvider
        │   ├── page.tsx            # Title screen + RPG intro cutscene
        │   └── game/
        │       └── page.tsx        # Main game loop (dialogue, choices, idle sandbox)
        ├── lib/
        │   ├── nodes.ts            # All NODES definitions, GameStats type, INITIAL_STATS
        │   ├── engine.ts           # processDailyTick(), applyEffects(), recalculateMacroEconomics()
        │   ├── gameState.ts        # GameState / Achievement types, clampStats()
        │   ├── storage.ts          # localStorage save / load / clear
        │   ├── language.tsx        # React language context + useLanguage() hook
        │   └── translations.ts     # All bilingual text (UI, nodes, achievements, crisis, engine messages)
        └── components/
            ├── TopBar.tsx          # HUD stat pills + language toggle + log/new-game buttons
            ├── VillagerSwarm.tsx   # Orchestrates 20 walking NPC actors
            ├── Villager.tsx        # Individual NPC: walks → starves → dies
            ├── DialogueCard.tsx    # NPC dialogue card with speaker, avatar, and text
            ├── ChoiceOverlay.tsx   # A/B/C choice selection panel
            ├── LogDrawer.tsx       # Sliding event log timeline
            ├── AchievementToast.tsx# Pop-up notification on achievement unlock
            ├── AvatarPlaceholder.tsx # 140 px emoji portrait + speaker label
            └── EconomicProfile.tsx # End-game ideology dashboard + full achievement gallery

NODES (nodes.ts)                    ← all narrative content lives here
  └─ Node types: dialogue | choice | idle | narration | achievement | title_secret
       ↓ player picks A / B / C
applyEffects() (engine.ts)          ← mutates GameStats
  ├─ add / set / log / achievement / goto
  ├─ clampStats()                   ← enforces min/max bounds
  └─ recalculateMacroEconomics()    ← GDP, CPI, unemployment from scratch
       ↓
GameState → localStorage            ← auto-save after every action
       ↓
React re-render                     ← TopBar pills, VillagerSwarm, dialogue UI

GDP  = (population × 20) + (marketLevel × 300) + (productivity × 2)
     + (techLevel × 500) + (academyLevel × 800) + (mineLevel × 1200)
     + (money × 0.1)

CPI  = 100 × (money / 5000) / (productivity / 100)

UNEMP = max(0, laborForce − jobsAvailable) / laborForce × 100
        where laborForce  = floor(population × 0.6)
              jobsAvailable = floor(productivity/10) + mine×8 + farm×3 + market×4

Daily income = (pop×5) + (market×150) + (productivity×3) + (mine×300×tech)
             × happiness modifier (×0.2 if hap ≤ 30, ×0.6 if hap < 50, ×1.3 if hap > 80)

• Node.js 18 +
• npm

git clone https://github.com/Yinghao-Guan/Hackonomics.git
cd Hackonomics/village-economy
npm install
npm run dev          # → http://localhost:3000

npm run build        # Production build (Turbopack)
npm run start        # Serve production build
npm run lint         # ESLint check

Append ?reset=1 to the game URL to wipe localStorage and start fresh:

http://localhost:3000/game?reset=1

Or click Clear Memory (Reset Save) on the title screen.

Every day resets to 3 AP. Daily actions cost 1 AP; construction costs 3 AP. This enforces opportunity cost at the mechanical level — you cannot do everything at once.

When a crisis fires (from the daily tick), the screen flashes red with a crisis alert overlay showing the event name, description, and the immediate stat shocks applied before the story event begins.

TopBar stat pills turn red and pulse when:

• foodStock < population (starvation imminent)
• cpi > 120 (inflation crisis)
• unemploymentRate > 20% (unemployment crisis)
• happiness < 40 (riot risk)

• Starvation: deaths = ⌈|foodDeficit| / 1.5⌉ per day
• Immigration: if GDP > 3000 && happiness ≥ 70 && foodStock > population × 3, migrants arrive
• Riots: if happiness ≤ 20, a riot event fires (destroys market, costs money and population)
• Exile (bad ending): if happiness = 0, villagers overthrow you
• Death (bad ending): if population = 0, the village is abandoned

34 unique achievements — 30 for choices (one per major decision) and 4 for endings. Each carries a short philosophical commentary connecting your in-game decision to its real-world economic school of thought.

The game is fully bilingual. Click the EN / 中文 button in the top-right corner of any screen to switch languages instantly. No page reload required.

Translation data lives in src/lib/translations.ts. The language state is stored in a React context (src/lib/language.tsx) and is accessible from any component via useLanguage().

Every A/B/C choice is constructed so that a thoughtful person in a specific economic tradition would choose it. The Austrian economist picks free markets in every crisis; the Keynesian picks government intervention. Neither is wrong within their own framework. The game never moralizes.

Decisions don't just change one number. Building a mine eventually triggers a monopoly crisis (Event 6). Printing money (Event 5) unlocks the Print Money daily action, which lets you keep inflating CPI. The systems interact continuously, not event by event.

The Action Point system forces opportunity cost decisions mechanically. The "AP remaining unused" warning exploits loss aversion — players feel compelled to spend all three points even when doing so is suboptimal. Li the donkey calls this out explicitly after it happens.

Every event is structured the same way: a human conflict introduces the concept emotionally, Li explains the economic theory with dark humor, then the choice is made. After the choice, Li names the concept explicitly and explains why every option had a price. Economics education through drama, not lecture.

Li (立, Prophet) is the game's narrator, economist-in-residence, and moral foil. He never tells you what to do. He names what you already did. He is also, empirically, a donkey.

The project was built for the Hackonomics hackathon. The codebase is intentionally lean — no external game engine, no animation library, no state management beyond React hooks and localStorage. If extending the game:

• New events: Add nodes to NODES in nodes.ts, add English translations to NODES_EN in translations.ts, and set the trigger condition in processDailyTick() in engine.ts.
• New achievements: Add the effect { type: "achievement", id, title, description } in a choice node, and add the English version to ACHIEVEMENT_EN in translations.ts.
• New languages: Add a key to the Lang type in translations.ts, extend the UI, NODES_EN, and ENGINE_MSG objects, and add the toggle case in TopBar.tsx.

No open-source license has been attached to this repository at this time.

This project was created by our team for the Hackonomics hackathon. All rights are reserved unless we explicitly publish a license later.