Alkatraz 0.9 — The Progression Overhaul

Cast smarter, grow stronger. Welcome to the age of magic.

This update transforms Alkatraz from a simple spell-slinging plugin into a full-fledged magic RPG. With 9 Magic Circles, a deep Research Tree, custom mobs that cast spells, data-driven spell options, and a wand hotbar system, 0.9 is the biggest update yet.

Circle Progression System
Research Tree
Arcane Knowledge & Research Points
New Spells
Spell Options Overhaul
Custom Magic Mobs
Wand Hotbar & Casting Mode
GUI Overhaul
Spell Components & Collision System
Profile Persistence Rewrite
First-Join Tutorial
Full Changelog

🔮 Circle Progression System

The core of 0.9: 9 Magic Circles that gate your power.

Circle	Arcane Knowledge Required	Rewards
I	300	+5 Max Mana, +1 Mana Regen, +1 Stat Point
II	1,040	+10 Max Mana, +1 Mana Regen, +1 Stat Point
III	2,636	+15 Max Mana, +2 Mana Regen, +2 Stat Points
IV	6,570	+20 Max Mana, +2 Mana Regen, +2 Stat Points
V	15,566	+25 Max Mana, +3 Mana Regen, +3 Stat Points
VI	36,916	+30 Max Mana, +3 Mana Regen, +3 Stat Points
VII	86,360	+35 Max Mana, +4 Mana Regen, +4 Stat Points
VIII	202,531	+40 Max Mana, +4 Mana Regen, +4 Stat Points
IX	474,531	+50 Max Mana, +5 Mana Regen, +5 Stat Points

Each circle also requires specific Research completions from Circle IV onward.

How to Advance

Open the Arcane Table (right-click an Enchanting Table with a wand in hand)
Navigate to Progression
Click the glowing (yellow) next-circle pane to view rewards and requirements
Confirm to trigger the Circle Up animation — a 2-second visual and audio spectacle with spiralling purple particles and enchanting sounds
Auto-advance can be toggled in config so you rank up the moment requirements are met

🌳 Research Tree

A fully-fledged directed acyclic graph (DAG) of research nodes across 7 categories (Magic + 6 elements).

How It Works

Earn Research Points by mastering spells, killing magic mobs, and advancing circles
Spend them on research nodes in the Research Library (accessible from the Arcane Table)
Complete objectives (cast spells, kill with spells, break blocks, enchant items, fish, level up, etc.)
Claim permanent rewards

Research Tree Structure

Awakened Focus (Magic — Root)
  ├── Mana Conservation (Magic)        → +0.25 Mana Regen
  ├── Ritual Geometry (Magic)          → +1 Stat Point
  ├── Spellcraft Field Notes (Magic)   → +2 Magic Affinity
  │
  ├── Fire Spark (Fire)                → +3 Fire Affinity, +1 Fire Point
  │   └── Fire Ember Control (Fire)    → +3 Fire Affinity
  │       └── 🔒 Fire Inferno Rite (Fire Capstone)
  │
  ├── Water First Tide (Water)         → +3 Water Affinity, +1 Water Point
  │   └── Water Restorative Current (Water)
  │       └── 🔒 Water Depth Oath (Water Capstone)
  │
  ├── Earth Stone Memory (Earth)       → +3 Earth Affinity, +1 Earth Point
  │   └── Earth Quarry Signs (Earth)
  │       └── 🔒 Earth Bulwark Vow (Earth Capstone)
  │
  ├── Air Open Breath (Air)            → +3 Air Affinity, +1 Air Point
  │   └── Air Kinetic Step (Air)
  │       └── 🔒 Air Storm Eye (Air Capstone)
  │
  ├── Light First Lantern (Light)      → +3 Light Affinity, +1 Light Point
  │   └── Light Mending Script (Light)
  │       └── 🔒 Light Radiant Oath (Light Capstone)
  │
  └── Dark Quiet Shadow (Dark)         → +3 Dark Affinity, +1 Dark Point
      └── Dark Tethered Whisper (Dark)
          └── 🔒 Dark Eclipse Compact (Dark Capstone)

Disciplined Channel (Magic Capstone — requires 3 core Magic nodes)
  → +2 Max Health, +2 Magic Resistance

Research Explorer GUI

Graph View: A 4×7 panable viewport that renders the entire research tree
State-coloured nodes: Grey (hidden), Red (locked), Icon (available), Book (in progress), Enchanted Book (completed)
Edge rendering: Purple stained-glass panes connecting parent-child nodes
Entry Detail: Full node info including description, requirements, tasks with progress (X/Y), rewards, and connected children
Categories: Filter by element or view the full magic tree

⚡ Arcane Knowledge & Research Points

Arcane Knowledge

Earned by casting spells (amount scales with your current circle level — higher circles earn more per cast). This is the primary currency for circle advancement.

Research Points

Earned from three sources:

Source	Points
Mastering a spell (max level)	10
Killing a magic mob	3
Advancing a circle	50

