The Book of Wishes

A Minecraft 1.21.1 NeoForge mod where an ancient, powerful entity grants your wishes — for a price.

What It Does

Write wishes in a magical book. An AI entity reads them, decides whether to grant them, and always demands payment. Every wish has a cost — no wish is ever free.

Features

• Custom Book of Wishes item — Write and submit wishes through a custom GUI
• Multiple AI backends — Embedded GGUF (no internet needed), Ollama, Groq, OpenAI, or Anthropic
• 50+ action types — Items, effects, teleportation, entity spawning, world modification, PvP actions, structure discovery, and more
• Payment system — The AI demands payment scaled to the wish: items, XP, named items, or resources from nearby players
• 5 AI personalities — Kind, Greedy, Trickster, Ancient, and Chaotic — each with unique response styles
• Reputation system — Trust level rises with granted wishes, falls with denials. Higher trust = better prices
• Difficulty scaling — Wishes get more expensive as you make more of them
• OP/Creative bypass — Players with operator permissions or in Creative mode always have wishes granted with no payment required
• Modded item support — Automatically scans the item registry so the AI knows about items from other mods
• Configurable structures — Add or remove structure types via config for modpack compatibility
• In-game config — Edit all settings from the Mods menu, no config file editing needed
• Wish history logging — All wishes are logged to disk for admin review
• Visual feedback — Enchantment particles while the AI thinks, totem particles on grant, smoke on denial, action bar payment notifications
• Mod list viewer — Type /wishes modlist to browse all detected mods and their items in-game

Requirements

• Minecraft 1.21.1
• NeoForge 21.1.x
• Java 21

Setup

1. Install the Mod

Download thebookofwishes-1.0.1.jar from Releases and place it in your server or client mods/ folder.

2. Choose an AI Backend

Backend	Internet Required	Setup Difficulty	Quality
Embedded	No	Easy	Good
Groq	Yes	Easy	Great
Ollama	No (local)	Moderate	Good
OpenAI	Yes	Easy	Great
Anthropic	Yes	Easy	Great

3. Configuration

Open the Mods menu in Minecraft, find "The Book of Wishes", click Config, and adjust settings in-game.

Alternatively, edit config/thebookofwishes-common.toml directly. Key settings:

[ollama]
  # AI backend: "embedded", "ollama", "groq", "openai", or "anthropic"
  llm_provider = "embedded"

  # Ollama settings
  endpoint = "http://localhost:11434"
  model = "llama3.1:8b"
  temperature = 0.4
  max_tokens = 1024

[groq]
  api_key = ""
  model = "openai/gpt-oss-120b"
  endpoint = "https://api.groq.com/openai/v1"

[embedded]
  model_path = "config/models/my-model.gguf"
  context_size = 2048
  gpu_layers = 0
  threads = 4

[gameplay]
  cooldown_seconds = 30
  max_wishes_per_book = 10
  enable_payment_system = true

[safety]
  max_destruction_radius = 128
  max_immortality_duration = 600

4. In-Game Usage

1. Craft the Book of Wishes:
   • Writable Book + Ender Eye + Nether Star
2. Right-click to open the book
3. Click + to add a new page
4. Type your wish
5. Click Grant Wish to submit
6. The AI processes your wish and writes its response back into the book

Building from Source

git clone https://github.com/THTStreamer/bookofwishes.git
cd bookofwishes
./gradlew build

The built jar will be in build/libs/.

Embedded AI Setup (Recommended)

Uses java-llama.cpp to run a GGUF model directly inside the mod. No external services needed.

1. Set llm_provider = "embedded" in config
2. Set model_path to your GGUF file
3. Download a recommended GGUF model:

Model	Size	RAM Required	Quality
Qwen3-1.7B-Q4_K_M	~1.1 GB	~2 GB	Good
Llama-3.2-3B-Q4_K_M	~2 GB	~3 GB	Better
Gemma-3-1B-Q4_K_M	~0.7 GB	~1.5 GB	Acceptable

4. Model loads automatically on first wish (takes a few seconds)

Groq Setup

Groq offers fast cloud inference with a generous free tier.

1. Get an API key from console.groq.com
2. Set llm_provider = "groq" in config
3. Set groq.api_key to your key (or enter it in the in-game config screen)
4. Pick a model like openai/gpt-oss-120b or llama-3.3-70b-versatile

Wish Types

The AI can grant wishes involving:

Category	Examples
Items	"Give me 64 diamonds"
Effects	"Grant me immortality for 5 minutes"
Teleportation	"Teleport me to the nearest village"
Entities	"Spawn 10 withers"
World	"Set the weather to thunder"
PvP	"Destroy the nearest player's base"
Structures	"Find the nearest stronghold"

Configuration Reference

Setting	Default	Description
ollama.llm_provider	"embedded"	AI backend
ollama.endpoint	http://localhost:11434	Ollama API URL
ollama.model	llama3.1:8b	Ollama model name
groq.api_key	""	Groq API key
groq.model	openai/gpt-oss-120b	Groq model name
groq.endpoint	https://api.groq.com/openai/v1	Groq API URL
embedded.model_path	""	Path to GGUF model file
embedded.context_size	2048	Context window size
embedded.gpu_layers	0	Layers to offload to GPU
embedded.threads	4	CPU threads for inference
gameplay.crafting_recipe_enabled	false	Enable vanilla crafting recipe
gameplay.cooldown_seconds	30	Cooldown between wishes
gameplay.max_wishes_per_book	10	Max wishes per book
gameplay.enable_payment_system	true	Enable payment extraction
safety.max_destruction_radius	128	Max destruction area radius
safety.max_immortality_duration	600	Max immortality in seconds
mod_compat.enable_registry_scanning	true	Scan modded items for AI

License

MIT