# Alkatraz 0.9.1 — The Forging Update > *Craft, imbue, and engrave. Forge the perfect arsenal.* 0.9.1 turns Alkatraz into a full magic RPG forging suite. A brand-new **Recipe Manager** lets you gate powerful gear behind unlock progression at every station, **Imbuing** converts vanilla weapons and armor into magic items with Magic Stones, and the **Engraving Table** lets you customize equipment with 28 trigger-based runes. Server owners get **PlaceholderAPI**, **localization**, and a configurable **loot & villager trading** system — while players benefit from **stat-driven spell power**, **wind-up cast animations**, and **hotbar safety** that survives even a server crash. --- ## Table of Contents 1. [Full Changelog](#-full-changelog) 2. [Recipe Manager & Recipe Book](#-recipe-manager--recipe-book) 3. [Imbuing](#-imbuing) 4. [Engraving Runes](#-engraving-runes) 5. [Stats, Spell Power & Magic Damage](#-stats-spell-power--magic-damage) 6. [PlaceholderAPI](#-placeholderapi) 7. [Localization](#-localization) 8. [Loot, Trading & Starter Content](#-loot-trading--starter-content) 9. [Hotbar Safety & Spell Hotbar](#-hotbar-safety--spell-hotbar) 10. [Public API](#-public-api) --- ## 📋 Full Changelog ### Added - **Recipe Manager & Recipe Book** — a fully configurable recipe system covering every crafting station, browsable and editable in-game via `/recipes` - **Recipe unlock progression** — recipes can be locked behind requirements (stats, permissions, research, spell mastery, playtime, world, and more) and unlocked in-game - **In-game Recipe Editor** — create, edit, duplicate, and delete recipes from the GUI (admin permissions) - **Imbuing system** — convert vanilla tools, weapons, and armor into imbued magic items using Magic Stones; 5 tiers grant bonus max mana - **Magic Stones** — new currency item dropped by magic mobs and sold by librarian villagers - **Engraving Table** — apply runes to magic items with a trigger selection menu and a confirmation screen showing mana cost and success/failure chances - **Engraving triggers** — 70+ trigger events across combat, movement, environment, inventory, gathering, player state, social, and WorldGuard region events - **Passive runes** — always-active runes that grant attributes while installed - **Magic Damage attribute** — boosts spell damage and explosions - **Stat-driven spell scaling** — spell power and cast time now scale from player profile stats - **Equipment that raises your max spell circle** — high-tier gear lets you cast spells above your circle - **Unified attribute pipeline** — stat points and equipment bonuses are routed through one system - **PlaceholderAPI expansion** — 60+ placeholders for stats, elements, spells, research, hotbar, and leaderboards - **Localization system** — `.lang` files with YAML string overrides - **Configurable loot system** — Magic Stone drops from magic mobs with Looting scaling - **Villager spellbook trading** — librarian villagers sell tiered spellbooks - **Starter spell** for new players - **Grimoire lectern UI** and improved spellbook display - **Wind-up cast animations** for Meteor Shower, Tsunami, Fissure, Tornado, Shadow Realm, and Radiance - **Hotbar inventory snapshot persistence** — survives server restarts and crashes - **`/summon` command** with count and location targeting; `/give` gained a count argument - **Self-target potion option** for potion spells - **Item Editor** now opens directly from recipe results - **Public API module** — spell registry, profile provider, GUI item registry, and full Javadoc for developers - **Magic mob data persistence** — mob definitions stored in the persistent data container ### Changed - **Enchanting tables** now open a choice menu: Arcane Table or vanilla enchanting - **Recipes unlock in-game** — a periodic sweep and live stat refresh unlock eligible recipes without a rejoin - **Wand cast codes** moved out of item NBT into memory - **Equipment system redesign** — elemental accessory variants and set bonuses - **Magic items** got a unique identity and centralized lore formatting; imbue naming reworked - **Magic mobs** now summon correctly on Minecraft 1.19.1 and 1.19.2 - **Particles** updated for 1.20.5+ enum renames - **Research menu** panning fixed for diagonal movement - **Imbuing** prevents imbuing items that are already imbued - **Magic item stack handling** now guards against air items and missing item meta ### Fixed - **Recipe editor menus** — lore line breaks, drag-and-drop, and right-click-to-clear - **Random spellbook item deletion** - **NBT primitive null error** - **Hotbar slot lock behavior** and death inventory handling - **Drop events** being cancelled after magic item component handling - **Research graph typos** and missing parents in locked lore - **Lang placeholder keys** no longer percent-wrapped - **Reload** correctly waits for recipe reload completion ### Removed - Deprecated **archmage ring** and **arcane artifact** items - Duplicate core classes (rewired to the API module) - Generated docs from the repository --- ## 🍳 Recipe Manager & Recipe Book <details> <summary><b>Click to expand</b> — configurable crafting, unlock progression, and an in-game recipe editor</summary> The headline feature of 0.9.1. Every craftable magic item now lives in a **config-driven recipe system** covering **all 11 recipe types** across **9 categories** — from crafting tables and furnaces to brewing stands, smithing tables, stonecutters, and anvils, plus custom recipe types. ### How it works 1. Run **`/recipes`** to open the Recipe Manager 2. Browse the 9 categories — Crafting, Furnace, Blast Furnace, Smoker, Campfire, Brewing, Smithing, Stonecutter, and Other 3. **Search** by recipe ID, display name, or result item, and **sort** alphabetically, by result, by ID, or by recently edited 4. Open a recipe to see its ingredients, result, and requirements ### Unlock Progression Recipes with requirements are **locked** by default. Players must meet the requirements and then click **Unlock** to permanently unlock the recipe. Requirements can combine stats, permissions, research, spell mastery, playtime, world, and more — each one shows a progress bar so players know exactly what's left. - Requirements are evaluated on join and whenever a crafting menu is opened - A **periodic sweep** plus live stat refresh unlocks eligible recipes in-game without a rejoin - Unlock notifications can fire chat, title, actionbar, sound, and particle channels (configurable) - Admins can force unlock/lock with `/recipes unlock`, `/recipes lock`, `/recipes give`, `/recipes check`, and `/recipes reload` ### In-Game Recipe Editor With the right permissions, admins can **create, edit, duplicate, and delete** recipes entirely in-game: - Change result, amount, display name, shape/ingredients, station inputs, experience, cooking time, requirements, permissions, and unlock message - Changes write straight to `plugins/Alkatraz/magic/recipes/<key>.yml` and reload the registry > See the [Recipes](https://github.com/NagasonicDev/Alkatraz/wiki/Recipes) page for the full guide. </details> --- ## ⚔️ Imbuing <details> <summary><b>Click to expand</b> — turn vanilla gear into magic items with Magic Stones</summary> Imbuing converts a **vanilla tool, weapon, or armor piece** into a **magic item** by infusing it with **Magic Stones** in a crafting grid. ### How to Imbue 1. Obtain **Magic Stones** — dropped by magic mobs (configurable chance + Looting bonus) or bought from librarian villagers 2. Place **1 vanilla item + N Magic Stones** in a crafting grid (shapeless recipe) 3. The result is the same item, now **imbued** — it keeps its material and durability, gains an "Imbued" prefix, and becomes usable in the Engraving Table The stone cost depends on the item's tier: | Tier | Materials | Stone Cost | |------|-----------|------------| | 1 | Wooden, Leather, Golden | 1 | | 2 | Stone, Chainmail | 2 | | 3 | Iron, Bow | 3 | | 4 | Diamond, Crossbow, Trident | 4 | | 5 | Netherite, Turtle Helmet | 5 | Each tier grants **bonus max mana** when equipped (Tier 1: +10 up to Tier 5: +100) and lets the item hold an engraving. Stone costs are configurable under `imbuing.stone_costs` in `config.yml`. > Imbue recipes are plain Bukkit recipes and do not appear in the Recipe Manager — real imbuing happens in the crafting grid. See [Equipment and Items](https://github.com/NagasonicDev/Alkatraz/wiki/Equipment-and-Items) for details. </details> --- ## 🔩 Engraving Runes <details> <summary><b>Click to expand</b> — 28 trigger-based and passive runes applied at the Engraving Table</summary> Customize your equipment with **28 runes** — physical items that are consumed when applied at the **Engraving Table**. ### How to Apply 1. Right-click an **Enchanting Table** and choose **Arcane Table** → **Magic Engineering** 2. Click a **magic item** to select it as the target 3. Click a **rune** from your inventory (type-incompatible runes are rejected) 4. If the rune is **triggered**, pick the trigger that activates it — **passive** runes skip this 5. Review the confirmation screen (target, rune, trigger, mana cost, success chance) and click **Confirm** Applying costs `100 + (current engravings × 50)` mana with an **80% success chance** — on failure the rune and mana are consumed but the item is unchanged. Each item has a `max_engravings` limit (default 1; higher-tier items up to 2). Runes are crafted at a crafting table using a shaped recipe built around a **Magic Stone**. ### Trigger Events Runes can trigger on **70+ events**: - **Combat** — spell cast, melee/ranged kill, critical hit, damage dealt/taken, blocking, projectiles, being targeted - **Movement** — sprint, swim, glide, fly, jump, land, enter water/lava, climb, teleport, world change, beds - **Environment** — lightning, explosion, fire, drowning, freezing, fall, void, starvation, rain, thunder - **Inventory** — use, left-click, swap hands, pick up, drop, consume, durability, repair, enchant - **Gathering** — break blocks, mine ore, place, fish, shear, buckets - **Player state** — equip, sneak, held slot, join/quit, death, respawn, level up, XP, heal, low health, mana, spell discovery, research completion - **Social & region** — chat, commands, villager trades, intervals, day/night, WorldGuard regions Effects include igniting, potions, damage, healing, explosions, teleporting, sounds, particles, and console commands — all gated by conditions (chance, circle level, mana, cooldowns, and more). > See the [Engravings](https://github.com/NagasonicDev/Alkatraz/wiki/Engravings) page for the full rune and trigger reference. </details> --- ## 📈 Stats, Spell Power & Magic Damage <details> <summary><b>Click to expand</b> — a unified attribute pipeline for combat scaling</summary> 0.9.1 rewires combat math into a unified **attribute pipeline**: - **Magic Damage attribute** — increases the damage of spells and spell-caused explosions - **Spell Power** — now scales from your player profile stats; your **cast time** scales with mastery and stats - **Max spell circle** — certain equipment raises the maximum circle your wand can cast, letting you reach above your progression - **Stat points** and **equipment bonuses** flow through the same pipeline, so everything stacks consistently > See [Stats and Elements](https://github.com/NagasonicDev/Alkatraz/wiki/Stats-and-Elements) and [Progression](https://github.com/NagasonicDev/Alkatraz/wiki/Progression) for the full picture. </details> --- ## 🔌 PlaceholderAPI <details> <summary><b>Click to expand</b> — 60+ placeholders for server owners</summary> Alkatraz now registers its own **PlaceholderAPI expansion** (`alkatraz`) automatically — no download command needed. Placeholders cover: - **Stats** — circle, mana, mana regen, spell power, arcane knowledge, research points, stat points, cast state, discovered spells - **Elements** — affinity and resistance per element, plus magic - **Spells** — discovered state, name, element, circle, mana cost, cast code, mastery, cooldowns - **Research** — completed count and per-node state - **Hotbar** — spell assigned to each slot - **Leaderboard** — ranked by Arcane Knowledge with configurable refresh interval and entry count Examples: `%alkatraz_stats_circle_roman%`, `%alkatraz_spells_cooldown_fireball_ready%`, `%alkatraz_leaderboard_top_1_name%` > See the [PlaceholderAPI](https://github.com/NagasonicDev/Alkatraz/wiki/PlaceholderAPI) page for the complete reference. </details> --- ## 🌍 Localization <details> <summary><b>Click to expand</b> — translate the plugin with `.lang` files</summary> Every user-facing string — menu titles, spell names, error messages — now lives in a **`.lang` file** using a simple `key = value` format. - The plugin ships with a bundled **English** base file; set `language: <name>` in `config.yml` and create `plugins/Alkatraz/lang/<language>.lang` - Only include the keys you want to override — anything missing falls back to English - **YAML overrides** let you rename spells and research nodes without touching their configs (`override.spells.<id>.name`, `override.research.nodes.<id>.name`) - `\n` for line breaks, `&` color codes, UTF-8 accents, and `/alkatraz reload` to apply changes > See the [Localization](https://github.com/NagasonicDev/Alkatraz/wiki/Localization) page for details. </details> --- ## 📜 Loot, Trading & Starter Content <details> <summary><b>Click to expand</b> — Magic Stones, spellbook trades, and a starter spell</summary> - **Configurable loot** — Magic Stone drop chance from magic mobs scales with the Looting enchantment (`magic_stone.base_drop_chance`, `magic_stone.looting_bonus`) - **Villager trading** — librarian villagers may sell **spellbooks** with tiered emerald/Magic Stone costs, randomized within configurable ranges - **Starter spell** — new players begin with a basic spell > See [Spellbooks and Loot](https://github.com/NagasonicDev/Alkatraz/wiki/Spellbooks-and-Loot) for the full loot table reference. </details> --- ## 🛡️ Hotbar Safety & Spell Hotbar <details> <summary><b>Click to expand</b> — hotbar inventory that survives restarts and crashes</summary> Hotbar casting got a durability upgrade: - Your **inventory snapshot is now saved to disk** when entering hotbar mode, so it survives server restarts and crashes - The snapshot is **restored automatically on join** if the previous session didn't exit cleanly - On **keep-inventory deaths**, your original items are restored into your live inventory - Slot-lock behavior and death handling have been fixed so nothing is lost or swapped </details> --- ## 📦 Public API <details> <summary><b>Click to expand</b> — build on Alkatraz from your own plugins</summary> Alkatraz ships a **public Java API** (`alkatraz-api`) that external plugins can depend on to create custom spells, register magic items, hook into the progression system, and extend the magic item pipeline with custom components, conditions, effects, and attribute sources — every class documented with full Javadoc. Add the Maven repository and dependency to your plugin: **Maven repository:** ```xml <repository> <id>repsy</id> <name>Alkatraz</name> <url>https://repo.repsy.io/nagasonic/alkatrazapi</url> </repository> ``` **Dependency:** ```xml <dependency> <groupId>me.nagasonic</groupId> <artifactId>alkatraz-api</artifactId> <version>0.9.1</version> </dependency> ``` What you can do with it: - **Custom spells** — extend `Spell` and register it with `SpellAPI.registerSpell()` - **Magic item definitions** — register items, engravings, components, triggers, conditions, effects, and attribute types through `MagicItemRegistries` - **Player profiles** — read circle, mana, element affinity/resistance, discovered spells, research, and more via `SpellAPI.getProfile(player)` - **Recipe API** — query, unlock, and lock recipes plus custom requirement types and crafting adapters via `Alkatraz.getRecipeManager()` - **Events** — listen to Bukkit events like `SpellPrepareEvent`, `PlayerCastEvent`, and `RecipeUnlockedEvent` - **Mob API** — declarative mob brains and spell cast configuration > See the [API Usage](https://github.com/NagasonicDev/Alkatraz/wiki/API-Usage) page for the full guide and a complete example plugin. </details> --- *Alkatraz 0.9.1 — August 2026*