Spend these in the Research Tree to unlock permanent upgrades.

✨ New Spells

Blink (Air — Circle IV)

Teleport up to 12 blocks in the direction you're facing. Cancels with mana refund if you'd end up inside a wall. Purple portal particles on cast.

Earthen Wall (Earth — Circle IV)

Raise a massive wall of earth that follows your gaze. Damages and launches enemies as it erupts through them. Configurable height (5-7) and length (15-25). Self-destruct mode restores the terrain when the wall crumbles.

Flaming Volley (Fire — Circle IV)

Fire a spread of flaming arrows that pierce through targets, set enemies ablaze for 5 seconds, and can optionally ignite the landscape. Configurable arrow count (3/5/7).

Whirlpool (Water — Circle IV)

Create a vortex at a target location that pulls enemies toward the centre and deals damage per tick. Configurable radius (4-7), duration (5-12s), and pull strength.

Wind Barrier (Air — Circle IV)

Summon a spherical wind barrier that deflects projectiles and pushes enemies away. Optionally follows the player (requires max mastery). Configurable radius (3-5) and duration (15-45s).

Summon Zombies (Dark — Circle IV)

Raise 2-4 zombies that fight for you for 30 seconds. They're tagged to avoid friendly fire and automatically target whatever you attack. Expired zombies despawn with smoke effects.

Light Buff (Light — Circle IV)

Bless nearby players (configurable 5-12 block radius) with Strength I, Speed I, and Resistance I. Duration configurable from 8 to 30 seconds. Yellow particle burst and beacon sounds.

Buff (Light — Circle II)

A customisable buff spell. Choose up to 3 buffs from a pool of effects: Strength (+15%/25%), Speed (+20%/35%), Defence (+15%/25%), Mana Regen (+20%), Magic Power (+20%), Cast Speed (+15%), Elemental Affinity (+10). Sneak to buff another player.

Debuff (Dark — Circle II)

A customisable debuff spell. Choose up to 3 debuffs from: Weakness (-15%/25%), Slow (-20%/35%), Vulnerability (-15%/25%), Mana Suppression (-20%), Magic Suppression (-20%), Cast Slow (-15%), Affinity Drain (-10).

⚙️ Spell Options Overhaul

All spell configuration has been migrated from hard-coded Java to YAML config files. Every spell now has a corresponding {spell_id}_options.yml file.

What this means for you

Server admins: Tweak every numerical value — damage, range, duration, cooldown, mana cost — without touching code
New option types: Pool & Slot options for spells like Buff/Debuff where you pick multiple effects
Custom menus: Spells with pooled slot systems get their own dedicated selection GUI
Impacts & Requirements: Each option value can have stat impacts (e.g., "+5% Cast Speed") and unlock requirements

👹 Custom Magic Mobs

The world is more dangerous now. Three new mobs replace a percentage of natural spawns:

Zombie Mage

Replaces: 5% of zombie spawns
Spells: Fireball, Earth Spike, Water Sphere
Behaviour: Keeps distance, casts ranged spells
Resists: Dark (+55%), Magic (+40%), Earth (+20%)
Weak to: Fire (-25%)
Drops a Wooden Wand

Zombie Fighter

Replaces: 3% of zombie spawns
Spell: Self-Buff (Speed II + Strength I on a 30-minute cooldown)
Behaviour: Aggressive melee, targets villagers and iron golems

Skeletal Mage

Replaces: 4% of skeleton spawns
Spells: Magic Missile, Stealth
Behaviour: Ranged caster that can turn invisible

How it works

Mobs use the same spell system as players — they have cast times, cooldowns, and wind-up animations with magic circle particles
Each mob has elemental affinities and resistances defined in YAML configs
Spell selection is smart: AttackSpells only cast if the mob has a target, Heal spells only if injured, Stealth only if visible
Distance keeping AI: Mobs maintain optimal spellcasting range, backing away when you get close
Fully implemented across all supported Minecraft versions (1.19 through 1.21.4+, including v26)

🪄 Wand Hotbar & Casting Mode

New Casting Mode: Hotbar

Switch between Code Casting (the classic 5-click gesture system) and Hotbar Casting (spell hotbar).

Enter hotbar mode: Right-click a wand → your inventory is saved and replaced with 8 spell slots + your wand
Cast: Right-click with a spell item selected
Exit: Right-click the wand in slot 8 — your inventory is fully restored
Configure: Assign any discovered spell to any hotbar slot via the Spells menu
Safety: All inventory interactions are locked while in hotbar mode (no drops, no swaps, no accidental loss)

Spell Cast Validator

Before any spell is cast, the system now validates:

Your wand's circle limit vs the spell's required circle
Your profile's circle level
Whether you've discovered the spell (unless you have alkatraz.allspells permission)

🖥️ GUI Overhaul

