# simple-AGI
## Emergent Artificial Intelligence for Minecraft

> **Minecraft Forge 1.20.1 · Java 17 · Mod ID: `simple_agi`**

[🇺🇦 Українська версія](README.md)

---

**simple-AGI** is a Minecraft Forge mod that replaces the vanilla mob AI with a full cognitive pipeline.

```
Body → Hormones → Emotions → Memory → MindContext → Decision → Action
```

Each AGI entity (mob) owns a brain with **emotions, memory, hormones, social bonds, a spatial belief map, instincts, and genetically inherited species traits**. The system is fundamentally **stochastic** — two identical mobs in the same conditions will make different choices, producing an emergent living ecosystem.

---

## Table of Contents

- [Features](#features)
- [How It Works](#how-it-works)
- [Architecture](#architecture)
- [Commands](#commands)
- [Technical Details](#technical-details)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)

---

## Features

### 1. Cognitive Stack (7 Layers)

| Layer | Component | Description |
|-------|-----------|-------------|
| **Layer 1** | Body / Perception | Health, movement, attack, environment scanning |
| **Layer 2** | Hormones / Emotions | 7 hormones → 8 emotions (fear, grief, loneliness, confidence, etc.) |
| **Layer 3** | Memory | Episodic memory with emotional weighting, persistent disk storage |
| **Layer 4** | Social | Signal field, emotional contagion, bonds, species disposition |
| **Layer 5** | Cognition | MindContext (50+ fields), DecisionEngine (16 rule blocks), role system |
| **Layer 6** | Decision | ActionField with softmax + stochastic sampling (NOT argmax!) |
| **Layer 7** | Execution | MobAgentBody — move, attack, flee, stop |

### 2. Hormones & Emotions

**7 Hormones:**
- `adrenaline` — rapid threat spike
- `cortisol` — chronic stress
- `dopamine` — reward for exploration
- `serotonin` — environment stability
- `oxytocin` — social proximity
- `hormoneAggression` — combat readiness
- `melatonin` — night-cycle rhythm

**8 Emotions:**
- `fear`, `confidence`, `grief`, `loneliness`, `comfort`, `peacefulness`, `boredom`, `stress`

### 3. Memory & Spatial Belief Map

- **MemorySystem** — weighted episodic memory (max 100 events). Importance = base × (1 + fear + adrenaline × 0.5). Events decay over time.
- **WorldModel** — spatial belief map (8-block grid). Each zone has `danger`, `food`, `safety`, `familiarity` with time-based decay.
- **PersistentMemoryManager** — disk persistence in JSON: `cognitive_data/entity/<uuid>.json`, `species/<type>.json`, `world/danger_zone.json`.

### 4. Social System

- **LocalSignalField** — spatial signal field (`DANGER`, `FOOD`, `ATTACK`, `HELP`, `SAFE`, `RETREAT`). Signals decay over ~143 ticks.
- **SocialExchangeSystem** — emotional contagion between mobs (fear-comfort transmission), bond reinforcement.
- **AttachmentSystem** — home + bonds to allies. Grief at ally death scales with bond strength.
- **ResourceExchangeSystem** — item trading between mobs (`OFFER_ITEM`, `ACCEPT_ITEM`).

### 5. Species Knowledge Inheritance

- **SpeciesKnowledgeStore** — cross-generation trait inheritance:
- `caution`, `aggression`, `curiosity`, `playerHostility`
- `generations` — generation counter
- On mob death, traits pass to the next generation with 70% weight.

### 6. Emergent Language

- **Phoneme** — 16-symbol alphabet (4 energy groups).
- **Utterance** — word (1–3 phonemes), unique int key for O(1) lookup.
- **LexiconEntry** — meaning vector (6 slots: DANGER, FOOD, SAFE, ATTACK, RETREAT, CONTACT).
- Language emerges spontaneously: a mob sees danger → makes a sound → a neighbor hears it during the threat → association reinforces → shared lexicon.
- Words with confidence `+0.55` are inherited across generations.

### 7. Build System

- **BuildPlanner** + **BuildExecutor** — planning and construction.
- Bot can build from templates: `shelter`, `small_house`, `farm`, `wall`, `pillar`.
- Features: inventory check, stall detection, retry logic.

### 8. Group Capability Assessment

- Scans `20-block` radius to identify allies and threats.
- States: `DOMINANT` (ratio > 1.4), `CONTESTED` (0.5–1.4), `VULNERABLE` (< 0.5), `ALONE`.
- Influences FLEE/ATTACK in the DecisionEngine.

### 9. Role System

Automatically assigned by context:
- `LEADER` — dominant group → broadcasts ATTACK signals
- `SCOUT` — high dopamine → boosts EXPLORE
- `ATTACKER` — aggressive state → boosts ATTACK
- `DEFENDER` — protects allies
- `FOLLOWER` — follows leader

### 10. Trauma Propagation

When a mob dies within a 24-block radius:
- Witnesses gain `fear` + `grief` (attenuated by distance).
- Allies receive `allyBonus` + `bondGrief` (scaled by bond strength).
- `RevengeMotive` activates.
- Adrenaline spike, emotional memory log, and `DEATH` WorldModel event trigger.

---

## How It Works

### Full Brain Cycle (per server tick)

```
SERVER TICK (every N ticks)
│
├─ AttachedMobController → loops over all AGENTS (up to 150)
│ │
│ ├─ 1. BODY: Homeostasis.quickTick(), FeelingsSystem.tick(), RevengeMotive.tick()
│ ├─ 2. SOCIAL: SocialExchange (every 40 ticks)
│ ├─ 3. THREAT: findNearestThreat() → memory → DANGER/HELP signal → WorldModel
│ ├─ 3b. WORLDMODEL: markVisited(); tick() (every 20 ticks)
│ ├─ 4. TIME: dayTime, isNight, isSunset, isSunrise
│ ├─ 5. GROUP: GroupCapabilityModel (every 30 ticks)
│ ├─ 6. REVENGE: RevengeMotive.getKillerEntity()
│ ├─ 7. SIGNALS: LocalSignalField.senseIntensity ×6 types
│ ├─ 7a. FOOD: scanNearestFood (every 25 ticks)
│ ├─ 7b. ZONES: findSafeZone / findFoodZone (every 40 ticks)
│ ├─ 8. MindContext: full snapshot (50+ fields)
│ ├─ 9. DecisionEngine: 16 rule blocks → ActionField
│ ├─ 10. ProfileBias: species-specific instincts
│ ├─ 11. RoleSystem: role-based field shift
│ ├─ softmaxNormalize() → sample() → ActionIntent
│ ├─ 12. executeForMob(): MobAgentBody executes action
│ ├─ 13. MicroBehavior (if IDLE/EXPLORE)
│ └─ 14. MemoryDecay: decayEntityRecords() + decayImportance()
```

### DecisionEngine (16 Rule Blocks)

| Block | Description | Key Factors |
|-------|-------------|-------------|
| Block 1 | **FLEE** | fear × 0.45, cortisol × 0.20, critical health < 25% |
| Block 2 | **ATTACK** | aggressionTrait × 0.30, hormoneAggression × 0.35, adrenaline × 0.20 |
| Block 3 | **EXPLORE** | curiosityTrait × 0.30, dopamine × 0.25, boredom × 0.25 |
| Block 4 | **IDLE** | peacefulness × 0.30, grief × 0.45 (paralysis) |
| Block 5 | **EAT / MOVE_TO_FOOD** | hungerRatio × 0.60, nearestFood bonus |
| Block 6 | **Cave penalty** | isInCave + dark → FLEE↑, IDLE↑ for non-aggressors |
| Block 7 | **Semantic food** | semanticFoodScore > 0.1 → EXPLORE↑ |
| Block 8-11 | **Signal blocks** | sigDanger, sigFood, sigAttack, sigHelp, sigSafe, sigRetreat |
| Block 12 | **Home pull** | homesickness > 0.3 → MOVE_TO(home) |
| Block 13 | **Temporal** | isNight + avoidsSun → IDLE↑, FLEE↑ |
| Block 14 | **Revenge** | revengeMotive > 0.4 → ATTACK(revengeTarget) |
| Block 15 | **GroupCapability** | DOMINANT → ATTACK↑; VULNERABLE → FLEE↑ |
| Block 16 | **WorldModel** | zoneDanger > 0.35 → FLEE↑; familiarity < 0.05 → EXPLORE↑ |

### Stochasticity

`ActionField.sample()` uses **softmax + random sampling** instead of argmax. This means **no mob is predictable** — the same mob in the same conditions may choose differently, following a flexible probability distribution.

---

## Architecture

### Project Structure

```
src/main/java/com/rayman/
├── action/
│ ├── ActionExecutor.java — Action execution (move, attack, flee, eat, explore)
│ ├── ActionField.java — Probability weight field (softmax + sample)
│ └── ActionIntent.java — Action intent (with target)
├── ai/
│ ├── AttachedMobController.java ← CENTRAL ORCHESTRATOR
│ ├── AgiGoal.java — Minecraft Goal API wrapper
│ └── AIController.java — BotEntity controller
├── body/
│ ├── BotEntity.java — Dedicated AI player-like entity
│ ├── MobAgentBody.java — Move/attack/stop for any Mob
│ ├── AgentBody.java — Base body interface
│ ├── InventorySystem.java — Inventory management
│ └── core/
│ ├── Homeostasis.java — Body state aggregator
│ ├── HormoneSystem.java — 7-hormone system
│ ├── FeelingsSystem.java — 8-emotion system
│ ├── InstinctSystem.java — Basic instincts
│ ├── ReflexSystem.java — Reflexes
│ ├── NervousSystem.java — Nervous system
│ ├── FatigueSystem.java — Fatigue
│ ├── PainSystem.java — Pain
│ └── TemperatureSystem.java — Temperature
├── core/
│ ├── MindContext.java ← COGNITIVE STATE SNAPSHOT (50+ fields)
│ ├── DecisionEngine.java ← 16 RULE BLOCKS
│ ├── ActionScheduler.java — Action scheduler
│ ├── AttentionSystem.java — Attention system
│ ├── GoalSystem.java — Goals
│ ├── MotivationSystem.java — Motivation
│ ├── PredictionSystem.java — Prediction
│ ├── FailureModel.java — Failure model
│ ├── StabilityGovernor.java — Behavior stability
│ ├── SkillSystem.java — Skills
│ ├── GroupCapabilityModel.java — Force balance assessment
│ ├── RevengeMotive.java — Revenge motive
│ ├── RoleSystem.java — Role system
│ ├── CognitiveLayer.java — Cognitive layer interface
│ └── MicroBehaviorSystem.java — Small animations
├── memory/
│ ├── MemorySystem.java — Episodic memory
│ └── PersistentMemoryManager.java — Persistent JSON storage
├── perception/
│ ├── PerceptionSystem.java — Perception system
│ ├── AttentionFocus.java — Attention focus (central/peripheral)
│ ├── VisualMemory.java — Visual memory
│ ├── VisibilityResolver.java — Visibility resolution
│ ├── DynamicVisibility.java — Dynamic visibility
│ └── PerceptionResult.java — Perception result
├── personality/
│ ├── Personality.java — Personality
│ ├── FeelingsSystem.java — Emotional system
│ └── SelfModel.java — Self-model
├── social/
│ ├── LocalSignalField.java — Spatial signal field
│ ├── SocialExchangeSystem.java — Emotional exchange
│ ├── AttachmentSystem.java — Bonds and home
│ ├── SocialMemory.java — Disposition toward entities
│ ├── SpeciesKnowledgeStore.java — Cross-generation memory
│ ├── SpeciesMind.java — Inherited traits
│ ├── MobBehaviorProfile.java — Species behavior profile
│ ├── CognitiveTier.java — Cognitive tier
│ └── ResourceExchangeSystem.java — Item exchange
├── language/
│ ├── LanguageSystem.java — Language processor
│ ├── Phoneme.java — 16-symbol alphabet
│ ├── Utterance.java — Word (1–3 phonemes)
│ ├── LexiconEntry.java — Lexicon entry (meaning vector)
│ ├── SpeciesLexicon.java — Species lexicon
│ ├── Ukrainian* — Ukrainian language extensions
│ └── OntologicalRoot.java — Ontological root
├── build/
│ ├── BuildPlanner.java — Build planning
│ ├── BuildExecutor.java — Build execution
│ ├── BuildValidator.java — Plan validation
│ └── BuildProgress.java — Progress tracking
├── structure/
│ ├── StructureTemplate.java — Building template
│ └── TemplateLibrary.java — Template library
├── world/
│ ├── WorldModel.java — Spatial belief map
│ └── WorldState.java — World state
├── SimpleAgi.java ← Main mod class
├── Config.java Configuration
└── ARCHITECTURE.md Full architectural documentation
```

---

## Commands

| Command | Description |
|---------|-------------|
| `/gamerule globalCognition true/false` | Auto-attach AGI to all new mobs |
| `/simpleagi spawn` | Create BotEntity |
| `/simpleagi kill` | Remove BotEntity |
| `/simpleagi attach` | Attach AGI to the mob you are looking at |
| `/simpleagi attach_type <type> [radius]` | Attach AGI to all mobs of a given type |
| `/simpleagi detach` | Detach AGI from the mob you are looking at |
| `/simpleagi detach_all` | Detach all agents |
| `/simpleagi agents` | Show number of active agents |
| `/simpleagi build <template>` | Start building (shelter, small_house, farm, wall, pillar) |
| `/simpleagi build_stop` | Stop building |

### Configuration (`config/simple_agi-common.toml`):
```toml
aiTickInterval = 5 # AI tick interval (server ticks)
maxAgents = 150 # Maximum active AGI mobs (1–1000)
```

---

## Technical Details

### Performance & Optimization

- **LOD (Level of Detail):**
- `0–32 blocks` → full AI
- `32–64 blocks` → half rate (skip 1/2)
- `>64 blocks` → quarter rate (skip 3/4)
- **Staggering:** Each mob has a unique `phase = gameTime + mob.getId()`, spreading operations across time.
- **Chunk boundary guard:** Skips mobs in unloaded chunks.
- **ConcurrentHashMap:** All static maps use `ConcurrentHashMap` for thread safety.

### Cognitive Tiers

| Tier | lvl | maxPhon | lexCap | shareWds | memCap | wmRes | canTrade |
|------|-----|---------|--------|----------|--------|-------|----------|
| PRIMITIVE | 1 | 0 | 0 | 0 | 20 | 32 blocks | false |
| SIMPLE | 2 | 1 | 12 | 0 | 40 | 16 blocks | false |
| SOCIAL | 3 | 2 | 24 | 4 | 60 | 8 blocks | true |
| INTELLIGENT | 4 | 3 | 48 | 8 | 80 | 6 blocks | true |
| SAPIENT | 5 | 3 | 96 | 16 | 200 | 4 blocks | true |

### Time Characteristics

| Operation | Interval | Frequency |
|-----------|----------|-----------|
| Body tick | every AI tick | ~4/sec |
| Threat scan | every AI tick | ~4/sec |
| WorldModel.observe | every AI tick | ~4/sec |
| Social exchange | 40 game-ticks | ~0.5/sec |
| Food item scan | 25 game-ticks | ~0.8/sec |
| GroupCapabilityModel | 30 game-ticks | ~0.67/sec |
| WorldModel tick (decay) | 20 game-ticks | ~1/sec |
| DANGER memory log | 20 game-ticks | ~1/sec |
| Memory auto-flush (DANGER) | 200 mem-ticks | ~1 per 10 sec |
| Memory auto-flush (DEATH) | immediate | — |

---

## Requirements

- **Minecraft:** 1.20.1
- **Forge:** e.g., 47.x
- **Java:** 17+
- **Gradle:** 8.8+

## Installation

1. Clone the repository.
2. Open in your IDE (IntelliJ IDEA / Eclipse / VS Code).
3. Run `./gradlew build` (or `gradlew.bat build` on Windows).
4. Find the `.jar` in `build/libs/simple_agi-<version>.jar`.
5. Place the JAR in your Minecraft profile's `mods/` folder.
6. Launch the game with Forge.

## Quick Start

1. Create a world.
2. Enable global cognition: `/gamerule globalCognition true` (or manually attach AGI: look at a mob and run `/simpleagi attach`).
3. All mobs now have their own brains, emotions, memories, and even language!
4. Use `/simpleagi agents` to track the number of active agents.
5. To build: `/simpleagi build shelter`.

---

## License

---

> **Note:** For full architectural documentation, see [ARCHITECTURE.md](ARCHITECTURE.md) (includes ASCII diagrams, impact matrices, detailed component interaction schematics, and a complete description of every cognitive layer).

UA:

# simple-AGI — Emergent Artificial Intelligence for Minecraft

> **Minecraft Forge 1.20.1 · Java 17 · Mod ID: `simple_agi`**

**simple-AGI** замінює стандартний ІІ мобів Minecraft повноцінним когнітивним пайплайном:

```
Тіло → Гормони → Емоції → Пам'ять → MindContext → Рішення → Дія
```

Кожен AGI-кієкт (mob) має власний мозок із емоціями, пам'яттю, гормонами, соціальними зв'язками, просторовою картой переконань, інстинктами та генетично успадкованими рисами виду. Система повністю стохастична — два однакові моби в однакових умовах зроблять різні вибори, створюючи ефект живої екосистеми.

---

## Зміст

- [Функціонал](#функціонал)
- [Механізми роботи](#механізми-роботи)
- [Архітектура](#архітектура)
- [Команди](#команди)
- [Технічні деталі](#технічні-деталі)
- [Вимоги](#вимоги)
- [Встановлення](#встановлення)
- [Швидкий старт](#швидкий-старт)

---

## Функціонал

### 1. Когнітивний стек мобів (7 шарів)

| Шар | Компонент | Опис |
|-----|-----------|------|
| **Шар 1** | Тіло / Сприйняття | Здоров'я, рух, атака, сканування оточення |
| **Шар 2** | Гормони / Емоції | 7 гормонів → 8 емоцій (страх, горе, самотність, впевненість тощо) |
| **Шар 3** | Пам'ять | Епізодична пам'ять із емоційним вагуванням, постійне збереження на диск |
| **Шар 4** | Соціум | Сигнальне поле, обмін емоціями, бонди, міжвидова диспозиція |
| **Шар 5** | Когніція | MindContext (50+ полів), DecisionEngine (16 блоків правил), рольова система |
| **Шар 6** | Рішення | ActionField із softmax + стохастичний sample (NE argmax!) |
| **Шар 7** | Виконання | MobAgentBody — рух, атака, втеча, зупинка |

### 2. Емоції та гормони

**7 гормонів:**
- `adrenaline` — швидкий сплеск при загрозі
- `cortisol` — хронічний стрес
- `dopamine` — винагорода за дослідження
- `serotonin` — стабільність середовища
- `oxytocin` — соціальна близькість
- `hormoneAggression` — бойова готовність
- `melatonin` — нічний цикл

**8 емоцій:**
- `fear` (страх), `confidence` (впевненість), `grief` (горе),
- `loneliness` (самотність), `comfort` (комфорт), `peacefulness` (благість),
- `boredom` (нудьга), `stress` (стрес)

### 3. Пам'ять та просторова карта

- **MemorySystem** — епізодична пам'ять із вагованою важливістю (max 100 подій). Важливість = base × (1 + fear + adrenaline × 0.5). Події затухають із часом.
- **WorldModel** — просторова карта переконань (`8-блоковая сітка`). Кожна зона має: `danger`, `food`, `safety`, `familiarity` — усі з часовим затуханням.
- **PersistentMemoryManager** — збереження на диск у JSON: `cognitive_data/entity/<uuid>.json`, `species/<type>.json`, `world/danger_zone.json`.

### 4. Соціальна система

- **LocalSignalField** — просторове сигнальне поле (`DANGER`, `FOOD`, `ATTACK`, `HELP`, `SAFE`, `RETREAT`). Сигнали затухають (~143 тіків).
- **SocialExchangeSystem** — передача емоцій між мобами (зараження страхом/теплом), посилення бондів.
- **AttachmentSystem** — дім + бонди до союзників. Горе при смерті союзника ураховує силу бонду.
- **ResourceExchangeSystem** — обмін предметами між мобами (`OFFER_ITEM`, `ACCEPT_ITEM`).

### 5. Міжпоколінна пам'ять виду

- **SpeciesKnowledgeStore** — успадковує риси між поколіннями:
- `caution` (обережність), `aggression` (агресивність), `curiosity` (цікавість)
- `playerHostility` (ворожість до гравців)
- `generations` — лічильник поколінь
- При смерті моба риси із 70% вагою передаються наступному поколінню.

### 6. Виникаюча мова (Emergent Language)

- **Phoneme** — 16-символьний алфавіт (4 групи енергії).
- **Utterance** — слово (1–3 фонеми), унікальний int-ключ для O(1) lookup.
- **LexiconEntry** — вектор значень (6 слотів: DANGER, FOOD, SAFE, ATTACK, RETREAT, CONTACT).
- Мова виникає спонтанно: моб бачить загрозу → видає звук → сусід чує в той самий тік під час загрози → асоціація закріплюється → загальний лексикон.
- Слова, набрані впевненість `>= 0.55`, успадковуються між поколіннями.

### 7. Будівельна система (Build System)

- **BuildPlanner** + **BuildExecutor** — планування та виконання будівництва.
- Бот може будувати з шаблонів: `shelter`, `small_house`, `farm`, `wall`, `pillar`.
- З перевірками: перевірка інвентаря, контролі залипання, повторні спроби.

### 8. Оцінка балансу сил (GroupCapabilityModel)

- Сканування `20 блоків` для визначення союзників і загроз.
- Стани: `DOMINANT` (ratio > 1.4), `CONTESTED` (0.5–1.4), `VULNERABLE` (< 0.5), `ALONE`.
- Впливає на FLEE/ATTACK у DecisionEngine.

### 9. Рольова система (RoleSystem)

Автоматично призначається за контекстом:
- `LEADER` — домінантна група → broadcasts ATTACK
- `SCOUT` — високий dopamine → EXPLORE ↑
- `ATTACKER` — агресивний стан → ATTACK ↑
- `DEFENDER` — захист союзників
- `FOLLOWER` — слідування за лідером

### 10. Травматичне поширення (Trauma Propagation)

При смерті моба в радіусі 24 блоків:
- Свідки отримують fear + grief (з послабленням за відстань).
- Союзники отримують allyBonus + bondGrief (залежно від бонду).
- RevengeMotive активується.
- Adrenaline + emotional memory log + WorldModel event `DEATH`.

---

## Механізми роботи

### Повний цикл роботи мозку (за серверний тік)

```
SERVER TICK (кожні N тіків)
│
├─ AttachedMobController → цикл по всіх AGENTS (до 150)
│ │
│ ├─ 1. ТІЛО: Homeostasis.quickTick(), FeelingsSystem.tick(), RevengeMotive.tick()
│ ├─ 2. СОЦІУМ: SocialExchange (кожні 40 тіків)
│ ├─ 3. ЗАГРОЗА: findNearestThreat() → пам'ять → DANGER/HELP сигнал → WorldModel
│ ├─ 3b. WORLDMODEL: markVisited(); tick() (кожні 20 тіків)
│ ├─ 4. ЧАС: dayTime, isNight, isSunset, isSunrise
│ ├─ 5. ГРУПА: GroupCapabilityModel (кожні 30 тіків)
│ ├─ 6. ПОМСТА: RevengeMotive.getKillerEntity()
│ ├─ 7. СИГНАЛИ: LocalSignalField.senseIntensity ×6 типів
│ ├─ 7a. ПІШУГА: scanNearestFood (кожні 25 тіків)
│ ├─ 7b. ЗОНИ: findSafeZone / findFoodZone (кожні 40 тіків)
│ ├─ 8. MindContext: повний знімок (50+ полів)
│ ├─ 9. DecisionEngine: 16 блоків правил → ActionField
│ ├─ 10. ProfileBias: вид-специфічні інстинкти
│ ├─ 11. RoleSystem: роль → окремий зсув поля
│ ├─ softmaxNormalize() → sample() → ActionIntent
│ ├─ 12. executeForMob(): MobAgentBody виконує дію
│ ├─ 13. MicroBehavior (якщо IDLE/EXPLORE)
│ └─ 14. MemoryDecay: decayEntityRecords() + decayImportance()
```

### DecisionEngine (16 блоків правил)

| Блок | Опис | Ключові фактори |
|------|------|-----------------|
| Блок 1 | **FLEE** | fear × 0.45, cortisol × 0.20, critical health < 25% |
| Блок 2 | **ATTACK** | aggressionTrait × 0.30, hormoneAggression × 0.35, adrenaline × 0.20 |
| Блок 3 | **EXPLORE** | curiosityTrait × 0.30, dopamine × 0.25, boredom × 0.25 |
| Блок 4 | **IDLE** | peacefulness × 0.30, grief × 0.45 (паралізація) |
| Блок 5 | **EAT / MOVE_TO_FOOD** | hungerRatio × 0.60, nearestFood bonus |
| Блок 6 | **Cave penalty** | isInCave + dark → FLEE↑, IDLE↑ у non-aggressor |
| Блок 7 | **Semantic food** | semanticFoodScore > 0.1 → EXPLORE↑ |
| Блок 8-11 | **Сигнальні блоки** | sigDanger, sigFood, sigAttack, sigHelp, sigSafe, sigRetreat |
| Блок 12 | **Home pull** | homesickness > 0.3 → MOVE_TO(home) |
| Блок 13 | **Temporal** | isNight + avoidsSun → IDLE↑, FLEE↑ |
| Блок 14 | **Revenge** | revengeMotive > 0.4 → ATTACK(revengeTarget) |
| Блок 15 | **GroupCapability** | DOMINANT → ATTACK↑; VULNERABLE → FLEE↑ |
| Блок 16 | **WorldModel Phase 9** | zoneDanger > 0.35 → FLEE↑; familiarity < 0.05 → EXPLORE↑ |

### Стохастичність

`ActionField.sample()` використовує softmax + випадковий sample замість argmax. Це означає, що **жоден моб не є передбачуваним** — один і той самий моб у тих самих умовах може обрати різні дії, відповідно до пружної розподілу ймовірностей.

---

## Архітектура

### Структура проєкту

```
src/main/java/com/rayman/
├── action/
│ ├── ActionExecutor.java — Виконавець дій (рух, атака, втеча, їжа, дослідження)
│ ├── ActionField.java — Поле ваг імовірностей (softmax + sample)
│ └── ActionIntent.java — Інтент дії (з ціллю)
├── ai/
│ ├── AttachedMobController.java ← ЦЕНТРАЛЬНИЙ ОРКЕСТРАТОР
│ ├── AgiGoal.java — Minecraft Goal API wrapper
│ └── AIController.java — Контролер BotEntity
├── body/
│ ├── BotEntity.java — Спеціальна сутність AI-бота
│ ├── MobAgentBody.java — Рух/атака/стоп для будь-якого Mob
│ ├── AgentBody.java — Базовий інтерфейс для тіл
│ ├── InventorySystem.java — Управління інвентарем
│ └── core/
│ ├── Homeostasis.java — Агрегатор тілесного стану
│ ├── HormoneSystem.java — 7-гормональна система
│ ├── FeelingsSystem.java — 8-емоційна система
│ ├── InstinctSystem.java — Базові інстинкти
│ ├── ReflexSystem.java — Рефлекси
│ ├── NervousSystem.java — Нервова система
│ ├── FatigueSystem.java — Втома
│ ├── PainSystem.java — Біль
│ └── TemperatureSystem.java — Температура
├── core/
│ ├── MindContext.java ← ЗНІМОК КОГНІТИВНОГО СТАНУ (50+ полів)
│ ├── DecisionEngine.java ← 16 БЛОКІВ ПРАВИЛ
│ ├── ActionScheduler.java — Планувальник дій
│ ├── AttentionSystem.java — Система уваги
│ ├── GoalSystem.java — Цілі
│ ├── MotivationSystem.java — Мотивація
│ ├── PredictionSystem.java — Прогнозування
│ ├── FailureModel.java — Модель невдач
│ ├── StabilityGovernor.java — Стабільність поведінки
│ ├── SkillSystem.java — Навички
│ ├── GroupCapabilityModel.java — Оцінка балансу сил
│ ├── RevengeMotive.java — Мотив помсти
│ ├── RoleSystem.java — Рольова система
│ ├── CognitiveLayer.java — Інтерфейс когнітивного шару
│ └── MicroBehaviorSystem.java — Дрібні анімації
├── memory/
│ ├── MemorySystem.java — Епізодична пам'ять
│ └── PersistentMemoryManager.java — Постійне збереження JSON
├── perception/
│ ├── PerceptionSystem.java — Система сприйняття
│ ├── AttentionFocus.java — Фокус уваги (central/peripheral)
│ ├── VisualMemory.java — Візуальна пам'ять
│ ├── VisibilityResolver.java — Розв'язання видимості
│ ├── DynamicVisibility.java — Динамічна видимість
│ └── PerceptionResult.java — Результат сприйняття
├── personality/
│ ├── Personality.java — Особистість
│ ├── FeelingsSystem.java — Емоційна система
│ └── SelfModel.java — Модель самого себе
├── social/
│ ├── LocalSignalField.java — Просторове сигнальне поле
│ ├── SocialExchangeSystem.java — Обмін емоціями
│ ├── AttachmentSystem.java — Бонди та дім
│ ├── SocialMemory.java — Диспозиція до істот
│ ├── SpeciesKnowledgeStore.java — Міжпоколінна пам'ять
│ ├── SpeciesMind.java — Успадковані риси
│ ├── MobBehaviorProfile.java — Профіль поведінки виду
│ ├── CognitiveTier.java — Когнітивний рівень
│ └── ResourceExchangeSystem.java — Обмін предметами
├── language/
│ ├── LanguageSystem.java — Мовний процесор
│ ├── Phoneme.java — 16-символьний алфавіт
│ ├── Utterance.java — Слово (1–3 фонеми)
│ ├── LexiconEntry.java — Вхід у лексикон (вектор значень)
│ ├── SpeciesLexicon.java — Лексикон виду
│ ├── Ukrainian* — Розширення для української мови
│ └── OntologicalRoot.java — Онтологічний корінь
├── build/
│ ├── BuildPlanner.java — Планування будівництва
│ ├── BuildExecutor.java — Виконання будівництва
│ ├── BuildValidator.java — Валідація плану
│ └── BuildProgress.java — Відстеження прогресу
├── structure/
│ ├── StructureTemplate.java — Шаблон будівлі
│ └── TemplateLibrary.java — Бібліотека шаблонів
├── world/
│ ├── WorldModel.java — Просторова карта переконань
│ └── WorldState.java — Держава світу
├── SimpleAgi.java ← Головний клас мода
├── Config.java Конфігурація
└── ARCHITECTURE.md Повна архітектурна документація
```

---

## Команди

| Команда | Опис |
|---------|------|
| `/gamerule globalCognition true/false` | Авто-прикріплення AGI до всіх нових мобів |
| `/simpleagi spawn` | Створити BotEntity |
| `/simpleagi kill` | Видалити BotEntity |
| `/simpleagi attach` | Прикріпити AGI до моба в прицілі |
| `/simpleagi attach_type <type> [radius]` | Прикріпити AGI до всіх мобів типу |
| `/simpleagi detach` | Відкріпити AGI від моба в прицілі |
| `/simpleagi detach_all` | Відкріпити всі агенти |
| `/simpleagi agents` | Кількість активних агентів |
| `/simpleagi build <template>` | Розпочати будівництво (shelter, small_house, farm, wall, pillar) |
| `/simpleagi build_stop` | Зупинити будівництво |

### Конфігурація (config/simple_agi-common.toml):
```toml
aiTickInterval = 5 # Інтервал AI-тіків (сервер-тіків)
maxAgents = 150 # Максимум активних AGI-мобів (1–1000)
```

---

## Технічні деталі

### Performance & Optimization

- **LOD (Level of Detail):**
- `0–32 блоків` → повна AI
- `32–64 блоків` → половинна частота (skip 1/2)
- `>64 блоків` → чверть частота (skip 3/4)
- **Staggering:** Кожен моб має унікальний `phase = gameTime + mob.getId()`, тому всі операції з різними інтервалами рознесені по часу.
- **Chunk boundary guard:** Пропуск мобів у进展情况ванних чанках.
- **ConcurrentHashMap:** Усі static мапи використовують `ConcurrentHashMap` для потокобезпечності.

### Когнітивні рівні (CognitiveTier)

| Tier | lvl | maxPhon | lexCap | shareWds | memCap | wmRes | canTrade |
|------|-----|---------|--------|----------|--------|-------|----------|
| PRIMITIVE | 1 | 0 | 0 | 0 | 20 | 32 блоки | false |
| SIMPLE | 2 | 1 | 12 | 0 | 40 | 16 блоків| false |
| SOCIAL | 3 | 2 | 24 | 4 | 60 | 8 блоків | true |
| INTELLIGENT | 4 | 3 | 48 | 8 | 80 | 6 блоків | true |
| SAPIENT | 5 | 3 | 96 | 16 | 200 | 4 блоки | true |

---

## Вимоги

- **Minecraft:** 1.20.1
- **Forge:** наприклад, 47.x
- **Java:** 17+
- **Gradle:** 8.8+

## Встановлення

1. Склонуйте репозиторій.
2. Відкрийте у IDE (IntelliJ IDEA / Eclipse / VS Code).
3. Виконайте `./gradlew build` (або `gradlew.bat build` на Windows).
4. Отримайте `.jar` у `build/libs/simple_agi-<версія>.jar`.
5. Покладіть JAR у папку `mods/` вашого профілю Minecraft.
6. Запустіть гру з Forge.

## Швидкий старт

1. Створіть світ.
2. Увімкніть глобальне когнітивне підключення: `/gamerule globalCognition true` (або прикріпіть AGI вручну: дивіться на моба і виконайте `/simpleagi attach`).
3. Всі моби відте мають власний мозок, емоції, пам'ять і навіть мову!
4. Використайте `/simpleagi agents` щоб відстежувати кількість активних агентів.
5. Для будівництва: `/simpleagi build shelter`.

---

## Ліцензія

Всі права захищено, автор: bruhasub

---

> **Примітка:** Для повної архітектурної документації див. [ARCHITECTURE.md](ARCHITECTURE.md) (включає ASCII-схеми, матриці впливів, детальні схеми зв'язків між компонентами та повний опис кожного когнітивного шару).

Simple AGI