The Obsessed Knocker (javaMod)

This repository contains the source code for The Obsessed Knocker, a highly advanced horror stalker mod built for Minecraft Forge 1.20.1.

Developed as a freelance software engineering project, this mod showcases complex custom entity AI architecture, spatial scanning (house detection), routine-tracking algorithms, custom networking, and an interactive dialogue-based GUI system.

---

👁️ Mod Concept & Gameplay

The Obsessed Knocker is a psychological horror mod featuring a single, persistent entity—The Knocker—that stalks players, studies their base layout, monitors their daily routine, and attempts to psychologically torment them.

Rather than engaging in immediate combat, the Knocker acts as a subtle observer: it will watch the player through windows, knock on doors, extinguish torches, steal items, and whisper to them. Through a custom item called The Whisper, players can type questions and receive replies from the entity, directly influencing its behavior and aggression.

---

🧠 Key Systems & Architecture

1. Advanced Stalker AI System (nl.akari.theobsessedknocker.entity.ai)

Unlike standard Minecraft mobs that use simple follow-target AI, the Knocker runs on a complex state machine and brain system (KnockerBrain.java and KnockerBehaviour.java):

• Observation Goals: The entity locates windows or glass block structures near the player to watch them (KnockerWatchWindowGoal.java). It will also stand at a distance and observe them silently (KnockerObservePlayerGoal.java).
• Psychological Interactions: It breaks player torches/light sources to increase darkness (KnockerBreakTorchGoal.java) and knocks on wooden/iron doors when players are inside (KnockerKnockDoorGoal.java).
• Thievery: The AI can sneak into player bases, identify containers, and steal items (KnockerStealItemGoal.java).
• Personality & Relationship Scaling: Aggression level changes dynamically depending on the relationship status (RelationshipState.java) and the entity's personality (KnockerPersonality.java), scaling from passive stalking to a terrifying berserker state.

2. Base & House Scanning Engine (nl.akari.theobsessedknocker.entity.ai.house)

The mod features a custom spatial analysis utility (HouseScanner.java) that allows the Knocker to detect what constitutes a player base:

• It scans surrounding block types (walls, roofs, doors, and bed positions).
• It registers boundaries and entry/exit points, storing the data dynamically via HouseData.java.
• The AI uses this data to plan break-ins, door knocks, and window-watching angles.

3. Player Routine Tracking (nl.akari.theobsessedknocker.entity.ai.player)

To optimize stalking timing, the mod tracks player behaviors over time:

• PlayerRoutineTracker.java monitors player sleep patterns, average coordinate movements, and interaction history.
• The Knocker uses this data to schedule its appearances when the player is most vulnerable.

4. Interactive Dialogue & GUI System (nl.akari.theobsessedknocker.whisper)

Players receive The Whisper (TheWhisperItem.java), which opens a custom text dialogue screen (WhisperMenuScreen.java):

• Standard and advanced conversational queries are sent over custom Forge network packets (ServerboundWhisperPacket.java).
• Dialogue options like "Who are you?", "Stay away", or "Help" are processed in WhisperDialogueManager.java.
• Talking to the entity can cause it to teleport near the player, pacify it, or trigger an aggressive pursuit phase.

5. Single-Instance Spawning & Control (nl.akari.theobsessedknocker.world)

• KnockerWorldManager.java handles the spawning lifecycle, enforcing a strictly single instance of the Knocker globally.
• Natural spawning is suppressed until Day 2 (48,000 game ticks).
• Spawning conditions require rain, night-time, or cave darkness to trigger a 1-in-60 random chance of arrival.

---

📁 Repository Structure

javaMod/
├── 📂 TheObsessedKnocker/          # Main Forge 1.20.1 source project
│   ├── 📂 src/main/java/          # Java source files (AI, UI, network, etc.)
│   ├── 📂 src/main/resources/     # Mod assets (animations, ogg sound files, textures)
│   ├── build.gradle               # Gradle build file
│   ├── gradle.properties          # Version and environment variables
│   └── gradlew / gradlew.bat      # Gradle wrapper scripts
├── TheObsessedKnocker.zip         # Packed zip backup of the development workspace
└── README.md                      # Project documentation

---

🚀 Setup & Build Instructions

To set up the workspace for development or compilation, navigate to the TheObsessedKnocker folder and run the appropriate commands.

Prerequisites

• Java 17 SDK (Mojang standard for 1.20.1+)
• An IDE (IntelliJ IDEA recommended)

1. Import Workspace

• IntelliJ IDEA: Open the project by selecting the TheObsessedKnocker/build.gradle file and choosing "Open as Project".
• Eclipse: Import as an existing Gradle project.

2. Generate Run Configurations

To generate local testing environments, run the following task:

# Windows
.\gradlew genIntellijRuns

# Linux / macOS
./gradlew genIntellijRuns

3. Build & Package Mod Jar

To compile the mod and generate the final distributable jar file:

# Windows
.\gradlew build

# Linux / macOS
./gradlew build

The compiled mod jar will be generated under TheObsessedKnocker/build/libs/.