# 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. --- ## Table of Contents 1. [Circle Progression System](#-circle-progression-system) 2. [Research Tree](#-research-tree) 3. [Arcane Knowledge & Research Points](#-arcane-knowledge--research-points) 4. [New Spells](#-new-spells) 5. [Spell Options Overhaul](#-spell-options-overhaul) 6. [Custom Magic Mobs](#-custom-magic-mobs) 7. [Wand Hotbar & Casting Mode](#-wand-hotbar--casting-mode) 8. [GUI Overhaul](#-gui-overhaul) 9. [Spell Components & Collision System](#-spell-components--collision-system) 10. [Profile Persistence Rewrite](#-profile-persistence-rewrite) 11. [First-Join Tutorial](#-first-join-tutorial) 12. [Full Changelog](#-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 1. **Earn Research Points** by mastering spells, killing magic mobs, and advancing circles 2. **Spend them** on research nodes in the **Research Library** (accessible from the Arcane Table) 3. **Complete objectives** (cast spells, kill with spells, break blocks, enchant items, fish, level up, etc.) 4. **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): 1. Welcome to Alkatraz 2. Crafting a Wooden Wand (lapis above stick) 3. Casting spells with the 5-click code system 4. Understanding mana 5. Useful commands 6. Progression overview (Circles, Research, Arcane Knowledge) 7. 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*

