Edu-Tycoon Core Game Engine

A headless, data-driven business simulation game engine built with TypeScript, Zustand, and decimal.js.

🎯 Overview

Edu-Tycoon is a modular game engine that separates game logic from content. The engine reads business parameters from configuration files rather than hard-coding them, making it easy to add new businesses and mechanics without changing core code.

Key Features

• Data-Driven Architecture: Add new businesses by editing JSON config, not code
• Arbitrary-Precision Math: Uses decimal.js for all financial calculations to handle numbers > $10^15
• Educational Mechanics: Skill system that directly impacts business efficiency
• Persistent State: Auto-saves to localStorage with custom Decimal serialization
• Headless Design: Pure logic engine with no UI dependencies
• Type-Safe: Built with TypeScript strict mode

🏗️ Architecture

┌─────────────────┐
│  Config Layer   │  Static content (Skills, Businesses)
└────────┬────────┘
         │
┌────────▼────────┐
│ Logic Registry  │  Factory pattern: logicType → Calculation Formula
└────────┬────────┘
         │
┌────────▼────────┐
│  Game Store     │  Zustand state management + Game loop
│   (Zustand)     │
└────────┬────────┘
         │
┌────────▼────────┐
│  Persistence    │  localStorage with Decimal serialization
└─────────────────┘

📁 Project Structure

src/
├── core/
│   ├── types.ts           # TypeScript interfaces (GameState, BusinessConfig, etc.)
│   ├── logicRegistry.ts   # Business logic factory (LINEAR_SIMPLE, etc.)
│   └── efficiency.ts      # Skill-based efficiency calculator
├── config/
│   └── gameData.ts        # Static content (SKILLS, BUSINESSES)
├── store/
│   └── useGameStore.ts    # Zustand store with tick, buyUpgrade, unlockSkill
└── test.ts                # Comprehensive test suite

🚀 Getting Started

Installation

npm install

Running Tests

npm test

This runs the comprehensive test suite that validates:

• State initialization
• Business logic calculations
• Efficiency system
• Buy/upgrade mechanics
• Tick revenue generation
• Skill unlocking
• Large number handling
• localStorage persistence

Build

npm run build

🎮 Core Concepts

1. Businesses

Businesses are defined in src/config/gameData.ts. Each business has:

• logicType: Determines the calculation formula (e.g., LINEAR_SIMPLE)
• params: Configuration for the formula (baseCost, baseRevenue, growthFactor)
• reqSkills: Skills needed for 100% efficiency

Example:

{
  id: "biz_lemonade_stand",
  name: "Lemonade Stand",
  logicType: "LINEAR_SIMPLE",
  params: {
    baseCost: 10,
    baseRevenue: 1,
    growthFactor: 1.07
  },
  reqSkills: ["skill_financial_literacy", "skill_sales_psychology"]
}

2. Logic Types

The engine uses a factory pattern to map logic types to formulas:

LINEAR_SIMPLE

• Upgrade Cost: baseCost × (growthFactor)^level
• Revenue: level × baseRevenue × efficiency

Future logic types (e.g., BANKING, IT_PROJECT) can be added by implementing the BusinessLogic interface.

3. Skills

Skills reduce efficiency penalties. Each skill has a penaltyWeight (0.0 to 1.0). If a business requires a skill the player doesn't have, efficiency is reduced by that skill's weight.

Efficiency Formula: α = max(0.1, 1.0 - Σ penaltyWeights of missing skills)

Example:

• Business requires 2 skills: Financial Literacy (0.3) and Sales Psychology (0.2)
• Player has no skills: Efficiency = 1.0 - 0.3 - 0.2 = 50%
• Player learns Financial Literacy: Efficiency = 1.0 - 0.2 = 80%
• Player learns both: Efficiency = 100%

4. The Game Loop

The tick(deltaTime) function runs periodically (e.g., every 1 second) to generate revenue:

for each unlocked business:
  rawRevenue = calculateRawRevenue(level)
  efficiency = calculateEfficiency(business, unlockedSkills)
  finalRevenue = rawRevenue × efficiency × deltaTime
  money += finalRevenue

🧪 API Reference

Store Actions

import { useGameStore } from './store/useGameStore';

const store = useGameStore.getState();

// Buy or upgrade a business
store.buyUpgrade("biz_lemonade_stand");

// Unlock a skill
store.unlockSkill("skill_financial_literacy");

// Run the game loop (1 second)
store.tick(1);

// Reset the game
store.resetGame();

// Get upgrade cost
const cost = store.getUpgradeCost("biz_lemonade_stand");

// Get current revenue per second
const revenue = store.getCurrentRevenue("biz_lemonade_stand");

// Get efficiency for a business
const efficiency = store.getEfficiency("biz_lemonade_stand");

State Access

const state = useGameStore.getState();

console.log(state.money.toString());           // Current wallet balance
console.log(state.businesses);                 // All business states
console.log(state.unlockedSkills);            // List of learned skills

🔧 Extending the Engine

Adding a New Business

1. Add a new entry to BUSINESSES in src/config/gameData.ts:

{
  id: "biz_coffee_shop",
  name: "Coffee Shop",
  description: "A cozy café serving premium coffee",
  reqSkills: ["skill_customer_service", "skill_financial_literacy"],
  logicType: "LINEAR_SIMPLE",
  params: {
    baseCost: 100,
    baseRevenue: 5,
    growthFactor: 1.15
  }
}

That's it! The engine automatically picks it up. No code changes needed.

Adding a New Logic Type

1. Add the type to LogicType in src/core/types.ts:

export type LogicType = "LINEAR_SIMPLE" | "EXPONENTIAL_COMPLEX";

2. Implement the logic class in src/core/logicRegistry.ts:

class ExponentialComplexLogic implements BusinessLogic {
  calculateUpgradeCost(level: number): Decimal {
    // Your formula here
  }
  
  calculateRawRevenue(level: number): Decimal {
    // Your formula here
  }
}

3. Add it to the factory function:

export function getBusinessLogic(config: BusinessConfig): BusinessLogic {
  switch (config.logicType) {
    case "LINEAR_SIMPLE":
      return new LinearSimpleLogic(config.params);
    case "EXPONENTIAL_COMPLEX":
      return new ExponentialComplexLogic(config.params);
    // ...
  }
}

Adding a New Skill

Add a new entry to SKILLS in src/config/gameData.ts:

{
  id: "skill_customer_service",
  name: "Customer Service Excellence",
  bookInfo: {
    title: "How to Win Friends and Influence People",
    author: "Dale Carnegie",
    summary: "Master the art of customer relations..."
  },
  penaltyWeight: 0.25
}

📊 Technical Specifications

• Language: TypeScript 5+ (Strict Mode)
• State Management: Zustand with persist middleware
• Math Library: decimal.js for arbitrary-precision arithmetic
• Persistence: localStorage with custom Decimal serialization
• Module System: ESM (ES Modules)

🎓 Educational Philosophy

Edu-Tycoon teaches business concepts through gameplay:

• Financial Literacy: Understanding costs, revenue, and profit margins
• Compound Growth: Exponential scaling of upgrade costs
• Skill Investment: Learning pays dividends through increased efficiency
• Opportunity Cost: Choosing which businesses and skills to prioritize

📝 License

MIT

🤝 Contributing

This is an MVP. Future enhancements could include:

• More business logic types (banking, IT projects, real estate)
• Prestige system for long-term progression
• Multiplayer competition
• Event system for random market changes
• Achievement system

---

Built with ❤️ for education and gameplay