Anexim/Mana-Loop
1
1
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4eeb258d301366ce922ac7e7d0740374b0380d4c
Mana-Loop/AGENTS.md
T
n8n-gitea 4eeb258d30
Build and Publish Mana Loop Docker Image / build-and-publish (push) Successful in 24s
Details
docs: update AGENTS.md to reflect store-modules deprecation and utils/ migration
2026-05-08 13:49:30 +02:00

668 lines
28 KiB
Markdown
Executable File
Raw Blame History

# Mana Loop - Project Architecture Guide
This document provides a comprehensive overview of the project architecture for AI agents working on this codebase.
---
## 🔑 Git Credentials (SAVE THESE)
**Repository:** `git@gitea.tailf367e3.ts.net:Anexim/Mana-Loop.git`
**HTTPS URL with credentials:**
```
https://n8n-gitea:tkF9HFgxL2k4cmT@gitea.tailf367e3.ts.net/Anexim/Mana-Loop.git
```
**Credentials:**
- **User:** n8n-gitea
- **Email:** n8n-gitea@anexim.local
- **Password:** tkF9HFgxL2k4cmT
**To configure git:**
```bash
git config --global user.name "n8n-gitea"
git config --global user.email "n8n-gitea@anexim.local"
```
---
## ⚠️ MANDATORY GIT WORKFLOW - MUST BE FOLLOWED
**Before starting ANY work, you MUST:**
1. **Pull the latest changes:**
```bash
cd /home/user/repos/Mana-Loop && git pull origin master
```
2. **Do your task** - Make all necessary code changes
3. **Before finishing, commit and push:**
```bash
cd /home/user/repos/Mana-Loop
git add -A
git commit -m "descriptive message about changes"
git push origin master
```
**This workflow is ENFORCED and NON-NEGOTIABLE.** Every agent session must:
- Start with `git pull`
- End with `git add`, `git commit`, `git push`
**Git Remote:** `git@gitea.tailf367e3.ts.net:Anexim/Mana-Loop.git`
---
## Project Overview
**Mana Loop** is an incremental/idle game built with:
- **Framework**: Next.js 16 with App Router
- **Language**: TypeScript 5
- **Styling**: Tailwind CSS 4 with shadcn/ui components
- **State Management**: Zustand with persist middleware (modular store architecture)
- **Database**: Prisma ORM with SQLite (for persistence features)
## Core Game Loop
1. **Mana Gathering**: Click or auto-generate mana over time
2. **Studying**: Spend mana to learn skills and spells
3. **Combat**: Climb the Spire, defeat guardians, sign pacts
4. **Crafting**: Enchant equipment with spell effects
5. **Prestige**: Reset progress for permanent bonuses (Insight)
## Directory Structure
```
src/
├── app/
│ ├── page.tsx # Main game UI (~reduced via component extraction)
│ ├── layout.tsx # Root layout with providers
│ ├── api/ # API routes (minimal use)
│ └── components/ # App-level components
│ ├── GameOverScreen.tsx
│ ├── LeftPanel.tsx
│ └── ...
├── components/
│ ├── ui/ # shadcn/ui components (auto-generated)
│ └── game/ # All game components (modular structure)
│ ├── index.ts # Barrel exports
│ ├── GameContext.tsx
│ ├── ActionButtons.tsx
│ ├── CalendarDisplay.tsx
│ ├── CraftingProgress.tsx
│ ├── ManaDisplay.tsx
│ ├── TimeDisplay.tsx
│ ├── tabs/ # Tab-specific components
│ │ ├── index.ts
│ │ ├── AchievementsTab.tsx
│ │ ├── AttunementsTab.tsx
│ │ ├── CraftingTab.tsx
│ │ ├── DebugTab.tsx
│ │ ├── EquipmentTab.tsx
│ │ ├── GolemancyTab.tsx
│ │ ├── LabTab.tsx
│ │ ├── LootTab.tsx
│ │ ├── PrestigeTab.tsx
│ │ ├── SkillsTab.tsx
│ │ ├── SpellsTab.tsx
│ │ ├── SpireTab.tsx
│ │ ├── StatsTab.tsx
│ │ ├── EquipmentSlotGrid.tsx
│ │ ├── EquipmentControls.tsx
│ │ ├── EnchantmentsPanel.tsx
│ │ ├── EquipmentInventory.tsx
│ │ ├── SkillRow.tsx
│ │ ├── SkillCategoryHeader.tsx
│ │ ├── MilestoneProgress.tsx
│ │ ├── SkillMultipliers.tsx
│ │ ├── SpireHeader.tsx
│ │ ├── GuardianPanel.tsx
│ │ ├── RoomDisplay.tsx
│ │ ├── FloorControls.tsx
│ │ ├── CombatStatsPanel.tsx
│ │ └── ActivityLog.tsx
│ ├── crafting/ # Crafting-specific components
│ │ ├── index.tsx
│ │ ├── EnchantmentDesigner/
│ │ ├── EnchantmentApplier.tsx
│ │ ├── EnchantmentPreparer.tsx
│ │ └── EquipmentCrafter.tsx
│ ├── stats/ # Stats display components
│ │ ├── index.tsx
│ │ ├── CombatStatsSection.tsx
│ │ ├── ManaStatsSection.tsx
│ │ ├── ManaTypeBreakdown.tsx
│ │ ├── StudyStatsSection.tsx
│ │ └── UpgradeEffectsSection.tsx
│ ├── debug/ # Debug tools
│ │ ├── index.tsx
│ │ ├── SkillDebug.tsx
│ │ ├── ElementDebug.tsx
│ │ ├── AttunementDebug.tsx
│ │ ├── GolemDebug.tsx
│ │ ├── PactDebug.tsx
│ │ └── GameStateDebug.tsx
│ ├── shared/ # Shared sub-components
│ │ ├── MemorySlotPicker.tsx
│ │ ├── StudyProgress.tsx
│ │ └── UpgradeDialog.tsx
│ └── LootInventory/ # Loot display components
│ ├── index.tsx
│ ├── MaterialItem.tsx
│ ├── EssenceItem.tsx
│ ├── BlueprintsSection.tsx
│ ├── EquipmentItem.tsx
│ └── LootInventoryDisplay.tsx
└── lib/
├── game/
│ ├── stores/ # Modular Zustand stores (NEW)
│ │ ├── index.ts # Combined store exports
│ │ ├── gameStore.ts # Main store (~11KB, core state + tick)
│ │ ├── manaStore.ts # Mana state and actions (~9KB)
│ │ ├── combatStore.ts # Combat system (~9KB)
│ │ ├── prestigeStore.ts # Prestige/loop system (~8KB)
│ │ ├── skillStore.ts # Skill state and actions (~11KB)
│ │ ├── uiStore.ts # UI state (~2KB)
│ │ ├── gameLoopActions.ts # Game loop logic
│ │ ├── gameActions.ts # Generic game actions
│ │ └── gameHooks.ts # Store hooks
│ ├── store/ # Legacy store slices (migration in progress)
│ │ ├── index.ts # Re-exports from store.ts + computed utils
│ │ ├── combatSlice.ts # Combat state slice
│ │ ├── manaSlice.ts # Mana state slice
│ │ ├── skillSlice.ts # Skill state slice
│ │ ├── craftingSlice.ts # Crafting state slice
│ │ └── computed.ts # Computed stats
│ ├── store-modules/ # Legacy store utilities
│ ├── crafting-actions/ # Modular crafting system (NEW)
│ │ ├── index.ts
│ │ ├── application-actions.ts
│ │ ├── design-actions.ts
│ │ ├── preparation-actions.ts
│ │ ├── equipment-actions.ts
│ │ ├── crafting-equipment-actions.ts
│ │ ├── disenchant-actions.ts
│ │ └── computed-getters.ts
│ ├── skill-evolution-modules/ # Modular skill evolution (NEW)
│ │ ├── index.ts # Main export (~11KB)
│ │ ├── mana-well-flow.ts # Mana Well/Flow skills (~15KB)
│ │ ├── quick-learner.ts # Quick Learner skill (~7KB)
│ │ ├── focused-mind.ts # Focused Mind skill (~6KB)
│ │ ├── enchanting-skills.ts # Enchanting skills (~15KB)
│ │ ├── invocation-skills.ts # Invocation skills (~15KB)
│ │ ├── hybrid-skills.ts # Hybrid skills (~22KB)
│ │ ├── guardian-skills.ts # Guardian-related skills (~4KB)
│ │ ├── insight-harvest.ts # Insight Harvest skill (~7KB)
│ │ ├── mana-utility-skills.ts # Mana utility skills (~7KB)
│ │ ├── elemental-attunement.ts # Elemental Attunement (~7KB)
│ │ ├── knowledge-retention.ts # Knowledge Retention (~4KB)
│ │ ├── learning-skills.ts # Learning skills (~1KB)
│ │ ├── magic-skills.ts # Magic skills (~1KB)
│ │ ├── utils.ts # Skill evolution utilities
│ │ └── types.ts # TypeScript interfaces
│ ├── constants/ # Modular constants (NEW)
│ │ ├── index.ts
│ │ ├── core.ts # Core game constants
│ │ ├── elements.ts # Element definitions
│ │ ├── guardians.ts # Guardian definitions
│ │ ├── prestige.ts # Prestige upgrade definitions
│ │ ├── rooms.ts # Room type definitions
│ │ ├── skills.ts # Skill definitions (~30KB)
│ │ ├── spells.ts # Spell definitions
│ │ └── spells-modules/ # Spell sub-modules
│ ├── data/ # Game data definitions (NEW)
│ │ ├── enchantment-effects.ts
│ │ ├── enchantments/ # Enchantment definitions
│ │ ├── equipment/ # Equipment definitions
│ │ ├── golems/ # Golem definitions
│ │ ├── achievements.ts
│ │ ├── crafting-recipes.ts
│ │ └── loot-drops.ts
│ ├── crafting-slice.ts # Legacy crafting (being modularized)
│ ├── skill-evolution.ts # Legacy skill evolution (reduced, ~1.5KB)
│ ├── constants.ts # Legacy constants (reduced, ~1KB)
│ ├── store.ts # Legacy store (reduced, ~14KB)
│ ├── computed-stats.ts # Computed stats functions
│ ├── navigation-slice.ts # Floor navigation actions
│ ├── study-slice.ts # Study system actions
│ ├── effects.ts # Unified effect computation
│ ├── upgrade-effects.ts # Skill upgrade effect definitions
│ ├── types.ts # TypeScript interfaces
│ ├── formatting.ts # Display formatters
│ └── utils/ # Utility functions
└── utils.ts # General utilities (cn function)
```
*Note: A complete, up-to-date project tree is automatically generated on each commit and saved to `docs/project-structure.txt`. This file is generated by the pre-commit hook using `.husky/scripts/generate-project-tree.js` and respects `.gitignore` rules.*
## Key Systems
### 1. State Management (Modular Store Architecture)
The game uses a **modular Zustand store architecture** with multiple specialized stores:
#### Store Modules (`src/lib/game/stores/`)
- **gameStore.ts**: Core state, tick logic, and main actions (~11KB)
- **manaStore.ts**: Mana gathering, elements, conversion (~9KB)
- **combatStore.ts**: Combat system, spells, floor progression (~9KB)
- **prestigeStore.ts**: Prestige/loop system, insight, upgrades (~8KB)
- **skillStore.ts**: Skill state, studying, evolution (~11KB)
- **uiStore.ts**: UI state, modals, debug settings (~2KB)
#### Legacy Store Files (Being Migrated/Deprecated)
- **store.ts**: Reduced from ~2812 lines to ~14KB (core logic moved to stores/)
- **store-modules/**: Legacy utility functions being moved to `src/lib/game/utils/`
- `room-utils.ts` → `utils/room-utils.ts`
- `enemy-utils.ts` → `utils/enemy-utils.ts`
- `activity-log.ts` → `utils/activity-log.ts`
- **crafting-slice.ts**: Reduced, being replaced by crafting-actions/
#### Store Interaction Pattern
```typescript
// Each store can interact with other stores via get() and custom hooks
// Example from combatStore.ts:
import { useManaStore } from './manaStore';
// Access other store state
const manaState = useManaStore.getState();
```
### 2. Crafting System (Modular Architecture)
The crafting system has been split into focused action modules:
#### Crafting Action Modules (`src/lib/game/crafting-actions/`)
- **design-actions.ts**: Enchantment design creation (~3KB)
- **preparation-actions.ts**: Equipment preparation (~1KB)
- **application-actions.ts**: Enchantment application (~2KB)
- **equipment-actions.ts**: Equipment management (~2.5KB)
- **crafting-equipment-actions.ts**: Equipment crafting (~2.5KB)
- **disenchant-actions.ts**: Disenchanting logic (~1KB)
- **computed-getters.ts**: Crafting computed values (~2KB)
- **index.ts**: Barrel exports
### 3. Skill Evolution System (Modular Architecture)
The massive ~3400-line `skill-evolution.ts` has been split into focused modules:
#### Skill Evolution Modules (`src/lib/game/skill-evolution-modules/`)
- **index.ts**: Main export combining all skill trees (~11KB)
- **mana-well-flow.ts**: Mana Well and Mana Flow skills (~15KB)
- **quick-learner.ts**: Quick Learner and related skills (~7KB)
- **focused-mind.ts**: Focused Mind and study skills (~6KB)
- **enchanting-skills.ts**: Enchanting skill tree (~15KB)
- **invocation-skills.ts**: Invocation and Pact Mastery (~15KB)
- **hybrid-skills.ts**: Cross-attunement hybrid skills (~22KB)
- **guardian-skills.ts**: Guardian-related skills (~4KB)
- **insight-harvest.ts**: Insight and prestige skills (~7KB)
- **mana-utility-skills.ts**: Utility mana skills (~7KB)
- **elemental-attunement.ts**: Elemental skills (~7KB)
- **knowledge-retention.ts**: Knowledge retention skill (~4KB)
- **learning-skills.ts**: Basic learning skills (~1KB)
- **magic-skills.ts**: Magic-related skills (~1KB)
- **utils.ts**: Shared utilities
- **types.ts**: TypeScript interfaces
### 4. Constants System (Modular Architecture)
Game constants have been organized into domain-specific modules:
#### Constants Modules (`src/lib/game/constants/`)
- **core.ts**: Core game constants (timing, limits)
- **elements.ts**: Element definitions and hierarchies
- **guardians.ts**: Guardian definitions and stats
- **prestige.ts**: Prestige upgrade definitions
- **rooms.ts**: Room type definitions
- **skills.ts**: Complete skill definitions (~30KB)
- **spells.ts**: Spell definitions
- **spells-modules/**: Organized spell sub-modules
- **index.ts**: Barrel exports
### 5. Game Data (New Structure)
#### Data Directory (`src/lib/game/data/`)
- **enchantment-effects.ts**: Enchantment effect catalog
- **enchantments/**: Enchantment definitions by category
- **equipment/**: Equipment type definitions
- **golems/**: Golem type definitions
- **achievements.ts**: Achievement definitions
- **crafting-recipes.ts**: Crafting recipe definitions
- **loot-drops.ts**: Loot table definitions
### Computed Stats (`computed-stats.ts`)
Extracted utility functions for stat calculations:
- `computeMaxMana()`, `computeRegen()`, `computeEffectiveRegen()`
- `calcDamage()`, `calcInsight()`, `getElementalBonus()`
- `getFloorMaxHP()`, `getFloorElement()`, `getMeditationBonus()`
- `canAffordSpellCost()`, `deductSpellCost()`
```typescript
interface GameState {
// Time
day: number;
hour: number;
paused: boolean;
// Mana (now in manaStore.ts)
rawMana: number;
elements: Record<string, ElementState>;
// Combat (now in combatStore.ts)
currentFloor: number;
floorHP: number;
activeSpell: string;
castProgress: number;
// Progression (now in skillStore.ts)
skills: Record<string, number>;
spells: Record<string, SpellState>;
skillUpgrades: Record<string, string[]>;
skillTiers: Record<string, number>;
// Equipment
equipmentInstances: Record<string, EquipmentInstance>;
equippedInstances: Record<string, string | null>;
enchantmentDesigns: EnchantmentDesign[];
// Prestige (now in prestigeStore.ts)
insight: number;
prestigeUpgrades: Record<string, number>;
signedPacts: number[];
}
```
### Effect System (`effects.ts`)
**CRITICAL**: All stat modifications flow through the unified effect system.
```typescript
// Effects come from two sources:
// 1. Skill Upgrades (milestone bonuses)
// 2. Equipment Enchantments (crafted bonuses)
getUnifiedEffects(state) => UnifiedEffects {
maxManaBonus, maxManaMultiplier,
regenBonus, regenMultiplier,
clickManaBonus, clickManaMultiplier,
baseDamageBonus, baseDamageMultiplier,
attackSpeedMultiplier,
critChanceBonus, critDamageMultiplier,
studySpeedMultiplier,
specials: Set<string>, // Special effect IDs
}
```
**When adding new stats**:
1. Add to `ComputedEffects` interface in `upgrade-effects.ts`
2. Add mapping in `computeEquipmentEffects()` in `effects.ts`
3. Apply in the relevant game logic (tick, damage calc, etc.)
## Important Patterns
### Adding a New Effect
1. **Define in `enchantment-effects.ts`** (now in `data/enchantment-effects.ts`):
```typescript
my_new_effect: {
id: 'my_new_effect',
name: 'Effect Name',
description: '+10% something',
category: 'combat',
baseCapacityCost: 30,
maxStacks: 3,
allowedEquipmentCategories: ['caster', 'hands'],
effect: { type: 'multiplier', stat: 'attackSpeed', value: 1.10 }
}
```
2. **Add stat mapping in `effects.ts`** (if new stat):
```typescript
// In computeEquipmentEffects()
if (effect.stat === 'myNewStat') {
bonuses.myNewStat = (bonuses.myNewStat || 0) + effect.value;
}
```
3. **Apply in game logic**:
```typescript
const effects = getUnifiedEffects(state);
damage *= effects.myNewStatMultiplier;
```
### Adding a New Skill
1. **Define in `constants/skills.ts`** (NEW location)
2. **Add evolution path in `skill-evolution-modules/`** (NEW location)
- Create new module or add to existing module
3. **Export from `skill-evolution-modules/index.ts`**
4. **Update UI in `components/game/tabs/SkillsTab.tsx`**
### Adding a New Spell
1. **Define in `constants/spells.ts`** (NEW location)
2. **Add to `constants/spells-modules/`** if categorized
3. **Add spell enchantment in `data/enchantment-effects.ts`**
4. **Add research skill in `constants/skills.ts`**
5. **Map research to effect in `EFFECT_RESEARCH_MAPPING`**
## Git Hooks (Husky)
This project uses **Husky** to manage git hooks for automated checks and agent assistance:
### Pre-Commit Hook (`.husky/pre-commit`)
Runs automatically before each commit:
1. **File Size Check**: Ensures no staged file exceeds 400 lines (improves AI agent readability)
2. **Project Structure Generation**: Updates `docs/project-structure.txt` with current tree (respects `.gitignore`)
### Post-Merge Hook (`.husky/post-merge`)
Runs after merging branches:
- Checks if `package.json` or `package-lock.json` changed
- Automatically runs `npm install` to sync dependencies
### Implementation Files
- Hook scripts: `.husky/` directory
- File size check: `.husky/scripts/check-file-size.js`
- Tree generator: `.husky/scripts/generate-project-tree.js`
---
## Common Pitfalls
1. **Forgetting to call `getUnifiedEffects()`**: Always use unified effects for stat calculations
2. **Direct stat modification**: Never modify stats directly; use effect system
3. **Missing tier multiplier**: Use `getTierMultiplier(skillId)` for tiered skills
4. **Ignoring special effects**: Check `hasSpecial(effects, SPECIAL_EFFECTS.X)` for special abilities
5. **Not updating modular stores**: Check all stores in `stores/` directory for related state
6. **Bypassing crafting-actions**: Use the modular actions in `crafting-actions/` for new crafting features
## Testing
Run `npm run test` before every commit. Tests must pass.
When fixing a bug, write a test that would have caught it first.
Test files live in src/lib/game/stores/__tests__/.
Critical paths that must always have tests:
- Any store action that modifies rawMana
- Any store action that modifies equippedInstances
- computeRegen, computeMaxMana, calcDamage
- canAffordSpellCost, spendRawMana, deductSpellCost
## Testing Guidelines
- Run `npm run lint` after changes
- Run `npm run test` to execute unit tests
- Check dev server logs
- Test with fresh game state (clear localStorage)
- **New**: Tests are organized alongside their modules (e.g., `stores/__tests__/`, `store-tests/`)
## Modular Architecture Pattern
The codebase has been refactored from large monolithic files into focused, modular components. This improves:
- **Maintainability**: Each module has a single responsibility
- **Readability**: Files are under 400 lines (pre-commit hook enforces this)
- **AI Agent Efficiency**: Smaller files are easier to understand and modify
### Key Modular Directories
| Directory | Purpose | Line Count Target |
|-----------|---------|-------------------|
| `stores/` | Zustand store modules | < 400 lines each |
| `crafting-actions/` | Crafting system actions | < 400 lines each |
| `skill-evolution-modules/` | Skill trees by category | < 400 lines each |
| `constants/` | Game constants by domain | < 400 lines each |
| `data/` | Game data definitions | < 400 lines each |
| `components/game/tabs/` | UI tab components | < 400 lines each |
| `components/game/crafting/` | Crafting UI components | < 400 lines each |
| `components/game/stats/` | Stats display components | < 400 lines each |
### Creating a New Module
1. **Identify the domain**: Which system does it belong to?
2. **Create focused file**: Keep under 400 lines
3. **Export from index**: Add to barrel export file
4. **Update imports**: Fix all references to old location
5. **Test**: Run lint and tests before committing
---
## File Size Guidelines
### Current File Sizes (After Modular Refactoring)
| File | Lines | Size (bytes) | Notes |
|------|-------|--------------|-------|
| `stores/gameStore.ts` | ~300 | ~11KB | Core state + tick logic |
| `stores/manaStore.ts` | ~250 | ~9KB | Mana system |
| `stores/combatStore.ts` | ~250 | ~9KB | Combat system |
| `stores/prestigeStore.ts` | ~200 | ~8KB | Prestige system |
| `stores/skillStore.ts` | ~300 | ~11KB | Skill system |
| `stores/uiStore.ts` | ~50 | ~2KB | UI state |
| `crafting-actions/*.ts` | ~50-150 | ~1-3KB each | Modular crafting |
| `skill-evolution-modules/*.ts` | ~100-600 | ~4-22KB each | Modular skills |
| `constants/*.ts` | ~50-1000 | ~1-30KB each | Modular constants |
| `page.tsx` | ~100 | ~4KB | Main UI (heavily reduced) |
| `components/game/tabs/*.tsx` | ~50-400 | ~2-15KB each | Tab components |
### Guidelines
- **400 lines maximum** per file (enforced by pre-commit hook)
- Extract to modules when approaching 300 lines
- Use barrel exports (`index.ts`) for clean imports
- Keep related functionality together in modules
- **Modular architecture** is now the standard - all new code should follow this pattern
### Automated File Size Check
A pre-commit hook automatically checks all staged files. Files exceeding **400 lines** will be rejected. The hook runs via Husky and uses `.husky/scripts/check-file-size.js`. If your file is too large, refactor it into smaller modules before committing.
---
## 🚫 BANNED CONTENT - NEVER ADD THESE
### Lifesteal and Healing are BANNED
**DO NOT add lifesteal or healing mechanics to player abilities.**
This includes:
- `lifesteal` spell effects
- `heal` or `regeneration` abilities for the player
- Any mechanic that restores player HP or mana based on damage dealt
- Life-stealing weapons or enchantments
**Rationale**: The game's core design is that the player cannot take damage - only floors can. Healing/lifesteal mechanics are unnecessary and would create confusing gameplay.
### Banned Mana Types
The following mana types have been **removed** and should **never be re-added**:
- `life` - Healing/lifesteal themed (banned)
- `blood` - Life + Water compound (banned due to lifesteal theme)
- `wood` - Life + Earth compound (banned due to life connection)
- `mental` - Mind/psionic themed (removed for design consistency)
- `force` - Telekinetic themed (removed for design consistency)
### Removed Features
- LabTab — permanently removed. Do not re-add under any name.
The lab element conversion UI was replaced by attunements.
---
## 🔮 Mana Types Overview
### Base Mana Types (7)
| Element | Symbol | Color | Theme |
|---------|--------|-------|-------|
| Fire | 🔥 | #FF6B35 | Destruction, burn damage |
| Water | 💧 | #4ECDC4 | Flow, freeze effects |
| Air | 🌬️ | #00D4FF | Speed, wind damage |
| Earth | ⛰️ | #F4A261 | Stability, armor pierce |
| Light | ☀️ | #FFD700 | Radiance, holy damage |
| Dark | 🌑 | #9B59B6 | Shadows, void damage |
| Death | 💀 | #778CA3 | Decay, rot damage |
### Utility Mana Types (1)
| Element | Symbol | Color | Theme |
|---------|--------|-------|-------|
| Transference | 🔗 | #1ABC9C | Mana transfer, Enchanter attunement |
### Compound Mana Types (3)
| Element | Recipe | Theme |
|---------|--------|-------|
| Metal | Fire + Earth | Armor piercing, forged weapons |
| Sand | Earth + Water | AOE damage, desert winds |
| Lightning | Fire + Air | Fast damage, armor pierce, chain effects |
### Exotic Mana Types (3)
| Element | Recipe | Theme |
|---------|--------|-------|
| Crystal | Sand + Sand + Light | Prismatic, high damage |
| Stellar | Fire + Fire + Light | Cosmic, ultimate fire/light |
| Void | Dark + Dark + Death | Oblivion, ultimate dark/death |
### Mana Type Hierarchy
```
Base Elements (7) → Compound (3) → Exotic (3)
↓
Utility (1) ← Special attunement-based
```
<!-- gitnexus:start -->
# GitNexus — Code Intelligence
This project is indexed by GitNexus as **Mana-Loop** (3795 symbols, 6409 relationships, 146 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
## Always Do
- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
## Never Do
- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
## Resources
| Resource | Use for |
|----------|---------|
| `gitnexus://repo/Mana-Loop/context` | Codebase overview, check index freshness |
| `gitnexus://repo/Mana-Loop/clusters` | All functional areas |
| `gitnexus://repo/Mana-Loop/processes` | All execution flows |
| `gitnexus://repo/Mana-Loop/process/{name}` | Step-by-step execution trace |
## CLI
| Task | Read this skill file |
|------|---------------------|
| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
<!-- gitnexus:end -->
Reference in New Issue View Git Blame Copy Permalink