# Changelog 0.8: - Update NBTAPI distribution for 1.21.11 - **Add Spellbooks** - Spellbooks are the survival mode method for discovering spells - Currently, there are **two** ways to obtain spellbooks, from **structure loot** or **mob loot**. - There are 2 types of spellbooks - Spellbooks: Just the base spellbook that contains the information of a single spell. - Random Spellbooks: These contain multiple spells, choosing one at random to obtain. - Added Mob Element Attributes - Stored in `mobs/*`, completely editable + can add mobs not already implemented. - Upgraded `Ground` system for Earth magic - Added much more types of `Ground`. - Earth magic can only use these blocks, otherwise it will not work. I will eventually post a list of these on the wiki on the Github. - Fixed Spell Cooldown text (idk how it was still broken for so long) - Added New Spells - Updated Earth Throw visual to match `Ground` - Added Spell options for Lesser Heal - Fixed Magic Missile continuous damage + particles on lower versions - Add AttackSpell hit tracking. - Make stat points be given when achieving max mastery of a spell. - Fix stat points not adding when leveling up. # New Spells ## Air Blades **Code:** RLSRS **Element:** Air **Level:** 2 **Cast Time:** 0.8s **Cooldown:** 6s *Arm yourself with blades of wind, releasing a fan of cutting air towards your foes.* ## Dark Tendrils **Code:** RLRLS **Element:** Dark **Level:** 3 **Cast Time:** 1.5s **Cooldown:** 15s *Summon tendrils of dark mana that hunt nearby targets and inflict debilitating effects.* ## Geyser **Code:** LSRLS **Element:** Water **Level:** 3 **Cast Time:** 0.8s **Cooldown:** 6s *Summons a column of water that erupts in front of the player, launching enemies and dealing damage.* ## Heal **Code:** RSRRS **Element:** Light **Level:** 3 **Cast Time:** 2.0s **Cooldown:** 45s *Heal yourself or any target.* ## Tremor **Code:** SLLRS **Element:** Earth **Level:** 3 **Cast Time:** 1.5s **Cooldown:** 25s *Sends out a shockwave through the ground, launching enemies up and dealing damage.*

