  Logica - Intelligent AI Enhancement Mod

  Give Minecraft mobs true intelligence

  📖 Description

  Logica is an AI enhancement mod built on the https://github.com/hongshanyin/Aperi_Oculos perception framework, bringing revolutionary intelligent
  behavior systems to Minecraft mobs. Through invisible marker blocks and advanced state machine architecture, every mob can become a smart guard, vigilant
  sentry, or professional patrol.

  ✨ Core Features

  🎯 Three AI Strategies

  🔴 Guard Strategy

  - Role: Territory defense, never leaving home
  - Behavior: Random wandering within 6-block radius of spawn point, returns home if too far
  - Trait: Loyal home guardian, ideal for defending key areas
  - Speed: Normal (1.0x)

  🔵 Sentries Strategy

  - Role: High-speed patrol, rapid response
  - Behavior: Strictly follows waypoint path at high speed, rarely stops
  - Trait: Plays bell alarm when spotting players, broadcasts alert to nearby mobs
  - Speed: Fast (1.3x)

  ⚪ Patrol Strategy

  - Role: Area search, comprehensive coverage
  - Behavior: Zigzag wandering between waypoints, forming wide search patterns
  - Trait: Pauses to look around at each waypoint, 3-4x coverage area vs sentries
  - Speed: Faster (1.2x)

  ---
  🧠 Intelligent State System

  Five AI states with smooth transitions:
  - IDLE - Executes strategy behavior: guard wandering/sentry patrol/patrol search
  - ALERT - Hears sound, quickly turns head, moves to investigate
  - COMBAT - Spots player, actively attacks
  - TRACKING - Lost sight during combat, tracks by sound
  - SEARCHING - Tracking timeout, searches near last known position

  ---
  👂 Realistic Perception System

  Advanced perception powered by Aperi Oculos:
  - ✅ Visual Detection - Considers distance, FOV angle, lighting, obstacles
  - ✅ Auditory Perception - Monitors 8 sound types: footsteps, block breaking, shooting, etc.
  - ✅ Invisibility Mechanics - Invisibility + no glowing = truly invisible
  - ✅ Lighting Effects - Can escape tracking in darkness (light level 0-3)

   Realistic armor-based stealth system:

  Armor Impact

  - Light Armor (Leather, Cloth)
    - ✅ No movement sound penalty
    - ✅ Sneaking reduces footstep range to 1 block
    - 💡 Ideal for infiltration missions and stealth operations
  - Heavy Armor (Chainmail, Iron, Diamond, Netherite)
    - ⚠️ Footstep range increased by 50%
    - 🔇 Sneaking reduces sound range by 50% (from increased base)
    - ⚖️ Trade-off between defense and stealth

  Strategic Choices

  - Stealth Build: Light armor + sneaking = Nearly silent (1-block sound range)
  - Warrior Build: Heavy armor + frontal combat = High defense but easily detected
  - Hybrid Build: Remove heavy armor at critical moments, switch tactics

  ---
  🗺️ Flexible Path System

  Marker Blocks (Visible in Creative, Fully Invisible in Survival)

  - Guard Marker 🔴 - Red, defines guard spawn point
  - Sentries Marker 🔵 - Light blue, activates high-speed patrol
  - Patrol Marker ⚪ - White, enables area search
  - Waypoints 🔵⚪ - Blue/white, defines movement routes

  Unique Waypoint Mechanics

  - Sentries - Waypoints must be connected (BFS search), strict routes
  - Patrol - All waypoints within 16-block radius of marker (no connection required), flexible layout

  Numbering System (0-15)

  - Each strategy supports 16 independent IDs
  - Same ID creates organized patrol routes
  - Different IDs allow complex multi-layer defenses

  ---
  🎮 Use Cases

  🏰 Adventure Maps/Structure

  - Create multi-layer defense systems (outer patrol + inner sentries + core guards)
  - Design stealth infiltration missions
  - Build puzzles requiring sound decoys

  🗡️ PVE Challenges

  - Intelligent boss rooms (guard boss + patrol minions)
  - Dynamic difficulty: mobs actively search for hiding players
  - Realistic tracking: shaking off pursuers requires skill

  🏗️ Building Protection

  - Protect important structures (villages, bases, portals)
  - Automated defense system: mobs never abandon posts
  - Works with Structure Blocks to save entire defense systems

  ---
  🔧 Technical Highlights

  Layered Architecture

  ┌─────────────────────────────────┐
  │   Aperi Oculos (Perception)     │
  │   - Visual/Auditory Detection   │
  │   - Event Broadcasting          │
  └──────────────┬──────────────────┘
                 │ Event-Driven
                 ▼
  ┌─────────────────────────────────┐
  │   Logica (Decision)             │
  │   - State Machine Management    │
  │   - Strategy System             │
  │   - Behavior Tree/Goals         │
  └──────────────┬──────────────────┘
                 │ Commands
                 ▼
  ┌─────────────────────────────────┐
  │   Minecraft (Execution)         │
  │   - Navigation/Turning/Attack   │
  └─────────────────────────────────┘

  Performance Optimization

  - ✅ Caching System: Aperi Oculos vision caching 5 ticks (75-85% hit rate)
  - ✅ Smart Queries: Avoids per-tick recalculation, minimizes overhead
  - ✅ Vanilla Compatible: Preserves vanilla attack goals, conflict-free integration

  ---
  ⚙️ Configuration Options

  Fully configurable AI parameters:
  [Strategies]
  guardRadius = 6.0                    # Guard wandering radius
  guardSpeedMultiplier = 1.0           # Guard speed multiplier
  sentriesSpeedMultiplier = 1.3        # Sentries speed multiplier
  sentriesRestChance = 0.1             # Sentries rest probability
  patrolSpeedMultiplier = 1.2          # Patrol speed multiplier
  patrolSearchRadius = 8.0             # Patrol wandering radius

  [Perception]
  investigationSpeedMultiplier = 1.5   # Investigation speed multiplier
  investigationDurationTicks = 200     # Investigation look-around duration
  alertSoundVolume = 1.0               # Alert sound volume
  enableAlertParticles = true          # Alert particle effects

  [Sentries Alert]
  sentriesAlertRadius = 32.0           # Sentries alert range
  sentriesBellCount = 3                # Bell sound count
  sentriesBellInterval = 20            # Bell sound interval
  sentriesAlertAllTypes = false        # Alert all mob types or same type only

  ---
  📋 Requirements

  - Required: https://github.com/hongshanyin/Aperi_Oculos 1.0+
  - Minecraft Version: 1.20.1
  - Mod Loader: Forge
  - Java Version: 17+

  ---
  🚀 Quick Start

  1. Install Dependencies
    - Download Aperi Oculos and place in mods/ folder
    - Download Logica and place in mods/ folder
  2. Place Marker Blocks
    - Enter Creative mode, open Logica tab
    - Select strategy marker block (Guard/Sentries/Patrol)
    - Place in target area
  3. Add Waypoints (Optional, Sentries/Patrol only)
    - Place corresponding waypoint blocks (same ID number)
    - Sentries: Waypoints must be connected
    - Patrol: Within 16 blocks of marker
  4. Spawn Mobs
    - Spawn mobs near marker blocks
    - Mobs automatically apply strategy (3x3x3 detection range)
  5. Switch to Survival Mode
    - All marker blocks become invisible
    - Enjoy the new intelligent AI experience!

  ---
  💡 Tips & Tricks

  Sound Decoy System

  - Breaking blocks, walking, shooting create vibrations
  - Mobs enter ALERT state when hearing sounds
  - Investigate sound location at 1.5x speed
  - Use to lure patrol mobs away

  Light Hiding

  - Stealth very effective at light level 0-3
  - Can escape tracking even during combat using darkness
  - Combine with sound decoys for stealth opportunities

  Structure Block Compatible

  - Marker blocks fully support structure saving
  - Pre-build defense systems and copy them
  - Perfect for adventure map creators

  ---
  🛠️ Developer

  Sorcery Dynasties

  - Aperi Oculos Perception Framework: https://github.com/hongshanyin/Aperi_Oculos
  - Logica Decision Layer Mod: https://github.com/hongshanyin/Logica

  ---
  📜 License

  This project is open source under [GPL] license.

  ---
Logica_AI-enhanced
