Cognition Clash

Table of Contents

1. Overview
2. Core Concept
3. Technology Stack
4. Project Structure
5. Architecture Deep Dive
6. Game Flow
7. Contributing

---

Overview

Cognition Clash is a 4-player, co-op, turn-based card game. Team up as one of of four unique roles—Vanguard, Striker, Mender, or Tactician—to overcome surreal challenges and powerful adversaries in a world that changes with every battle.

This project was built with a focus on a clean, modular, and scalable architecture to make future development and maintenance as easy as possible.

Core Concept

The game loop is centered around cooperative, card-based combat and strategic, long-term progression.

• The Oracle (AI Game Master): The game is controlled by a central AI Game Master known as The Oracle. It is responsible for dynamically generating key aspects of the game to ensure endless replayability and challenge. Its duties include:
  • Enemy Generation: Creating adversaries with unique combinations of stats, skills, and affinities.
  • Strategic Puzzles: Designing the core combat challenges by generating new card effects and status afflictions.
  • Battle Objectives: Providing optional goals within missions for extra rewards.
  • Narrative Weaving: Crafting the overarching story, mission briefings, and environmental descriptions for each adventure.
• The Shifting Reality: The game is set in a surreal, ever-changing world dynamically crafted by The Oracle. Each adventure is a unique journey through bizarre landscapes against strange foes.
• Four Player Co-op: Team up with three other players to survive. Strategy and teamwork are essential.
• Fixed, Interdependent Roles: Choose from one of four unique classes, each with a specific function in combat.
• Card-Based Combat: Your actions are dictated by the cards in your hand. Each card has an Energy cost and a unique set of effects. On your turn, spend your Energy to play cards, then end your turn to let the enemy act.
• The Stagger System: Adversaries have a Resolve Bar. Use cards with 'Impact' to deplete it. When the bar breaks, the enemy becomes 'Staggered'—they skip their next turn and take massively increased damage.
• Deep Stat System: Characters are defined by a robust set of stats for survivability, offense, resources, and utility, including a full status effect (Affinity) system.
• Equipment & AI Cores: Player power is primarily derived from equipment.
  • Four Slots: Equip items in your Main Hand, Off-Hand, Relic, and Charm slots.
  • Strategic Effects: Items are powerful because they grant new passive abilities and triggered effects, not just raw stats.
  • AI Core Customization: Slot powerful AI Cores, found from challenging encounters, into your gear to gain unique, build-defining effects. This is the primary way to customize your playstyle.
• Mastery System: Instead of traditional leveling, progression is handled through a Mastery Tree unique to each role.
  • Earn Mastery Points (MP) from battles to unlock nodes in your tree.
  • Unlocks include new, powerful cards and game-changing passive abilities.
  • Progression is about expanding your strategic options, not just increasing raw numbers. Base stats do not increase.
• Currencies:
  • Shards: A common currency earned from battles, intended for buying card packs.
  • AI Data: A rarer currency for crafting specific cards and other high-end upgrades.

Technology Stack

• Framework: React (using Hooks)
• Language: TypeScript
• AI Integration: Google Gemini API via the @google/genai SDK
• Backend & Realtime Database: Google Firebase (for multiplayer features)
• Styling: Tailwind CSS

Project Structure

/
├── public/              # Static assets (including /sounds/)
├── src/
│   ├── components/      # Reusable UI components
│   ├── constants.ts     # Game balance values (stats, cards, mastery trees)
│   ├── hooks/           # Custom React hooks for stateful logic
│   ├── screens/         # Top-level components for each major app view
│   ├── services/        # API and external service layers
│   ├── types.ts         # Core TypeScript type definitions
│   ├── App.tsx          # Root component, high-level router
│   └── index.tsx        # Application entry point
├── README.md            # This file

Architecture Deep Dive

State Management

1. Application State: Managed in App.tsx. This includes the current screen (appState) and multiplayer game session data.
2. Progression State: The usePlayerProfile hook manages all long-term player data (currencies, mastery unlocks, equipment) and persists it to local storage.
3. Game State: The useGameLoop (single-player) and useMultiplayerGameLoop (co-op) hooks encapsulate all real-time battle logic.

Game Flow

1. Main Menu (MainMenu): User can start a "Quick Battle", manage their Loadout, view their Mastery Tree, or check their card collection/stats.
2. Battle (GameScreen / MultiplayerGameScreen): The core card-based combat loop. Stats are dynamically calculated based on the player's loadout.
3. Post-Battle (PostBattleScreen): After a battle, players are shown a summary and awarded Mastery Points and currencies for their performance.
4. Progression (MasteryScreen, EquipmentLoadoutScreen): Players spend their earned MP in the mastery tree or equip new gear and AI cores to enhance their capabilities for future battles.

Contributing

When adding new features or fixing bugs, please adhere to the existing architecture:

• Create Reusable Components: If a UI element is used in more than one place, extract it into /components.
• Isolate Logic in Hooks: Avoid putting complex business logic directly inside UI components.
• Keep Screens as Orchestrators: Screen components in /screens should primarily orchestrate data flow from hooks to presentational components.
• Use the Service Layer: All external API calls (Gemini, Firebase) must go through the services directory.
• Define Your Types: Use TypeScript and define all shared data structures in types.ts.