# Alkatraz Beta 0.7 ## Spell Options Added in 0.7, Spell Options are a new mechanic that allows players to customise certain aspects of a spell to fit their own use. This could be the size, speed, or range of a spell. For example, the **Fireball** spell now has options that allow a player to modify: - Explosion Size - Whether it breaks blocks. - Speed Currently, not all spells have options, as this version is a testing ground for the mechanic. ## I would greatly appreciate feedback: [Discord](https://discord.gg/DvSzE9Qtst) ## Spell Cooldowns Due to balance risks, I have decided to add cooldowns to most spells in the plugin, to reduce spamming that could lead to boring fights and to encourage creative thinking. Cooldowns can be seen on the [Wiki](https://github.com/NagasonicDev/Alkatraz/wiki/Spells) ## Reworked Stat Storage After this update, the new stat storage system has been implemented, meaning that old files will not work with the updated plugin. For this reason, check the **How to Update** section. # How to Update: Files that must be deleted: - `/spells` directory - Player Stats should be reset

# Changelog - Add Reinforced Wand - 3 new spells: - Earth Spike: Creates a spike out of the ground, dealing damage to enemies. - Water Pulse: Summons a wave of water, expanding outwards from the caster, knocking back enemies and extinguishing flames and lava. - Barrier: Creates a magical barrier, that can withstand 20 hitpoints worth of damage from attack spells. - Change PlayerCastEvent to be called when the spell is casted, not when the circle is being prepared. - Created PlayerSpellPrepareEvent to replace PlayerCastEvent at this time. - Remove various debug messages. - Add SpellComponents, which represent the various parts of spells, including blocks, entities and particles. - Introduced Spell collisions, which allow spells to collide with each other, allowing them to be destroyed or offset. - When a AttackSpell (Fireball, Magic Missile etc.) collides with a BarrierSpell (Barrier), the power of the AttackSpell is subtracted from the hitpoints of the barrier spell. If the barrier spell completely absorbs the AttackSpell, the attack is stopped, and in most cases (except for Fire Wall, which just doesn't continue), the spell is canceled. On the other hand, if the barrier spell is destroyed by the AttackSpell, the difference is subtracted from the power of the AttackSpell, reducing it. If the ratio of the power to the new power is less than 25%, the AttackSpell is 'countered'. - Fixed multi player casting. Previously, spell values were stored globally, meaning they would be overrided when a new player casted the spell. Following this update, spells now have SpellProperties, which hold the various information needed in each seperate cast. - Reduced Air Burst Particle velocity. 0.2 -> 0.1 - Made the top part of Fire Wall to be lava pop particles instead of normal flame particles. - Fixed Fire Wall extension glitch. - Removed Spell#getCastEvent replaced it by including the prepare event into circleAction(). - Changed Magic Missile to be non-instantaneous. instant -> 10 b/s - Added AttackSpell and BarrierSpell classes, extending Spell, to contain data and methods specific to attack spells and barrier spells. Changed the following Spells to AttackSpells: - Magic Missile - Fireball - Fire Blast - Air Burst - Water Sphere - Earth Throw - Fire Wall - Added `resource_pack_override` to `config.yml`, is not currently used, but will mess up some things if you change it to true, so keep it false. - Fixed NBT-API shaded package warning on server startup. # How to Update These are the config files that need to be deleted to properly update. - `config.yml` - All the Attack Spell configs.