Menu	What's New
Arcane Table (Enchanting Table + Wand)	New hub menu — access Progression and Research Library
Progression Menu	Visual circle display with coloured panes (Lime = done, Yellow = next, Red = locked), shows requirements and rewards per circle
Circle Up Confirmation	Review what you'll get before committing, with re-validation
Research Graph	Panable 4×7 grid showing the entire research tree with state-coloured nodes and edge connections
Research Entry	Full detail view: description, parent requirements, objective progress, rewards, children
Research Categories	Filter by element or view the full magic tree
Spell Options	Paginated menu with synthetic grouped options, custom pooled-slot selection menus for Buff/Debuff
Spells Menu	New "Configure Spell Hotbar" button, shows discovered vs locked states
Hotbar Spell Selection	Assign discovered spells to 8 hotbar slots with a scrollable pool, auto-advance focus
Stats Menu	Now shows Circle Level, Arcane Knowledge, Research Points, element affinities/resistances with stat point investment

💥 Spell Components & Collision System

The combat interaction system has been rebuilt:

Barrier types: Physical barriers block physical attacks, Magic barriers block magic attacks, Combined barriers block both
Power penetration: If attack damage exceeds barrier HP by 125%, remaining power punches through
Projectile deflection: Wind barriers actively deflect incoming projectiles away from the caster
Block destruction: Physical attacks that destroy a barrier also remove the attacking block
Collision tracking: Pairs are tracked to prevent double-processing

💾 Profile Persistence Rewrite

Each player gets a folder: Alkatraz/playerdata/<uuid>/ with separate files per profile type
Stat-driven architecture: All magic profile data stored in typed maps (ints, doubles, bools, strings, string sets) instead of discrete fields
Hotbar persistence: Slot-to-spell-ID mappings saved and restored across sessions
Research tracking: Started/completed research, objective progress, and reward flags all persisted
Spell options: Per-player spell option selections saved
Spell mastery: Dynamic stat keys (mastery_<spellId>) created on first use
Arcane Knowledge: Backward compatible with legacy experience stat

🎓 First-Join Tutorial

A 7-step guided tutorial for new players (configurable via first_join_tutorial in config.yml):

Welcome to Alkatraz
Crafting a Wooden Wand (lapis above stick)
Casting spells with the 5-click code system
Understanding mana
Useful commands
Progression overview (Circles, Research, Arcane Knowledge)
Final encouragement with a clickable wiki link

Delivered via titles, chat messages, action bars, and clickable/hoverable text — plays automatically for first-time joiners.

🧾 Full Changelog

Added

9 Magic Circle progression system with configurable requirements and rewards
Research Tree with 24 nodes across 7 categories, objectives, and permanent rewards
Arcane Knowledge — earned by casting, spent on circle advancement
Research Points — earned by mastering spells, killing magic mobs, and advancing circles
9 new spells: Blink, Buff, Debuff, Earthen Wall, Flaming Volley, Light Buff, Summon Zombies, Whirlpool, Wind Barrier
3 custom magic mobs: Zombie Mage, Zombie Fighter, Skeletal Mage — with spell-casting AI and elemental stats
Spell Options YAML system — all spell configuration migrated to data-driven config files
Wand Hotbar casting mode with inventory snapshot/restore
Spell Cast Validator — circle, wand, and discovery checks
SpellComponentHandler — projectile deflection, power penetration, barrier type interactions
Circle Up animation — 2-second visual and audio effect on circle advancement
First-Join Tutorial — 7-step guided onboarding
GUIs: Arcane Table hub, Progression Menu, Circle Up Confirmation, Research Graph (panable), Research Entry, Research Categories, Pooled Slot Selection, Hotbar Spell Selection
Profile persistence per-player folder structure with typed stat maps
CastEvent/SpellPrepareEvent event system for both players and mobs
SpellMasteryRequirement, ArcaneKnowledgeRequirement, ResearchRequirement for circle gates
ResearchObjectiveListener — tracks 10+ gameplay events for research progress
ResearchPointService with configurable point sources
Support for Minecraft versions v26_R1 and v26_R2 (latest)

Changed

Spells menu: Now has hotbar configuration button, shows discovered/locked states
Stats menu: Now shows circles, arcane knowledge, research points, element stats with investment
Profile persistence: Single YAML file → folder per player with typed stats
PlayerCastEvent: Now extends CastEvent (shared player+mob event hierarchy)
Spell.java: Added cancelCast(), mobCast(), option system, mastery-based cast time reduction, arcane knowledge on cast
SpellRegistry: All spells registered via registerIfEnabled() reading YAML configs
AlkatrazCommand: Added castmode/hotbar, spawnmob, gencode subcommands
Configs: Added first_join_tutorial toggle

Fixed

Profile persistence with spell masteries — mastery data no longer lost between sessions

Removed

Hard-coded spell options (replaced by YAML configs)
Old monolithic mob entity classes (replaced by NMS-abstracted MagicEntity system)

Alkatraz 0.9 — July 2026

Alkatraz Magic

Links

Tags

Creators

Details

0.9

Compatibility

Changes