# Changelog: - Changed Stat storing system. - Added 2 spells: - **Swift** (2nd Circle): Launches the player forward. - **Fire Wall** (3rd Circle): Creates a wall of flames to deter enemies. - **1.21.11** support. - **ADDED WAND RECIPES!!!**, which can be viewed from the wiki at https://github.com/NagasonicDev/Alkatraz/wiki. - Added Reinforced Wand - Added Wand casting limits - Added Persistent disguises - Fixed Disguise Spell - Modified Stealth visibility to include players at the same circle level, rather than only higher circle. - Added stealth move particles # How to Update: Following this update, the following files must be deleted to update properly: - wands/wooden_wand.yml - spells/disguise.yml - spells/stealth.yml - playerdata/playerdata.yml

# BUG FIX - Fixed NMS_v1_21_R5 registering on 1.21.10 instead of NMS_v1_21_R6.

# Changelog: - Added NMS Support - Experience Bars no longer interfere with true Exp. - New Spells: - **Disguise**: Allows the user to disguise as another online player. - **Stealth**: Hides the user from view of other players. User appears transparent if the other player has a greater circle level. - **Detect**: Scans the surroundings for entities. Hostile mobs glow red, passive glow white, unstealth players glow yellow, stealth players glow gray (if lower circle level). - Added `/alkatraz reload` command, to reload spell configs. - Added PlayerCastEvent (for future API) - Changed wand lore creation. - Fixed HOTBAR_SWAP Inventory Click. - Changed Spell Descriptions from `String` -> `String List` - Added `Registered {spell}` logging on startup. - Made NBT-API shaded. So it is now not a dependency. - NULL element was changed to NONE element (in spell comments) - Alkatraz has become a multi-module project, which doesn't change much on the server-side, but it is a big change. # How To Update Due to changes in `.yml`'s, it is vital to delete the `/spells` directory in the `Alkatraz` folder. Player data must also be reset, due to the addition of the stealth boolean. # Dependencies Following this update, Alkatraz has **NO** dependencies.

# Changelog - Added Stats GUI & Stat Points (`/alkatraz stats`) - `stat_points` stat - `reset_tokens` stat - `stats.yml` file in playerdata/ - Added Fire Blast Spell - Added `alkatraz.command.spells.other` permission, to view another player's /spells gui. - Added `circle_ticks` to `config.yml`, which is how often the particles for casting are displayed. Default 10 (0.5s). - Fixed `/alkatraz circle set`. - Changed `Magic Damage` -> `Magic Affinity` to match element stats. - Revamped Circle Leveling - Max Mana: - 0: 100 - 1: 267 -> 200 - 2: 433 -> 400 - 3: 600 -> 800 - 4: 767 -> 1250 - 5: 933 -> 2000 - 6: 1100 -> 2750 - 7: 1267 -> 4000 - 8: 1433 -> 7500 - 9: 1600 -> 10000 - Mana Regen: - Previous: - Calculated by `max_mana_of_circle / (100 + (max_mana_of_circle - 100) * (8/150))` - New: - 0: 1 - 1: 2 - 2: 2.5 - 3: 3 - 4: 5 - 5: 6.25 - 6: 7.5 - 7: 10 - 8: 12.5 - 9: 15 - Added Spell Effectiveness Scaling. Spells now scale damage/effectiveness with the affinity of the caster, and with the resistance of the attacked. - Fixed Fireball Damage Scaling (didn't work in the first place) - Fixed Lesser Heal Particles when healing another player. - Updated Mana Costs: - Air Burst: 36 -> 15 - Earth Throw: 36 -> 15 - Fireball: 36 -> 15 - Water Sphere: 36 -> 15 - Lesser Heal: 66 -> 75 - Changed Lesser Heal Max Mastery: 100 -> 150 # Update Requirements: - Delete All Spell Config Files - Delete `config.yml`

## Additions: - Circle/Level System - Scaling Max Mana and Mana Regeneration - Spells locked behind Circle Requirement - Changed Mana Costs - 3 new Spells - Air Burst (1st circle) - Earth Throw (1st circle) - Lesser Heal (2nd circle) ## Fixes - Fixed Casting Delays Support: [Discord](https://discord.gg/DvSzE9Qtst)